AI导哈

代码库语义检索系统

为前沿编码代理提供代码库语义检索服务，结合密集语义搜索和代码感知稀疏检索，支持跨文件上下文关联和精确本地验证。

  • by ezsx
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 ezsx/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 / update_graph;
  • 跨文件存储库上下文的有界图扩展；
  • 监视器启动协调和分支切换后的有界图恢复， 重新启动和增量索引更新；
  • 明确的精确搜索切换，而不是在MCP内部进行炮击。

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

为什么它存在

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

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

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

在哪里增加价值

目标不是“语义搜索而不是grep”。目标是给一个 frontier编码代理是大型存储库的更好的第一张地图。

rg 当代理已经知道确切的字符串时，这是极好的。它仍然是 标识符、环境变量、路由文字、表名和错误的权限 实时工作树中的消息。

当代理需要回答以下问题时，此MCP非常有用：

  • 哪些文件属于此功能或运行时流？
  • 哪些文档/规范/测试/部署文件解释了我要编辑的代码？
  • 路由、env-var、配置键或策略如何跨仓库连接？
  • 重启或分支切换后，我是否可以充分信任索引和图形 在编辑之前使用它们？

实例来自 vpn-server 狗粮：

  • 关于迷你应用连接流链接Telegram迷你应用文档的查询， 可观察性规范、用户api路由代码、连接流外观和worker 背景。平原 rg "/v1/connect-flow/connect" 找到了几十个匹配项，但是 没有解释端到端的路由。
  • 关于用户流量计费的查询找到了维护遥测SQL， 处理程序代码以及相关的单元/集成测试 peer_pubkey_hash, peer_identifier，以及 user_traffic_hourly.准确 rg 之后仍然可以用于验证。
  • 精确的环境变量查找仍然会路由到本地 rgMCP通过以下方式做出贡献 检测这是一个精确的锚点任务，并暴露新鲜度状态。

检索路线

主要路线是：

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, update_graph -显式图生命周期。
  • start_watcher, stop_watcher -明确的观察者生命周期。

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

代理工作流

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

  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 阻塞生命周期状态时，代理应停止并报告主机端提示 而不是试图默默地修复它。

对于日常代理恢复，更倾向于先修复后重建的操作：

py -3.12 scripts/agents/repo_semantic_ensure_ready.py `
  --repo C:\path\to\target-repo `
  --mode safe-recover `
  --start-watcher `
  --require-graph `
  --json

这可能会启动观察程序并运行有界启动协调 主动匹配回购/配置文件。它还可以在以下情况下运行有界图修复 索引是新鲜的，图形恢复是安全的。它仍然没有建造或重建 索引或图表。

运行时模型

一个正在运行的堆栈一次索引一个目标存储库。目标存储库 是一个明确的启动参数；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端点，因此后端 容器重启不会终止聊天传输。Claude使用相同的共享 直接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 是操作检查吗 代理商应该依靠。

对于代理侧飞行前：

py -3.12 scripts/agents/repo_semantic_ensure_ready.py --repo C:\path\to\target-repo

默认情况下，帮助程序是只读的(diagnose 模式）。它报告是否搜索， 稀疏检索、图扩展、观察器和HTTP回退都是可用的。房屋出租 代理执行有界修复，使用显式 --mode safe-recover；这可能 启动已激活的匹配repo/profile的监视器，但仍然不会 构建或重建索引或图。

对于直接HTTP回退工具调用：

py -3.12 scripts/agents/repo_semantic_call_tool.py index_status

那个脚本打印了一个稳定的 ok/error 默认情况下为信封。使用 --payload 仅 当人类特别想要解码的MCP有效载荷而不需要包装字段时。

对于目标仓库更广泛的可靠性烟雾：

py -3.12 scripts/agents/repo_semantic_reliability_smoke.py `
  --repo C:\path\to\target-repo

烟雾使用HTTP回退，验证准备就绪，运行一个小程序 repo_context_search 探测、检查 graph_status，并报告稳定情景 结果。默认情况下，它不会重建：它不会构建索引、重建图、， 切换repos/backends或修改源文件。添加 --allow-start-watcher 仅 当代理被明确允许启动已处于活动状态的监视器时 回购。

观察者状态是明确的：

  • watcher.enabled=true 意味着运行时配置为支持增量 看。
  • watcher.running=true 意味着轮询监视器实际上是活动的。
  • watcher.start_required=true 意味着不会进行实时增量索引 直到 start_watcher 被明确地调用。
  • watcher.autostart_policy=manual 目前是有意的；状态/搜索工具 不要自行启动生命周期操作。

当明确调用时， start_watcher 首先运行启动文件协调 在观察者停止时更改，然后开始轮询未来的更改。 它仍然是一个显式的生命周期操作，而不是状态/搜索调用所做的操作 含蓄地。

图形新鲜度与向量新鲜度分开维护。在P6.B之后， 有界恢复可以从当前索引块更新图，而无需 全图重建。这在以下情况下很重要：

  • 分支开关；
  • MCP/容器重启；
  • 观察者追赶，改变了索引块；
  • 每个文件输入签名缺少遗留图工件。

如果图形恢复超出安全的自动界限，状态应建议 需要权限 update_graph(allow_large_update=true) 在推荐之前 rebuild_graph重建仍然是硬工件/模式的最后手段 不匹配或真正无限制的更新。

狗粮检查站

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

  • 目标回购： C:\nullexp_vpn\vpn-server;
  • 轮廓： gpu-pplx-v100-infinity;
  • 索引块： 17035;
  • 图表：准备就绪， 36250 节点和 49015 边缘；
  • 观察者：跑步；
  • 图扩展：允许并通过验证 repo_context_search.

实际场景通过：

  1. 新编码代理的项目概述；
  2. 跨区域实施图 /v1/connect-flow/connect;
  3. 精确的锚点查找 CONNECT_FLOW_TELEGRAM_BETA_SECRET 随着 rg 权威和图表被压制。
  4. 图形辅助迷你应用程序/连接流上下文搜索 graph_mode=expand 和 graph_used=true;
  5. MCP重启后的安全恢复，无需重建索引或图形；
  6. 小型灯具分支开关e2e： start_watcher ->启动协调->图形更新-> 图搜索返回新的路线。

旧的检查点保留在 docs/dogfood/2026-05-07-vpn-server-frontier-agent-checkpoint.md；README 反映了新的P6.B恢复狗粮状态。

当前限制

  • 堆栈仍然需要精心设置。这还不是一个命令， 精心打造的社区设施。
  • 直接MCP传输可以依赖于客户端；HTTP回退包装器是 当前代理脚本使用的可靠路径。
  • 增量更改后，稀疏的BM25统计数据可能会过时。混合搜索 仍然可用，但仍应与当地人核实确切的锚 rg.
  • 图提取是有用的，但有意限制。这不是一个完整的 调用图引擎，而不是GraphRAG摘要，也不是隐藏的计划器。
  • 今天，一些图形提取器警告是非阻塞的，特别是对于Python AST 解析大型真实存储库中的边缘案例。

仓库的规划

  • 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.

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

相关 MCP