@supermodeltools/mcp-server 0.6.4 → 0.7.0

package/README.md

@@ -294,6 +294,92 @@ Analyzes code structure, dependencies, and relationships across a repository. Us
 - Cleans up temporary files automatically
 - Cross-platform compatible
 
+### Individual Graph Tools
+
+For targeted analysis, use these specialized tools instead of the comprehensive `explore_codebase`:
+
+#### `get_call_graph`
+
+Generate a function-level call graph showing caller/callee relationships.
+
+**Use this to:**
+- Find all functions that call a specific function
+- Find all functions called by a specific function
+- Trace call chains through the codebase
+- Understand function dependencies
+
+**Parameters:**
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `directory` | string | Yes | Path to repository directory |
+| `jq_filter` | string | No | jq filter for custom data extraction |
+
+#### `get_dependency_graph`
+
+Generate a module-level dependency graph showing import relationships.
+
+**Use this to:**
+- Understand module dependencies
+- Find circular dependencies
+- Identify tightly coupled modules
+- Plan module extraction or refactoring
+
+**Parameters:**
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `directory` | string | Yes | Path to repository directory |
+| `jq_filter` | string | No | jq filter for custom data extraction |
+
+#### `get_domain_graph`
+
+Generate a high-level domain classification graph.
+
+**Use this to:**
+- Understand the architectural domains in a codebase
+- See how code is organized into logical areas
+- Get a bird's-eye view of system structure
+- Identify domain boundaries
+
+**Parameters:**
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `directory` | string | Yes | Path to repository directory |
+| `jq_filter` | string | No | jq filter for custom data extraction |
+
+#### `get_parse_graph`
+
+Generate an AST-level parse graph with fine-grained code structure.
+
+**Use this to:**
+- Analyze detailed code structure
+- Find specific syntax patterns
+- Understand class/function definitions at AST level
+- Support precise refactoring operations
+
+**Parameters:**
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `directory` | string | Yes | Path to repository directory |
+| `jq_filter` | string | No | jq filter for custom data extraction |
+
+### Choosing the Right Tool
+
+| Tool | Best For | Output Size |
+|------|----------|-------------|
+| `explore_codebase` | Comprehensive analysis with built-in queries | Largest - all graph types |
+| `get_call_graph` | Function call tracing, debugging | Medium - functions only |
+| `get_dependency_graph` | Module refactoring, circular deps | Small - modules only |
+| `get_domain_graph` | Architecture overview | Smallest - domains only |
+| `get_parse_graph` | AST analysis, precise refactoring | Large - full AST |
+
+**Tip:** Start with `get_domain_graph` for a quick architecture overview, then drill down with `get_call_graph` or `get_dependency_graph` for specific areas.
+
+> **Note:** All graph tools accept a `directory` parameter and an optional `jq_filter`. If you start the server with a default working directory (`node dist/index.js /path/to/repo`), the `directory` argument can be omitted from tool calls.
+
 ## 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.
@@ -502,6 +588,69 @@ To enable verbose logging, set the `DEBUG` environment variable:
 
 Benchmark this MCP server using [mcpbr](https://github.com/caspianmoon/mcpbr-benchmark-caching) with the provided [`mcpbr-config.yaml`](./mcpbr-config.yaml) configuration.
 
+## Local Development & Testing
+
+### Building from Source
+
+```bash
+git clone https://github.com/supermodeltools/mcp.git
+cd mcp
+npm install
+npm run build
+```
+
+### Running Locally
+
+```bash
+# Start the MCP server
+node dist/index.js
+
+# Or with a default working directory
+node dist/index.js /path/to/repo
+```
+
+### Testing Tools Locally
+
+Run the integration tests to verify the server and tools:
+
+```bash
+# Run all tests including integration tests
+npm test
+
+# Run only integration tests
+npm test -- src/server.integration.test.ts
+```
+
+### Using MCP Inspector
+
+For interactive testing, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+
+```bash
+# Install the inspector
+npm install -g @modelcontextprotocol/inspector
+
+# Run with your server
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+This opens a web UI where you can:
+- See all available tools
+- Call tools with custom arguments
+- View responses in real-time
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Type checking
+npm run typecheck
+```
+
 ## Links
 
 - [API Documentation](https://docs.supermodeltools.com)

package/dist/filtering.js

@@ -5,8 +5,19 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.maybeFilter = maybeFilter;
 exports.isJqError = isJqError;
+/**
+ * jq filtering utilities for JSON response transformation.
+ * Provides optional jq filter application to API responses.
+ * @module filtering
+ */
 // @ts-nocheck
 const jq_web_1 = __importDefault(require("jq-web"));
+/**
+ * Optionally applies a jq filter to a response object.
+ * @param jqFilter - The jq filter string, or undefined to skip filtering
+ * @param response - The JSON response to filter
+ * @returns The filtered response, or the original response if no filter provided
+ */
 async function maybeFilter(jqFilter, response) {
     if (jqFilter && typeof jqFilter === 'string') {
         return await jq(response, jqFilter);
@@ -15,9 +26,20 @@ async function maybeFilter(jqFilter, response) {
         return response;
     }
 }
+/**
+ * Applies a jq filter to JSON data.
+ * @param json - The JSON data to filter
+ * @param jqFilter - The jq filter expression
+ * @returns The filtered result
+ */
 async function jq(json, jqFilter) {
     return (await jq_web_1.default).json(json, jqFilter);
 }
+/**
+ * Type guard to check if an error is a jq parsing error.
+ * @param error - The error to check
+ * @returns True if the error is a jq-related error with stderr output
+ */
 function isJqError(error) {
     return error instanceof Error && 'stderr' in error;
 }

package/dist/index.js

@@ -34,8 +34,17 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Entry point for the Supermodel MCP Server.
+ * Starts the MCP server with optional default working directory.
+ * @module index
+ */
 const server_1 = require("./server");
 const logger = __importStar(require("./utils/logger"));
+/**
+ * Main entry point that initializes and starts the MCP server.
+ * Accepts an optional workdir argument from the command line.
+ */
 async function main() {
     // Parse command-line arguments to get optional default workdir
     // Usage: node dist/index.js [workdir]

package/dist/server.js

@@ -37,10 +37,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Server = void 0;
+/**
+ * MCP Server implementation for the Supermodel codebase analysis tools.
+ * Provides JSON-RPC handlers for code graph generation and exploration.
+ * @module server
+ */
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const sdk_1 = require("@supermodeltools/sdk");
 const create_supermodel_graph_1 = __importDefault(require("./tools/create-supermodel-graph"));
+const graph_tools_1 = require("./tools/graph-tools");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const zip_repository_1 = require("./utils/zip-repository");
 const undici_1 = require("undici");
@@ -77,53 +83,32 @@ class Server {
             version: '0.0.1',
         }, {
             capabilities: { tools: {}, logging: {} },
-            instructions: `# Server Instructions: Supermodel Codebase Explorer
+            instructions: `# Supermodel: Code Graph Tools
 
-## Graph Rules
-- This API produces graphs of the code contained within a target directory.
-- STRATEGY: Before debugging, planning, or analyzing a change to a code repository, generate a code graph. Use it to localize changes and find what files to search more efficiently than grep.
+Generate code graphs to understand a codebase before making changes.
 
-## Debugging Strategy
-1. Generate a code graph of the given repository or a subset.
-2. Analyze the nodes and relationships which appear to be related to your issue.
-3. Analyze the broader context of these nodes in relationships within their domain and subdomain.
-4. Use the graph like a diagram to navigate the codebase more efficiently than raw grep and to analyze the potential blast radius of any change.
-  
-## Planning Strategy
-1. Generate a code graph of the given repository or a subset.
-2. Analyze relationships like dependencies, calls, and inheritance to identify the potential blast radius of a proposed change.
-3. Examine other elements of the same Domain and Subdomain to look for patterns including best practices or anti-patterns.
-4. Look at the nodes you plan to change and find their physical locations, allowing you to analyze more efficiently than blind grepping.
+## Recommended Workflow
 
-## Analysis Strategy
-1. Generate a code graph of the given repository or a subset.
-2. Analyze the system domains to understand the high-level system architecture.
-3. Examine leaf nodes to see the structure of the broader tree.
-4. Use the graph like a map to navigate the codebase more efficiently than blind grepping.
+1. Start with \`get_domain_graph\` to understand architecture
+2. Use \`get_call_graph\` or \`get_dependency_graph\` to drill into specific areas
+3. Use \`get_parse_graph\` only when you need full structural detail
 
-## Performance Optimization
+Node IDs are consistent across all graph types. A function ID from \`get_domain_graph\` can be looked up in \`get_call_graph\` results to find its callers.
 
-For localized bugs:
-1. Identify the affected subsystem from the issue description
-2. Analyze only that subdirectory (e.g., \`django/db\` instead of full repo)
-3. This is faster, uses less memory, and avoids ZIP size limits
+## Performance
 
-Example:
-- Full repo: directory="/repo" → 180MB, 50k nodes
-- Subsystem: directory="/repo/django/db" → 15MB, 3k nodes
+- First call takes 30+ seconds (API processing time)
+- Analyze subdirectories for faster results: \`src/auth\` instead of full repo
+- Use \`jq_filter\` to extract only the data you need
 
-## Error Handling
+## explore_codebase
 
-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
+Returns the complete graph with all data combined. Useful for comprehensive exports or integration with external tools. For iterative analysis, prefer the individual graph tools above.
 
-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
+## Errors
 
-This helps the maintainers fix bugs faster and avoids wasting your iteration budget on issues you cannot work around locally.`,
+- \`error.recoverable: true\` → retry after brief wait
+- \`error.reportable: true\` → server bug, can be reported`,
         });
         const config = new sdk_1.Configuration({
             basePath: process.env.SUPERMODEL_BASE_URL || 'https://api.supermodeltools.com',
@@ -143,15 +128,29 @@ This helps the maintainers fix bugs faster and avoids wasting your iteration bud
         this.setupHandlers();
     }
     setupHandlers() {
+        // Collect all tools: the main explore_codebase tool plus individual graph tools
+        const allTools = [
+            create_supermodel_graph_1.default,
+            ...graph_tools_1.graphTools,
+        ];
+        // Create a map for quick handler lookup, checking for duplicates
+        const toolMap = new Map();
+        for (const t of allTools) {
+            if (toolMap.has(t.tool.name)) {
+                throw new Error(`Duplicate tool name: ${t.tool.name}`);
+            }
+            toolMap.set(t.tool.name, t);
+        }
         this.server.server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
             return {
-                tools: [create_supermodel_graph_1.default.tool],
+                tools: allTools.map(t => t.tool),
             };
         });
         this.server.server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             const { name, arguments: args } = request.params;
-            if (name === create_supermodel_graph_1.default.tool.name) {
-                return create_supermodel_graph_1.default.handler(this.client, args, this.defaultWorkdir);
+            const tool = toolMap.get(name);
+            if (tool) {
+                return tool.handler(this.client, args, this.defaultWorkdir);
             }
             throw new Error(`Unknown tool: ${name}`);
         });

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

@@ -34,18 +34,15 @@ 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");
+const buffer_1 = require("buffer");
 const path_1 = require("path");
 const types_1 = require("../types");
 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.';
+const api_helpers_1 = require("../utils/api-helpers");
 exports.metadata = {
     resource: 'graphs',
     operation: 'write',
@@ -202,49 +199,13 @@ Query types available: graph_status, summary, get_node, search, list_nodes, func
         required: [],
     },
 };
-/**
- * Generate an idempotency key in format {repo}-{pathHash}:supermodel:{hash}
- * Includes path hash to prevent collisions between same-named repos
- */
-function generateIdempotencyKey(directory) {
-    const repoName = (0, path_1.basename)(directory);
-    const absolutePath = (0, path_1.resolve)(directory);
-    // Always include path hash to prevent collisions
-    const pathHash = (0, crypto_1.createHash)('sha1').update(absolutePath).digest('hex').substring(0, 7);
-    let hash;
-    let statusHash = '';
-    try {
-        // Get git commit hash
-        hash = (0, child_process_1.execSync)('git rev-parse --short HEAD', {
-            cwd: directory,
-            encoding: 'utf-8',
-        }).trim();
-        // Include working tree status in hash to detect uncommitted changes
-        const statusOutput = (0, child_process_1.execSync)('git status --porcelain', {
-            cwd: directory,
-            encoding: 'utf-8',
-        }).toString();
-        if (statusOutput) {
-            // Create hash of status output
-            statusHash = '-' + (0, crypto_1.createHash)('sha1')
-                .update(statusOutput)
-                .digest('hex')
-                .substring(0, 7);
-        }
-    }
-    catch {
-        // Fallback for non-git directories: use path hash as main identifier
-        hash = pathHash;
-    }
-    return `${repoName}-${pathHash}:supermodel:${hash}${statusHash}`;
-}
 const handler = async (client, args, defaultWorkdir) => {
     if (!args) {
         args = {};
     }
     const { jq_filter, directory: providedDirectory, query, targetId, searchText, namePattern, filePathPrefix, labels, depth, relationshipTypes, limit, includeRaw, } = args;
     // Use provided directory or fall back to default workdir
-    const directory = providedDirectory || defaultWorkdir;
+    const directory = providedDirectory ?? defaultWorkdir;
     // Validate directory - check if explicitly invalid first
     if (providedDirectory !== undefined && typeof providedDirectory !== 'string') {
         logger.error('Invalid directory parameter:', providedDirectory);
@@ -274,7 +235,7 @@ const handler = async (client, args, defaultWorkdir) => {
         logger.debug('Using default workdir:', directory);
     }
     // Generate idempotency key for API request
-    const idempotencyKey = generateIdempotencyKey(directory);
+    const idempotencyKey = (0, api_helpers_1.generateIdempotencyKey)(directory);
     logger.debug('Auto-generated idempotency key:', idempotencyKey);
     // Check if we can skip zipping (graph already cached)
     // Use get() atomically to avoid TOCTOU race condition
@@ -308,7 +269,7 @@ const handler = async (client, args, defaultWorkdir) => {
         const zipResult = await (0, zip_repository_1.zipRepository)(directory);
         zipPath = zipResult.path;
         cleanup = zipResult.cleanup;
-        logger.debug('Auto-zip complete:', zipResult.fileCount, 'files,', formatBytes(zipResult.sizeBytes));
+        logger.debug('Auto-zip complete:', zipResult.fileCount, 'files,', (0, api_helpers_1.formatBytes)(zipResult.sizeBytes));
     }
     catch (error) {
         // Log full error details for debugging
@@ -366,8 +327,8 @@ const handler = async (client, args, defaultWorkdir) => {
             code: 'ZIP_CREATION_FAILED',
             recoverable: false,
             reportable: true,
-            repo: REPORT_REPO,
-            suggestion: REPORT_SUGGESTION,
+            repo: api_helpers_1.REPORT_REPO,
+            suggestion: api_helpers_1.REPORT_SUGGESTION,
             details: { directory: (0, path_1.basename)(directory), errorType: error.name || 'Error' },
         });
     }
@@ -406,18 +367,6 @@ const handler = async (client, args, defaultWorkdir) => {
     }
 };
 exports.handler = handler;
-/**
- * Format bytes as human-readable string
- */
-function formatBytes(bytes) {
-    if (bytes < 1024)
-        return `${bytes} B`;
-    if (bytes < 1024 * 1024)
-        return `${(bytes / 1024).toFixed(2)} KB`;
-    if (bytes < 1024 * 1024 * 1024)
-        return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
-    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
-}
 /**
  * Handle query-based requests when graph is already cached
  * Uses the cached graph directly to avoid TOCTOU issues
@@ -484,7 +433,7 @@ async function handleQueryMode(client, params) {
         }
         catch (error) {
             // Error details are already logged by fetchFromApi and logErrorResponse
-            return (0, types_1.asErrorResult)(classifyApiError(error));
+            return (0, types_1.asErrorResult)((0, api_helpers_1.classifyApiError)(error));
         }
     }
     // Handle query errors
@@ -581,7 +530,7 @@ function logRequest(url, method, bodySize, idempotencyKey) {
     logger.debug(`  Method: ${method}`);
     logger.debug(`  URL: ${url}`);
     logger.debug(`  Idempotency-Key: ${idempotencyKey}`);
-    logger.debug(`  Body size: ${formatBytes(bodySize)}`);
+    logger.debug(`  Body size: ${(0, api_helpers_1.formatBytes)(bodySize)}`);
     logger.debug(`  Content-Type: multipart/form-data`);
 }
 /**
@@ -590,7 +539,7 @@ function logRequest(url, method, bodySize, idempotencyKey) {
 function logResponse(status, statusText, responseSize, duration) {
     logger.debug(`[${getTimestamp()}] [API RESPONSE]`);
     logger.debug(`  Status: ${status} ${statusText}`);
-    logger.debug(`  Response size: ${formatBytes(responseSize)}`);
+    logger.debug(`  Response size: ${(0, api_helpers_1.formatBytes)(responseSize)}`);
     logger.debug(`  Duration: ${duration}ms`);
 }
 /**
@@ -653,9 +602,9 @@ async function fetchFromApi(client, file, idempotencyKey) {
     const startTime = Date.now();
     logger.debug('Reading file:', file);
     const fileBuffer = await (0, promises_1.readFile)(file);
-    const fileBlob = new Blob([fileBuffer], { type: 'application/zip' });
+    const fileBlob = new buffer_1.Blob([fileBuffer], { type: 'application/zip' });
     const fileSize = fileBuffer.length;
-    logger.debug('File size:', formatBytes(fileSize));
+    logger.debug('File size:', (0, api_helpers_1.formatBytes)(fileSize));
     // Get the base URL from environment or use default
     const baseUrl = process.env.SUPERMODEL_BASE_URL || 'https://api.supermodeltools.com';
     const apiUrl = `${baseUrl}/v1/graphs/supermodel`;
@@ -716,128 +665,6 @@ async function fetchFromApi(client, file, idempotencyKey) {
         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
  */
@@ -858,7 +685,7 @@ async function handleLegacyMode(client, file, idempotencyKey, jq_filter) {
             });
         }
         // Error details are already logged by fetchFromApi and logErrorResponse
-        return (0, types_1.asErrorResult)(classifyApiError(error));
+        return (0, types_1.asErrorResult)((0, api_helpers_1.classifyApiError)(error));
     }
 }
 exports.default = { metadata: exports.metadata, tool: exports.tool, handler: exports.handler };

package/dist/tools/graph-tools.js

@@ -0,0 +1,277 @@
+"use strict";
+/**
+ * Individual graph type tools for targeted codebase analysis.
+ * Each tool calls a specific graph API endpoint for focused results.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.graphTools = exports.parseGraphTool = exports.domainGraphTool = exports.dependencyGraphTool = exports.callGraphTool = void 0;
+const promises_1 = require("fs/promises");
+const buffer_1 = require("buffer");
+const types_1 = require("../types");
+const filtering_1 = require("../filtering");
+const zip_repository_1 = require("../utils/zip-repository");
+const logger = __importStar(require("../utils/logger"));
+const api_helpers_1 = require("../utils/api-helpers");
+const GRAPH_TYPES = [
+    {
+        name: 'call',
+        toolName: 'get_call_graph',
+        description: `Generate a call graph showing function-to-function call relationships.
+
+Returns: Function nodes with "calls" relationships between them.
+
+Use this to:
+- Find all callers of a specific function
+- Find all functions called by a specific function
+- Trace execution flow through the codebase
+- Debug by following call chains
+
+Best for: Debugging, understanding "what calls what", tracing execution paths.`,
+        endpoint: '/v1/graphs/call',
+        operationId: 'generateCallGraph',
+        apiMethod: 'generateCallGraph',
+    },
+    {
+        name: 'dependency',
+        toolName: 'get_dependency_graph',
+        description: `Generate a dependency graph showing import relationships between files.
+
+Returns: File nodes with "IMPORTS" relationships between them.
+
+Use this to:
+- Map which files import which other files
+- Find circular dependencies
+- Understand module coupling
+- Plan safe refactoring of imports
+
+Best for: Refactoring, understanding module dependencies, finding import cycles.`,
+        endpoint: '/v1/graphs/dependency',
+        operationId: 'generateDependencyGraph',
+        apiMethod: 'generateDependencyGraph',
+    },
+    {
+        name: 'domain',
+        toolName: 'get_domain_graph',
+        description: `Generate a domain classification graph showing high-level architecture.
+
+Returns: Domains with descriptions, responsibilities, subdomains, and file/function/class assignments.
+
+Use this to:
+- Understand the architectural structure of a codebase
+- See how code is organized into logical domains
+- Identify domain boundaries and responsibilities
+- Get a bird's-eye view before diving into details
+
+Best for: New codebases, architecture overview, understanding system organization.`,
+        endpoint: '/v1/graphs/domain',
+        operationId: 'generateDomainGraph',
+        apiMethod: 'generateDomainGraph',
+    },
+    {
+        name: 'parse',
+        toolName: 'get_parse_graph',
+        description: `Generate a full parse graph with all code structure elements.
+
+Returns: All nodes (File, Directory, Class, Function, Type) and structural relationships (CONTAINS, DEFINES, DECLARES, IMPORTS).
+
+Use this to:
+- Get complete structural information about the codebase
+- Find all classes, functions, and types
+- Understand containment and definition relationships
+- Support detailed refactoring analysis
+
+Best for: Comprehensive analysis when you need the full code structure.`,
+        endpoint: '/v1/graphs/parse',
+        operationId: 'generateParseGraph',
+        apiMethod: 'generateParseGraph',
+    },
+];
+/**
+ * Create a tool definition and handler for a specific graph type
+ */
+function createGraphTool(config) {
+    const metadata = {
+        resource: 'graphs',
+        operation: 'write',
+        tags: [config.name],
+        httpMethod: 'post',
+        httpPath: config.endpoint,
+        operationId: config.operationId,
+    };
+    const tool = {
+        name: config.toolName,
+        description: config.description,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                directory: {
+                    type: 'string',
+                    description: 'Path to the repository directory to analyze.',
+                },
+                jq_filter: {
+                    type: 'string',
+                    title: 'jq Filter',
+                    description: 'Optional jq filter to extract specific data from the response.',
+                },
+            },
+            required: [],
+        },
+    };
+    const handler = async (client, args, defaultWorkdir) => {
+        if (!args) {
+            args = {};
+        }
+        const { jq_filter, directory: providedDirectory } = args;
+        if (providedDirectory !== undefined && typeof providedDirectory !== '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".',
+            });
+        }
+        if (jq_filter !== undefined && typeof jq_filter !== 'string') {
+            return (0, types_1.asErrorResult)({
+                type: 'validation_error',
+                message: 'Invalid "jq_filter" parameter. Provide a jq filter string.',
+                code: 'INVALID_JQ_FILTER',
+                recoverable: false,
+                suggestion: 'Pass jq_filter as a string, e.g. jq_filter=".nodes".',
+            });
+        }
+        const directory = providedDirectory ?? defaultWorkdir;
+        if (!directory || typeof directory !== 'string') {
+            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.',
+            });
+        }
+        const idempotencyKey = (0, api_helpers_1.generateIdempotencyKey)(directory, config.name);
+        logger.debug(`[${config.toolName}] Idempotency key:`, idempotencyKey);
+        // Create ZIP of repository
+        let zipPath;
+        let cleanup = null;
+        try {
+            const zipResult = await (0, zip_repository_1.zipRepository)(directory);
+            zipPath = zipResult.path;
+            cleanup = zipResult.cleanup;
+            logger.debug(`[${config.toolName}] ZIP created:`, zipResult.fileCount, 'files,', (0, api_helpers_1.formatBytes)(zipResult.sizeBytes));
+        }
+        catch (error) {
+            const message = typeof error?.message === 'string' ? error.message : String(error);
+            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.',
+                });
+            }
+            return (0, types_1.asErrorResult)({
+                type: 'internal_error',
+                message: `Failed to create ZIP archive: ${message}`,
+                code: 'ZIP_CREATION_FAILED',
+                recoverable: false,
+                reportable: true,
+                repo: api_helpers_1.REPORT_REPO,
+                suggestion: api_helpers_1.REPORT_SUGGESTION,
+            });
+        }
+        try {
+            const fileBuffer = await (0, promises_1.readFile)(zipPath);
+            const fileBlob = new buffer_1.Blob([fileBuffer], { type: 'application/zip' });
+            logger.debug(`[${config.toolName}] Calling API...`);
+            console.error(`[Supermodel] Generating ${config.name} graph...`);
+            // Call the appropriate API method via SupermodelClient
+            const apiMethod = client.graphs[config.apiMethod].bind(client.graphs);
+            const response = await apiMethod(fileBlob, { idempotencyKey });
+            console.error(`[Supermodel] ${config.name} graph complete.`);
+            // Apply optional jq filter
+            const result = await (0, filtering_1.maybeFilter)(jq_filter, response);
+            return (0, types_1.asTextContentResult)(result);
+        }
+        catch (error) {
+            if ((0, filtering_1.isJqError)(error)) {
+                logger.error(`[${config.toolName}] jq filter error:`, error.message);
+                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. Example: jq_filter=".nodes" or jq_filter=".graph.nodeCount"',
+                });
+            }
+            logger.error(`[${config.toolName}] API error:`, error.message);
+            return (0, types_1.asErrorResult)((0, api_helpers_1.classifyApiError)(error));
+        }
+        finally {
+            if (cleanup) {
+                try {
+                    await cleanup();
+                }
+                catch (cleanupError) {
+                    logger.warn(`[${config.toolName}] Cleanup failed:`, cleanupError);
+                }
+            }
+        }
+    };
+    return { metadata, tool, handler };
+}
+// Helper to find graph type by name (safer than array indexing)
+function getGraphType(name) {
+    const config = GRAPH_TYPES.find(t => t.name === name);
+    if (!config) {
+        throw new Error(`Unknown graph type: ${name}`);
+    }
+    return config;
+}
+// Create all graph tools
+exports.callGraphTool = createGraphTool(getGraphType('call'));
+exports.dependencyGraphTool = createGraphTool(getGraphType('dependency'));
+exports.domainGraphTool = createGraphTool(getGraphType('domain'));
+exports.parseGraphTool = createGraphTool(getGraphType('parse'));
+// Export all tools as an array for easy registration
+exports.graphTools = [
+    exports.callGraphTool,
+    exports.dependencyGraphTool,
+    exports.domainGraphTool,
+    exports.parseGraphTool,
+];

package/dist/utils/api-helpers.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * Shared utilities for API operations across graph tools.
+ * Extracted to eliminate code duplication between graph-tools.ts and create-supermodel-graph.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPORT_SUGGESTION = exports.REPORT_REPO = void 0;
+exports.formatBytes = formatBytes;
+exports.generateIdempotencyKey = generateIdempotencyKey;
+exports.classifyApiError = classifyApiError;
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const path_1 = require("path");
+exports.REPORT_REPO = 'https://github.com/supermodeltools/mcp.git';
+exports.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.';
+/**
+ * Format bytes as human-readable string
+ */
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(2)} KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+/**
+ * Generate an idempotency key in format {repo}-{pathHash}:{graphType}:{hash}
+ * Includes path hash to prevent collisions between same-named repos
+ */
+function generateIdempotencyKey(directory, graphType = 'supermodel') {
+    const repoName = (0, path_1.basename)(directory);
+    const absolutePath = (0, path_1.resolve)(directory);
+    // Always include path hash to prevent collisions
+    const pathHash = (0, crypto_1.createHash)('sha1').update(absolutePath).digest('hex').substring(0, 7);
+    let hash;
+    let statusHash = '';
+    try {
+        // Get git commit hash
+        hash = (0, child_process_1.execSync)('git rev-parse --short HEAD', {
+            cwd: directory,
+            encoding: 'utf-8',
+        }).trim();
+        // Include working tree status in hash to detect uncommitted changes
+        const statusOutput = (0, child_process_1.execSync)('git status --porcelain', {
+            cwd: directory,
+            encoding: 'utf-8',
+        }).toString();
+        if (statusOutput) {
+            // Create hash of status output
+            statusHash = '-' + (0, crypto_1.createHash)('sha1')
+                .update(statusOutput)
+                .digest('hex')
+                .substring(0, 7);
+        }
+    }
+    catch {
+        // Fallback for non-git directories: use path hash as main identifier
+        hash = pathHash;
+    }
+    return `${repoName}-${pathHash}:${graphType}:${hash}${statusHash}`;
+}
+/**
+ * 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: exports.REPORT_REPO,
+            suggestion: exports.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: exports.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: exports.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: exports.REPORT_REPO,
+        suggestion: exports.REPORT_SUGGESTION,
+        details: { errorType: error.name || 'Error' },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supermodeltools/mcp-server",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "MCP server for Supermodel API - code graph generation for AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -38,7 +38,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.1",
-    "@supermodeltools/sdk": "0.6.4",
+    "@supermodeltools/sdk": "0.7.0",
     "archiver": "^7.0.1",
     "ignore": "^7.0.5",
     "jq-web": "^0.6.2",