semantic-code-mcp

自建代码语义检索 MCP Server —— 自然语言查询 → 相关代码片段。

「效果优先」技术栈：Tree-sitter AST 切分 + voyage-code-3 embedding（int8 量化）+ sqlite-vec 向量库 + BM25 全文 + RRF 融合 + Voyage rerank-2.5 重排 + Call Graph 图扩展。一个 VOYAGE_API_KEY 跑通 embedding + rerank 全链路。

工程特性：watchdog 文件实时监控 + 多工作区 LRU 管理 + MCP progress notification + 协程级取消（取消后立即返回；已在飞的索引批次在后台跑完并持久化，不丢数据也不重复计费重建）。

架构

codebase_search(query, dir)
        │
        ▼
  WorkspaceManager ── LRU(max 8) ── FileWatcher(watchdog + 2s debounce)
        │
        ▼
  Indexer ── 全量扫描/watcher增量(O(变更数)) ── Chunker(Tree-sitter AST) ── Embedder(voyage-code-3)
        │                                                                        │
        │                                                          Store(sqlite-vec + FTS5 + 文件hash)
        ▼
  Retriever ── 向量召回 + BM25召回 ── RRF融合 ── rerank（Voyage/Cohere）── Call Graph扩展 ── top_n 代码片段
        │
        ▼
  MCP Server ── async tools + progress notification + 协程级取消

Related MCP server: code-rag

安装

发布包名为 semcode-mcp（PyPI 上 semantic-code-mcp 已被同名项目占用）：

# 方式一（推荐）：uv 环境零安装，MCP 客户端配置里直接 uvx 启动
uvx semcode-mcp

# 方式二：npx（要求已装 uv，该 npm 包是透传 uvx 的薄壳）
npx -y semcode-mcp

# 方式三：pip
pip install semcode-mcp

# 源码开发
pip install -e .

配置

复制 .env.example 为 .env 并填入 key：

高级配置

在 MCP 客户端注册

{
  "mcpServers": {
    "semantic-code": {
      "command": "uvx",
      "args": ["semcode-mcp"],
      "env": {
        "VOYAGE_API_KEY": "your-voyage-key"
      }
    }
  }
}

npx 用法把 command/args 换成 "npx", ["-y", "semcode-mcp"]； 源码开发用 pip install -e . 后配 "semcode-mcp", []（包采用相对 import， 不支持 python server.py 直接跑，需用 console script 或 python -m semantic_code_mcp.server）。

工具

codebase_search

唯一工具，首次调用自动全量索引，之后 watcher 驱动增量同步（O(变更数)，极速）。支持 MCP progress notification 实时回报索引进度。需要强制重建索引时删除 ~/.semantic-code-mcp/ 下对应 .db 文件即可。

工作原理

1. 切分：Tree-sitter 解析 AST，按函数/类边界切块，保留 file_path / symbol / 行号 元数据。

2. 向量化：voyage-code-3 对代码块生成 1024 维向量（input_type=document）。

3. 存储：向量入 sqlite-vec（vec0 虚拟表），同时入 FTS5 全文索引；blob_hash = SHA256(path+code) 实现内容寻址去重。

4. 检索：查询同时走向量 KNN 与 BM25，用 RRF 融合排名，再用 rerank（默认 Voyage rerank-2.5）精排出 top_n。

5. 图扩展：主结果沿 call graph 扩展 1 跳，把调用者/被调用者连带召回（附 relation 标记）。

6. 实时监控：watchdog 监控文件变更（2s debounce），后台主动增量同步（O(变更数)），查询时零等待；后台失败不丢变更，下次查询前兜底。

7. LRU 管理：多工作区并发（最多 8 个），超限自动淘汰最久未用的 workspace。

索引存储

每个工作区按目录路径哈希存为 ~/.semantic-code-mcp/<hash>.db（可用 SCM_DB_DIR 改）。删除该目录即清空所有索引。

隐私与数据边界

本工具的完整数据流向，用于评估能否用于敏感/闭源仓库：

会出网的数据（默认配置）

⚠️ Voyage 数据条款（重要，索引闭源代码前必读）

按 Voyage TOS Section 3(iii)（2026-07 复核）：

• 默认（opt-out 前）提交内容可被 Voyage 用于训练和改进模型

• Opt-out 需要：账户绑定支付方式 + 组织 Admin 身份，dashboard → Terms of Service → 底部 toggle 切到 Opted Out

• Opt-out 后为 zero-day retention（处理完即删），但不追溯之前提交的数据，且免费额度可能被作废

• Batch API 上传的文件会保留 30 天（本工具不使用 Batch API）

用于公司/闭源代码前，先完成 opt-out 或使用全本地模式。 Cohere（可选 rerank 后端）条款请自行评估。

始终留在本地的

• 索引库全部落盘本机 ~/.semantic-code-mcp/（向量 + 代码原文 + call graph），不上传任何服务

• 无遥测、无统计上报，除上表 API 外零网络请求

索引范围控制

• 全层级遵守 .gitignore（含否定模式）：.env、构建产物等被忽略的文件不会进索引

• 例外：AGENTS.md/.windsurfrules 等 agent 指导文件即使被 gitignore 也会索引（有意设计，它们对检索架构问题价值极高）

• ⚠️ 硬编码在代码里的密钥会随代码块发往上表供应商，敏感仓库索引前请先清理或用全本地模式

全本地模式（代码零出网）

pip install sentence-transformers
SCM_EMBED_BACKEND=local        # 本地 embedding（默认 Qwen/Qwen3-Embedding-0.6B）
# 不配 COHERE_API_KEY         # rerank 自动跳过，用 RRF 融合排序

检索质量会下降（参考公开评测中自托管 0.6B 方案的差距），但数据完全不离开本机。

路线

• 阶段 1 ✅：Tree-sitter + voyage-code-3 + hybrid + rerank —— 第一梯队 RAG

• 阶段 2 ✅：Call Graph 图扩展（caller/callee 连带召回）+ int8 量化向量（存储省 71%，一致率 95%）

• 阶段 3 ✅：工程化 —— watchdog 文件监控 + 多工作区 LRU + progress + cancel

• 阶段 4 ✅（部分）：意图感知排序（调用链直查 edges / 测试意图 / 文档意图）+ 文档配置索引（AGENTS.md 豁免 gitignore）+ 50 条分类评测集

• 阶段 5 ✅：单工具化 + 后台主动增量同步 + 分阶段进度条日志 + Java 调用链（接收者边/构造类型名/泛型剥离）+ 配置意图（yaml 反转 boost）

  • 并发 embedding 流水线（worker 只跑网络调用，sqlite 写回留在调用线程，顺序写回；CLIProxyAPI 9067 块全量 77s，≈串行 3 倍）

• HyDE 已评测，结论默认关：Top-1 86%→82%、延迟 2.9s→10.4s、Recall@5 98%→100%；架构类 +40 分但配置/SDK 类 -40（变体稀释精确标识符信号）。 改进线：选择性扩展——仅对不含精确标识符的模糊查询开 HyDE

• 后续候选：选择性 HyDE、本地后端对照评测、超大仓库 ANN 索引

评测（eval_golden.py，CLIProxyAPI 778 文件 / 9067 块）

50 条 query × 10 类（符号定位/调用链/架构职责/配置schema/同名干扰/SDK边界/协议契约/测试/中文/细节）， 机械化打分可复现（期望文件 + must_contain 关键字）：

附加 K 类私有业务仓库探针（不计入主总分）：在真实业务仓库上验证复合意图拆分/ 子查询分数混合/保底、trigram 中文召回、实现意图降权、expand_graph=True 全链路。 探针定义在 gitignore 的 eval_local_probes.py（PROBE_TARGET + PROBE_GOLDEN， 写法见 eval_golden.py 的 K 类加载段），不存在自动跳过（--skip-java 显式跳过）—— 你可以对自己的仓库建一组同格式探针作为私有回归安全网。

复测：python eval_golden.py --json；回归测试：python test_fixes.py

模型选型说明

• embedding 为什么是 voyage-code-3 而非 Voyage 4 系列：4 系列（2026-01）是通用文本模型， 没有 voyage-code-4；官方文档代码检索场景仍推荐 code-3。想试通用旗舰可 SCM_EMBED_MODEL=voyage-4-large（需重建索引），与 code-3 的对比评测列入后续。

• rerank 为什么默认 Voyage：与 embedding 同一个 key 零额外配置；rerank-2.5 公开基准 优于 Cohere v3.5（官方数据 +7.94%，本项目评测 Top-1 +4）；免费额度 200M token 且无 试用 key 10 次/分钟限速（评测提速 6.5×）。Cohere 保留为可选后端。

工程边界（已知成本）

• rerank 限速：未绑卡/试用 key 限速低（Cohere 试用 10 次/分钟）。密集调用设 SCM_RERANK_MIN_INTERVAL 节流；429 自动退避重试兜底。

• 复合 query 额外延迟：中文双动作查询（"生成…并清理…"）每个子查询多发一次 rerank（+200~400ms/次，最多 2 次）。仅复合措辞触发，普通查询零开销。

• 阈值标定范围：子查询分数门槛 0.2、两段拆分等参数按 Cohere 分数分布在中文 Java 仓库 + Go 仓库双评测集上标定；切换 rerank 后端（分数分布不同）或其它语言/ 仓库表现异常时，优先复核 _COMPOUND_SUB_MIN_SCORE。

性能数据（42 块 / 9 文件）