@supermodeltools/mcp-server 0.5.4 → 0.6.0

package/README.md

@@ -212,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`

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',
@@ -245,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);
@@ -303,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 {
@@ -431,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
@@ -686,19 +706,141 @@ async function fetchFromApi(client, file, idempotencyKey) {
         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
  */
@@ -710,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.4",
+  "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",