Open Grok MCP

用于VS代码的OpenGrok MCP服务器

使用GitHub Copilot和模型上下文协议（MCP）直接从VS code查询和探索OpenGrok中的代码存储库。

认证上下文

OpenGrok通常需要OAuth/SSO身份验证。由于MCP不直接支持OAuth流，因此此服务器使用会话Cookie进行身份验证。OpenGrok会话通常在大约30分钟的不活动后过期，需要定期刷新令牌。此MCP服务器管理该身份验证-您在设置过程中配置一次Cookie，服务器处理会话管理。当Cookie过期时，只需在配置中更新它们并重新加载VS代码。

______________________________________________________________________

🚀 安装和设置

方法1:VSIX安装（快速设置）

步骤1：安装扩展

下载预构建的扩展包：

• 下载： opengrok-mcp-extension-1.0.5.vsix

安装：

1. 打开VS代码
2. 转到扩展（Ctrl+Shift+X）
3. 单击“从VSIX安装…”
4. 选择已下载的 .vsix 文件
5. 重新加载VS代码（Ctrl+Shift+P→ “开发人员：重新加载窗口”）

步骤2：配置身份验证Cookie

1. 按 Ctrl+Shift+P
2. 键入“OpenGrok：更新身份验证Cookie”
3. 在提示时粘贴您的OpenGrok会话Cookie
4. VS代码自动重新加载

要获取Cookie，请参阅 获取身份验证Cookie.

______________________________________________________________________

方法2：手动MCP配置

步骤1：构建MCP服务器

# Clone repository
git clone https://github.com/sumanthreddyy/OpenGrokMCP.git
cd openGrok-MCP

# Install dependencies and build
npm install
npm run build

步骤2：更新VS代码MCP配置

编辑 %APPDATA%\Code\User\mcp.json:

{
  "mcpServers": {
    "opengrok": {
      "command": "node",
      "args": ["C:/path/to/openGrok-MCP/dist/index.js"],
      "env": {
        "OPENGROK_URL": "http://your-opengrok-instance.com/source",
        "OPENGROK_USE_OAUTH": "true",
        "OPENGROK_COOKIES": "session_cookie=YOUR_SESSION_ID; JSESSIONID=YOUR_SESSION_ID"
      }
    }
  }
}

替换：

• C:/path/to/openGrok-MCP/dist/index.js 使用您到内置服务器的实际路径
• 您复制的会话Cookie的Cookie值

步骤3：重新加载VS代码

按 Ctrl+Shift+P → “开发人员：重新加载窗口”

______________________________________________________________________

方法3：构建并打包为VSIX

如果你想自己从源代码构建扩展包：

先决条件：

• Node.js 18+
• npm

步骤：

# Build MCP server
npm install
npm run build

# Build extension
cd extension
npm install
npm run compile

# Create distributable package
npm run package

结果： extension/opengrok-mcp-extension-1.0.5.vsix

然后你可以分享这个 .vsix 与其他人一起安装文件，或者他们可以使用上面的方法1进行安装。

______________________________________________________________________

获取身份验证Cookie

1. 在浏览器中打开您的OpenGrok实例（例如。， http://your-opengrok-instance.com/source)
2. 使用您的凭据登录（如果需要身份验证）
3. 按 F12 打开开发人员工具
4. 首选 应用 tab → Cookie → 选择您的OpenGrok域名
5. 复制相关会话Cookie（通常包括会话标识符，如 JSESSIONID)

- 格式： cookie_name=value; another_cookie=value

______________________________________________________________________

用法

设置后（使用上述三种方法中的任何一种），通过GitHub Copilot使用这些工具：

______________________________________________________________________

opengrok_search

跨项目按关键字搜索代码

例子： “在MyProject中搜索“身份验证””

• 查找具有行号和代码段的匹配文件
• 返回带有上下文的顶级结果
• 默认情况下不区分大小写

opengrok_get_file

查看文件的完整源代码

例子： “显示UserAuthentication.java文件”

• 返回带有行号的完整文件内容
• 使用搜索结果中的路径
• 支持多种编程语言

opengrok_list_projects

浏览OpenGrok中的所有可用项目

例子： “列出所有可用项目”

• 显示OpenGrok实例中的所有索引项目
• 在搜索查询中使用项目名称
• 项目名称区分大小写（例如。， MyProject，不 myproject)

opengrok_xref

查找对符号（函数、类、变量）的所有引用

例子： “查找PaymentProcessor类的所有用途”

• 显示引用符号的文件
• 包括行号和上下文
• 有助于理解代码影响

______________________________________________________________________

故障排除

“401未经授权”错误

原因： 您的Cookie已过期（通常在大约30分钟不活动后）

修复：

1. 获取新鲜饼干（重复中的步骤 获取身份验证Cookie)
2. 使用新的cookie值更新您的配置
3. 重新加载VS代码

“找不到项目”

原因： 项目名称错误或不存在

修复：

• 询问Copilot：“列出所有可用项目”
• 项目名称区分大小写（例如。， MyProject，不 myproject)

搜索未返回任何结果

可能的原因：

• Cookie无效/过期→ 获取新鲜饼干
• 项目名称不正确→ 使用list_projects检查拼写
• 不存在匹配项→ 尝试更简单的搜索词

安装后“找不到扩展”

修复：

• 完全关闭VS代码
• 重新打开VS代码
• 扩展现在应该出现在“扩展”面板中

______________________________________________________________________

从源头构建

如果您想自定义扩展或为开发做出贡献：

先决条件

• Node.js 18+
• npm

构建步骤

Windows（批处理文件-最简单）：

.\build-extension.bat

Windows（PowerShell）：

.\build-extension.ps1

手动构建（任何操作系统）：

# 1. Build MCP server
npm install
npm run build

# 2. Build extension
cd extension
npm install
npm run compile

# 3. Create distributable package
npm run package

输出

创建： extension/opengrok-mcp-extension-1.0.5.vsix

与其他人共享此文件，或者他们可以从存储库下载。

______________________________________________________________________

项目结构

openGrok-MCP/
├── src/                          # MCP Server source code
│   ├── index.ts                  # Server entry point, tool definitions
│   ├── opengrok-client.ts        # OpenGrok API wrapper
│   ├── auth.ts                   # Authentication/cookie handling
│   └── config.ts                 # Configuration loader
│
├── extension/                     # VS Code Extension
│   ├── src/
│   │   └── extension.ts          # Extension activation, UI commands
│   ├── package.json              # Extension manifest
│   ├── tsconfig.json             # TypeScript config
│   └── out/                       # Compiled extension (generated)
│
├── dist/                          # Compiled MCP server (generated)
├── build-extension.bat            # Windows batch build script
├── build-extension.ps1            # PowerShell build script
├── package.json                   # Root package configuration
├── tsconfig.json                  # Root TypeScript configuration
└── README.md                      # This file

______________________________________________________________________

运作原理

建筑

MCP服务器遵循 哑服务器、智能LLM 设计：

1. 服务器提供工具 -基本搜索、文件提取、列出项目
2. LLM决定工作流程 -Copilot决定搜索和获取什么
3. 用户提问 -自然语言查询，如“显示支付处理器”

工作流示例

User: "How does authentication work in MyProject?"

1. Copilot uses opengrok_search
   → Finds files containing "authentication"
   → Gets snippets and line numbers

2. Copilot reviews and selects relevant files
   → Identifies: handler, processor, data structure files

3. Copilot uses opengrok_get_file
   → Fetches complete source code for each file

4. Copilot analyzes and explains
   → Explains the flow: validation → JSON building → API call

OpenGrok详细信息

OpenGrok是一个快速的代码搜索引擎，它：

• 为多个项目和存储库建立索引
• 提供全文搜索
• 跟踪交叉引用（外部参照）
• 需要OAuth/SSO身份验证

此MCP服务器包装OpenGrok的API并将结果返回给Copilot进行智能分析。

______________________________________________________________________

配置参考

环境变量

使用手动配置（mcp.json）时：

Cookie生命周期

• 持续时间： 约30分钟不活动
• 何时刷新： 当你看到401错误时
• 如何获得： 看 获取身份验证Cookie
• 所需Cookie： 会话cookie（例如。， JSESSIONID)

______________________________________________________________________

提示与技巧

有效搜索

• 使用特定术语：“PaymentGateway”与“payment”
• 引用短语： "boarding pass"
• 合并术语： "user AND authentication"

热门项目

• 您的OpenGrok项目将在此处列出
• 让Copilot列出所有项目：“列出所有可用项目”

了解结果

• 搜索返回片段（匹配的前~100个字符）
• 使用 opengrok_get_file 完整的上下文
• Copilot根据代码段内容自动获取相关文件

______________________________________________________________________

贡献

发现错误或想贡献？

• 报告问题： 在GitHub上打开一个问题
• 贡献代码： 提交带有改进的拉取请求
• 分享反馈： 告诉我们哪些功能会有所帮助

______________________________________________________________________

支持

对于用户

如果扩展不起作用：

1. 检查 先决条件 -你有新鲜的饼干吗？
2. 审查 故障排除 -大多数问题都与cookie有关
3. 测试连接：按Ctrl+Shift+P→ “OpenGrok：测试连接”
4. 检查VS代码日志：查看输出→ 扩展主机

对于开发者

如果你从源代码构建：

• 看 从源头构建
• 检查 项目结构
• 查看源代码注释以了解实现细节

______________________________________________________________________

许可证

MIT-有关详细信息，请参阅许可证文件

______________________________________________________________________

版本

当前： 1.0.5\ 最后更新时间： 2026年1月\ 存储库： https://github.com/sumanthreddyy/OpenGrokMCP