repo-context-mcp 快速入门

这是什么？适合谁？

repo-context-mcp 是一个帮助 AI coding agent 理解仓库的 MCP server——不把整个 monorepo 倒进提示词。它提供三个聚焦工具：repo_map（轻量目录树 + manifest/入口文件）、search_code（快速子串搜索，返回 path:line）、pack_context（按 token 预算打包 markdown 上下文）。本地运行、无云、无遥测、stdio 传输。94 个 fork 的异常高占比反映其工程实用性被社区认可。

适合人群：在大型代码库里用 Codex / Claude Code / Cursor / Cline 的开发者、苦于 Agent 浪费 token 重新遍历 node_modules 的用户、想给 Agent 提供精简高效上下文的团队。 使用前提：Node.js 18+、任一 MCP 客户端。

快速上手（3 步）

第一步：安装

# 从源码运行
git clone https://github.com/nduc99911/repo-context-mcp.git
cd repo-context-mcp
npm install
npm run build

# 或（发布后）npx 一键运行
npx -y repo-context-mcp

第二步：注册到 MCP 客户端

在 Codex / Claude Code / Cursor / Cline 的 MCP 配置中添加 server，启动命令指向 node dist/...（或 npx）。

第三步：先跑 CLI 验证

不接 MCP 客户端也能直接体验：

node dist/cli.js map .                        # 当前仓库的 repo map
node dist/cli.js search login examples/sample-repo   # 子串搜索

初级用法

• repo_map：让 Agent 先调 repo_map 建立”地图感”——目录树 + manifest + 入口，几个 token 换全局视野。
• search_code：找具体实现时用子串搜索直接拿到 path:line 命中，代替 Agent 盲目读文件。
• pack_context：给一个 token 预算，它产出打包好的 markdown 上下文，适合”把相关代码带进这次对话”的场景。

高级玩法

1. 固定工作流：在 AGENTS.md / CLAUDE.md 里写死”先 repo_map → search_code 定位 → pack_context 装配”的三步上下文协议，Agent 不再自由发挥。
2. 大库 token 节流：对 10 万行级 monorepo，用 pack_context 的 token 预算硬约束，把上下文成本从”整个仓库”降到”相关切片”。
3. CI 里生成仓库快照：用 CLI 的 map 输出做 PR 描述里的结构摘要，或接入文档站。

常见踩坑（5 条）

踩坑 1：Node 版本过低

• 现象：构建或运行报错
• 原因：要求 Node.js 18+
• 解决：升级 Node 后 npm run build 重来

踩坑 2：期待语义搜索

• 现象：搜”处理用户登录的函数”没结果
• 原因：search_code 是子串搜索，不是 embedding 语义检索
• 解决：用具体标识符（函数名/类名/错误字符串）搜索，语义定位交给 Agent 推理

踩坑 3：把 pack_context 当全量导出

• 现象：预算设得过大失去意义
• 原因：工具设计目标是”预算内的精准切片”
• 解决：从小预算开始，按需扩

踩坑 4：stdio 传输配置错

• 现象：客户端连不上 server
• 原因：MCP 配置的启动命令/路径不对
• 解决：先在终端跑通 node dist/cli.js map .，再把同一命令写进配置

踩坑 5：在 node_modules 巨大的仓库跑 map

• 现象：map 输出冗长
• 原因：默认包含范围可能覆盖依赖目录（以实现为准）
• 解决：按仓库文档配置忽略规则（如有）；先在 sample-repo 上体验预期输出形态

FAQ（5 个常见问题）

Q1：repo-context-mcp 免费吗？ A：MIT 开源免费，本地运行零成本。

Q2：和 Claude Code 自带 的代码检索有什么区别？ A：自带检索绑定单一产品；本工具走 MCP 标准，Codex、Claude Code、Cursor、Cline 通用，且三个工具的输出形态专为 token 效率设计。

Q3：会上传我的代码吗？ A：不会——local-only、no cloud、no telemetry，stdio 传输全程本机。

Q4：支持哪些语言的项目？ A：repo_map 基于目录结构与 manifest/入口文件，天然语言无关；search_code 是纯文本子串匹配，同样语言无关。

Q5：npx 包发布了吗？ A：README 标注 “after publish”——发布状态以 npmjs 为准，未发布前用源码方式运行。

小技巧（5 条）

1. 先 CLI 后 MCP：用 CLI 在样例仓库理解三个工具的输出形态，再接客户端。
2. 搜索用错误字符串：报错信息里的独特子串是最佳搜索词。
3. 预算阶梯：pack_context 先 4k 预算看不够再加，比一次性 32k 更省。
4. map 结果缓存进会话：让 Agent 在会话开头调一次 repo_map 后复用结论。
5. 和 grep/rg 互补：精确找文本用 search_code，复杂正则仍可让 Agent 调 ripgrep。

进阶学习建议

• 阅读三个工具的实现（树构建、子串索引、预算打包），理解”token 经济学”如何驱动工具设计
• 把”map → search → pack”三步协议写进你所有仓库的 AGENTS.md，实测 token 节省比例
• 对比 Aider 的 repo map 与本方案的异同，思考入口文件识别策略
• 基于 stdio MCP 的无遥测设计，为团队内网环境做一次安全部署评审

参考链接

• repo-context-mcp GitHub 仓库

本文基于公开资料于 2026-08-17 整理，社区指标反映 GitHub 公开数据。独立实测未进行，功能和配置项可能随版本更新而变化，请以官方文档为准。