Smooth.CodeRepositoryIndexMcp

关键词

代码索引AGENTS.md 支持多仓库管理领域映射混合检索

使用说明（Markdown 格式）

项目概述

  • Smooth.CodeRepositoryIndexMcp 是一个完整的 MCP 服务器实现，支持通过 MCP 协议向 AI 客户端提供资源（资源索引、数据访问）、工具（调用外部功能）以及提示模板（Prompts）的能力。服务器端负责会话管理、能力声明，并支持多传输协议（HTTP API、标准输入输出等）。
  • 代码结构中包含：HTTP API 服务器、STDIO 服务器、工具实现、资源索引、AGENTS.md 支持、领域/域模型映射、以及测试覆盖等。

主要功能点

  • MCP 核心能力暴露的工具集
    • search_codebase：对已索引代码进行上下文感知的检索。
    • get_agents_context：加载指定上下文的 AGENTS.md 全文。
    • get_domain_map：返回域模型与上下文关系图。
    • get_file：按相对路径获取文件及其上下文元数据。
    • where_am_i：将文件路径解析到所属的 bounded context。
  • 多仓库索引与管理
    • 支持单仓库和多仓库模式，注册仓库、按别名解析、范围作用域（scope）的解析。
    • 通过 repos.yaml、--repos 参数或根目录推断来定义要索引的仓库集合。
  • 索引与检索体系
    • Shallow/Deep 两阶段索引：浅索引收集 AGENTS.md 与域映射，深索引进行代码分块与全文检索（Lucene）。
    • 结合 Lucene 索引与外部工具（ripgrep/grep）实现混合检索（HybridSearchService）。
    • AGENTS.md 优先级与上下文预算机制，确保领域知识在上下文中优先呈现。
  • AGENTS.md 驱动的上下文推断
    • 通过 AGENTS.md 的 Scope 和 BoundingContext 实现对文件的上下文解析与映射。
  • 容错与测试覆盖
    • 提供 Unit 测试和 Integration 测试，覆盖仓库解析、ContextMapper、AgentsMdFinder、Indexing、Lucene、FullTextStore、HybridSearch 等关键组件。

安装与运行步骤

  • 安装依赖
    • .NET 10 SDK
    • git（用于仓库根定位、变更检测等）
    • 可选：ripgrep（用于外部检索的加速）
  • 构建与运行
    • HTTP API 服务器: 通过 .NET 运行 Smooth.CodeRepositoryIndexMcp.Api 项目，启动后监听 HTTP 请求，提供 MCP JSON-RPC 2.0 接口。
    • STDIO/MCP 服务器: 通过 Smooth.CodeRepositoryIndexMcp.Cli 或对应的 MCP 入口启动 STDIO 传输模式的 MCP 服务器。
    • 多仓库模式：通过配置 repos.yaml、--repos 参数或根目录推断实现多仓库并行索引与服务分离。
  • 快速测试
    • 项目包含集成测试：McpApiTests、UnitTests 等，演示了通过 HTTP API 进行 MCP 请求、返回 JSON-RPC 的结果。

服务器配置（MCP 客户端连接信息示例） 说明：MCP 客户端需要向 MCP 服务器提供一个启动配置，以便建立连接。以下为示例描述，请将 <实际路径> 与 <repo_root> 替换为你的实际部署路径。MCP 客户端不需要读取代码实现，只需根据下面的配置信息启动连接即可。

  • HTTP API 服务器（推荐方式，适用于大多数编辑器/IDE） server_name: smooth-code-repo-index-http command: dotnet args: [ "<path_to_your_built_api_dll>/Smooth.CodeRepositoryIndexMcp.Api.dll", "--root", "<repo_root_path>" ] 注释：该配置启动一个通过 HTTP Transport 与 MCP 客户端通信的 MCP 服务器。MCP 客户端通过 HTTP 调用 / 端点进行 JSON-RPC 2.0 请求，服务器返回结果。

  • STDIO 服务器（CLI / 本地开发场景） server_name: smooth-code-repo-index-stdio command: dotnet args: [ "<path_to_built_cli_dll>/Smooth.CodeRepositoryIndexMcp.Cli.dll", "reindex", "--root", "<repo_root_path>" ] 注释：该配置通过 STDIO 传输向 MCP 客户端提供服务，适用于使用文本 IO 的开发环境。

  • 说明与参数

    • server_name: 用于标识服务器实例的名称，便于在多服务环境中区分。
    • command: 启动服务器所执行的命令，通常为 dotnet 或者脚本/二进制路径。
    • args: 启动参数数组，通常包括 --root 指向待索引的仓库根，必要时还可包含 --workspace、--repos、--config 等参数来定制多仓库环境。
    • 注释：MCP 客户端仅需要这些信息来启动连接；实际的仓库配置（如根路径、工作区、仓库定义等）由服务器端决定，客户端无需读取服务器内部实现细节。

基本使用方法

  • 启动服务器后，MCP 客户端可通过 JSON-RPC 调用以下工具：
    • where_am_i: 传入路径，返回所属 bounded context 与 AGENTS.md 路径。
    • get_agents_context: 传入 bounded context 名称，获取 AGENTS.md 内容（若缓存中存在）。
    • get_domain_map: 获取域映射文本，帮助理解上下文关系。
    • search_codebase: 根据查询在代码库中进行上下文感知的检索。
    • get_file: 获取文件及其上下文元数据。
  • 使用建议
    • 先进行仓库初始化并建立索引（需执行 index 流程，包含 shallow 和 deep 两种模式的索引）。
    • 为编辑器/IDE 配置 MCP 连接，确保在多仓库场景下正确指向目标仓库。
    • 使用 get_agents_context 和 domain_map 等工具快速了解领域边界与上下文约束。
  • 典型工作流
    • 启动 API 服务器（HTTP）或 STDIO 服务器，确保客户端能通过 MCP 协议与服务交互。
    • 调用 initialize/initialize-like 请求进行初始协商并获取服务器信息与能力清单（包含可用工具）。
    • 使用 search_codebase 与 where_am_i 组合来实现代码理解与导航。

关键词 代码索引, AGENTS.md 支持, 多仓库管理, 领域映射, 混合检索

分类ID 1

服务器信息

访问项目