@supermodeltools/mcp-server 0.4.0

package/README.md

@@ -0,0 +1,109 @@
+# Supermodel MCP Server
+
+[![npm](https://img.shields.io/npm/v/@supermodeltools/mcp-server)](https://www.npmjs.com/package/@supermodeltools/mcp-server)
+[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
+
+MCP server that exposes [Supermodel API](https://docs.supermodeltools.com) graph generation to AI agents. Generates dependency graphs, call graphs, domain models, and full Supermodel IR from code repositories.
+
+## Install
+
+```bash
+npm install -g @supermodeltools/mcp-server
+```
+
+Or run directly:
+
+```bash
+npx @supermodeltools/mcp-server
+```
+
+## Configuration
+
+Get your API key from the [Supermodel Dashboard](https://supermodeltools.com/dashboard).
+
+| Variable | Description |
+|----------|-------------|
+| `SUPERMODEL_API_KEY` | Your Supermodel API key (required) |
+| `SUPERMODEL_BASE_URL` | Override API base URL (optional) |
+
+## Usage
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "supermodel": {
+      "command": "npx",
+      "args": ["-y", "@supermodeltools/mcp-server"],
+      "env": {
+        "SUPERMODEL_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### 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
+
+```bash
+claude mcp add supermodel -- npx -y @supermodeltools/mcp-server
+```
+
+## Tools
+
+### `create_supermodel_graph_graphs`
+
+Generates Supermodel IR from a zipped repository.
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `file` | string | Path to repository ZIP file |
+| `Idempotency-Key` | string | Unique request key for caching |
+| `jq_filter` | string | Optional jq filter to reduce response size |
+
+**Prepare your repo:**
+
+```bash
+git archive -o /tmp/repo.zip HEAD
+```
+
+**Example prompt:**
+> Generate a supermodel graph for `/tmp/repo.zip`
+
+## Troubleshooting
+
+Debug logs go to stderr:
+
+- `[DEBUG] Server configuration:` - Startup config
+- `[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: Exclude node_modules/dist (use `git archive`)
+
+## Links
+
+- [API Documentation](https://docs.supermodeltools.com)
+- [Supermodel SDK](https://www.npmjs.com/package/@supermodeltools/sdk)

package/dist/filtering.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maybeFilter = maybeFilter;
+exports.isJqError = isJqError;
+// @ts-nocheck
+const jq_web_1 = __importDefault(require("jq-web"));
+async function maybeFilter(jqFilter, response) {
+    if (jqFilter && typeof jqFilter === 'string') {
+        return await jq(response, jqFilter);
+    }
+    else {
+        return response;
+    }
+}
+async function jq(json, jqFilter) {
+    return (await jq_web_1.default).json(json, jqFilter);
+}
+function isJqError(error) {
+    return error instanceof Error && 'stderr' in error;
+}

package/dist/index.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const server_1 = require("./server");
+async function main() {
+    const server = new server_1.Server();
+    await server.start();
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/server.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Server = void 0;
+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 types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+class Server {
+    server;
+    client;
+    constructor() {
+        this.server = new mcp_js_1.McpServer({
+            name: 'supermodel_api',
+            version: '0.0.1',
+        }, {
+            capabilities: { tools: {}, logging: {} },
+            instructions: 'This MCP server provides tools for analyzing code repositories. Before using the graph generation tools, follow these instructions.\n\nPREPARING REPOSITORY ZIP FILES:\nAll graph generation tools require a ZIP archive of your repository.\n\nFor Git Repositories (Recommended):\nRun: cd /path/to/your/repo && git archive -o /tmp/repo.zip HEAD\nThis method automatically respects .gitignore, only includes tracked files, creates cleaner smaller archives, and produces reproducible results.\n\nFor Any Directory:\nRun: cd /path/to/your/repo && zip -r /tmp/repo.zip . -x "node_modules/*" -x ".git/*" -x "dist/*" -x "build/*" -x "target/*" -x "*.pyc" -x "__pycache__/*" -x "venv/*" -x ".venv/*" -x "vendor/*" -x ".idea/*" -x ".vscode/*"\n\nINCLUDE: Source code files (.py, .js, .ts, .tsx, .java, .go, .rs, .rb, .kt, .scala, .c, .cpp, .h, .hpp), configuration files (package.json, tsconfig.json, pyproject.toml, Cargo.toml, go.mod, pom.xml), and type definitions (.d.ts, .pyi).\n\nEXCLUDE: Dependencies (node_modules/, vendor/, venv/, .venv/, target/), build outputs (dist/, build/, out/, .next/, __pycache__/), version control (.git/), IDE files (.idea/, .vscode/), and large binaries/images/datasets.\n\nIf ZIP exceeds 50MB, ensure dependencies are excluded, consider analyzing a subdirectory, or check for accidentally committed binary files.\n\nGRAPH CACHING STRATEGY:\nGraph generation is expensive. NEVER re-upload the same repository state twice.\n\nIdempotency Keys: Every graph tool requires an Idempotency-Key parameter. Use format: {repo_identifier}:{graph_type}:{content_hash} Example: myproject:supermodel:abc123def\n\nGenerate content hash via: git rev-parse --short HEAD (for git repos) or shasum -a 256 /tmp/repo.zip | cut -d\' \' -f1 | head -c 12 (for ZIP hash).\n\nREGENERATE when: source code files changed, new files added affecting analysis scope, files deleted from graph, or dependencies changed (for dependency graph only).\n\nDO NOT regenerate when: only documentation/comments changed, only formatting changed, only non-code files changed, or switching between analysis tasks on same code state.\n\nSESSION MANAGEMENT:\nWithin a session: keep graph results in memory/context, reference previous results instead of re-calling APIs, use jq_filter to extract specific parts.\n\nAcross sessions: store the idempotency key used, store a summary of the graph (node count, key relationships), on resume check if code state matches before regenerating.\n\nGRAPH TYPE SELECTION:\ncreate_supermodel_graph_graphs - Best for comprehensive analysis, includes all graph types. Use jq_filter to extract specific data.\ncreate_call_graph_graphs - Function-level call relationships. Invalidate when function signatures change.\ncreate_dependency_graph_graphs - Module/package dependencies. Invalidate when imports or package manifests change.\ncreate_domain_graph_graphs - High-level domain model. Most stable, only invalidate for structural changes.\ncreate_parse_graph_graphs - AST-level relationships. Most sensitive, invalidate for any syntax changes.\n\nOPTIMIZATION: Call create_supermodel_graph_graphs ONCE (includes all types), use jq_filter to extract needed data, track last idempotency key, last commit/ZIP hash, generation timestamp, and summary stats.\n\nEXAMPLE WORKFLOW:\n1. Create ZIP: git archive -o /tmp/repo.zip HEAD\n2. Get hash: git rev-parse --short HEAD (e.g. abc123)\n3. Call create_supermodel_graph_graphs with file=/tmp/repo.zip and Idempotency-Key=myproject:supermodel:abc123\n4. Store result. Later queries use same key or extract from cached result.\n5. After code changes, check new hash. If different, regenerate with new key. If same, use cached result.',
+        });
+        const config = new sdk_1.Configuration({
+            basePath: process.env.SUPERMODEL_BASE_URL || 'https://api.supermodeltools.com',
+            apiKey: process.env.SUPERMODEL_API_KEY,
+        });
+        console.error('[DEBUG] Server configuration:');
+        console.error('[DEBUG] Base URL:', config.basePath);
+        console.error('[DEBUG] API Key set:', !!process.env.SUPERMODEL_API_KEY);
+        this.client = {
+            graphs: new sdk_1.DefaultApi(config),
+        };
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        this.server.server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+            return {
+                tools: [create_supermodel_graph_1.default.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);
+            }
+            throw new Error(`Unknown tool: ${name}`);
+        });
+    }
+    async start() {
+        const transport = new stdio_js_1.StdioServerTransport();
+        await this.server.connect(transport);
+        console.error('Supermodel MCP Server running on stdio');
+    }
+}
+exports.Server = Server;

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

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handler = exports.tool = exports.metadata = void 0;
+const promises_1 = require("fs/promises");
+const types_1 = require("../types");
+const filtering_1 = require("../filtering");
+exports.metadata = {
+    resource: 'graphs',
+    operation: 'write',
+    tags: [],
+    httpMethod: 'post',
+    httpPath: '/v1/graphs/supermodel',
+    operationId: 'generateSupermodelGraph',
+};
+exports.tool = {
+    name: 'create_supermodel_graph_graphs',
+    description: "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nUpload a zipped repository snapshot to generate the Supermodel Intermediate Representation (SIR) artifact bundle.\n\n# Response Schema\n(Refer to the schema in the existing documentation)\n",
+    inputSchema: {
+        type: 'object',
+        properties: {
+            file: {
+                type: 'string',
+                description: 'Path to the zipped repository archive containing the code to analyze.',
+            },
+            'Idempotency-Key': {
+                type: 'string',
+            },
+            jq_filter: {
+                type: 'string',
+                title: 'jq Filter',
+                description: 'A jq filter to apply to the response to include certain fields.',
+            },
+        },
+        required: ['file', 'Idempotency-Key'],
+    },
+};
+const handler = async (client, args) => {
+    if (!args) {
+        return (0, types_1.asErrorResult)('No arguments provided');
+    }
+    const { jq_filter, file, 'Idempotency-Key': idempotencyKey } = args;
+    if (!file || typeof file !== 'string') {
+        return (0, types_1.asErrorResult)('File argument is required and must be a string path');
+    }
+    if (!idempotencyKey || typeof idempotencyKey !== 'string') {
+        return (0, types_1.asErrorResult)('Idempotency-Key argument is required');
+    }
+    try {
+        // Read the file into a Buffer and convert to Blob
+        // The SDK expects a Blob type, not a stream
+        console.error('[DEBUG] Reading file:', file);
+        const fileBuffer = await (0, promises_1.readFile)(file);
+        // Create a Blob from the buffer
+        // In Node.js 18+, Blob is available globally
+        const fileBlob = new Blob([fileBuffer], { type: 'application/zip' });
+        console.error('[DEBUG] File size:', fileBuffer.length, 'bytes');
+        console.error('[DEBUG] Making API request with idempotency key:', idempotencyKey);
+        // Construct the request object
+        const requestParams = {
+            file: fileBlob,
+            idempotencyKey: idempotencyKey
+        };
+        const response = await client.graphs.generateSupermodelGraph(requestParams);
+        console.error('[DEBUG] API request successful');
+        return (0, types_1.asTextContentResult)(await (0, filtering_1.maybeFilter)(jq_filter, response));
+    }
+    catch (error) {
+        if ((0, filtering_1.isJqError)(error)) {
+            return (0, types_1.asErrorResult)(error.message);
+        }
+        // Enhanced error logging
+        console.error('[ERROR] API call failed:', error);
+        console.error('[ERROR] Error name:', error.name);
+        console.error('[ERROR] Error message:', error.message);
+        console.error('[ERROR] Error stack:', error.stack);
+        if (error.response) {
+            console.error('[ERROR] Response status:', error.response.status);
+            console.error('[ERROR] Response statusText:', error.response.statusText);
+            console.error('[ERROR] Response headers:', error.response.headers);
+            try {
+                const responseText = await error.response.text();
+                console.error('[ERROR] Response body:', responseText);
+            }
+            catch (e) {
+                console.error('[ERROR] Could not read response body');
+            }
+        }
+        if (error.request) {
+            console.error('[ERROR] Request was made but no response received');
+        }
+        return (0, types_1.asErrorResult)(`API call failed: ${error.message || String(error)}. Check server logs for details.`);
+    }
+};
+exports.handler = handler;
+exports.default = { metadata: exports.metadata, tool: exports.tool, handler: exports.handler };

package/dist/types.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asTextContentResult = asTextContentResult;
+exports.asErrorResult = asErrorResult;
+function asTextContentResult(result) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+            },
+        ],
+        isError: false
+    };
+}
+function asErrorResult(message) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: message,
+            },
+        ],
+        isError: true,
+    };
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@supermodeltools/mcp-server",
+  "version": "0.4.0",
+  "description": "MCP server for Supermodel API - code graph generation for AI agents",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "supermodel-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/supermodeltools/mcp.git"
+  },
+  "homepage": "https://docs.supermodeltools.com",
+  "bugs": {
+    "url": "https://github.com/supermodeltools/mcp/issues"
+  },
+  "license": "UNLICENSED",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "supermodel",
+    "ai-agent",
+    "code-analysis",
+    "cursor",
+    "claude"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "@supermodeltools/sdk": "^0.3.8",
+    "jq-web": "^0.6.2",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  }
+}