{"id":35432396,"url":"https://github.com/supermodeltools/mcp","last_synced_at":"2026-04-22T16:01:39.524Z","repository":{"id":331480765,"uuid":"1122416397","full_name":"supermodeltools/mcp","owner":"supermodeltools","description":"Supermodel Model Context Protocol server. Generate code graphs in Cursor, Codex or Claude Code!","archived":false,"fork":false,"pushed_at":"2026-03-20T00:11:21.000Z","size":9416,"stargazers_count":7,"open_issues_count":10,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-20T15:31:24.373Z","etag":null,"topics":["ai-agent","architecture","architecture-docs","claude","code-analysis","code-graph","codex","cursor","mcp","mcp-server","model-context-protocol","supermodel"],"latest_commit_sha":null,"homepage":"https://repos.supermodeltools.com/mcp/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/supermodeltools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-24T17:18:06.000Z","updated_at":"2026-03-20T00:11:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/supermodeltools/mcp","commit_stats":null,"previous_names":["supermodeltools/mcp"],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/supermodeltools/mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermodeltools%2Fmcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermodeltools%2Fmcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermodeltools%2Fmcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermodeltools%2Fmcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/supermodeltools","download_url":"https://codeload.github.com/supermodeltools/mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermodeltools%2Fmcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30847059,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-23T01:54:41.487Z","status":"online","status_checked_at":"2026-03-23T02:00:09.028Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","architecture","architecture-docs","claude","code-analysis","code-graph","codex","cursor","mcp","mcp-server","model-context-protocol","supermodel"],"created_at":"2026-01-02T21:09:43.139Z","updated_at":"2026-04-02T14:13:18.524Z","avatar_url":"https://github.com/supermodeltools.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Supermodel MCP Server\n\n[![npm](https://img.shields.io/npm/v/@supermodeltools/mcp-server)](https://www.npmjs.com/package/@supermodeltools/mcp-server)\n[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)\n[![CI](https://github.com/supermodeltools/mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/supermodeltools/mcp/actions/workflows/ci.yml)\n\nMCP server that gives AI agents instant codebase understanding via the [Supermodel API](https://docs.supermodeltools.com). Pre-computed code graphs enable sub-second responses for symbol lookups, call-graph traversal, and cross-subsystem analysis.\n\n---\n\n## ⭐ Star the Supermodel Ecosystem\n\nIf this is useful, please star our tools — it helps us grow:\n\n[![mcp](https://img.shields.io/github/stars/supermodeltools/mcp?style=social)](https://github.com/supermodeltools/mcp) \u0026nbsp;[![mcpbr](https://img.shields.io/github/stars/supermodeltools/mcpbr?style=social)](https://github.com/supermodeltools/mcpbr) \u0026nbsp;[![typescript-sdk](https://img.shields.io/github/stars/supermodeltools/typescript-sdk?style=social)](https://github.com/supermodeltools/typescript-sdk) \u0026nbsp;[![arch-docs](https://img.shields.io/github/stars/supermodeltools/arch-docs?style=social)](https://github.com/supermodeltools/arch-docs) \u0026nbsp;[![dead-code-hunter](https://img.shields.io/github/stars/supermodeltools/dead-code-hunter?style=social)](https://github.com/supermodeltools/dead-code-hunter) \u0026nbsp;[![Uncompact](https://img.shields.io/github/stars/supermodeltools/Uncompact?style=social)](https://github.com/supermodeltools/Uncompact) \u0026nbsp;[![narsil-mcp](https://img.shields.io/github/stars/supermodeltools/narsil-mcp?style=social)](https://github.com/supermodeltools/narsil-mcp)\n\n---\n\n## Install\n\n### Quick Setup (Recommended)\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/supermodeltools/mcp/main/setup.sh | bash\n```\n\n\u003cdetails\u003e\n\u003csummary\u003ePrefer to inspect before running? (Click to expand)\u003c/summary\u003e\n\nDownload, review, then execute:\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/supermodeltools/mcp/main/setup.sh -o setup.sh\ncat setup.sh\nchmod +x setup.sh\n./setup.sh\n```\n\nOr clone the entire repo:\n\n```bash\ngit clone https://github.com/supermodeltools/mcp.git\ncd mcp\n./setup.sh\n```\n\n\u003c/details\u003e\n\n### Manual Install\n\n```bash\nnpm install -g @supermodeltools/mcp-server\n```\n\nOr run directly:\n\n```bash\nnpx @supermodeltools/mcp-server\n```\n\n## Configuration\n\nGet your API key from the [Supermodel Dashboard](https://dashboard.supermodeltools.com).\n\n| Variable | Description |\n|----------|-------------|\n| `SUPERMODEL_API_KEY` | Your Supermodel API key (required) |\n| `SUPERMODEL_BASE_URL` | Override API base URL (optional) |\n| `SUPERMODEL_CACHE_DIR` | Directory for pre-computed graph cache files (optional) |\n| `SUPERMODEL_TIMEOUT_MS` | API request timeout in ms (default: 900000 / 15 min) |\n| `SUPERMODEL_NO_API_FALLBACK` | Set to disable on-demand API calls; cache-only mode (optional) |\n| `SUPERMODEL_EXPERIMENT` | Experiment mode. Set to `graphrag` to enable GraphRAG tools (optional) |\n\n### Global Setup (Recommended)\n\nSet your API key globally in your shell profile so it's available to all MCP clients:\n\n```bash\n# Add to ~/.zshrc (macOS) or ~/.bashrc (Linux)\nexport SUPERMODEL_API_KEY=\"your-api-key\"\n```\n\nWith the API key set globally, you can omit the `env` block from your MCP configs:\n\n```json\n{\n  \"mcpServers\": {\n    \"supermodel\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@supermodeltools/mcp-server\"]\n    }\n  }\n}\n```\n\n## Usage\n\n### Claude Code CLI\n\n```bash\nclaude mcp add supermodel --env SUPERMODEL_API_KEY=your-api-key -- npx -y @supermodeltools/mcp-server\n```\n\nOr if `SUPERMODEL_API_KEY` is already set in your shell environment:\n\n```bash\nclaude mcp add supermodel -- npx -y @supermodeltools/mcp-server\n```\n\nVerify installation:\n\n```bash\nclaude mcp list\n```\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"supermodel\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@supermodeltools/mcp-server\"],\n      \"env\": {\n        \"SUPERMODEL_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n### Default Working Directory\n\nFor benchmarking tools or batch processing, pass a default working directory as a CLI argument:\n\n```bash\nnpx @supermodeltools/mcp-server /path/to/repository\n```\n\nTools will use this directory automatically if no explicit `directory` parameter is given.\n\n## Tools\n\n### `symbol_context` (Default Mode)\n\nDeep dive on a specific function, class, or method. Given a symbol name, instantly returns its definition location, source code, all callers, all callees, domain membership, and related symbols in the same file.\n\n**Output includes:**\n- Definition location (file, line range) and source code\n- Callers (who calls this symbol)\n- Callees (what this symbol calls)\n- Architectural domain membership\n- Related symbols in the same file\n- File import statistics\n\n**Parameters:**\n\n| Argument | Type | Required | Description |\n|----------|------|----------|-------------|\n| `symbol` | string | No* | Name of the function, class, or method. Supports `ClassName.method` syntax and partial matching. |\n| `symbols` | string[] | No* | Array of symbol names for batch lookup. More efficient than multiple calls. |\n| `directory` | string | No | Path to repository directory. Omit if server was started with a default workdir. |\n| `brief` | boolean | No | Return compact output (no source code). Recommended for 3+ symbols. |\n\n\\* Either `symbol` or `symbols` must be provided.\n\n**Example prompts:**\n- \"Look up the symbol `filter_queryset` in this codebase\"\n- \"What calls `QuerySet.filter` and what does it call?\"\n\n### GraphRAG Mode (Experimental)\n\nActivate with `SUPERMODEL_EXPERIMENT=graphrag`. Replaces `symbol_context` with a graph-oriented tool for call-graph traversal and cross-subsystem analysis.\n\n#### `explore_function`\n\nBFS traversal of a function, class, or method call graph. Shows source code, callers, callees, and cross-subsystem boundaries with `← DIFFERENT SUBSYSTEM` markers.\n\n**Parameters:**\n\n| Argument | Type | Required | Description |\n|----------|------|----------|-------------|\n| `symbol` | string | Yes | Function, class, or method name to explore. Supports partial matching and `ClassName.method` syntax. |\n| `direction` | string | No | `downstream` (callees), `upstream` (callers), or `both` (default). |\n| `depth` | number | No | Hops to follow: 1–3 (default: 2). |\n| `directory` | string | No | Repository path. |\n\n**Output:** Readable narrative showing upstream/downstream neighbors with domain context at each hop.\n\n### Recommended Workflow\n\n**Default mode:**\n1. Identify symbols from the issue and call `symbol_context` to explore them (batch via `symbols` array or parallel calls)\n2. Use Read/Grep to examine source code at identified locations\n3. Start editing by turn 3. Max 3 MCP calls total.\n\n**GraphRAG mode:**\n1. Identify key symbols from the issue, call `explore_function` to understand their call-graph context. Issue multiple calls in parallel (read-only, safe).\n2. Use the cross-subsystem markers and source code from the response to start editing. Max 2 MCP calls total.\n\n## Pre-computed Graphs\n\nFor fastest performance, pre-compute graphs ahead of time using the `precache` CLI subcommand. This calls the Supermodel API once and saves the result to disk, enabling sub-second tool responses with no API calls at runtime.\n\n### Pre-compute a graph\n\n```bash\nnpx @supermodeltools/mcp-server precache /path/to/repo --output-dir ./supermodel-cache\n```\n\nOptions:\n- `--output-dir \u003cdir\u003e` — Directory to save the cache file (default: `./supermodel-cache` or `SUPERMODEL_CACHE_DIR`)\n- `--name \u003cname\u003e` — Repository name for the cache key (default: auto-detected from git remote + commit hash)\n\n### Use cached graphs at runtime\n\n```bash\nSUPERMODEL_CACHE_DIR=./supermodel-cache npx @supermodeltools/mcp-server\n```\n\nThe server loads all cached graphs from `SUPERMODEL_CACHE_DIR` at startup. If no cache exists for a given repository, the server falls back to an on-demand API call (which takes 5-15 minutes for large repos).\n\n### Startup precaching\n\nUse the `--precache` flag to automatically generate and cache the graph for the default workdir on server startup:\n\n```bash\nnpx @supermodeltools/mcp-server /path/to/repo --precache\n```\n\nThis is useful in automated environments (e.g., Docker containers for benchmarking) where you want the graph ready before any tool calls.\n\n## Benchmarking\n\nBenchmark this MCP server using [mcpbr](https://github.com/greynewell/mcpbr) with the provided [`mcpbr-config.yaml`](./mcpbr-config.yaml) configuration.\n\n## Local Development\n\n### Building from Source\n\n```bash\ngit clone https://github.com/supermodeltools/mcp.git\ncd mcp\nnpm install\nnpm run build\n```\n\n### Running Locally\n\n```bash\nnode dist/index.js                    # Start MCP server\nnode dist/index.js /path/to/repo      # With default workdir\nnode dist/index.js precache /path/to/repo  # Pre-compute graph\n```\n\n### Running Tests\n\n```bash\nnpm test              # Run all tests\nnpm run test:coverage # Run with coverage\nnpm run typecheck     # Type checking\n```\n\n### Using MCP Inspector\n\nFor interactive testing, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):\n\n```bash\nnpx @modelcontextprotocol/inspector node dist/index.js\n```\n\n## Troubleshooting\n\n### Timeout Errors\n\nThe first analysis of a repository requires an API call that can take 5-15 minutes. If your MCP client times out:\n\n1. **Pre-compute the graph** — Use `precache` to generate the graph ahead of time (see [Pre-computed Graphs](#pre-computed-graphs))\n2. **Increase your MCP client timeout** — For Claude Code CLI, set `MCP_TOOL_TIMEOUT=900000` in your shell profile\n3. **Analyze a subdirectory** — Target specific parts of your codebase to reduce analysis time\n\n### Common Issues\n\n- **401 Unauthorized:** Check `SUPERMODEL_API_KEY` is set correctly\n- **Permission denied:** Check read permissions on the directory\n- **ENOTFOUND or connection errors:** Check your internet connection and firewall settings\n\n### Debug Logging\n\nSet the `DEBUG` environment variable for verbose logging:\n\n```json\n{\n  \"mcpServers\": {\n    \"supermodel\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@supermodeltools/mcp-server\"],\n      \"env\": {\n        \"SUPERMODEL_API_KEY\": \"your-api-key\",\n        \"DEBUG\": \"supermodel:*\"\n      }\n    }\n  }\n}\n```\n\n## Blog\n\n- [Why Code Graphs Matter for AI Agents](https://greynewell.com/blog/why-code-graphs-matter/)\n- [The Architecture of Supermodel's Code Graph API](https://greynewell.com/blog/supermodel-code-graph-api-architecture/)\n- [Building Uncompact: Lessons from Production](https://greynewell.com/blog/building-uncompact-lessons-from-production/)\n\n## Links\n\n- [API Documentation](https://docs.supermodeltools.com)\n- [Supermodel SDK](https://www.npmjs.com/package/@supermodeltools/sdk)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupermodeltools%2Fmcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupermodeltools%2Fmcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupermodeltools%2Fmcp/lists"}