# 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 获取项目：

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

安装依赖并构建：

```powershell
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`：

```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 注册：

```powershell
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`](examples/codex-config.toml)。

### 启动 HTTP MCP

```powershell
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：

```powershell
$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 工具契约无需变化。

## 配置

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

对应环境变量为：

```text
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。

## 开发与验证

```powershell
npm run build
npm test
```

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

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

```powershell
npx @modelcontextprotocol/inspector
```

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

实现遵循 [OpenAI 官方 MCP Server 指南](https://developers.openai.com/plugins/build/mcp-server)及标准 [`search` / `fetch` 数据形状](https://developers.openai.com/api/docs/mcp)。

## 当前边界

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

## License

MIT