GitLab合并请求评论服务器

GitLab MCP服务器

用于检索GitLab合并请求注释的模型上下文协议（MCP）服务器。

🔒 只读的：此服务器仅从GitLab获取数据。它从不修改MR状态、注释或任何其他GitLab数据。

这是什么？

此MCP服务器使AI编码代理（如Cursor、Claude Desktop或任何兼容MCP的客户端）能够以结构化、对代理友好的格式从GitLab合并请求中获取注释。它旨在帮助代理商：

• 📋 将未解决的注释编译成修复计划
• 🎯 提取包含文件路径和行号的内联讨论
• 🔍 按分辨率状态过滤反馈
• 📝 生成人类可读的摘要

特性

• 统一评论结构：将内联讨论和概述注释组合成单一的标准化格式
• 智能过滤：包括/排除系统注释，按分辨率状态过滤
• 文件路径提取：自动从内联注释中提取文件路径
• 线程上下文：按讨论主题分组的相关评论
• 双输出格式：JSON用于编程，Markdown用于人类阅读
• 重试逻辑：通过指数回退处理瞬态错误
• 分页支持：自动获取所有页面
• 安全第一：基于令牌的身份验证，日志中的秘密编辑

快速开始

1.安装依赖项

npm install

2.构建服务器

npm run build

3.设置GitLab代币

在GitLab中创建个人访问令牌：

1. 首选 GitLab公司 → 偏好设置 → 访问令牌
2. 使用创建令牌 read_api 作用域（建议只读访问）
3. 复制令牌

4.配置MCP客户端

对于光标

添加到 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gitlab-mr-comments": {
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/server.js"],
      "env": {
        "GITLAB_BASE_URL": "https://gitlab.com",
        "GITLAB_TOKEN": "glpat_your_token_here"
      }
    }
  }
}

适用于克劳德桌面

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%/Claude/claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "gitlab-mr-comments": {
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/server.js"],
      "env": {
        "GITLAB_BASE_URL": "https://gitlab.com",
        "GITLAB_TOKEN": "glpat_your_token_here"
      }
    }
  }
}

5.重新启动MCP客户端

重新启动Cursor或Claude Desktop以使配置生效。

可用工具

此MCP服务器提供以下工具：

gitlab_get_mr_comments

从GitLab合并请求中获取评论，包括内联讨论和概述注释。

工具名称: gitlab_get_mr_comments

描述：从GitLab合并请求中获取注释。以结构化格式返回内联讨论和概述注释。支持按分辨率状态过滤和排除系统注释。对AI代理审查反馈和计划代码修复很有用。

何时使用:

• 查看合并请求的未解决注释
• 获取对特定文件的反馈
• 根据审阅者的意见生成修复计划
• 检查讨论的解决状态

用法

基本用法

问你的AI代理：

“从项目my-org/my-repo中的MR！123获取所有未解决的注释”

代理将自动发现并使用 gitlab_get_mr_comments 工具具有适当的参数。

示例工具调用

{
  "tool": "gitlab_get_mr_comments",
  "arguments": {
    "project": "my-org/my-repo",
    "mr": 123,
    "onlyUnresolved": true,
    "includeSystem": false
  }
}

刀具参数

备注: onlyResolved 和 onlyUnresolved 是相互排斥的。

代理工作流示例

修复计划生成

User: "Review all unresolved comments on MR !456 and create a fix plan"

Agent:
1. Calls gitlab_get_mr_comments with onlyUnresolved=true
2. Groups comments by file_path
3. Generates prioritized fix plan:
   - src/api/users.ts (3 comments)
     • Line 45: Add error handling
     • Line 78: Extract to helper
     • Line 92: Add validation

文件特定审查

User: "What feedback did reviewers leave on src/api/users.ts?"

Agent:
1. Fetches all comments from MR
2. Filters client-side for file_path = "src/api/users.ts"
3. Summarizes feedback for that specific file

释放准备就绪

User: "Summarize blocking issues on MR !789"

Agent:
1. Fetches all unresolved comments
2. Searches for keywords: "blocker", "must fix", "breaking"
3. Presents summary of blocking issues

环境变量

快速设置：

cp .env.example .env
# Edit .env with your GITLAB_TOKEN

看 .env.example 了解详细的配置选项。

自主管理GitLab

要与自我管理的GitLab实例一起使用：

{
  "env": {
    "GITLAB_BASE_URL": "https://gitlab.your-company.com",
    "GITLAB_TOKEN": "glpat_your_token_here"
  }
}

故障排除

“GITLAB_TOKEN环境变量是必需的”

原因：MCP服务器在环境中找不到GitLab令牌

解决方案:

1. 验证MCP配置：检查您的MCP配置文件并确保 GITLAB_TOKEN 是在 env 章节：

   • 光标： ~/.cursor/mcp.json
   • 克劳德桌面： ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）

   例子：

   复制

   {
     "mcpServers": {
       "gitlab-mr-comments": {
         "command": "node",
         "args": ["/absolute/path/to/gitlab-mcp/dist/server.js"],
         "env": {
           "GITLAB_TOKEN": "glpat_your_token_here"
         }
       }
     }
   }
   

2. 重新启动客户端：添加/更改令牌后，您必须完全重新启动Cursor或Claude Desktop

3. 检查令牌格式：确保令牌以开头 glpat- 并且没有多余的空格或引号

4. 备注A. .env 作为MCP服务器运行时，不使用项目目录中的文件。令牌必须在MCP客户端的配置文件中。

“身份验证失败”

原因：令牌无效或丢失，权限不足

解决方案:

• 验证 GITLAB_TOKEN 设置正确
• 确保令牌具有 read_api 范围
• 支票令牌尚未过期
• 验证令牌是否可以访问项目

“未找到项目或MR”

原因：项目路径或MR编号不正确

解决方案:

• 使用项目 路径 （例如。， my-org/my-project)，不是数字ID
• 使用MR IID （the !123 URL中可见的数字），而不是内部ID
• 确保您的令牌可以访问该项目

“超出费率限制”

原因：对GitLab API的请求过多

解决方案:

• 请稍候，然后重试
• 使用 onlyUnresolved 过滤以减少请求
• 集 includeOverviewNotes: false 如果不需要
• 对于GitLab.com：免费层=300个请求/分钟

“请求超时”

原因：大型MR或慢速网络

解决方案:

• 增加 REQUEST_TIMEOUT 环境变量
• 使用过滤器减少数据量
• 检查GitLab实例的网络连接

服务器未显示在Cursor/Claude中

原因：配置或路径问题

解决方案:

• 验证到的绝对路径 dist/server.js 是正确的
• 检查配置文件中的JSON语法
• 更改配置后重新启动Cursor/Claude Desktop
• 检查日志：游标登录 ~/.cursor/logs，克劳德登录 ~/Library/Logs/Claude

“找不到工具”或“有哪些可用工具？”

原因：AI代理无法发现 gitlab_get_mr_comments 工具

解决方案:

1. 验证服务器是否已连接:

   • 在IDE中检查MCP服务器状态（通常在设置/扩展中）
   • 在连接的服务器列表中查找“gitlab mr comments”
   • 如果未连接，请参阅上面的“服务器未显示”

2. 工具名称为: gitlab_get_mr_comments

   • 您可以告诉您的代理：“使用gitlab_get_mr_commits工具从项目zapier/team-sbruth/templates中的mr！530获取评论”

3. 检查服务器日志:

   • 查看“GitLab MR评论工具注册成功”消息
   • 如果缺失，服务器可能未正确启动

4. 重新启动两个IDE，然后重试:

   • 有时工具发现需要新的连接

发展

以开发模式运行

npm run dev

运行测试

npm test

生成JSON模式

npm run build
node scripts/generate-schema.ts

代码检查

npm run lint
npm run format

安全

许可证管理

• ✅ 做：使用令牌 read_api 范围（最小特权）
• ✅ 做：将令牌存储在环境变量或安全配置文件中
• ❌ 不要：将令牌提交到版本控制
• ❌ 不要：公开分享代币

只读保证

此服务器是 明确设计为只读:

• ✅ GitLab客户端仅实现 GET 请求：
• ✅ 不 POST, PUT, PATCH，或 DELETE 方法存在
• ✅ 建议的令牌范围为 read_api （只读）
• ✅ 整合测试验证没有调用突变端点

数据隐私

• 所有数据都在内存中处理（无磁盘写入）
• 无缓存或持久存储
• 机密会自动从日志中删除
• 未联系任何外部服务（仅限直接使用GitLab API）

建筑

AI Agent (Cursor/Claude)
        ↓ stdio (MCP Protocol)
MCP Server
        ↓ HTTPS (GET only)
GitLab REST API

看 SYSTEM_DESIGN.md 获取详细的架构文档。

演出

典型性能 （GitLab.com，美国地区）：

• 对于评论数≤500的MR，延迟≤2s p50
• ≤5s p95潜伏期

优化提示:

• 使用 onlyUnresolved 减少数据量
• 集 includeOverviewNotes: false 如果不需要
• 使用 perPage: 100 （最大）尽量减少往返

贡献

欢迎投稿！请阅读系统设计文档并遵循现有的代码模式。

关键原则

1. 只读的：从不添加写入操作
2. 类型安全：使用TypeScript和Zod进行验证
3. 错误处理：提供可操作的错误消息
4. 测试：添加新功能的测试
5. 文档：更新README和示例

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

支持

• 问题: https://github.com/mpaarating/gitlab-mcp/issues
• 文档：参见 docs/ 目录
• 产品需求文档：参见 docs/GITLAB_MCP_PRD.md
• 系统设计：参见 docs/SYSTEM_DESIGN.md

致谢

内置：

• 模型上下文协议SDK
• GitLab REST API
• TypeScript、Zod、undici

由以下材料制成❤️ 用于AI驱动的代码审查工作流程