OpenGrok MCP Server

OpenGrok MCP服务器

MCP服务器将OpenGrok搜索引擎与人工智能连接起来，在海量代码库中实现即时上下文

______________________________________________________________________

📚 Table of Contents

• 概述
• 如何安装
• 配置指南
• 提示示例
• 工具参考
• VS代码集成
• 系统架构
• 建筑与测试
• 故障排除和支持
• 许可证信息

______________________________________________________________________

概述

💡 独立架构： VS Code扩展包括预打包的MCP服务器。你不需要Python、外部Node.js安装或复杂的环境设置。只需安装即可。

______________________________________________________________________

安装

选项1-VS代码扩展（推荐）

安装 OpenGrok MCP 从VS代码市场，或在扩展面板中搜索“OpenGrok”。

该扩展提供了一个可视化的配置UI，并自动管理MCP服务器进程。

选项2-npm/npx

全局安装：

npm install -g opengrok-mcp-server
opengrok-mcp setup      # interactive wizard: URL, credentials, MCP client registration

或者在不安装的情况下运行：

npx opengrok-mcp-server setup

该向导将凭据安全地存储在操作系统密钥链（macOS密钥链、Windows凭据管理器、Linux libsecret）中，并为无头Linux提供加密文件回退。

______________________________________________________________________

配置指南

1. 提供连接详细信息：

- 安装后 设置面板 将发射。 - 输入您的OpenGrok端点、用户名和密码。击打 保存设置. *（凭据已锁定在您的本地操作系统密钥链中）。* - 插件会立即验证连接。第一次运行时，VS Code会要求您 重新加载窗口 注册MCP工具。 - *（需要稍后更改？请使用 OpenGrok: Manage Configuration 命令或单击状态栏中的齿轮图标）。*

1. 激活副驾驶中的MCP源：

- 启动 GitHub Copilot 聊天助手 窗户。确保您正在使用 代理 模式。 - 单击回形针/工具图标(🔧)在提示框中。 - （如果 更新工具 按钮出现，单击它）。 - 定位 OpenGrok 在列表中，选中该框，然后确认。

⚠️ 请注意，VS Code管理工具授权 每个工作区。如果打开其他存储库，可能需要重新选中Copilot中的OpenGrok框。

CLI命令（v7.0+）

setup 支持 克劳德代码CLI, GitHub Copilot命令行界面，以及 Codex CLI.VS Code由扩展自动配置，无需CLI步骤。凭据存储在操作系统密钥链中，并带有AES-256-GCM加密文件回退，适用于无头/CI环境。

🔌 第三方客户支持

虽然为VS Code量身定制，但集成服务器逻辑与本机支持MCP协议的其他代理完美运行，包括：

克劳德桌面版 | 光标IDE | 帆板运动 | 克劳德代码 | 谷歌反重力

👉 参见 MCP_CLIENTS.md 用于配置片段和高级守护进程设置。

______________________________________________________________________

提示示例

与GitHub Copilot Chat自然地讨论您的代码库：

Find the implementation of the render_pipeline function within the graphics engine project.

Retrieve the contents of /src/utils/math.cpp from line 450 to 520.

What is the definition of TextureManager? Please show me the header file declaration too.

Look for all places in the code where ThreadPool is instantiated or referenced.

______________________________________________________________________

工具参考

主要业务

🚀 优化的工作流程（复合工具）

💡 这些专用工具将多个网络请求合并到一个操作中，通过 高达90%.

*（注意：搜索功能支持语言过滤 file_type 作为 java, cxx, python, golang等等）*

🔍 调查与分析工具（v5.6+）

🧠 内存工具（仅代码模式，v5.4+）

🧬 代码模式（v5+）——适用于大型多语言代码库

集 OPENGROK_CODE_MODE=true 切换到针对多步骤调查优化的5工具界面：

全部 env.opengrok.* 呼叫出现 同步的 在代码内部——沙盒使用SharedArrayBuffer+Atomics通道透明地桥接异步HTTP调用。对于复杂的调查，通常可以节省80-95%的代币。

v9.0+用于交互式提示和AI辅助的沙盒方法：

当 env.opengrok.search() 回报 零结果 并且采样是可用的， _suggestions: string[] 会自动注入结果中——在调用之前检查它 sample() 明确地。

// 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 };

沙盒暴露了一个 活文档存储库 --两个持久的markdown文件可以在不同的轮次中保存：

通过以下方式访问 env.opengrok.readMemory(filename) / env.opengrok.writeMemory(filename, content) 在沙盒内，或通过 opengrok_read_memory / opengrok_update_memory / opengrok_memory_status 经典模式下的工具。Delta编码返回 [unchanged] 反复阅读；当空间紧张时，丰富度评分的修剪会保留最有价值的日志条目。

⚙️ Automated Compilation Data (Optional)

项目选择器和交互式消歧（引语）

当 OPENGROK_ENABLE_ELICITATION=true，服务器在两个地方使用MCP Elicitation：

1. 会话开始 — opengrok_api （代码模式）提示用户选择一个工作项目（如果没有） OPENGROK_DEFAULT_PROJECT 已配置，并且存在多个项目。
2. 执行中期 --沙盒JS可以调用 env.opengrok.elicit(message, schema) 要求用户在执行过程中的任何时候在多个匹配的文件、修订或项目之间进行选择。

需要支持MCP激励的客户端：

• 克劳德代码 v2.1.76+✓

在VS Code配置面板中启用，或设置 OPENGROK_ENABLE_ELICITATION=true 在MCP客户端环境配置中。服务器会优雅地降级到 { action: "cancel" } 在不受支持的客户端上--没有错误。

LLM采样

服务器通过MCP采样将LLM调用委托回客户端-使用客户端的模型订阅，而不需要单独的API密钥。在三个地方使用：

1. 沙盒错误说明 --何时 opengrok_execute 代码失败，采样会生成简洁的解释和修复建议。
2. 依赖关系图摘要 --大型 opengrok_dependency_map 通过传统模式下的采样对图形（>10个节点）进行总结。
3. 零结果查询重新表述 （v9.0+，代码模式）--当 env.opengrok.search() 返回0个结果，自动注入采样 _suggestions 进入结果对象。沙盒JS也可以调用 env.opengrok.sample(prompt) 明确用于任何AI生成的文本。

支持的客户端：

• VS代码副本 ✓
• 克劳德代码 --支持待定（已跟踪 人类学/克劳德编码#1785)

当采样不可用时，服务器会正常降级-- sample() 回报 null, _suggestions 没有注射。

______________________________________________________________________

VS代码集成

调色板命令

核心设置配置文件

Expand for JSON Settings Reference

高级配置（v7--env变量）

对于独立服务器(npx opengrok-mcp-server 或Claude Code），设置这些环境变量：

核心设置

代码模式和性能

存储体

速率限制

响应缓存

安全与审计

MCP协议特性

OpenGrok API

HTTP传输（v7.0+）

日志记录

VS Code用户可以设置 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代码设置中。

MCP SDK注意事项： 此版本使用 @modelcontextprotocol/sdk v1.29.0。 MCP SDK v2处于alpha之前；我们将在稳定时迁移（预计2026年第3季度至第4季度）。 v2将支持工具参数和资源模板的增强完成。

______________________________________________________________________

HTTP传输（v7.0+）

默认情况下，服务器通过以下方式进行通信 标准 （标准MCP）。对于团队部署，您还可以公开 可流式传输的HTTP端点:

OPENGROK_HTTP_PORT=3666 npm run serve
# or add to your MCP client config:
# "OPENGROK_HTTP_PORT": "3666"

会话管理

• 每个HTTP客户端接收一个隔离的 McpServer 实例（每会话工厂模式）
• 会话在30分钟不活动后过期； OPENGROK_HTTP_MAX_SESSIONS 限制并发会话数（默认值：100）
• GET /mcp/sessions 返回带有活动会话计数和最旧会话年龄的JSON

认证

配置以下选项之一：

在资源服务器模式下，此服务器验证由您自己的IdP发出的JWT——没有内置 /token 终点。RFC 9728受保护的资源元数据在以下位置提供 /.well-known/oauth-protected-resource.

RBAC角色

故障保险：未知或缺失的令牌默认为 readonly，不 admin.

______________________________________________________________________

安全（v7.0+）

v7.0包括一个全面的安全审计，包括以下强化：

⚠️ v7.0.0重大更改 - OPENGROK_HTTP_CLIENT_ID 和 OPENGROK_HTTP_CLIENT_SECRET 远离的。迁移到 OPENGROK_JWKS_URI + OPENGROK_RESOURCE_URI 对于OAuth 2.1（资源服务器模型——自带IdP）。 - 存储体 migrate() 已删除——不再支持传统的6文件布局。2英尺布局(active-task.md + investigation-log.md)自v5.4以来一直是默认设置。 - CORS现在只有在以下情况下才允许使用 OPENGROK_ALLOWED_ORIGINS 已设置；未经身份验证的通配符CORS已禁用。

______________________________________________________________________

系统架构

Show topological diagram

 [ AI Client ]                       [ Integration Layer ]                    [ Data Source ]
                              │                                 │
 +---------------+            │       +-------------------+     │      +----------------------+
 │ GitHub        ││ OpenGrok MCP      ││ OpenGrok REST API &  │
 │ Copilot Chat  │            │       │ Server (Node.js)  │HTTP │      │ Web Interface        │
 +---------------+            │       +-------------------+     │      +----------------------+
      │    ▲                           │          │
      │    │ (Configures & Hosts)      │    (Context Optimization)
      ▼    │                           │          │
 +---------------+                     │   o Context Fetch      │      +----------------------+
 │ VS Code       │                     │   o Multi-Search       │      │ Local File System    │
 │ Extension     │                     │   o Auto-Truncate      │

______________________________________________________________________

## 建筑与测试

Initializing

npm install

Code Quality & Tests

npm run lint # Strict TypeScript & ESLint validation npm test # Execute the Vitest test suite (1113 tests) npm run test:sandbox # Sandbox integration tests (requires compile first) npm run test:coverage # Coverage report (≥89% threshold)

Packaging

npm run compile # Generate the esbuild artifact (includes sandbox-worker.js) npm run vsix # Create the downloadable extension file

我们利用GitHub Actions实现自动CD。标记提交（例如。， `v1.2.3`)自动触发构建矩阵并将工件附加到新的 .

如需深入了解架构或公关指南，请阅读 [贡献.md](CONTRIBUTING.md).

______________________________________________________________________

## 故障排除和支持

**Copilot聊天中缺少MCP工具**

- 单击回形针(`🔧`)图标到“更新工具”
- 跑 `Developer: Reload Window`

**“连接失败”错误**

- 仔细检查你的 `OPENGROK_BASE_URL`
- 确保您没有被公司VPN/代理阻止

**401未经授权/身份验证失败**

- 跑吧 `OpenGrok: Configure Credentials` 再次保存用户名/密码的命令

**自签名SSL证书**

- 通过设置关闭严格验证 `opengrok-mcp.verifySsl` 到 `false`

**查询速度慢或超时**

- 使用限制范围 `file_type` 争论或针对特定项目
- OpenGrok可能正在索引；跑 `opengrok_index_health`

**需要详细的日志吗？**

- 设置环境变量 `OPENGROK_LOG_LEVEL=debug` 获取广泛的stdout跟踪数据

### OpenGrok版本兼容性

|OpenGrok引擎|状态|已知限制|
| ---------------- | ------------- | ----- |
| **v1.13.x及以上版本** |本机支持|无（完整的REST API功能）|
| **v1.7.0--v1.12.x** |传统模式|使用HTML抓取进行符号查找和归咎|
| **v1.7.0以下** |不支持|不可预测的行为|

______________________________________________________________________

## 许可证信息

该系统分布在 [PolyForm非商业许可证1.0.0](LICENSE).

- ✅ **被允许：** 个人使用、爱好项目、学术研究、教育
- ❌ **禁止：** 任何商业、企业、企业或有偿使用

**商业许可：**
要在企业环境（内部工具、CI管道、业务基础设施）中使用此扩展，严格需要商业许可证。
接触 [rudroy09@gmail.com](mailto:rudroy09@gmail.com) 企业级定价。

阅读 [许可证商业.md](LICENSE-COMMERCIAL.md) 完整条款。