Deepcontext MCP

🚀 大型代码库的智能上下文

DeepContext 是一个 MCP 服务器，它为 Codex CLI、Claude Code 等代码编写助手添加了支持符号感知的语义搜索功能，使它们即使在处理大型代码库时也能获得更精确的上下文信息。目前支持 TypeScript 和 Python 语言。

🚀 快速开始

1. 访问 Wildcard DeepContext 页面。
2. 点击“生成 API 密钥”。
3. 复制你的 API 密钥。
4. 为你的 MCP 客户端粘贴安装命令。
5. 输入 index this codebase 对当前目录进行索引。

Claude Code

claude mcp add deepcontext \
  -e WILDCARD_API_KEY=your-wildcard-api-key \
  -- npx @wildcard-ai/deepcontext@latest

Codex

# 添加到 ~/.codex/config.toml
[mcp_servers.deepcontext]
command = "npx"
args = ["-y", "@wildcard-ai/deepcontext@latest"]
env = { "WILDCARD_API_KEY" = "your-wildcard-api-key" }

💻 演示

点击查看演示

✨ 为什么选择 DeepContext MCP？

大多数代码编写助手使用基于 grep 的精确文本匹配搜索，这种搜索方式会遗漏语义相关的代码，并且会用不相关的结果填满上下文窗口。在大型代码库中，这个问题会更加严重，因为文本搜索可能会返回数百个匹配项，很快就会超出对话容量。这会导致代码补全速度变慢、出现更多幻觉内容以及成功率降低。

DeepContext 为代码编写助手提供智能搜索功能，通过仅查找相关代码块来保留上下文窗口。

• 语义准确性：通过代码的含义和关系进行匹配，而不是基于文本模式，能够找到跨文件的相关函数，这是关键字搜索所无法做到的。
• 减少令牌使用量：返回精确的代码块，而不是包含搜索词的每个文件，从而保留对话上下文窗口并降低成本。
• 搜索速度快：通过预索引数据立即搜索代码，实现即时文件发现。

📚 详细文档

MCP 工具

index_codebase

为你的代码库创建可搜索的索引，以便进行语义搜索。

search_codebase

使用自然语言或关键字查询查找相关代码。

get_indexing_status

显示代码库的索引状态和文件数量。

clear_index

删除代码库的所有索引数据。

架构

MCP 集成流程

• 代码编写助手通过模型上下文协议与 DeepContext 进行通信。
• MCP 服务器接收请求，验证参数，并将其路由到适当的核心组件。
• 对于像索引这样的长时间运行操作，会生成独立的后台进程以防止超时。
  • 后台工作进程可以处理大型代码库，而不会阻塞 MCP 通道。

基于 AST 的解析

• Tree-sitter 解析器分析源代码以构建抽象语法树。
  • 支持 Python、TypeScript 和 JavaScript 语言语法，以实现准确解析。
  • 对函数、类、接口和模块进行语义节点识别。
• 符号提取识别函数、类、接口、类型、变量和常量。
  • 作用域分析确定局部、导出和全局可见性。
  • 提取函数签名中的参数和返回类型。
• 导入/导出分析映射模块依赖关系和跨文件关系。
• 在语义边界处创建代码块，而不是任意的行或令牌分割。
  • 通过基于范围的解析和重叠窗口处理大文件。

带重排序的混合搜索

• 搜索操作分为三个阶段。
  • 混合搜索结合了向量相似度和 BM25 全文搜索。
  • 使用 Jina reranker-v2 进行最终相关性优化。
• 向量相似度使用嵌入查找语义相关的代码。
  • Jina 文本嵌入为代码块生成 1024 维向量。
• BM25 执行传统的关键字匹配以查找精确术语。
  • 全文索引支持精确的标识符和注释匹配。
• 使用可配置的权重融合结果，然后由 Jina 重排器重新排序。

增量索引

• 使用文件修改时间和内容哈希来跟踪更改。
  • SHA-256 哈希在字节级别检测内容修改。
• 在重新索引期间，仅重新处理哈希不同的文件。
  • 避免对未更改的文件进行不必要的解析和嵌入生成。

内容过滤

• 根据文件扩展名模式、路径组件和内容分析对文件进行评分。
  • 进行语言检测和文件类型分类，以做出处理决策。
• 在索引期间排除测试文件、生成的代码、压缩文件和构建输出。
  • 对常见测试框架和构建工具输出进行模式匹配。
• 过滤文档和配置文件，专注于源代码。

📦 自托管

自托管需要对代码进行修改，以直接与向量存储和嵌入提供程序集成，因为当前实现使用 Wildcard API 后端。

前提条件

• Node.js 20+，以支持 ES 模块并进行性能优化。
• Turbopuffer API 密钥，用于向量存储和混合搜索操作。
• Jina AI API 密钥，用于文本嵌入和重排序服务。

安装步骤

git clone https://github.com/Wildcard-Official/deepcontext-mcp.git
cd deepcontext
npm install
npm run build

集成步骤

claude mcp add deepcontext-local \
  -e TURBOPUFFER_API_KEY=your-turbopuffer-key \
  -e JINA_API_KEY=your-jina-key \
  -- node /path/to/deepcontext/dist/standalone-mcp-integration.js

🤝 贡献代码

感谢你的关注！由于我们是一家处于早期阶段的初创公司，专注于快速迭代，目前暂不接受外部贡献。我们可能会在未来开放贡献渠道 —— 你可以给仓库点个 ⭐ 以保持关注。

📄 许可证

本项目采用 Apache 许可证。