ContextTree MCP 🌳

面向 AI 编码助手的深度语义代码搜索——基于 AST 解析与本地嵌入实现，100% 离线运行。

ContextTree MCP 是一个本地 Model Context Protocol 服务器，它让你的 AI 编码助手获得对代码库的结构化理解能力。它融合了两个世界：

• tree-sitter 将源文件解析为 AST，并提取逻辑块——函数、方法、带有文档字符串的类签名。

• sentence-transformers（all-MiniLM-L6-v2）把每个逻辑块（连同文件路径、类名、方法名和文档字符串一起）嵌入到本地的 ChromaDB 向量存储中。

最终效果是：你的助手能够按语义而非关键词来查找代码，而且每一次搜索命中都会返回精确的文件路径和行号。

🔒 隐私优先。 一切都在你的机器本地运行：解析、嵌入模型、向量索引。不调用云端、无遥测数据，代码永远不会离开它所在的磁盘。

为什么不用纯文本搜索？

grep 和全文搜索只能做字符串匹配。它们恰恰在开发者最需要帮助的地方失灵：

Related MCP server: CodeGrok MCP

功能特点

• 🌲 AST 感知分块 —— 通过 tree-Sitter 对函数、方法和类签名建立索引，而不是任意文本窗口。

• 🧩 上下文增强逻辑块 —— 每个索引文档都嵌入了它的文件路径、所属类、方法名、文档字符串和函数体，因此像 “支付重试逻辑” 这样的查询会命中正确的方法。

• ⚡ 增量索引 —— 通过 SHA-256 内容哈希跟踪每个文件；只重新处理变更/新增/删除的文件。

• 🔍 语义搜索 —— 自然语言查询 → 返回按相关度排序的代码片段及准确的行号范围。

• 📞 AST 调用关系查询 —— 查找任意符号（函数或类）的真实调用位置，并过滤掉字符串字面量、注释等误报。

• 🗄️ 持久性本地索引 —— ChromaDB 用于 .chroma/ 目录，重启后仍然存在，永远不会提交到 Git。

• 🔌 stdio MCP 传输 —— 可以接入 Claude Desktop、OpenCode、Cursor、Cline 或其他与 MCP 兼容的客户端。

技术栈

安装说明

需要 Python 3.12+ 版本。uv 被推荐为快捷、现代的包管理器：

git clone https://github.com/<your-org>/mcp-context-tree.git
cd mcp-context-tree

# Option A — uv (recommended): resolves dependencies from pyproject.toml, locks uv.lock
uv sync

# Option B — classic pip + venv
python -m venv venv && source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

💡 首次运行会下载嵌入模型（约 90 MB）。PyTorch 作为 sentence-transformers 的依赖项会被安装进来；CPU 版本就足够了——不需要 GPU。

注册到 MCP 客户端

配置示例（Claude Desktop / 任何支持 stdio 服务器的客户端）：

{
  "mcpServers": {
    "context-tree": {
      "command": "<path-to-venv>/bin/python",
      "args": ["-m", "context_tree"],
      "env": {}
    }
  }
}

(在 Windows 上请使用 <path-to-venv>\Scripts\python.exe。)

暴露给助手的工具

典型工作流：

1. index_workspace("D:/projects/my-app")
2. semantic_search("where do we handle payment retries", limit=8)
3. find_ast_usages("PaymentGateway.retry")

已支持的语言

文档

• 🏛 ARCHITECTURE.md —— 项目布局、ChromaDB 数据 Schema、AST 提取逻辑、增量索引设计。

• 🇷 🇺 README.ru.md —— 俄语文档。

路线规划

• 监听模式 —— 文件变更时自动重新建立索引（file watcher）。

• 通过 tree-sitter 绑定扩展到更多语言。

• 混合检索（BM25 + 向量的重排序）。

• 基于调用图的排序算法（“谁在调用它？”）。

• 发布到 PyPI（context-tree-mcp）。

贡献力量

欢迎 issue 和 PR。请保持与 ARCHITECTURE.md 的一致性。

License

MIT — 详见 LICENSE。