OpenGrok MCP Server

共 31 个工具：Code Mode 中有 2–5 个（opengrok_api + opengrok_execute，以及在 OPENGROK_ENABLE_MEMORY_TOOLS=true 时提供的 3 个记忆工具），标准模式中有 26 个（OPENGROK_CODE_MODE=false）。

主要工具

组合工具

这些工具会将多个 API 调用合并为一次操作。

调查工具

（注意：搜索工具支持按语言筛选。请使用规范分析器名称传入 file_type——C++ 使用 cxx，Go 使用 golang，shell 使用 sh，JS 使用 javascript。也接受以下别名：cpp/c++→cxx、go→golang、bash/shell→sh、js→javascript、ts→typescript、cs→csharp、py→python、rb→ruby、rs→rust。）

defs/refs/symbol 回退说明——defs、refs 和 symbol 搜索需要指定项目范围（传入 projects 或设置 OPENGROK_DEFAULT_PROJECT）；否则可能返回过多跨项目命中结果。如果实例的 REST 端点对这些类型返回错误或空结果，客户端会自动回退到解析 Web UI，以便 LLM 仍能获得答案。opengrok_call_graph 需要 API v2，在 v1 上会降级为基于 refs 的视图。

设置 OPENGROK_CODE_MODE=true（默认值）。在会话开始时调用一次 opengrok_api，以获取完整的 API 规范。之后的所有操作都通过 opengrok_execute 执行。

所有沙盒 API 调用均为同步调用——使用扁平全局函数（search(...)），无需 await。env.opengrok.* 对象形式（env.opengrok.search(...)）与之等效。

搜索与发现

search() 仅使用规范文件类型名称（例如 cxx、golang、sh）——请参阅上方的别名列表。传入 expandFunction: true 可将匹配结果扩展为其所在函数体（会增加主机端读取，每次调用最多读取 3 个文件）。

读取与导航

历史记录与归属信息

代码智能

traceCallChain 的调用方来自引用搜索；被调用方来自 tree-sitter AST 分析，支持的语言包括 C/C++、Java、Go、Python、JS/TS、Rust 等。两个长时间运行的方法都会通过后台客户端进行扇出——这是一个无速率限制、每次操作预算较短的同级连接，因此深度遍历不会消耗前台速率限制配额。

系统

示例

// Example opengrok_execute code
const refs = env.opengrok.search("handleCrash", { searchType: "refs", maxResults: 5 });
const first = refs.results[0];
const content = env.opengrok.getFileContent(first.project, first.path, {
  startLine: first.matches[0].lineNumber - 5,
  endLine: first.matches[0].lineNumber + 10,
});
return { callerFile: first.path, code: content.content };

当 search() 返回零条结果且启用了采样时，结果中会自动注入 _suggestions: string[]——显式调用 sample() 前请先检查此字段。

Tree-sitter 智能分析——范围读取和 expandFunction 会使用 tree-sitter AST 分析，将匹配项扩展到其所属函数体（使用 WASM 语法，无需主机工具链）。各级别适用不同的行数预算：minimal 为 200 行，standard 为 400 行，generous 为 600 行。使用 OPENGROK_GRAMMAR_DIR 覆盖语法目录；通过 npm run copy-grammars 添加新语法（参见 CONTRIBUTING.md）。

fitToBuffer 截断——超过 8 MB 桥接缓冲区的沙箱结果会由 fitToBuffer() 裁剪；该函数会保留完整的结果元素，而不是从 JSON 中间截断。被裁剪的结果会带有 _truncated: true——看到该标记时，请缩小查询范围或使用 cursor 分页。

用户询问（设置 OPENGROK_ENABLE_ELICITATION=false 可禁用，默认值：true）

启用后，如果未配置 OPENGROK_DEFAULT_PROJECT 且存在多个项目，opengrok_api 会在会话开始时提示用户选择工作项目。沙箱代码也可以调用 env.opengrok.elicit()，在执行期间请用户从多个匹配项中进行选择。需要客户端支持 MCP Elicitation——Claude Code v2.1.76+ 支持此功能。在其他客户端上会平稳降级为 { action: "cancel" }。

采样（OPENGROK_ENABLE_SAMPLING=true，默认值：false）

通过 MCP Sampling 将大模型调用委托回客户端，使用客户端的模型订阅，无需单独的 API 密钥。会在三个场景下自动触发：解释沙箱错误、总结大型依赖关系图（>10 个节点），以及改写零结果查询（注入 _suggestions）。VS Code Copilot 支持采样；其他客户端的支持情况各不相同。采样不可用时，服务会平稳降级。

警告

采样会自动触发，并非按需调用。单次调查会话可能会因沙箱错误、零结果搜索和大型依赖关系图而产生多次采样调用。部分客户端在首次确认提示后，每次调用都会消耗高级请求额度。启用时请注意这一点。

Code Mode 默认包含 2 个工具（api + execute；设置 OPENGROK_ENABLE_MEMORY_TOOLS=true 后为 5 个）。两个文件会在不同轮次和会话重启后持续保留：

核心

代码模式与性能

记忆库

速率限制

响应缓存

MCP 协议

OpenGrok API

安全与审计

日志记录

代理

VS Code 用户也可以在 VS Code 设置中设置 opengrok-mcp.baseUrl、opengrok-mcp.codeMode、opengrok-mcp.contextBudget、opengrok-mcp.memoryBankDir、opengrok-mcp.defaultProject、opengrok-mcp.responseFormatOverride、opengrok-mcp.compileDbPaths、opengrok-mcp.enableObservationMasker 和 opengrok-mcp.observationMaskerTurns。密码等机密值绝不会写入 VS Code 设置。

**MCP SDK 说明：**此版本使用 @modelcontextprotocol/sdk v1.30.0（v1 系列）。

默认情况下，服务通过 stdio 通信。对于团队共享部署，可通过库 API 使用 HTTP 传输层（src/server/transport/http-transport.ts 中的 startHttpTransport()），但目前尚未接入 CLI 入口——下文虽有 OPENGROK_HTTP_PORT 的说明，但 main.ts 尚未读取该变量以自动启动 HTTP 服务。自定义部署时，请直接使用 startHttpTransport()。

会话管理

• 每个 HTTP 客户端都会获得一个隔离的 McpServer 实例（按会话创建实例的模式）
• 会话在不活动 30 分钟后过期；OPENGROK_HTTP_MAX_SESSIONS 限制并发会话数（默认值：100）
• GET /mcp/sessions 返回包含活动会话数和最早会话时长的 JSON

身份验证

在资源服务器模式下，此服务会验证由你自己的 IdP 签发的 JWT——没有内置的 /token 端点。设置 OPENGROK_JWT_ISSUER 后，其他签发者颁发的令牌将被拒绝。RFC 9728 受保护资源元数据位于 /.well-known/oauth-protected-resource。

RBAC 角色

未知或缺失的令牌将被拒绝，并返回 403 Forbidden。未配置身份验证时，未经身份验证的请求会被授予 admin 权限（本地开发模式）。

CORS

基于浏览器的客户端受来源允许列表控制（OPENGROK_ALLOWED_ORIGINS，以逗号分隔）。未配置身份验证时，本地开发允许回环来源（localhost、127.0.0.1、[::1]）；配置身份验证后（OPENGROK_HTTP_AUTH_TOKEN 或 RBAC 令牌），回环来源不再默认允许——必须明确列出每个允许的来源，包括本地来源。

完整的安全架构（威胁模型、防御层、加固指南）请参阅 SECURITY.md。

**沙箱信任建议：**在 VS Code 的 MCP 设置中配置 OpenGrok MCP 时，你可以设置 sandboxEnabled: true，以便自动批准工具调用而无需确认提示。这是安全的，因为所有工具执行都在 QuickJS WASM 沙箱中进行，无法访问主机——大模型无法通过此服务执行任意系统命令。