@supermodeltools/mcp-server 0.5.3 → 0.6.0

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:
 
@@ -152,6 +212,44 @@ Verify installation:
 claude mcp list
 ```
 
+## Health Checks
+
+This MCP server implements the [MCP ping utility](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/ping) for connection health monitoring. The ping mechanism allows clients to verify that the server is responsive and the connection remains alive.
+
+### How It Works
+
+- **Request**: Client sends a `ping` JSON-RPC request with no parameters
+- **Response**: Server responds promptly with an empty result object `{}`
+- **Automatic**: Handled automatically by the MCP SDK - no additional configuration needed
+
+### Use Cases
+
+- **Pre-flight checks**: Verify server is accessible before starting work
+- **Connection monitoring**: Detect stale connections during long-running sessions
+- **Periodic health checks**: Confirm server remains responsive
+
+### Example
+
+```json
+// Request
+{
+  "jsonrpc": "2.0",
+  "id": "123",
+  "method": "ping"
+}
+
+// Response
+{
+  "jsonrpc": "2.0",
+  "id": "123",
+  "result": {}
+}
+```
+
+If the server doesn't respond within a reasonable timeout (typically 5-10 seconds), the connection should be considered stale.
+
+For more details, see the [MCP specification for ping/health checks](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/ping).
+
 ## Tools
 
 ### `explore_codebase`
@@ -196,9 +294,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 +471,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/server.js

@@ -110,7 +110,20 @@ For localized bugs:
 
 Example:
 - Full repo: directory="/repo" → 180MB, 50k nodes
-- Subsystem: directory="/repo/django/db" → 15MB, 3k nodes`,
+- Subsystem: directory="/repo/django/db" → 15MB, 3k nodes
+
+## Error Handling
+
+When a tool call returns an error, check the structured error fields:
+- \`error.recoverable: true\` → wait briefly and retry the request
+- \`error.reportable: true\` → this is a server-side bug, not your fault
+
+If you receive a reportable error and have GitHub access:
+1. Search the \`error.repo\` issues for the \`error.code\` to avoid duplicates
+2. If no existing issue, open one with the error code, message, and any reproduction context
+3. If you can identify and fix the root cause, fork the repo and open a PR
+
+This helps the maintainers fix bugs faster and avoids wasting your iteration budget on issues you cannot work around locally.`,
         });
         const config = new sdk_1.Configuration({
             basePath: process.env.SUPERMODEL_BASE_URL || 'https://api.supermodeltools.com',

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

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handler = exports.tool = exports.metadata = void 0;
+exports.classifyApiError = classifyApiError;
 const promises_1 = require("fs/promises");
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
@@ -43,6 +44,8 @@ const filtering_1 = require("../filtering");
 const queries_1 = require("../queries");
 const zip_repository_1 = require("../utils/zip-repository");
 const logger = __importStar(require("../utils/logger"));
+const REPORT_REPO = 'https://github.com/supermodeltools/mcp.git';
+const REPORT_SUGGESTION = 'This may be a bug in the MCP server. You can help by opening an issue at https://github.com/supermodeltools/mcp/issues with the error details, or fork the repo and open a PR with a fix.';
 exports.metadata = {
     resource: 'graphs',
     operation: 'write',
@@ -53,7 +56,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
 
@@ -243,12 +248,24 @@ const handler = async (client, args, defaultWorkdir) => {
     // Validate directory - check if explicitly invalid first
     if (providedDirectory !== undefined && typeof providedDirectory !== 'string') {
         logger.error('Invalid directory parameter:', providedDirectory);
-        return (0, types_1.asErrorResult)('Invalid "directory" parameter. Provide a valid directory path as a string.');
+        return (0, types_1.asErrorResult)({
+            type: 'validation_error',
+            message: 'Invalid "directory" parameter. Provide a valid directory path as a string.',
+            code: 'INVALID_DIRECTORY',
+            recoverable: false,
+            suggestion: 'Pass directory as a string path, e.g. directory="/workspace/my-repo"',
+        });
     }
     // Check if we have any directory at all
     if (!directory || typeof directory !== 'string') {
         logger.error('Invalid directory parameter:', directory);
-        return (0, types_1.asErrorResult)('No "directory" parameter provided and no default workdir configured. Please provide a directory path or start the server with a workdir argument.');
+        return (0, types_1.asErrorResult)({
+            type: 'validation_error',
+            message: 'No "directory" parameter provided and no default workdir configured.',
+            code: 'MISSING_DIRECTORY',
+            recoverable: false,
+            suggestion: 'Provide a directory path or start the MCP server with a workdir argument (e.g. npx @anthropic-ai/supermodel-mcp /path/to/repo).',
+        });
     }
     if (providedDirectory) {
         logger.debug('Using provided directory:', directory);
@@ -301,20 +318,58 @@ const handler = async (client, args, defaultWorkdir) => {
         if (error.stack) {
             logger.error('Stack trace:', error.stack);
         }
-        // Return user-friendly, actionable error messages
-        if (error.message.includes('does not exist')) {
-            return (0, types_1.asErrorResult)(`Directory not found. Please verify the path exists: ${directory}`);
+        // Normalize: guard against non-Error throws (string, object, undefined)
+        const message = typeof error?.message === 'string' ? error.message : String(error);
+        // Return structured, actionable error messages
+        if (message.includes('does not exist')) {
+            return (0, types_1.asErrorResult)({
+                type: 'not_found_error',
+                message: `Directory not found: ${directory}`,
+                code: 'DIRECTORY_NOT_FOUND',
+                recoverable: false,
+                suggestion: 'Verify the path exists. Use an absolute path to the repository root or subdirectory.',
+                details: { directory },
+            });
         }
-        if (error.message.includes('Permission denied')) {
-            return (0, types_1.asErrorResult)(`Permission denied. Check that you have read access to: ${directory}`);
+        if (message.includes('Permission denied')) {
+            return (0, types_1.asErrorResult)({
+                type: 'resource_error',
+                message: `Permission denied accessing directory: ${directory}`,
+                code: 'PERMISSION_DENIED',
+                recoverable: false,
+                suggestion: 'Check that the MCP server process has read access to this directory.',
+                details: { directory },
+            });
         }
-        if (error.message.includes('exceeds limit')) {
-            return (0, types_1.asErrorResult)(error.message + '\n\nTry analyzing a subdirectory or excluding more files.');
+        if (message.includes('exceeds limit')) {
+            return (0, types_1.asErrorResult)({
+                type: 'resource_error',
+                message,
+                code: 'ZIP_TOO_LARGE',
+                recoverable: true,
+                suggestion: 'Analyze a subdirectory instead of the full repository (e.g. directory="/repo/src/core"). This reduces ZIP size and processing time.',
+                details: { directory },
+            });
         }
-        if (error.message.includes('ENOSPC')) {
-            return (0, types_1.asErrorResult)('Insufficient disk space. Free up space and try again.');
+        if (message.includes('ENOSPC')) {
+            return (0, types_1.asErrorResult)({
+                type: 'resource_error',
+                message: 'Insufficient disk space to create ZIP archive.',
+                code: 'DISK_FULL',
+                recoverable: false,
+                suggestion: 'Free up disk space or analyze a smaller subdirectory.',
+            });
         }
-        return (0, types_1.asErrorResult)(`Failed to create ZIP archive. Check the MCP server logs for details.`);
+        return (0, types_1.asErrorResult)({
+            type: 'internal_error',
+            message: `Failed to create ZIP archive: ${message}`,
+            code: 'ZIP_CREATION_FAILED',
+            recoverable: false,
+            reportable: true,
+            repo: REPORT_REPO,
+            suggestion: REPORT_SUGGESTION,
+            details: { directory: (0, path_1.basename)(directory), errorType: error.name || 'Error' },
+        });
     }
     // Execute query with cleanup handling
     try {
@@ -429,40 +484,7 @@ async function handleQueryMode(client, params) {
         }
         catch (error) {
             // Error details are already logged by fetchFromApi and logErrorResponse
-            // Return a user-friendly, actionable error message
-            let errorMessage = '';
-            if (error.response) {
-                const status = error.response.status;
-                switch (status) {
-                    case 401:
-                        errorMessage = 'Authentication failed. Set your SUPERMODEL_API_KEY environment variable and restart the MCP server.';
-                        break;
-                    case 403:
-                        errorMessage = 'Access forbidden. Your API key does not have permission for this operation. Contact support if this is unexpected.';
-                        break;
-                    case 404:
-                        errorMessage = 'API endpoint not found. The service URL may be incorrect. Check your SUPERMODEL_BASE_URL configuration.';
-                        break;
-                    case 429:
-                        errorMessage = 'Rate limit exceeded. Wait a few minutes and try again.';
-                        break;
-                    case 500:
-                    case 502:
-                    case 503:
-                    case 504:
-                        errorMessage = 'Server error. The Supermodel API is temporarily unavailable. Try again in a few minutes.';
-                        break;
-                    default:
-                        errorMessage = `API error (HTTP ${status}). Check the MCP server logs for details.`;
-                }
-            }
-            else if (error.request) {
-                errorMessage = 'No response from server. Check your network connection and verify the API is reachable.';
-            }
-            else {
-                errorMessage = 'Request failed. Check the MCP server logs for details.';
-            }
-            return (0, types_1.asErrorResult)(errorMessage);
+            return (0, types_1.asErrorResult)(classifyApiError(error));
         }
     }
     // Handle query errors
@@ -625,7 +647,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,33 +665,182 @@ 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);
-        // Re-throw with enhanced error message
+        // Preserve error.response so classifyApiError can read the status code (#75)
         if (error.response?.status === 401) {
-            throw new Error(`API authentication failed (401 Unauthorized). Please check your SUPERMODEL_API_KEY environment variable.`);
+            error.message = 'API authentication failed (401 Unauthorized). Please check your SUPERMODEL_API_KEY environment variable.';
         }
         else if (error.response?.status === 403) {
-            throw new Error(`API access forbidden (403 Forbidden). Your API key may not have permission to access this resource.`);
+            error.message = 'API access forbidden (403 Forbidden). Your API key may not have permission to access this resource.';
         }
         else if (error.response?.status >= 500) {
-            throw new Error(`Supermodel API server error (${error.response.status}). The service may be temporarily unavailable.`);
+            error.message = `Supermodel API server error (${error.response.status}). The service may be temporarily unavailable.`;
         }
         throw error;
     }
 }
+/**
+ * Classify an API error into a structured error response.
+ * Extracts HTTP status, network conditions, and timeout signals
+ * to produce an agent-actionable error with recovery guidance.
+ */
+function classifyApiError(error) {
+    // Guard against non-Error throws (strings, nulls, plain objects)
+    if (!error || typeof error !== 'object') {
+        return {
+            type: 'internal_error',
+            message: typeof error === 'string' ? error : 'An unexpected error occurred.',
+            code: 'UNKNOWN_ERROR',
+            recoverable: false,
+            reportable: true,
+            repo: REPORT_REPO,
+            suggestion: REPORT_SUGGESTION,
+            details: { errorType: typeof error },
+        };
+    }
+    if (error.response) {
+        const status = error.response.status;
+        switch (status) {
+            case 401:
+                return {
+                    type: 'authentication_error',
+                    message: 'Invalid or missing API key.',
+                    code: 'INVALID_API_KEY',
+                    recoverable: false,
+                    suggestion: 'Set the SUPERMODEL_API_KEY environment variable and restart the MCP server.',
+                    details: { apiKeySet: !!process.env.SUPERMODEL_API_KEY, httpStatus: 401 },
+                };
+            case 403:
+                return {
+                    type: 'authorization_error',
+                    message: 'API key does not have permission for this operation.',
+                    code: 'FORBIDDEN',
+                    recoverable: false,
+                    suggestion: 'Verify your API key has the correct permissions. Contact support if unexpected.',
+                    details: { httpStatus: 403 },
+                };
+            case 404:
+                return {
+                    type: 'not_found_error',
+                    message: 'API endpoint not found.',
+                    code: 'ENDPOINT_NOT_FOUND',
+                    recoverable: false,
+                    suggestion: 'Check SUPERMODEL_BASE_URL environment variable. Default: https://api.supermodeltools.com',
+                    details: { baseUrl: process.env.SUPERMODEL_BASE_URL || 'https://api.supermodeltools.com', httpStatus: 404 },
+                };
+            case 429:
+                return {
+                    type: 'rate_limit_error',
+                    message: 'API rate limit exceeded.',
+                    code: 'RATE_LIMITED',
+                    recoverable: true,
+                    suggestion: 'Wait 30-60 seconds and retry. Consider analyzing smaller subdirectories to reduce API calls.',
+                    details: { httpStatus: 429 },
+                };
+            case 500:
+            case 502:
+            case 503:
+            case 504:
+                return {
+                    type: 'internal_error',
+                    message: `Supermodel API server error (HTTP ${status}).`,
+                    code: 'SERVER_ERROR',
+                    recoverable: true,
+                    reportable: true,
+                    repo: REPORT_REPO,
+                    suggestion: 'The API may be temporarily unavailable. Wait a few minutes and retry. If persistent, open an issue at https://github.com/supermodeltools/mcp/issues with the error details, or fork the repo and open a PR with a fix.',
+                    details: { httpStatus: status },
+                };
+            default: {
+                const isServerError = status >= 500;
+                return {
+                    type: isServerError ? 'internal_error' : 'validation_error',
+                    message: `API request failed with HTTP ${status}.`,
+                    code: 'API_ERROR',
+                    recoverable: isServerError,
+                    ...(isServerError && {
+                        reportable: true,
+                        repo: REPORT_REPO,
+                        suggestion: 'The API may be temporarily unavailable. Wait a few minutes and retry. If persistent, open an issue at https://github.com/supermodeltools/mcp/issues with the error details, or fork the repo and open a PR with a fix.',
+                    }),
+                    ...(!isServerError && { suggestion: 'Check the request parameters and base URL configuration.' }),
+                    details: { httpStatus: status },
+                };
+            }
+        }
+    }
+    if (error.request) {
+        // Distinguish timeout from general network failure
+        if (error.code === 'UND_ERR_HEADERS_TIMEOUT' || error.code === 'UND_ERR_BODY_TIMEOUT' || error.message?.includes('timeout')) {
+            return {
+                type: 'timeout_error',
+                message: 'API request timed out. The codebase may be too large for a single analysis.',
+                code: 'REQUEST_TIMEOUT',
+                recoverable: true,
+                suggestion: 'Analyze a smaller subdirectory (e.g. directory="/repo/src/core") or increase SUPERMODEL_TIMEOUT_MS.',
+            };
+        }
+        return {
+            type: 'network_error',
+            message: 'No response from Supermodel API server.',
+            code: 'NO_RESPONSE',
+            recoverable: true,
+            suggestion: 'Check network connectivity. Verify the API is reachable at the configured base URL.',
+            details: { baseUrl: process.env.SUPERMODEL_BASE_URL || 'https://api.supermodeltools.com' },
+        };
+    }
+    // Catch-all for unexpected errors - include the actual message
+    return {
+        type: 'internal_error',
+        message: error.message || 'An unexpected error occurred.',
+        code: 'UNKNOWN_ERROR',
+        recoverable: false,
+        reportable: true,
+        repo: REPORT_REPO,
+        suggestion: REPORT_SUGGESTION,
+        details: { errorType: error.name || 'Error' },
+    };
+}
 /**
  * Legacy mode: direct jq filtering on API response
  */
@@ -681,43 +852,16 @@ async function handleLegacyMode(client, file, idempotencyKey, jq_filter) {
     catch (error) {
         if ((0, filtering_1.isJqError)(error)) {
             logger.error('jq filter error:', error.message);
-            return (0, types_1.asErrorResult)(`Invalid jq filter syntax. Check your filter and try again.`);
+            return (0, types_1.asErrorResult)({
+                type: 'validation_error',
+                message: `Invalid jq filter syntax: ${error.message}`,
+                code: 'INVALID_JQ_FILTER',
+                recoverable: false,
+                suggestion: 'Check jq filter syntax. Use the query parameter instead for structured queries (e.g. query="summary").',
+            });
         }
         // Error details are already logged by fetchFromApi and logErrorResponse
-        // Return a user-friendly, actionable error message
-        let errorMessage = '';
-        if (error.response) {
-            const status = error.response.status;
-            switch (status) {
-                case 401:
-                    errorMessage = 'Authentication failed. Set your SUPERMODEL_API_KEY environment variable and restart the MCP server.';
-                    break;
-                case 403:
-                    errorMessage = 'Access forbidden. Your API key does not have permission for this operation. Contact support if this is unexpected.';
-                    break;
-                case 404:
-                    errorMessage = 'API endpoint not found. The service URL may be incorrect. Check your SUPERMODEL_BASE_URL configuration.';
-                    break;
-                case 429:
-                    errorMessage = 'Rate limit exceeded. Wait a few minutes and try again.';
-                    break;
-                case 500:
-                case 502:
-                case 503:
-                case 504:
-                    errorMessage = 'Server error. The Supermodel API is temporarily unavailable. Try again in a few minutes.';
-                    break;
-                default:
-                    errorMessage = `API error (HTTP ${status}). Check the MCP server logs for details.`;
-            }
-        }
-        else if (error.request) {
-            errorMessage = 'No response from server. Check your network connection and verify the API is reachable.';
-        }
-        else {
-            errorMessage = 'Request failed. Check the MCP server logs for details.';
-        }
-        return (0, types_1.asErrorResult)(errorMessage);
+        return (0, types_1.asErrorResult)(classifyApiError(error));
     }
 }
 exports.default = { metadata: exports.metadata, tool: exports.tool, handler: exports.handler };

package/dist/types.js

@@ -13,12 +13,15 @@ function asTextContentResult(result) {
         isError: false
     };
 }
-function asErrorResult(message) {
+function asErrorResult(error) {
+    const text = typeof error === 'string'
+        ? error
+        : JSON.stringify({ error }, null, 2);
     return {
         content: [
             {
                 type: 'text',
-                text: message,
+                text,
             },
         ],
         isError: true,

package/package.json

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