@supermodeltools/mcp-server 0.5.3 → 0.5.4

package/README.md

@@ -8,6 +8,45 @@ MCP server that provides deep codebase analysis to AI agents via the [Supermodel
 
 ## Install
 
+### Quick Setup (Recommended)
+
+Run the setup script to configure the recommended timeout settings:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/supermodeltools/mcp/main/setup.sh | bash
+```
+
+<details>
+<summary>Prefer to inspect before running? (Click to expand)</summary>
+
+Download, review, then execute:
+
+```bash
+# Download the script
+curl -sSL https://raw.githubusercontent.com/supermodeltools/mcp/main/setup.sh -o setup.sh
+
+# Review the contents
+cat setup.sh
+
+# Make executable and run
+chmod +x setup.sh
+./setup.sh
+```
+
+Or clone the entire repo:
+
+```bash
+git clone https://github.com/supermodeltools/mcp.git
+cd mcp
+./setup.sh
+```
+
+</details>
+
+This will configure `MCP_TOOL_TIMEOUT=900000` for optimal performance with large codebases.
+
+### Manual Install
+
 ```bash
 npm install -g @supermodeltools/mcp-server
 ```
@@ -18,6 +57,45 @@ Or run directly:
 npx @supermodeltools/mcp-server
 ```
 
+## ⚠️ Important: Configure Timeout for Large Codebase Analysis
+
+The `explore_codebase` tool can take **5-15 minutes** to analyze large repositories. Most MCP clients have a default timeout of 60-120 seconds, which will cause the operation to fail prematurely.
+
+**Quick Setup:**
+
+Add this to your shell profile to set a 15-minute timeout:
+
+```bash
+export MCP_TOOL_TIMEOUT=900000
+```
+
+**Installation by Client:**
+
+<details>
+<summary><strong>Claude Code CLI</strong></summary>
+
+Add to your shell profile (`~/.zshrc` for macOS or `~/.bashrc` for Linux):
+
+```bash
+export MCP_TOOL_TIMEOUT=900000
+```
+
+Then reload your shell:
+
+```bash
+source ~/.zshrc  # or ~/.bashrc
+```
+
+Verify it's set:
+
+```bash
+echo $MCP_TOOL_TIMEOUT
+```
+
+</details>
+
+**Note:** Timeout configuration via `MCP_TOOL_TIMEOUT` is only supported in Claude Code CLI. For more details, see the [official Claude Code documentation](https://code.claude.com/docs/en/settings.md).
+
 ## Configuration
 
 Get your API key from the [Supermodel Dashboard](https://dashboard.supermodeltools.com).
@@ -114,25 +192,7 @@ Add to `~/.cursor/mcp.json`:
 }
 ```
 
-### Claude Desktop
-
-Add to `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "supermodel": {
-      "command": "npx",
-      "args": ["-y", "@supermodeltools/mcp-server"],
-      "env": {
-        "SUPERMODEL_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
-```
-
-### Claude Code
+### Claude Code CLI
 
 Add the MCP server with your API key:
 
@@ -196,9 +256,176 @@ Analyzes code structure, dependencies, and relationships across a repository. Us
 - Cleans up temporary files automatically
 - Cross-platform compatible
 
+## Tool Performance & Timeout Requirements
+
+The `explore_codebase` tool analyzes your entire repository to build a comprehensive code graph. Analysis time scales with repository size and complexity.
+
+| Tool | Typical Duration | Recommended Timeout | Repository Size |
+|------|------------------|---------------------|--------------------|
+| `explore_codebase` | 2-5 min | 600000ms (10 min) | Small (<1k files) |
+| `explore_codebase` | 5-10 min | 900000ms (15 min) | Medium (1k-10k files) |
+| `explore_codebase` | 10-15 min | 1200000ms (20 min) | Large (10k+ files) |
+
+**Default recommendation**: The server uses a 15-minute timeout (`900000ms`) by default, which works well for most medium-sized repositories.
+
+**Caching behavior**: The first run analyzes your codebase and caches the results. Subsequent queries on the same repository are typically much faster (seconds instead of minutes) as they use the cached graph.
+
+**Setting custom timeouts**: If you need to adjust the timeout for larger repositories, you can set the `SUPERMODEL_TIMEOUT_MS` environment variable:
+
+```json
+{
+  "mcpServers": {
+    "supermodel": {
+      "command": "npx",
+      "args": ["-y", "@supermodeltools/mcp-server"],
+      "env": {
+        "SUPERMODEL_API_KEY": "your-api-key",
+        "SUPERMODEL_TIMEOUT_MS": "1200000"
+      }
+    }
+  }
+}
+```
+
 ## Troubleshooting
 
-Debug logs go to stderr:
+### Timeout Errors
+
+#### "Request timeout"
+
+**Cause:** The analysis is taking longer than your MCP client's timeout allows (varies by client—Claude Code CLI defaults to ~2 minutes, Claude Desktop enforces 5 minutes). Large repositories or complex codebases may require more time to analyze.
+
+**Solutions:**
+
+1. **Analyze a subdirectory instead** - Target specific parts of your codebase:
+   ```bash
+   # Instead of analyzing the entire repo
+   explore_codebase(directory="/path/to/repo")
+
+   # Analyze just the core module
+   explore_codebase(directory="/path/to/repo/src/core")
+   ```
+
+2. **Increase your MCP client timeout** - For Claude Code CLI, set the `MCP_TOOL_TIMEOUT` environment variable:
+
+   ```bash
+   # Set timeout to 15 minutes (900000ms) for large codebase analysis
+   export MCP_TOOL_TIMEOUT=900000
+   ```
+
+   Then reload your shell or start a new terminal session. This timeout applies to all MCP tool executions.
+
+   **Note:** Timeout configuration is currently only supported in Claude Code CLI.
+
+3. **Verify `.gitignore` excludes build artifacts** - Ensure your repository excludes:
+   - `node_modules/`, `vendor/`, `venv/`
+   - `dist/`, `build/`, `out/`
+   - `.next/`, `.nuxt/`, `.cache/`
+
+   The MCP server automatically excludes these patterns when zipping, but `.gitignore` prevents them from being in your working directory in the first place—both improve performance and reduce analysis size.
+
+#### "Analysis interrupted mid-way"
+
+**Cause:** Network interruption or the MCP server process was terminated before completion.
+
+**Solutions:**
+
+1. **Check MCP server logs** - Logs location varies by client:
+
+   > **Note:** Log filenames match your MCP server name from the config. If you named it differently (e.g., `my-server`), look for `mcp-server-my-server.log` instead of `mcp-server-supermodel.log`.
+
+   **Claude Desktop (macOS):**
+   ```bash
+   tail -f ~/Library/Logs/Claude/mcp-server-supermodel.log
+   ```
+
+   **Claude Desktop (Windows):**
+   ```powershell
+   Get-Content "$env:APPDATA\Claude\Logs\mcp-server-supermodel.log" -Wait
+   ```
+
+   **Claude Desktop (Linux):**
+   ```bash
+   tail -f ~/.config/Claude/logs/mcp-server-supermodel.log
+   ```
+
+   **Cursor:**
+   ```bash
+   # Check the Cursor logs directory
+   tail -f ~/Library/Application\ Support/Cursor/logs/mcp-server-supermodel.log
+   ```
+
+   **Claude Code:**
+   ```bash
+   # Logs are shown in the terminal when running with verbose mode
+   claude --verbose
+   ```
+
+2. **Retry the analysis** - Temporary network issues often resolve on retry
+
+3. **Check your internet connection** - The analysis requires a stable connection to the Supermodel API
+
+4. **Verify the API is accessible:**
+   ```bash
+   curl -H "Authorization: Bearer YOUR_API_KEY" https://api.supermodeltools.com/health
+   ```
+
+#### "ERROR Request failed. Check the MCP server logs"
+
+**Multiple possible causes:**
+
+##### 1. Missing or invalid API key
+
+Check if your API key is set:
+```bash
+echo $SUPERMODEL_API_KEY
+```
+
+Verify it's valid at [Supermodel Dashboard](https://dashboard.supermodeltools.com).
+
+**Solution:**
+```bash
+# Set in your shell profile (~/.zshrc or ~/.bashrc)
+export SUPERMODEL_API_KEY="your-api-key"
+source ~/.zshrc
+
+# Or update your MCP client config with the correct key
+```
+
+##### 2. API service outage or rate limiting
+
+Check the error details in logs (see log locations above).
+
+**Solution:**
+- Visit [Supermodel Status](https://status.supermodeltools.com) for service status
+- If rate limited, wait a few minutes before retrying
+- Consider upgrading your API plan if hitting rate limits frequently
+
+##### 3. Repository too large
+
+The API has size limits for analysis. Check the [Supermodel documentation](https://docs.supermodeltools.com) for current limits.
+
+**Solution:**
+```bash
+# Check your repo size
+du -sh /path/to/repo
+
+# If too large, analyze subdirectories instead
+explore_codebase(directory="/path/to/repo/src")
+```
+
+##### 4. Network or firewall issues
+
+Corporate firewalls may block outbound requests to the Supermodel API.
+
+**Solution:**
+- Test connectivity: `curl https://api.supermodeltools.com/health`
+- Check firewall rules allow HTTPS to `api.supermodeltools.com`
+- Contact your IT department if behind a corporate proxy
+
+### Debug Logging
+
+Debug logs go to stderr and include:
 
 - `[DEBUG] Server configuration:` - Startup config
 - `[DEBUG] Auto-zipping directory:` - Starting zip creation
@@ -206,12 +433,32 @@ Debug logs go to stderr:
 - `[DEBUG] Making API request` - Request details
 - `[ERROR] API call failed:` - Error details with HTTP status
 
-**Common issues:**
-- 401: Check `SUPERMODEL_API_KEY` is set
-- ZIP too large: Directory contains too many files/dependencies. Ensure `.gitignore` is configured properly
-- Permission denied: Check read permissions on the directory
-- Insufficient disk space: Free up space in your system's temp directory
-- Directory does not exist: Verify the path is correct and absolute
+To enable verbose logging, set the `DEBUG` environment variable:
+
+```bash
+# In your MCP config
+{
+  "mcpServers": {
+    "supermodel": {
+      "command": "npx",
+      "args": ["-y", "@supermodeltools/mcp-server"],
+      "env": {
+        "SUPERMODEL_API_KEY": "your-api-key",
+        "DEBUG": "supermodel:*"
+      }
+    }
+  }
+}
+```
+
+### Common Issues
+
+- **401 Unauthorized:** Check `SUPERMODEL_API_KEY` is set correctly
+- **ZIP too large:** Directory contains too many files/dependencies. Ensure `.gitignore` is configured properly
+- **Permission denied:** Check read permissions on the directory
+- **Insufficient disk space:** Free up space in your system's temp directory
+- **Directory does not exist:** Verify the path is correct and absolute
+- **ENOTFOUND or connection errors:** Check your internet connection and firewall settings
 
 ## Benchmarking
 

package/dist/tools/create-supermodel-graph.js

@@ -53,7 +53,9 @@ exports.metadata = {
 };
 exports.tool = {
     name: 'explore_codebase',
-    description: `Analyzes code within the target directory to produce a graph that can be used to navigate the codebase when solving bugs, planning or analyzing code changes.
+    description: `Comprehensive codebase analysis using Supermodel API. ⚠️ This operation takes 5-15 minutes for large repositories. Ensure your Claude CLI timeout is configured (MCP_TOOL_TIMEOUT=900000). Analyzes code structure, dependencies, and patterns while respecting .gitignore.
+
+Analyzes code within the target directory to produce a graph that can be used to navigate the codebase when solving bugs, planning or analyzing code changes.
 
 ## Example Output
 
@@ -625,7 +627,7 @@ async function logErrorResponse(error) {
     }
 }
 /**
- * Fetch graph from API with comprehensive logging
+ * Fetch graph from API with comprehensive logging and progress updates
  */
 async function fetchFromApi(client, file, idempotencyKey) {
     const startTime = Date.now();
@@ -643,17 +645,44 @@ async function fetchFromApi(client, file, idempotencyKey) {
         file: fileBlob,
         idempotencyKey: idempotencyKey,
     };
+    // Start progress logging
+    console.error('[Supermodel] Starting codebase analysis...');
+    // Set up periodic progress updates every 15 seconds
+    let progressInterval = null;
+    let elapsedSeconds = 0;
+    progressInterval = setInterval(() => {
+        elapsedSeconds += 15;
+        console.error(`[Supermodel] Analysis in progress... (${elapsedSeconds}s elapsed)`);
+    }, 15000);
     try {
         const response = await client.graphs.generateSupermodelGraph(requestParams);
         const duration = Date.now() - startTime;
+        // Clear progress interval
+        if (progressInterval) {
+            clearInterval(progressInterval);
+            progressInterval = null;
+        }
         // Calculate approximate response size
         const responseSize = JSON.stringify(response).length;
         logResponse(200, 'OK', responseSize, duration);
+        // Log completion with summary
+        const summary = response.summary;
+        if (summary) {
+            console.error(`[Supermodel] Analysis complete, retrieving results... (${summary.filesProcessed || 0} files processed)`);
+        }
+        else {
+            console.error('[Supermodel] Analysis complete, retrieving results...');
+        }
         logger.debug(`[${getTimestamp()}] [API SUCCESS] Request completed successfully`);
         return response;
     }
     catch (error) {
         const duration = Date.now() - startTime;
+        // Clear progress interval on error
+        if (progressInterval) {
+            clearInterval(progressInterval);
+            progressInterval = null;
+        }
         logger.error(`[${getTimestamp()}] [API FAILURE] Request failed after ${duration}ms`);
         // Log detailed error information
         await logErrorResponse(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supermodeltools/mcp-server",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "MCP server for Supermodel API - code graph generation for AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",