supermodeltools/mcp

# Supermodel MCP 服务器 [](https://www.npmjs.com/package/@supermodeltools/mcp-server) [](https://modelcontextprotocol.io) [](https://github.com/supermodeltools/mcp/actions/workflows/ci.yml) 通过 [Supermodel API](https://docs.supermodeltools.com) 为 AI 代理提供即时代码库理解能力的 MCP 服务器。预计算的代码图支持亚秒级响应，可用于符号查找、调用图遍历和跨子系统分析。 ## 安装 ### 快速设置（推荐） ``` curl -sSL https://raw.githubusercontent.com/supermodeltools/mcp/main/setup.sh | bash ```

想在运行前先检查代码？（点击展开）

下载、审查，然后执行： ``` curl -sSL https://raw.githubusercontent.com/supermodeltools/mcp/main/setup.sh -o setup.sh cat setup.sh chmod +x setup.sh ./setup.sh ``` 或者克隆整个代码库： ``` git clone https://github.com/supermodeltools/mcp.git cd mcp ./setup.sh ```

### 手动安装 ``` npm install -g @supermodeltools/mcp-server ``` 或者直接运行： ``` npx @supermodeltools/mcp-server ``` ## 配置 从 [Supermodel 仪表板](https://dashboard.supermodeltools.com) 获取您的 API 密钥。 | 变量 | 描述 | |----------|-------------| | `SUPERMODEL_API_KEY` | 您的 Supermodel API 密钥（必填） | | `SUPERMODEL_BASE_URL` | 覆盖 API 基础 URL（可选） | | `SUPERMODEL_CACHE_DIR` | 用于存放预计算图缓存文件的目录（可选） | | `SUPERMODEL_TIMEOUT_MS` | API 请求超时时间，以毫秒为单位（默认：900000 / 15 分钟） | | `SUPERMODEL_NO_API_FALLBACK` | 设置以禁用按需 API 调用；仅缓存模式（可选） | | `SUPERMODEL_EXPERIMENT` | 实验模式。设置为 `graphrag` 可启用 GraphRAG 工具（可选） | ### 全局设置（推荐） 在您的 shell 配置文件中全局设置您的 API 密钥，以便所有 MCP 客户端都能使用它： ``` # 添加到 ~/.zshrc (macOS) 或 ~/.bashrc (Linux) export SUPERMODEL_API_KEY="your-api-key" ``` 设置全局 API 密钥后，您可以省略 MCP 配置中的 `env` 块： ``` { "mcpServers": { "supermodel": { "command": "npx", "args": ["-y", "@supermodeltools/mcp-server"] } } } ``` ## 用法 ### Claude Code CLI ``` claude mcp add supermodel --env SUPERMODEL_API_KEY=your-api-key -- npx -y @supermodeltools/mcp-server ``` 或者，如果 `SUPERMODEL_API_KEY` 已在您的 shell 环境中设置： ``` claude mcp add supermodel -- npx -y @supermodeltools/mcp-server ``` 验证安装： ``` claude mcp list ``` ### Cursor 添加到 `~/.cursor/mcp.json`： ``` { "mcpServers": { "supermodel": { "command": "npx", "args": ["-y", "@supermodeltools/mcp-server"], "env": { "SUPERMODEL_API_KEY": "your-api-key" } } } } ``` ### 默认工作目录 对于基准测试工具或批处理，将默认工作目录作为 CLI 参数传递： ``` npx @supermodeltools/mcp-server /path/to/repository ``` 如果未给出显式的 `directory` 参数，工具将自动使用此目录。 ## 工具 ### `symbol_context`（默认模式） 深入了解特定的函数、类或方法。给定一个符号名称，立即返回其定义位置、源代码、所有调用者、所有被调用者、域成员身份以及同一文件中的相关符号。 **输出包括：** - 定义位置（文件、行范围）和源代码 - 调用者（谁调用了此符号） - 被调用者（此符号调用了什么） - 架构域成员关系 - 同一文件中的相关符号 - 文件导入统计信息 **参数：** | 参数 | 类型 | 必填 | 描述 | |----------|------|----------|-------------| | `symbol` | string | 否* | 函数、类或方法的名称。支持 `ClassName.method` 语法和部分匹配。 | | `symbols` | string[] | 否* | 用于批量查找的符号名称数组。比多次调用更高效。 | | `directory` | string | 否 | 代码库目录的路径。如果服务器启动时设置了默认工作目录，则可省略。 | | `brief` | boolean | 否 | 返回精简输出（无源代码）。建议用于 3 个或更多符号。 | \* 必须提供 `symbol` 或 `symbols` 中的至少一个。 **示例提示：** - "在此代码库中查找符号 `filter_queryset`" - "什么调用了 `QuerySet.filter`，它又调用了什么？" ### GraphRAG 模式（实验性） 通过 `SUPERMODEL_EXPERIMENT=graphrag` 激活。用面向图的工具取代 `symbol_context`，用于调用图遍历和跨子系统分析。 #### `explore_function` 对函数、类或方法调用图进行 BFS（广度优先）遍历。通过 `← DIFFERENT SUBSYSTEM` 标记显示源代码、调用者、被调用者以及跨子系统边界。 **参数：** | 参数 | 类型 | 必填 | 描述 | |----------|------|----------|-------------| | `symbol` | string | 是 | 要探索的函数、类或方法名称。支持部分匹配和 `ClassName.method` 语法。 | | `direction` | string | 否 | `downstream`（被调用者），`upstream`（调用者），或 `both`（默认）。 | | `depth` | number | 否 | 要跟踪的跳数：1–3（默认：2）。 | | `directory` | string | 否 | 代码库路径。 | **输出：** 可读的叙述，显示每一跳带有域上下文的上游/下游邻居。 ### 推荐工作流 **默认模式：** 1. 从问题中识别符号并调用 `symbol_context` 来探索它们（通过 `symbols` 数组进行批量处理或并行调用） 2. 使用 Read/Grep 检查已识别位置的源代码 3. 到第 3 轮开始编辑。总共最多 3 次 MCP 调用。 **GraphRAG 模式：** 1. 从问题中识别关键符号，调用 `explore_function` 以了解其调用图上下文。并行发出多个调用（只读，安全）。 2. 使用响应中的跨子系统标记和源代码开始编辑。总共最多 2 次 MCP 调用。 ## 预计算图 为了获得最快的性能，请使用 `precache` CLI 子命令提前预计算图。这会调用一次 Supermodel API 并将结果保存到磁盘，从而在运行时无需 API 调用即可实现亚秒级的工具响应。 ### 预计算图 ``` npx @supermodeltools/mcp-server precache /path/to/repo --output-dir ./supermodel-cache ``` 选项： - `--output-dir ` — 用于保存缓存文件的目录（默认：`./supermodel-cache` 或 `SUPERMODEL_CACHE_DIR`） - `--name ` — 缓存键的代码库名称（默认：从 git remote + commit hash 自动检测） ### 在运行时使用缓存的图 ``` SUPERMODEL_CACHE_DIR=./supermodel-cache npx @supermodeltools/mcp-server ``` 服务器在启动时会从 `SUPERMODEL_CACHE_DIR` 加载所有缓存的图。如果给定代码库不存在缓存，服务器将回退到按需 API 调用（对于大型代码库，这需要 5-15 分钟）。 ### 启动预缓存 使用 `--precache` 标志在服务器启动时自动生成并缓存默认工作目录的图： ``` npx @supermodeltools/mcp-server /path/to/repo --precache ``` 这在自动化环境（例如，用于基准测试的 Docker 容器）中非常有用，可确保在进行任何工具调用之前图已准备就绪。 ## 基准测试 使用提供的 [`mcpbr-config.yaml`](./mcpbr-config.yaml) 配置，通过 [mcpbr](https://github.com/greynewell/mcpbr) 对此 MCP 服务器进行基准测试。 ## 本地开发 ### 从源代码构建 ``` git clone https://github.com/supermodeltools/mcp.git cd mcp npm install npm run build ``` ### 本地运行 ``` node dist/index.js # Start MCP server node dist/index.js /path/to/repo # With default workdir node dist/index.js precache /path/to/repo # Pre-compute graph ``` ### 运行测试 ``` npm test # Run all tests npm run test:coverage # Run with coverage npm run typecheck # Type checking ``` ### 使用 MCP Inspector 要进行交互式测试，请使用 [MCP Inspector](https://github.com/modelcontextprotocol/inspector)： ``` npx @modelcontextprotocol/inspector node dist/index.js ``` ## 故障排除 ### 超时错误 首次分析代码库需要进行 API 调用，这可能需要 5-15 分钟。如果您的 MCP 客户端超时： 1. **预计算图** — 使用 `precache` 提前生成图（参见 [预计算图](#pre-computed-graphs)） 2. **增加您的 MCP 客户端超时时间** — 对于 Claude Code CLI，请在您的 shell 配置文件中设置 `MCP_TOOL_TIMEOUT=900000` 3. **分析子目录** — 定位到代码库的特定部分以减少分析时间 ### 常见问题 - **401 Unauthorized：** 检查 `SUPERMODEL_API_KEY` 是否设置正确 - **Permission denied：** 检查目录的读取权限 - **ENOTFOUND 或连接错误：** 检查您的互联网连接和防火墙设置 ### 调试日志 设置 `DEBUG` 环境变量以获取详细日志： ``` { "mcpServers": { "supermodel": { "command": "npx", "args": ["-y", "@supermodeltools/mcp-server"], "env": { "SUPERMODEL_API_KEY": "your-api-key", "DEBUG": "supermodel:*" } } } } ``` ## 博客 - [为什么代码图对 AI 代理很重要](https://greynewell.com/blog/why-code-graphs-matter/) - [Supermodel 代码图 API 的架构](https://greynewell.com/blog/supermodel-code-graph-api-architecture/) - [构建 Uncompact：来自生产环境的经验教训](https://greynewell.com/blog/building-uncompact-lessons-from-production/) ## 链接 - [API 文档](https://docs.supermodeltools.com) - [Supermodel SDK](https://www.npmjs.com/package/@supermodeltools/sdk)

标签：AI代理, AI编程助手, API密钥, Claude Code, Codex, Cursor, GNU通用公共许可证, GraphRAG, MCP, MITM代理, Model Context Protocol, Node.js, npm, Supermodel API, 代码分析工具, 代码图, 代码库理解, 代码索引, 威胁情报, 开发者工具, 暗色界面, 符号查找, 缓存, 自动化攻击, 调用图, 跨系统分析