Repo Semantic MCP

回购语义mcp

repo-semantic-mcp 是用于边界编码代理的存储库检索MCP。 它帮助代理在编辑之前在大型代码库中收集基础上下文：

• 检查索引是否准备就绪，是否足够新鲜，可以使用；
• 检索相关代码、文档、测试、部署文件和策略文件；
• 将密集语义搜索与代码感知稀疏检索相结合；
• 可选择通过类型化存储库图扩展强结果；
• 告诉代理人确切的当地时间 rg 验证是正确的权威。

MCP不是隐藏的编码代理，不会生成最终答案。这 前沿模型仍然是规划者、读者、编辑和审阅者。此服务器是 其下方的检索基板。

当前形状

目前的实施提供了：

• Qdrant支持 code 和 docs 收藏；
• 命名为密集和稀疏向量，采用加权RRF融合；
• 标识符、路径、路由、环境变量和

引用文字；

• index_status.v2 具有运行时、后端、新鲜度、检索和图形

诊断；

• repo_context_search 面向代理的上下文信封；
• search_v2 加上遗留的列表形式的语义/混合工具；
• 显式SQLite图形工件 build_graph / rebuild_graph;
• 跨文件存储库上下文的有界图扩展；
• 明确的精确搜索切换，而不是在MCP内部进行炮击。

公认的长期架构记录在 docs/architecture/P6-final-architecture.md.

为什么它存在

大型存储库对于编码代理来说很难，因为有用的上下文很少 在一个文件中。变化可能涉及：

• 运行时代码；
• 测验；
• 部署配置；
• 文件/规范；
• 代理策略文件；
• 环境合同；
• 跨服务流。

平原 rg 仍然是精确标识符和文字的权威，但它 没有解释哪些远程文件属于同一实现流。 语义搜索有助于概念，但仅靠原始嵌入往往无法准确 锚和代码结构。该项目将两者结合起来， 用于连接存储库上下文的确定性图层。

检索路线

主要路线是：

agent query / agent-provided subqueries
  -> dense retrieval over Qdrant
  -> sparse code-normalized retrieval over Qdrant
  -> weighted RRF fusion
  -> optional typed graph expansion from strong seeds
  -> final RRF over dense+sparse+graph branches
  -> grounded context envelope

图形扩展对于跨区域问题很有用，例如：

• “此流在哪里端到端实现？”
• 查找此路由的处理程序、测试、文档和部署契约
• “将此迷你应用程序操作连接到后端工作程序”
• “这个env/config契约在系统中移动到哪里？”

对于纯精确查找，有意抑制或避免图扩展。 对于精确的环境变量、路由字符串、表名、错误消息和路径 碎片，MCP应推荐本地 rg 验证。

重要工具

面向检索的代理：

• repo_context_search -具有分支诊断的主上下文路由，

文件组、匹配/未覆盖的术语、图形诊断和下一步操作。

• search_v2 -稳定的搜索包络，没有强制的图语义。
• semantic_search, semantic_search_code, semantic_search_docs -遗产

语义结果列表。

• hybrid_search, hybrid_search_code, hybrid_search_docs -传统混合动力车

结果列表。

准备状态和生命周期：

• index_status -代理应该调用的第一个工具。
• graph_status -详细的图形状态。
• build_index, rebuild_index, reindex_paths -显式索引生命周期。
• build_graph, rebuild_graph -显式图生命周期。

搜索和状态永远不会隐式重建索引或图形。

代理工作流

针对在目标存储库中工作的编码代理的建议策略：

1. 呼叫 repo-semantic-search.index_status().
2. 验证 repo_root 是预期的存储库。
3. 验证 search_available=true.
4. 检查运行时/后端/新鲜度/图形诊断。
5. 使用 repo_context_search 或 search_v2 缩小范围。
6. 读取返回的文件/范围。
7. 使用本地 rg 在编辑之前获取确切的锚点。
8. 除非用户明确要求，否则不要调用生命周期工具。

如果MCP报告 runtime_switch_required, backend_switch_required，或a 阻塞生命周期状态时，代理应停止并报告主机端提示 而不是试图默默地修复它。

运行时模型

一个正在运行的堆栈一次索引一个目标存储库。目标存储库 是一个明确的启动参数；MCP不会猜测活动的IDE文件夹。

这是故意的：

• Codex和Claude可以共享相同的MCP端点；
• 目标回购转换是确定性的；
• 集合名称包括repo/profile/model/schema标识；
• 生命周期操作保持明确。

快速开始

注册一次代理集成：

pwsh -File scripts/agents/register_repo_semantic_search.ps1

启动目标存储库的堆栈：

pwsh -File scripts/agents/start_repo_semantic_for_project.ps1 `
  -RepoPath C:\path\to\target-repo

对于明确的配置文件：

pwsh -File scripts/agents/ensure_repo_semantic_search.ps1 `
  -Build `
  -Profile gpu `
  -TargetRepoPath C:\path\to\target-repo

CPU回退：

pwsh -File scripts/agents/ensure_repo_semantic_search.ps1 `
  -Build `
  -Profile cpu `
  -TargetRepoPath C:\path\to\target-repo

当前狗粮期间使用的V100/Volta配置文件：

pwsh -File scripts/agents/ensure_repo_semantic_search.ps1 `
  -Build `
  -Profile gpu-pplx-v100-infinity `
  -TargetRepoPath C:\path\to\target-repo

注册后，如果客户端已打开，请重新启动。Codex使用 连接到正在运行的容器的stdio包装器。克劳德使用共享 HTTP端点。

档案

堆栈是后端抽象的：MCP与配置的端点进行通信 以相同的方式对事件、嵌入和未来的重新登录/ColBERT端点进行建模。这 服务器不应该关心模型是否在WSL本机、llama.cpp本机中运行， Docker GPU或其他主机进程，只要端点合约匹配即可。

常见配置文件：

• cpu -兼容性配置文件使用 intfloat/multilingual-e5-small.
• gpu / gpu-qwen3 -用于Qwen3嵌入的NVIDIA Docker配置文件。
• gpu-bge-m3 -实验/调试配置文件。
• gpu-pplx-v100-infinity -V100友好版Infinity配置文件

pplx-embed-v1.

Qdrant默认为 qdrant/qdrant:v1.17.1；当前索引架构为 3.

准备就绪

真相的来源是：

pwsh -File scripts/agents/repo_semantic_status.ps1

或者：

http://127.0.0.1:8011/readyz

/readyz 报告运行时就绪状态、活动仓库、配置文件、索引状态， search_available，并嵌入 index_status 细节。Docker容器 健康是有益的，但是 /readyz 和 index_status 是操作检查吗 代理商应该依靠。

狗粮检查站

当前的检查点是针对大型VPN后端/控制平面进行的 存储库：

• 目标回购： C:\nullexp_vpn\vpn-server;
• 轮廓： gpu-pplx-v100-infinity;
• 索引块： 16966;
• 图表：准备就绪， 36097 节点和 48862 边缘。

通过了三个实际场景：

1. 新编码代理的项目概述；
2. 跨区域实施图 /v1/connect-flow/connect;
3. 精确的锚点查找 CONNECT_FLOW_TELEGRAM_BETA_SECRET 和 rg

权威和图表被压制。

看 docs/dogfood/2026-05-07-vpn-server-frontier-agent-checkpoint.md.

仓库的规划

• apps/repo-semantic-mcp/ -MCP应用程序入口点和容器映像。
• services/repo_semantic/ -索引、检索、状态、图形、存储和

后端逻辑。

• deploy/repo-semantic-search/ -Docker编写堆栈和环境配置文件。
• scripts/agents/ -启动、注册、状态和客户端包装器。
• docs/architecture/ -公认的建筑。
• docs/specifications/ -实施规范。
• docs/research/ -研究输入和提示。
• docs/dogfood/ -实用的狗粮检查站。
• tests/ -MCP服务的单元和集成覆盖。

开发说明

• 传统的列表形工具必须保持向后兼容。
• 生命周期工具必须保持明确。
• 密集的查询文本保持原始状态。
• 稀疏查询文本在保留精确锚点的同时进行了代码规范化。
• 使用加权RRF代替直接的原始分数混合。
• 图扩展是有界的、确定性的和可解释的。
• 陈旧的图表/索引状态必须可见，并且不得对结果产生无声影响。
• 精确的本地 rg 当代理具有文件系统访问权限时，它仍然具有权威性。

许可证

此存储库准备在下发布 PolyForm Noncommercial 1.0.0.

这意味着在许可条款下允许复制和修改，但是 除非许可证明确更改，否则不允许商业使用。