mcp-deepcontext

支持在 Claude Code 中进行符号感知的语义搜索的 MCP 服务器

动机

大多数代码搜索工具将代码视为文本，忽略了赋予代码意义的语义结构。当你在大型代码库中工作时，你不仅仅是想找到字符串出现的位置。你想要找到函数在哪里被调用、类型在哪里实现，或者哪些模块依赖于特定的符号。

该 MCP 服务器通过向 Claude 公开语义代码分析功能来弥补这一差距。Claude 不再需要通过 grep 搜索文本，而是可以询问诸如“这个接口在哪里实现？”或“这个函数的所有调用者是谁？”之类的问题，并获得准确的、符号感知的搜索结果。这使得针对不熟悉的代码库进行真正有用的对话成为可能。

架构

graph TD
    A[Claude Desktop] -->|MCP Protocol| B[mcp-deepcontext Server]
    B -->|Parse & Index| C[Symbol Database]
    B -->|AST Analysis| D[TypeScript Compiler API]
    B -->|Semantic Search| E[Vector Embeddings]
    
    C -->|Symbol Locations| B
    D -->|Type Information| B
    E -->|Similarity Scores| B
    
    F[Your Codebase] -->|Watch & Reindex| B

入门指南

安装

npm install -g mcp-deepcontext

快速开始

添加到你的 Claude Desktop 配置文件 (~/Library/Application Support/Claude/claude_desktop_config.json) 中：

{
  "mcpServers": {
    "deepcontext": {
      "command": "mcp-deepcontext",
      "args": ["--workspace", "/path/to/your/project"]
    }
  }
}

然后重启 Claude Desktop。服务器将在启动时索引你的代码库。

工作原理

该服务器使用 TypeScript 编译器 API 来构建代码库的完整符号图。这包括类型定义、函数签名、类层次结构和导入关系。当 Claude 查询信息时，服务器可以提供精确的位置和上下文。

对于语义搜索，服务器会为代码符号及其周围的上下文生成嵌入。这允许基于意图而非精确文本进行模糊匹配。符号数据库通过触发增量重新索引的文件监视器与文件更改保持同步。

MCP 协议通过 search_symbols、find_references、get_definition 和 find_implementations 等工具公开此功能。Claude 可以将这些工具链接起来，以回答有关代码结构和关系的复杂问题。

配置

服务器接受以下命令行参数：

• --workspace <path>：要索引的项目根目录（必需）

• --languages <list>：要索引的语言列表，以逗号分隔（默认：typescript,javascript）

• --exclude <patterns>：要排除的 Glob 模式（默认：node_modules,dist,build,.git）

• --max-file-size <bytes>：跳过大于此大小的文件（默认：1MB）

• --embedding-model <name>：用于嵌入的模型名称（默认：text-embedding-3-small）

环境变量：

• OPENAI_API_KEY：生成嵌入所需的 API 密钥

• DEEPCONTEXT_LOG_LEVEL：设置为 debug 以获取详细日志

常见问题解答

问：支持哪些语言？

目前支持具有完整类型感知的 TypeScript 和 JavaScript。计划支持 Python 和 Go。

问：这适用于大型代码库吗？

是的，索引是增量的，符号数据库使用高效的图结构。已在高达 50 万行代码的代码库上进行测试，运行良好。

问：生成嵌入需要多少成本？

对于典型的 10 万行代码库，初始索引会生成约 1 万个嵌入，使用 text-embedding-3-small 的成本约为 0.02 美元。增量更新的成本要低得多。

问：我可以在不使用嵌入的情况下使用它吗？

可以，传递 --no-embeddings 以禁用语义搜索。你仍然可以使用所有符号感知工具，如查找引用和跳转到定义。

问：这会将我的代码发送到外部服务吗？

只有提取的符号名称及其直接上下文会被发送到 OpenAI 以生成嵌入。你可以通过 --no-embeddings 禁用此功能，以实现完全本地化操作。

许可证

MIT