使用说明
大型回购MCP服务器
基于标准 模型上下文协议 服务器被设计为大型复杂存储库的标准工具包。用途 ripgrep 用于跨任何大小的代码库进行快速、有界的搜索。
建筑
┌─────────────────────────────────────────────────────────────────┐
│ MCP Client (Codex CLI / Claude Desktop / Claude Code) │
│ │
│ tools/call ──► JSON-RPC 2.0 request │
│ Content-Length: N\r\n\r\n{...} │
└─────────────┬───────────────────────────────────▲───────────────┘
│ stdin │ stdout
▼ │
┌─────────────────────────────────────────────────────────────────┐
│ large-repo-mcp server │
│ │
│ ┌──────────┐ ┌────────────┐ ┌──────────────────────┐ │
│ │ Frame │───►│ JSON-RPC │───►│ Tool Dispatch │ │
│ │ Parser │ │ Router │ │ │ │
│ │ │ │ │ │ project_search_rg │ │
│ │ Content- │ │ initialize │ │ symbol_search │ │
│ │ Length │ │ tools/list │ │ read_range │ │
│ │ framing │ │ tools/call │ │ list_files │ │
│ └──────────┘ │ ping │ └──────────┬───────────┘ │
│ └────────────┘ │ │
│ │ │
│ ┌────────────────────────────────────────────▼──────────┐ │
│ │ Security Layer │ │
│ │ │ │
│ │ • Path confinement (resolve + realpath + root check) │ │
│ │ • Command allowlist (rg only, shell: false) │ │
│ │ • Request size limit (1 MB) │ │
│ │ • Response size limit (200 KB) │ │
│ │ • Null-byte rejection │ │
│ └───────────────────────────┬───────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ rg (ripgrep) │ │
│ │ subprocess │ │
│ │ │ │
│ │ • 15s timeout │ │
│ │ • JSON output │ │
│ │ • Streaming │ │
│ └─────────────────┘ │
│ stderr ──► │
│ structured JSON logs │
└─────────────────────────────────────────────────────────────────┘
请求流
Client Server ripgrep
│ │ │
│ Content-Length: N\r\n\r\n │ │
│ {"jsonrpc":"2.0", │ │
│ "method":"tools/call",...} │ │
│──────────────────────────────►│ │
│ │ validate request size (≤1MB) │
│ │ parse JSON-RPC frame │
│ │ validate tool + arguments │
│ │ resolve & confine paths │
│ │ │
│ │ spawn rg --json ... │
│ │──────────────────────────────►│
│ │ │
│ │ stream results (line-by-line)│
│ │◄──────────────────────────────│
│ │ │
│ │ enforce match/byte limits │
│ │ kill rg if limit reached │
│ │ │
│ Content-Length: M\r\n\r\n │ │
│ {"jsonrpc":"2.0", │ │
│ "result":{...}} │ │
│◄──────────────────────────────│ │
│ │ │
安全保证
| 保证 | 机制 | 限额 |
|---|---|---|
| 快速、有界搜索 | 带匹配上限的ripgrep | 最多500个匹配 |
| 响应大小上限 | 字节级输出预算 | 200 KB |
| 子进程超时 | setTimeout + child.kill() |
15秒 |
| 路径限制 | path.resolve + realpath +根前缀检查 |
仅限repo根 |
| Symlink防逃逸 | fs.realpath() 解析然后重新验证 |
双重检查 |
| 命令执行 | 允许列表(rg 仅）+ shell: false |
无壳注射 |
| 请求大小限制 | 解析前帧级拒绝 | 1 MB |
| 输入净化 | 空字节拒绝、类型验证 | 所有工具输入 |
| 子进程清理 | 跟踪集，在关机信号时被杀死 | SIGTERM/SIGINT/exit |
支持的客户端
- Codex 命令行界面
- 克劳德桌面
- 克劳德代码
- 任何支持stdio传输的MCP客户端（协议版本
2024-11-05)
需求
- Node.js 18+
- ripgrep (
rg)onPATHsymbol_search需要PCRE2支持（大多数官方软件包都包含它）
验证ripgrep：
rg --version # should show version
rg --pcre2-version # should show PCRE2 version
安装ripgrep：
| 平台 | 命令 |
|---|---|
| macOS | brew install ripgrep |
| Ubuntu/Debian | sudo apt-get install ripgrep |
| Fedora | sudo dnf install ripgrep |
| 窗户 | winget install BurntSushi.ripgrep.MSVC |
| 货物 | cargo install ripgrep --features pcre2 |
安装
npm install
npm run build
跑
npm start
默认回购根行为：
- 如果
REPO_ROOT未设置，repo根目录是当前工作目录(process.cwd()). - 集
REPO_ROOT明确地覆盖。
PowerShell：
$env:REPO_ROOT = "C:\absolute\path\to\repo"
npm start
MCP配置
食品法典委员会（全球）
添加 ~/.codex/config.toml:
[mcp_servers.large_repo_mcp]
command = "node"
args = ["C:/absolute/path/to/mcp/dist/server.js"]
startup_timeout_sec = 30
[mcp_servers.large_repo_mcp.env]
REPO_ROOT = "."
食品法典委员会（地方项目）
添加 .codex/config.toml 在一个项目中：
[mcp_servers.large_repo_mcp]
command = "node"
args = ["C:/absolute/path/to/mcp/dist/server.js"]
startup_timeout_sec = 30
[mcp_servers.large_repo_mcp.env]
REPO_ROOT = "."
克劳德桌面
添加到克劳德桌面MCP配置：
{
"mcpServers": {
"large_repo_mcp": {
"command": "node",
"args": ["C:/absolute/path/to/mcp/dist/server.js"],
"env": {
"REPO_ROOT": "C:/absolute/path/to/target-repo"
}
}
}
}
克劳德代码
添加 .mcp.json 在一个项目或 ~/.claude/mcp.json 全球地：
{
"mcpServers": {
"large_repo_mcp": {
"command": "node",
"args": ["C:/absolute/path/to/mcp/dist/server.js"],
"env": {
"REPO_ROOT": "."
}
}
}
}
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
REPO_ROOT |
process.cwd() |
存储库根目录 |
LARGE_REPO_MCP_LOG_LEVEL |
error |
日志级别： error, warn, info, debug |
LARGE_REPO_MCP_DEBUG |
-- | 设置为 1 强制调试日志记录 |
工具
project_search_rg
使用ripgrep搜索存储库。支持正则表达式模式和可选的glob过滤器。
┌──────────────────────────────────────────────────────┐
│ project_search_rg │
│ │
│ Input Output │
│ ───── ────── │
│ pattern (string, required) matches[] │
│ globs (string[], max 50) .path │
│ maxMatches (1-500, def 100) .line │
│ .column │
│ .text │
│ .submatches[] │
│ truncated │
│ truncateReason │
│ timedOut │
│ serverVersion │
│ durationMs │
└──────────────────────────────────────────────────────┘
示例调用：
{
"name": "project_search_rg",
"arguments": {
"pattern": "TODO|FIXME",
"globs": ["*.ts", "*.tsx"],
"maxMatches": 50
}
}
symbol_search
使用单词边界匹配搜索精确的符号(\b...\b).自动检测项目类型（TypeScript或Python）并相应地限定文件类型。
┌──────────────────────────────────────────────────────┐
│ symbol_search │
│ │
│ Input Output │
│ ───── ────── │
│ symbol (string, required) projectType │
│ maxMatches (1-500, def 100) matchMode │
│ matches[] │
│ .path │
│ Detection logic: .line │
│ ┌────────────────────┐ .column │
│ │ tsconfig.json? │ .text │
│ │ yes → typescript │ .submatches[] │
│ │ no → check files │ │
│ │ .py only → python│ │
│ │ .ts only → ts │ │
│ │ fallback → ts │ │
│ └────────────────────┘ │
└──────────────────────────────────────────────────────┘
示例调用：
{
"name": "symbol_search",
"arguments": {
"symbol": "handleRequest",
"maxMatches": 20
}
}
read_range
从文件中读取特定的行范围。路径必须是相对的，并在repo根目录内解析。
┌──────────────────────────────────────────────────────┐
│ read_range │
│ │
│ Input Output │
│ ───── ────── │
│ path (relative, required) path (normalized) │
│ startLine (int, required) requestedLines │
│ endLine (int, required) returnedLines │
│ lines[] │
│ Constraints: .line │
│ • max 500 lines per call .text │
│ • path confined to repo root truncated │
│ • symlinks resolved + checked truncateReason │
└──────────────────────────────────────────────────────┘
示例调用：
{
"name": "read_range",
"arguments": {
"path": "src/server.ts",
"startLine": 1,
"endLine": 50
}
}
list_files
使用ripgrep列出存储库文件 --files 带有可选的球形过滤器。不包括 .git, node_modules, dist, build，以及 coverage 默认情况下。
┌──────────────────────────────────────────────────────┐
│ list_files │
│ │
│ Input Output │
│ ───── ────── │
│ globs (string[], max 50) files[] (paths) │
│ maxResults (1-500, def 500) returned │
│ truncated │
│ Auto-excluded dirs: truncateReason │
│ .git, node_modules, dist, timedOut │
│ build, coverage │
└──────────────────────────────────────────────────────┘
示例调用：
{
"name": "list_files",
"arguments": {
"globs": ["src/**/*.ts"],
"maxResults": 100
}
}
项目类型检测
服务器自动检测存储库的作用域是TypeScript还是Python symbol_search 文件类型。每个进程运行一次检测并缓存。
┌─────────────────────┐
│ tsconfig.json │
│ exists? │
└──────┬──────────────┘
yes │ no
┌──────────┘ │
▼ ▼
┌──────────┐ ┌────────────────────┐
│TYPESCRIPT│ │ Python project │
└──────────┘ │ file exists? │
│ (pyproject.toml, │
│ requirements.txt, │
│ setup.py, etc.) │
└──────┬─────────────┘
yes │ no
┌──────────┤ │
▼ │ ▼
┌────────────┐ │ ┌──────────────────┐
│package.json│ │ │ package.json │
│ exists? │ │ │ exists? │
└─────┬──────┘ │ └──────┬───────────┘
yes │ no │ yes │ no
│ │ │ │ │ │ │
▼ │ ▼ │ ▼ │ ▼
┌────────┐│ ┌──────┐ │ ┌──────────┐ ┌──────────────┐
│ Both ││ │PYTHON│ │ │TYPESCRIPT│ │ Count .ts vs │
│ scan ││ └──────┘ │ └──────────┘ │ .py files │
│ files │▼ ▼ └──────┬───────┘
└───┬────┘ ┌──────────┐ more │ more
│ │ No pkg, │ .py │ .ts
▼ │ has py │ │ │
┌────────────┐ │ file → │ ▼ ▼
│ .py only → │ │ PYTHON │ ┌──────┐ ┌──┐
│ PYTHON │ └──────────┘ │PYTHON│ │TS│
│ .ts only → │ └──────┘ └──┘
│ TS │
│ fallback → │
│ TS │
└────────────┘
开发工作流程
npm run typecheck # type-check without emitting
npm test # build + run unit & integration tests
npm run lint # run ESLint
npm run format:check # check Prettier formatting
故障排除
| 问题 | 解决方案 |
|---|---|
rg 未找到 |
安装ripgrep并确保其已打开 PATH |
symbol_search PCRE2错误 |
安装支持PCRE2的ripgrep（大多数官方软件包都包含它） |
Request exceeds 1048576 bytes |
拆分大型请求；最大入站JSON-RPC帧体为1 MB |
truncated: true |
增加 maxMatches/maxResults （上限）、缩小查询范围或添加glob |
没有结果 symbol_search |
检查 projectType 作为响应，检测可能选择了错误的语言；使用 project_search_rg 作为退路 |
许可证
麻省理工学院