Merge pull request #6 from graphops/chris/configurable-timeout

feat: configurable timeout and release script

Author: sahra-karakoc

Cargo.lock

@@ -1,10 +1,14 @@
 [package]
 name = "subgraph-mcp"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2021"
-authors = ["sahra"]
+authors = ["GraphOps"]
 license = "Apache-2.0"
 
+[lib]
+name = "subgraph_mcp"
+path = "src/lib.rs"
+
 [dependencies]
 tokio = { version = "1.44.2", features = ["full"] }
 reqwest = { version = "0.12.15", features = ["json"] }
@@ -26,3 +30,6 @@ http = "1.3.1"
 tracing = "0.1"
 once_cell = "1.20"
 prometheus-client = { version = "0.23.1" }
+
+[dev-dependencies]
+wiremock = "0.6"

Cargo.toml

@@ -110,6 +110,59 @@ For example, if `pwd` outputs `/Users/user/subgraph-mcp`, the full command path
 
 After adding the configuration, restart Claude Desktop.
 
+#### Request Timeout Configuration (for Local Execution)
+
+The server includes configurable timeout settings for HTTP requests to The Graph's Gateway. This helps handle complex GraphQL queries that may take longer to execute.
+
+**Default Behavior**
+
+By default, the server uses a **120-second timeout** for all HTTP requests to The Graph's Gateway. This provides a good balance between allowing complex queries to complete while preventing indefinite hangs.
+
+**Custom Timeout Configuration**
+
+You can customize the timeout in several ways:
+
+Option 1: Environment Variable (Recommended)
+
+Set the `SUBGRAPH_REQUEST_TIMEOUT_SECONDS` environment variable:
+
+```bash
+export SUBGRAPH_REQUEST_TIMEOUT_SECONDS=300  # 5 minutes
+```
+
+For Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "subgraph-mcp": {
+      "command": "/path/to/subgraph-mcp",
+      "env": {
+        "GATEWAY_API_KEY": "YOUR_GATEWAY_API_KEY",
+        "SUBGRAPH_REQUEST_TIMEOUT_SECONDS": "300"
+      }
+    }
+  }
+}
+```
+
+Option 2: Programmatic Configuration (for developers)
+
+When building applications with the server library:
+
+```rust
+use std::time::Duration;
+use subgraph_mcp::SubgraphServer;
+
+// Use default timeout (120 seconds)
+let server = SubgraphServer::new();
+
+// Use custom timeout
+let server = SubgraphServer::with_timeout(Duration::from_secs(300));
+```
+
+**Note**: Very long timeouts (>5 minutes) should be used cautiously as they may impact overall application responsiveness.
+
 **Important**: Claude Desktop may not automatically utilize server resources. To ensure proper functionality, manually add `Subgraph Server Instructions` resource to your chat context by clicking on the context menu and adding the resource.
 
 ## Available Tools
@@ -263,6 +316,39 @@ The following application-specific metrics are exposed:
 
 Additionally, the `axum-prometheus` library provides standard HTTP request metrics for the metrics server itself (prefixed with `http_`).
 
+## Troubleshooting
+
+### Request Timeout Errors
+
+If you encounter "Request timed out" or "MCP error -32001" errors, this typically indicates that GraphQL queries are taking longer than the configured timeout to complete.
+
+**Solutions:**
+
+**If you're running your own local server instance:**
+
+1. **Increase the timeout** using the `SUBGRAPH_REQUEST_TIMEOUT_SECONDS` environment variable:
+   ```bash
+   export SUBGRAPH_REQUEST_TIMEOUT_SECONDS=300  # 5 minutes
+   ```
+
+**If you're using the remote hosted service:**
+
+1. **Contact support** - Timeout settings are managed by the hosted service and cannot be customized by end users.
+
+**For all users:**
+
+2. **Check query complexity** - Very complex queries with large result sets may need longer timeouts or query optimization.
+
+3. **Verify The Graph Gateway status** - Occasional timeout issues may be due to temporary Gateway performance issues.
+
+**Default Timeout**: Local server instances use a 120-second timeout by default (increased from 30 seconds in earlier versions). Remote hosted service timeout settings may differ.
+
+### Common Issues
+
+- **"API key not found"**: Ensure your `GATEWAY_API_KEY` environment variable is set correctly
+- **"Configuration error"**: Check that your Gateway API key is valid and has appropriate permissions
+- **Connection refused**: Verify the server is running and accessible on the configured port
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.