Codebase RAG MCP

一个本地优先、无需 API Key 的代码库检索 MCP Server。它扫描指定仓库，按代码窗口分块，并通过 BM25、符号名、文件路径和精确匹配进行混合排序，可直接接入 Codex，也提供标准 search / fetch 工具用于 ChatGPT 知识检索场景。

功能

• 优先使用 git ls-files，遵守仓库的嵌套 .gitignore；非 Git 目录使用文件系统扫描。
• 支持 TypeScript、JavaScript、Python、Go、Rust、Java、C/C++、C#、Ruby、Shell、SQL、Markdown、Vue、Svelte 等常见文本代码格式。
• 自动拆分 camelCase、snake_case 和路径词，支持常见中文代码查询扩展，例如“用户登录认证”。
• 返回精确文件路径、行号、带行号代码片段、匹配原因和可继续读取的稳定 ID。
• 路径读取限定在配置的仓库根目录；默认跳过符号链接、二进制、密钥、环境变量文件、压缩代码和大文件。
• 同时支持本地 stdio 与无状态 Streamable HTTP /mcp。

快速开始

要求 Node.js 20 或更高版本。

从 GitHub 获取项目：

git clone https://github.com/sudoriaa/codebase-rag-mcp.git
cd codebase-rag-mcp

安装依赖并构建：

npm install
npm run build
node dist/cli.js --root C:/path/to/your-repository

最后一条命令会启动 stdio MCP Server，它会等待 MCP 客户端连接，因此终端保持运行属于正常状态。

接入 Codex

将以下内容放进用户级 %USERPROFILE%/.codex/config.toml，或者受信任仓库的 .codex/config.toml：

[mcp_servers.codebase-rag]
command = "C:/Program Files/nodejs/node.exe"
args = [
  "C:/absolute/path/codebase-rag-mcp/dist/cli.js",
  "--root",
  "C:/absolute/path/your-repository"
]
cwd = "C:/absolute/path/codebase-rag-mcp"
startup_timeout_sec = 60
tool_timeout_sec = 120

Windows TOML 路径建议使用 /。command 只填写可执行程序，其他参数分别放入 args。桌面应用继承的 PATH 可能与 PowerShell 不同，因此长期使用时建议填写 node.exe 的绝对路径。

也可以用 CLI 注册：

codex mcp add codebase-rag -- "C:\Program Files\nodejs\node.exe" "C:\absolute\path\codebase-rag-mcp\dist\cli.js" --root "C:\absolute\path\your-repository"
codex mcp get codebase-rag --json

配置后重启 Codex 桌面应用或 IDE 扩展。示例配置见 examples/codex-config.toml。

启动 HTTP MCP

node dist/cli.js --root C:/path/to/your-repository --transport http --host 127.0.0.1 --port 3000

端点：

• MCP：http://127.0.0.1:3000/mcp
• 健康检查：http://127.0.0.1:3000/health
• 引用源文件：http://127.0.0.1:3000/source/:documentId

默认仅监听本机。部署到其他机器时，应在反向代理层加入 TLS、身份认证和访问控制，并用 --public-base-url 设置模型可访问的规范地址。

直接监听 0.0.0.0 或其他非本机地址时，服务会要求设置 Bearer Token：

$env:CODEBASE_MCP_TOKEN = "replace-with-a-long-random-token"
node dist/cli.js --root C:/path/to/your-repository --transport http --host 0.0.0.0 --port 3000

客户端随后需要为 /mcp 和 /health 发送 Authorization: Bearer <token>。服务返回的引用地址会自动附带 HMAC 签名，因此用户可以直接打开对应 /source 链接；手工访问未签名的 /source 地址仍需 Bearer Token。通过本机反向代理发布时，可以继续让服务监听 127.0.0.1，并由代理负责外部认证。

MCP 工具

工具	用途
search	标准文档搜索，返回 id/title/url
fetch	根据 search 返回的 ID 获取完整文件
search_code	混合检索代码片段，可按路径、语言、符号类型和测试文件过滤
get_code_context	根据 chunk ID 获取前后文，最多扩展 200 行
find_symbol	查找类、函数、方法、接口、类型和枚举定义
get_file_outline	返回文件的 imports 和符号大纲
get_index_status	查看索引统计及跳过原因
refresh_index	文件变化后重新扫描并重建内存索引

推荐调用顺序：

1. 用 search_code 查找实现和相关片段。
2. 用 get_code_context 展开高分片段。
3. 精确定位定义时用 find_symbol。
4. 只有确实需要完整文件时再用 fetch。

检索方式

索引完全运行在本机内存中：

1. 代码文件按最多 120 行、20 行重叠切片。
2. 从常见语言声明中提取 class、interface、type、enum、function、method 等符号。
3. 正文使用 BM25 召回，符号和路径单独排序。
4. 使用 reciprocal-rank fusion 合并正文、符号、路径和精确匹配得分。
5. 默认每个文件最多返回两个片段，避免重复模板代码占满结果。

这一版没有外部向量数据库，也不会上传源码。对于大规模多仓库、跨语言语义检索，可以在现有 CodebaseIndex.search 前后增加 embedding 召回或 reranker，MCP 工具契约无需变化。

配置

--root PATH
--transport stdio|http
--host HOST
--port PORT
--public-base-url URL
--max-file-bytes N
--max-files N

对应环境变量为：

CODEBASE_ROOT
CODEBASE_TRANSPORT
CODEBASE_HOST
CODEBASE_PORT
CODEBASE_PUBLIC_BASE_URL
CODEBASE_MCP_TOKEN
CODEBASE_MAX_FILE_BYTES
CODEBASE_MAX_FILES

默认单文件上限为 1 MiB，文件数量上限为 20,000。

开发与验证

npm run build
npm test

测试覆盖索引构建、.gitignore、中文查询扩展、符号与路径过滤、路径越界、标准 search/fetch、内存 MCP、真实 stdio 子进程和 Streamable HTTP。

MCP Inspector 也可以直接检查 HTTP 服务：

npx @modelcontextprotocol/inspector

然后选择 Streamable HTTP 并填写 http://127.0.0.1:3000/mcp。

实现遵循 OpenAI 官方 MCP Server 指南及标准 search / fetch 数据形状。

当前边界

• 索引在进程重启后重建，没有持久化缓存。
• Git 仓库完整遵守 Git 忽略规则；非 Git 目录目前读取根目录 .gitignore。
• 符号抽取采用轻量声明解析，不等同于完整编译器 AST。
• 文件变化后调用 refresh_index；当前版本未启用文件监听。

License

MIT