Smooth Code Repo Index MCP

光滑。代码仓库索引Mcp

用于AI编码代理的Monrepo代码索引和检索，具有一流的 AGENTS.md 支持。

AI代理？ 请您的AI编码代理设置此仓库： AI编码代理设置说明

光滑。CodeRepositoryIndexMcp为AI代理（Claude Code、Cursor、GitHub Copilot等）提供结构化、上下文感知的代码库访问。 *AGENTS.md 文件被视为 一等公民 --领域知识的权威来源，总是在任何代码之前加载，从不从上下文预算中删除。在monorepo中，它们是帮助代理理解 什么：这个有界的上下文有什么作用，适用什么规则，已经做出了什么决定。

目录

• 这如何帮助AI编码代理
• 正在写入AGENTS.md文件
• 入门指南

- 先决条件 - AI编码代理设置说明 - 人工设置指南

• MCP工具

- MCP工具参考

• CLI参考
• 贡献
• 工作原理、架构决策和搜索质量
• 许可证

______________________________________________________________________

这如何帮助AI编码代理

没有它，代理依赖于盲搜索(grep, find, read)--在不了解代码库组织方式的情况下猜测文件位置。

有了它，代理商可以获得：

• where_am_i --在进行更改之前，知道文件属于哪个有界上下文，防止意外的跨域修改。
• get_agents_context --加载上下文的AGENTS.md，获取显式声明的规则、模式和约束，而不是从代码中推断出来。
• get_domain_map --查看上下文之间关系的全貌，这在变化可能产生跨领域影响时非常有用。
• search_codebase --上下文感知、优先级排序搜索。关键文件排名较高，结果会自动包含相关的AGENTS.md。
• get_file --检索文件及其上下文元数据，以便代理知道适用哪些域规则。

实际区别在于：在大型单仓库中，最难的部分不是编写代码，而是了解你在哪里以及适用什么规则。此工具解决了方向问题。AGENTS.md-first方法预先加载防止错误的知识，而不是希望代理通过阅读足够的代码来发现约定。

写你的 *AGENTS.md 文件

工具的质量与您的质量成正比 *AGENTS.md 文件夹。建议的方法是创建 **本地化的 *AGENTS.md 域、子域、特征和有界上下文级别的文件** --很少更深。每个文件都捕获了源代码本身无法传达的上下文知识：决策背后的原因、不明显的行为、跨领域的约束，以及AI代理在该上下文中必须遵循的规则。

使用精益AI编码器模板 作为您的基础结构： .ai/templates/TEMPLATE_AGENTS.md它提供了一个有重点的框架，当与质量标准规则结合时，它会产生所需的部分（TL；DR、不可协商、系统上下文、架构决策、关键行为、变更日志），同时将文件集中在人工智能编码器的需求上，而不是人类产品文档上。

将模板与质量标准规则配对: .ai/rules/knowledge-conventional-contexts-quality.instructions.md该规则定义了所需的节顺序、三部分值测试（错误预防、决策质量、系统理解）、要避免的反模式和漂移最小化义务。将其与模板一起使用——最好是将其添加到AI代理的规则中——以获得以AI编码器为中心的AGENTS.md文件，其内容单独缓存，并在代码结果之前自动添加到每个搜索响应中。

______________________________________________________________________

入门指南

先决条件

• .NET 10 SDK
• git
• 可选： ripgrep --使用正则表达式和模糊匹配增强搜索

安装ripgrep：

# macOS (Apple Silicon / Intel)
brew install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

# Linux (Debian/Ubuntu)
sudo apt install ripgrep

AI编码代理设置说明

本节供AI编码代理（Claude Code、Cursor、GitHub Copilot、Windsurf等）阅读此自述文件。 如果您是协助人类开发人员的AI代理，请按照以下说明设置Smooth。CodeRepositoryIndexMcp用于用户的存储库。

当用户要求您为他们的仓库设置MCP索引器时，或者当您检测到此工具可用但未配置时， 询问用户是否希望您进行设置目标是人类无需付出任何努力。

步骤1：确保安装了必备组件

验证用户是否具备所需的先决条件：

• .NET 10 SDK --需要 dotnet tool install
• git
• 可选： ripgrep --使用正则表达式和模糊匹配增强搜索

如果。NET SDK缺失，请引导用户在继续之前安装它。

步骤2：确定用户的编辑器

询问用户他们正在使用哪种AI编码工具，然后按照以下适当的路径进行操作。

步骤3：安装或更新工具

安装或更新到最新版本：

dotnet tool update -g Smooth.CodeRepositoryIndexMcp --prerelease
dotnet tool update -g Smooth.CodeRepositoryIndexMcp.Cli --prerelease

注： dotnet tool update -g 如果缺少该工具，则安装该工具；如果已安装，则更新该工具——它可以处理这两种情况。 --prerelease 是必需的，因为此软件包尚未达到稳定的1.0版本。

步骤4：为回购建立索引

smooth-code-repo-index index --root .

这将创建一个浅索引并安装一个 post-merge git自动挂钩。对于全文搜索，请添加 --deep.

步骤5：添加 .index/ 到 .gitignore --必须

不要跳过此步骤。 这 .index/ 目录包含生成的数据，这些数据永远不能提交。

# Check if .index/ is already in .gitignore (ensures newline before appending)
grep -q '\.index/' .gitignore 2>/dev/null || { [ -s .gitignore ] && [ -n "$(tail -c1 .gitignore)" ] && echo >> .gitignore; echo '.index/' >> .gitignore; }

步骤6：为用户编辑器配置MCP

克劳德代码：

在用户级别注册MCP服务器，使其在所有项目和工作树中工作：

claude mcp add -s user smooth-repo-index -- bash -c 'smooth-code-repo-index-mcp --root "$(git rev-parse --git-common-dir | sed '\''s/\.git$//'\'')"'

注： 项目级别 .claude/mcp.json 在git工作树中不起作用。用户级注册避免了这种限制。

对于光标：

创建 .cursor/mcp.json （或符号链接 .ai/ 到 .cursor/):

{
  "mcpServers": {
    "smooth-repo-index": {
      "command": "bash",
      "args": ["-c", "smooth-code-repo-index-mcp --root \"$(git rev-parse --git-common-dir | sed 's/\\.git$//')\""]
    }
  }
}

或者，如果回购已经 .ai/mcp.json:

ln -s .ai .cursor

对于GitHub Copilot（VS代码）：

推荐： 使用带有stdio传输的.NET工具（如下）。它比HTTP/API服务器更可靠，测试也更好。API服务器是不支持stdio MCP的编辑器的后备方案。

VS Code中的GitHub Copilot（1.99+）支持stdio MCP服务器。创建 .vscode/mcp.json:

{
  "servers": {
    "smooth-repo-index": {
      "type": "stdio",
      "command": "bash",
      "args": ["-c", "smooth-code-repo-index-mcp --root \"$(git rev-parse --git-common-dir | sed 's/\\.git$//')\""]
    }
  }
}

适用于GitHub Copilot CLI （终端， gh copilot 交互模式）：

Copilot CLI使用单独的配置文件： ~/.copilot/mcp-config.json （Linux/macOS）或 %USERPROFILE%\.copilot\mcp-config.json （Windows）。CLI还支持 /mcp add 在交互模式下，作为直接编辑文件的替代方案。

使用Git Bash的Mac/Linux或Windows：

{
  "mcpServers": {
    "smooth-repo-index": {
      "type": "stdio",
      "command": "bash",
      "args": ["-c", "smooth-code-repo-index-mcp --root \"$(git rev-parse --show-toplevel)\""],
      "tools": ["*"]
    }
  }
}

Windows（PowerShell，没有Git Bash）：

{
  "mcpServers": {
    "smooth-repo-index": {
      "type": "stdio",
      "command": "pwsh",
      "args": ["-Command", "smooth-code-repo-index-mcp --root `\"$(git rev-parse --show-toplevel)`\""],
      "tools": ["*"]
    }
  }
}

或通过 /mcp add 在Copilot CLI交互模式下——出现提示时，提供：

• 姓名： smooth-repo-index
• 服务器类型： 2 — 工作室
• 命令（Mac/Linux/Windows+Git Bash）： bash -c 'smooth-code-repo-index-mcp --root "$(git rev-parse --show-toplevel)"'
• 命令（Windows PowerShell，无Git Bash）： ` pwsh -Command "smooth-code-repo-index-mcp --root "$(git rev-parse --show-toplevel)"" `
• 环境变量： （留空）
• 工具： *

对于需要HTTP传输的编辑器（API服务器）：

⚠️ 注： 尚未对HTTP/API传输进行广泛测试。Claude Code（stdio）是主要支持和测试的配置。仅当编辑器不支持stdio MCP时，才使用API服务器。

对于需要HTTP传输的编辑器，API服务器在容器中运行。检测可用的容器运行时，然后帮助用户设置Compose：

# Detect container runtime
docker --version 2>/dev/null && RUNTIME=docker || { podman --version 2>/dev/null && RUNTIME=podman; }

Podman用户： 全部 docker 和 docker compose 下面的命令与 podman 和 podman compose。相应替换。

1. 创建 .docker/.env 从示例中可以看出：

WORKSPACE_PATH=./workspace
REPO1_PATH=/absolute/path/to/this/repo

1. 创建 .docker/repos.yaml:

repos:
  this-repo:
    path: /repos/repo1

1. 启动API服务器：

$RUNTIME compose -f .docker/docker-compose.yaml up -d api

1. 配置编辑器以指向 http://localhost:5224.

稍后添加更多存储库： 要索引其他存储库，请在中添加卷装载 docker-compose.yaml，更新 repos.yaml 使用新的别名/路径，并重新启动容器(docker compose restart api).

步骤7：将MCP使用说明添加到目标仓库的CLAUDE.md--MUST

不要跳过此步骤。 如果没有这些说明，AI代理将不会使用MCP工具，并将回退到grep/find。

添加 下面是精确的标记块 逐字到 CLAUDE.md （或 AGENTS.md)of 您为其启用此功能的仓库 --不是 smooth-code-repo-index-mcp 项目本身。如果用户有root CLAUDE.md 这适用于他们所有的项目（例如。 ~/source/CLAUDE.md)，将其添加到那里，这样所有repos都会自动受益。请勿对其进行意译、总结或重写：

## Codebase Navigation (MCP) — Non-Negotiable

When the `smooth-repo-index` MCP tools are available, they are the **primary and required** code discovery method. Do NOT use Grep, Glob, find, rg, or grep for searching code — use the MCP tools.

| Task | Use | Do NOT use |
|:-----|:----|:-----------|
| Search code | `search_codebase` | Grep, rg, grep, find |
| Identify context | `where_am_i` | Manual path inspection |
| Load context | `get_agents_context` | Read on AGENTS.md files |
| Understand repo structure | `get_domain_map` | Glob + manual scanning |
| Read file with metadata | `get_file` | Read (unless MCP unavailable) |

Only fall back to Grep/Glob/Read if the MCP server is not connected or a tool call fails.

步骤7b：将AGENTS.md质量标准添加到目标仓库的根AGENTS.md--MUST

不要跳过此步骤。 结构良好的AGENTS.md文件索引为 critical 优先级，并且始终在搜索结果中的代码之前加载。它们是改进的主要机制 search_codebase 排名和 get_agents_context 整个仓库的检索质量。

添加 下面是精确的标记块 逐字到 根 AGENTS.md 目标仓库的根目录（如果不存在，请在仓库根目录创建一个）。不要改写或改写它：

## Contextual Knowledge Standards

AGENTS.md files are indexed at `critical` priority by the MCP server and their content is always loaded before code in search results. Well-maintained AGENTS.md files directly improve `search_codebase` ranking and `get_agents_context` retrieval — they are the primary mechanism for optimizing what the MCP returns to AI agents.

步骤8：验证

设置后使用其工具之一确认MCP服务器正在工作（例如。， get_domain_map 或 where_am_i).如果已连接，请向用户报告成功。如果没有，请检查.NET工具是否在PATH上，编辑器是否已重新加载其MCP配置。

更新

要将工具更新到最新版本，请执行以下操作：

dotnet tool update -g Smooth.CodeRepositoryIndexMcp --prerelease
dotnet tool update -g Smooth.CodeRepositoryIndexMcp.Cli --prerelease

对于HTTP/API服务器（Docker/Podman）：

docker pull ghcr.io/generik0/smooth-code-repo-index-mcp:latest
docker compose -f .docker/docker-compose.yaml up -d api

MCP服务器在启动时重建所有索引，因此更新后不需要手动重新索引。

卸载

完全删除平滑。代码仓库中的CodeRepositoryIndexMcp：

1. 移除git钩子： rm .git/hooks/post-merge
2. 删除索引目录： rm -rf .index/
3. 删除 .index/ 进入 .gitignore
4. 删除MCP注册：

- 克劳德代码： claude mcp remove -s user smooth-repo-index - 光标： 删除 .cursor/mcp.json （或符号链接） - GitHub副本（VS代码）： 删除 .vscode/mcp.json - GitHub Copilot命令行界面： 移除 smooth-repo-index 进入 ~/.copilot/mcp-config.json （Linux/macOS）或 %USERPROFILE%\.copilot\mcp-config.json （Windows） - HTTP/API： 停止集装箱(docker compose -f .docker/docker-compose.yaml down)

1. 卸载工具（可选）： dotnet tool uninstall -g Smooth.CodeRepositoryIndexMcp && dotnet tool uninstall -g Smooth.CodeRepositoryIndexMcp.Cli

注： 卸载.NET工具 不 移除 post-merge 挂钩或 .index/ 安装它们的repos目录。按照步骤1-3手动清理。

AI代理摘要

当用户说“设置索引器”或您看到此仓库的工具可用时：

1. 问： *您想让我为此仓库设置Smooth.CodeRepositoryIndexMcp吗？我将安装工具，对代码库进行索引，并配置编辑器的MCP连接*
2. 验证先决条件（.NET 10 SDK，git）
3. 从上下文中检测编辑器（哪个代理正在运行）
4. 如果需要HTTP传输：检测容器运行时(docker --version → 后备方案 podman --version)
5. 安装或更新工具至最新版本
6. 跑 smooth-code-repo-index index --root .
7. 必须： 添加 .index/ 到 .gitignore --生成的数据不得提交
8. 编写相应的MCP配置文件：

- 克劳德代码： claude mcp add -s user smooth-repo-index ... - 光标： .cursor/mcp.json - GitHub副本（VS代码1.99+）： .vscode/mcp.json 随着 "servers" 键（与游标格式相同的stdio格式） - GitHub Copilot CLI（终端）： ~/.copilot/mcp-config.json （Linux/macOS）或 %USERPROFILE%\.copilot\mcp-config.json （Windows）带 "mcpServers" 密钥；使用 bash 在Mac/Linux/Windows+Git Bash上运行命令，或 pwsh 在没有Git Bash的Windows上；或者使用 /mcp add 在交互模式下（见步骤6） - HTTP传输： 在上旋转API容器和点编辑器 http://localhost:5224

1. 必须： 将MCP使用说明添加到 目标 回购 CLAUDE.md （不是平滑回购指数mcp项目）——没有这个，代理就不会使用mcp工具。如果根 CLAUDE.md 涵盖所有项目的存在，更喜欢这样。
2. 必须： 将AGENTS.md质量标准块添加到目标仓库的根目录 AGENTS.md （如果缺失，则创建）-这告诉未来的人工智能代理在编写上下文知识文档时要遵循哪些模板和质量标准，直接提高搜索和索引质量。
3. 验证连接是否正常

人类不需要手动做任何事情。

AI代理：停在这里。 以下部分适用于手动设置的人类开发人员。不要执行这些步骤，而是使用上面的AI设置说明。

______________________________________________________________________

人体设置说明

有关手动设置（安装、索引、编辑器配置、CLI使用、容器运行时、卸载），请参阅 人工设置指南.

______________________________________________________________________

MCP工具

当作为MCP服务器（stdio或HTTP）运行时，会暴露五个工具：

所有工具都接受可选 repo 多仓库模式的参数。当a --scope 在服务器上设置，工具默认为该仓库。

有关完整的刀具参数说明，请参见 MCP工具参考.

CLI参考

有关完整的命令参考和配置选项，请参阅 CLI参考.

______________________________________________________________________

贡献

有关本地开发设置、运行测试、发布二进制文件、代码标准和AI DevEx配置，请参阅 贡献指南.

______________________________________________________________________

工作原理、架构决策和搜索质量

有关索引管道、架构决策记录（ADR）和搜索质量报告的完整说明，请参阅 运作原理.

______________________________________________________________________

许可证

麻省理工学院——见 许可证.

此项目包括Apache License 2.0下的第三方依赖关系。看 第三方通知S.md 了解详情。