GitLab合并请求管理工具

GitLab MR MCP

将您的AI助手连接到GitLab。问以下问题 “列出打开的合并请求”, “显示MR#123的评论”, “获取MR#456的提交讨论”，或 “查找功能分支的合并请求” 直接在您的聊天中。

目录

• 快速设置
• 你能做什么
• 配置选项
• 故障排除
• 工具参考
• 路线图
• 发展
• 安全说明
• 支持

快速设置

安装

# Using pipx (recommended)
pipx install gitlab-mr-mcp

# Or using uv
uv tool install gitlab-mr-mcp

# Or using pip
pip install gitlab-mr-mcp

注： 使用 pipx 或 uv tool 建议使用，因为它们会自动添加 gitlab-mcp 命令到您的PATH。如果使用 pip install，确保您的Python脚本目录在PATH中，或使用命令的完整路径。

获取您的GitLab代币

1. 转到GitLab→ 设置→ 访问令牌
2. 使用创建令牌 read_api 范围（添加 api 范围（如果你想要写访问权限）
3. 复制令牌

配置您的MCP客户端

多项目设置（推荐）

为了与 多个GitLab项目，添加到全局MCP配置(~/.cursor/mcp.json 光标）：

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "gitlab-mcp",
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

这种单一配置适用于 您的所有项目.使用 search_projects 或 list_my_projects 要查找项目ID，请指定 project_id 在您的请求中。

单个项目设置

对于与a合作 单个项目，您可以设置默认项目ID：

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "gitlab-mcp",
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_PROJECT_ID": "12345"
      }
    }
  }
}

重启MCP客户端，开始向GitLab提问！

你能做什么

连接后，在聊天中尝试以下命令：

多项目工作流

• “我可以访问哪些项目？”
• “搜索后端项目”
• “显示项目12345的打开的MR”
• “列出组/我的项目的合并请求”

单个项目命令

• “列出打开的合并请求”
• “显示合并请求456的详细信息”
• “获取MR#123的评论和讨论”
• “显示MR#456的测试摘要”
• “合并请求#789中哪些测试失败？”
• “给我看看MR#456的管道”
• “获取合并请求#789的失败作业日志”
• “向我展示MR#456的讨论”
• “获取合并请求#789中提交的所有评论”
• “查找功能/auth改进分支的合并请求”
• “显示针对main的已关闭合并请求”
• “对MR#456中的讨论abc123的回复是‘谢谢您的反馈！’”
• “在MR#789中创建新的评论，询问错误处理”
• “解决MR#123中的讨论def456”
• “批准合并请求#456”
• “将MR#123与壁球合并”
• “管道成功时合并MR#789”

处理审查意见

增强的审核工具允许您与合并请求讨论进行交互：

1. 首先，获取评论 查看讨论ID：

   复制

   "Show me reviews for MR #123"
   

2. 对具体讨论的答复 使用讨论ID：

   复制

   "Reply to discussion abc123 in MR #456 with 'I'll fix this in the next commit'"
   

3. 创建新的讨论线索 开始对话：

   复制

   "Create a review comment in MR #789 asking 'Could you add error handling here?'"
   

4. 解决讨论 当问题得到解决时：

   复制

   "Resolve discussion def456 in MR #123"
   

备注：The get_merge_request_reviews 该工具现在在输出中显示讨论ID和注释ID，从而在回复或解析时可以轻松引用特定的讨论。

批准和合并

使用批准和合并工具完成MR生命周期：

1. 批准合并请求:

   复制

   "Approve MR #123"
   

2. 与选项合并:

   复制

   "Merge MR #456 with squash"
   "Merge MR #789 and remove source branch"
   "Merge MR #123 when pipeline succeeds"
   

3. 撤销批准 （如果需要）：

   复制

   "Unapprove MR #456"
   

合并选项：

• squash -Squash提交为单个提交
• should_remove_source_branch -合并后删除源分支
• merge_when_pipeline_succeeds -管道通过时自动合并
• sha -确保HEAD没有改变（安全检查）

备注：您无法批准自己的MR。如果MR存在冲突、处于草稿状态或不符合批准要求，合并将失败。

使用测试报告（建议用于测试失败）

GitLab提供了两种检查测试结果的工具——使用摘要进行快速检查，使用完整报告进行详细调试：

选项1：测试摘要（快速和轻量级）⚡

使用 get_pipeline_test_summary 快速概述：

"Show me the test summary for MR #123"
"How many tests passed in MR #456?"

您将获得：

• 📊 每个测试套件的通过/失败计数
• ⏱️ 总执行时间
• 🎯 通过率百分比
• ⚡ 快速 -不包括详细的错误消息

选项2：完整测试报告（详细）🔍

使用 get_merge_request_test_report 详细调试：

"Show me the test report for MR #123"
"What tests failed in merge request #456?"

您将获得：

• ✅ 具体测试名称 通过/失败
• ❌ 错误消息 和堆栈痕迹
• 📦 测试套件 按类/文件组织
• ⏱️ 执行时间 每次测试
• 📊 通过率 和汇总统计
• 📄 文件路径 以及行号

两者如何工作：

• 自动获取合并请求的最新管道
• 从该管道中检索测试数据（使用GitLab的 /pipelines/:pipeline_id/test_report 或 /test_report_summary API

输出示例：

## Summary

**Total**: 45 | **Passed**: 42 | **Failed**: 3 | **Errors**: 0
**Pass Rate**: 93.3%

## Failed Tests

### [FAIL] test_login_with_invalid_password

**Duration**: 0.300s
**Class**: `tests.auth_test.TestAuth`

**Error Output**:
AssertionError: Expected 401, got 200

为什么使用此日志而不是作业日志？

• 🎯 没有噪音：只有测试结果，没有构建/设置输出
• 📊 结构化数据：易于人工智能理解并提出修复建议
• 🚀 快速：比完整作业日志小得多
• 🔍 精确：显示确切的测试名称和错误位置

要求：

您的CI必须使用以下方式上传测试结果 artifacts:reports:junit 在 .gitlab-ci.yml:

test:
  script:
    - pytest --junitxml=report.xml
  artifacts:
    reports:
      junit: report.xml

处理管道作业和日志

管道工具为调试测试失败提供了两步工作流程：

步骤1：获取管道概述

使用 get_merge_request_pipeline 查看所有作业及其状态：

"Show me the pipeline for MR #456"

您将获得：

• 管道概述（状态、持续时间、覆盖范围）
• 按状态（失败、正在运行、成功）分组的所有作业
• 作业ID 对于每个作业（使用这些来获取日志）
• 在GitLab中查看职位的直接链接
• 工作级别的时间安排和阶段信息

步骤2：获取特定作业日志

使用 get_job_log 使用作业ID获取实际输出：

"Get the log for job 12345"
"Show me the output of job 67890"

您将获得：

• 完成作业输出/跟踪
• 日志大小和行数
• 对于非常长的日志，自动截断为最后15000个字符

典型工作流程：

You: "Show me the pipeline for MR #123"
AI: "Pipeline failed. 2 jobs failed:
     - test-unit (Job ID: 12345)
     - test-integration (Job ID: 67890)"

You: "Get the log for job 12345"
AI: [Shows full test output with error details]

You: "Fix the failing test"
AI: [Analyzes the log and suggests fixes]

为什么是两个工具？

• 演出：仅在需要时获取日志（不是一次全部获取）
• 灵活性：检查任何作业的日志（失败、成功或正在运行）
• 上下文高效：避免不必要地倾倒大量原木

与承诺讨论合作

这 get_commit_discussions 该工具提供了对合并请求中单个提交的讨论和评论的全面见解：

1. 查看所有提交讨论 对于合并请求：

   复制

   "Show me commit discussions for MR #123"
   

2. 获取详细的提交对话历史记录:

   复制

   "Get all comments on commits in merge request #456"
   

此工具特别适用于：

• 代码审查跟踪：查看关于具体提交的所有反馈
• 讨论历史：了解代码讨论的演变
• 提交级别上下文：查看与特定代码更改相关的注释
• 审查进度：监控已讨论的提交

技术实施：

• 用途 /projects/:project_id/merge_requests/:merge_request_iid/commits 以正确的分页方式获取所有提交
• 使用以下命令获取所有合并请求讨论 /projects/:project_id/merge_requests/:merge_request_iid/discussions 支持分页
• 使用位置数据按提交SHA筛选讨论，以显示提交特定的对话
• 正确处理个人评论和讨论线程

输出包括：

• 提交和讨论总数汇总
• 个人提交详细信息（SHA、标题、作者、日期）
• 每个提交的所有讨论和评论，以及文件位置
• 用回复完成对话线程
• 差异相关评论的文件位置
• 将对话与回复联系起来

配置选项

MCP配置（推荐）

直接在MCP客户端配置中配置环境变量，如所示 快速设置。这将在项目中保留特定于项目的设置。

环境变量

或者，在shell中设置环境变量：

export GITLAB_PROJECT_ID=12345
export GITLAB_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
export GITLAB_URL=https://gitlab.com

SOCKS代理支持

通过设置SOCKS5代理路由所有GitLab API请求 SOCKS_PROXY:

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "gitlab-mcp",
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_PROJECT_ID": "12345",
        "SOCKS_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}

或者通过环境变量：

export SOCKS_PROXY=socks5://127.0.0.1:1080

当 SOCKS_PROXY 未设置，直接建立连接（无代理）。

查找您的项目ID

• 转到您的GitLab项目→ 设置→ 将军→ 项目ID
• 或者检查URL： https://gitlab.com/username/project （使用数字ID）

故障排除

认证错误：验证您的令牌是否具有 read_api 权限未过期。

项目未找到：仔细检查您的项目ID是否正确（它是一个数字，而不是项目名称）。

连接问题：确保您的GitLab URL可访问且正确。

脚本未找到：确保MCP配置中的路径指向实际的服务器位置，并且脚本是可执行的。

工具参考

项目发现工具

合并请求工具

所有项目范围的工具都接受可选 project_id 参数。如果未提供，则返回 GITLAB_PROJECT_ID 有人是。

路线图

最近添加

• v1.4.0版本：项目发现工具、MCP最佳实践（工具标题、注释）、改进的提示
• v1.3.1：修复了Cursor中的多工作区环境变量冲突
• v1.3.0版本：用于路由GitLab API请求的SOCKS5代理支持
• v1.2.0版本：合并、批准和取消批准MR工具-完成MR生命周期
• v1.1.0版本：创建和更新MR工具，更清晰的输出格式

接下来

• [ ] 问题管理 -列出、创建、更新问题并添加评论
• [ ] 行内注释 -在特定行添加代码审查注释

考虑到

• []MR的轻量级文件列表（更改的文件没有完全差异）
• []通过API重新调整MR

超出范围

有意不包括分支操作、文件内容获取和完全差异——使用 git 在本地执行这些任务时，它更快、更有能力。

有功能请求吗？ 打开一个问题!

发展

项目结构

gitlab_mr_mcp/
├── __init__.py          # Package version
├── __main__.py          # Entry point for python -m
├── server.py            # MCP server implementation
├── config.py            # Configuration management
├── gitlab_api.py        # GitLab API client
├── utils.py             # Utility functions
├── logging_config.py    # Logging configuration
└── tools/               # Tool implementations
    ├── __init__.py
    ├── list_merge_requests.py
    ├── get_merge_request_details.py
    ├── create_merge_request.py
    ├── update_merge_request.py
    └── ... (more tools)

添加工具

1. 在中创建新文件 gitlab_mr_mcp/tools/ 目录
2. 添加导入和导出到 gitlab_mr_mcp/tools/__init__.py
3. 添加到 list_tools() 在 gitlab_mr_mcp/server.py
4. 将处理程序添加到 call_tool() 在 gitlab_mr_mcp/server.py

添加提示

提示为AI助手提供工作流程指导。在中添加新提示 gitlab_mr_mcp/prompts.py:

1. 将提示内容定义为字符串常量
2. 将条目添加到 PROMPTS 字典与 title, description，以及 content

NEW_PROMPT = """
Your prompt content here - focus on decision trees and when to use which tool.
"""

PROMPTS = {
    # ... existing prompts ...
    "new-prompt": {
        "title": "Human Readable Title",
        "description": "Short description for prompt list",
        "content": NEW_PROMPT,
    },
}

开发设置

1. 安装开发依赖项：

make install
# or: uv pip install -e ".[dev]"

2. 可用的make命令：

make install   # Install in editable mode with dev deps
make dev       # Build and install wheel locally
make test      # Run tests
make lint      # Run linters
make format    # Format code
make check     # Lint + test
make clean     # Remove build artifacts

3. 设置预提交挂钩：

pre-commit install

这将自动检查并格式化您的代码：

• ✨ 尾随空格 -自动删除
• 📄 文件结束问题 -自动修复
• 🎨 代码格式化（黑色） -自动格式化
• 📦 进口排序（isort） -自动组织
• 🐍 Python风格（flake8） -带有缺陷标记和指纹检测
• 🔒 安全问题（土匪） -安全检查
• 📋 YAML/JSON格式 -已验证

4. 格式化所有现有代码（仅限第一次）：

make format
# or: black --line-length=120 . && isort --profile black --line-length=120 .

5. 对所有文件手动运行预提交：

pre-commit run --all-files

运行测试

make test
# or: uv run pytest tests/ -v

安全说明

• 从不将访问令牌提交到版本控制
• 使用具有最小权限的项目特定令牌(read_api 范围）
• 定期旋转令牌
• 将令牌存储在MCP配置中（不应提交）

支持

• 检查 GitLab API文档
• 未决问题 github/amirsina-mandegari/gitlab-mr-mcp

许可证

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