MCP Gitlab

🚀 MCP GitLab 服務器

MCP GitLab 服務器是一個基於模型上下文協議（MCP）的服務器，它提供了全面的 GitLab API 集成。該服務器使大語言模型（LLMs）能夠與 GitLab 倉庫進行交互，管理合併請求、問題，並執行各種 Git 操作。

🚀 快速開始

本服務器提供了便捷的使用方式，讓你可以輕鬆開啟與 GitLab 的交互之旅。以下為你介紹不同的啟動途徑：

使用 uvx（推薦 - 無需安裝）

# 無需安裝，直接運行
uvx mcp-gitlab

從源代碼安裝

# 克隆倉庫
git clone https://github.com/Vijay-Duke/mcp-gitlab.git
cd mcp-gitlab

# 安裝依賴並使用 uv 運行
uv sync
uv run mcp-gitlab

# 或者以開發模式安裝幷包含測試依賴
uv sync --all-extras
uv run pytest  # 運行測試

✨ 主要特性

核心特性

• 🔐 認證與用戶：獲取當前用戶信息並查找用戶資料。
• 🔍 項目管理：列出、搜索並獲取 GitLab 項目的詳細信息。
• 📝 問題管理：列出、讀取、搜索問題並發表評論。
• 🔀 合併請求管理：列出、讀取、更新、批准和合併合並請求。
• 📁 倉庫文件操作：瀏覽、讀取文件並提交文件更改。
• 🌳 分支與標籤管理：列出並管理分支和標籤。
• 🔧 CI/CD 管道管理：查看管道狀態、作業和工件。
• 💬 討論管理：讀取並解決合併請求討論。
• 🎯 智能操作：支持批量操作、AI 摘要和智能差異比較。

高級特性

• 批量操作：原子性地執行多個 GitLab 操作，並支持回滾。
• AI 優化摘要：生成合並請求、問題和管道的簡潔摘要。
• 智能差異比較：獲取結構化的差異比較結果，並可配置上下文和大小限制。
• 安全預覽：在提交前預覽文件更改。
• 交叉引用支持：在批量模式下引用先前操作的結果。

📦 安裝指南

使用 uvx（推薦 - 無需安裝）

# 直接運行，無需安裝
uvx mcp-gitlab

從源代碼安裝

# 克隆倉庫
git clone https://github.com/Vijay-Duke/mcp-gitlab.git
cd mcp-gitlab

# 安裝依賴並使用 uv 運行
uv sync
uv run mcp-gitlab

# 或者以開發模式安裝幷包含測試依賴
uv sync --all-extras
uv run pytest  # 運行測試

💻 使用示例

基礎用法

# 自動檢測並列出問題
# 首先從 git 倉庫獲取當前項目
project = await session.call_tool("gitlab_get_current_project")

# 然後列出未解決的問題
issues = await session.call_tool("gitlab_list_issues", {
    "state": "opened"
})

高級用法

# 使用批量操作創建修復
# 原子性操作：獲取問題 → 創建分支 → 提交修復 → 創建合併請求
result = await session.call_tool("gitlab_batch_operations", {
    "operations": [
        {
            "name": "issue",
            "tool": "gitlab_get_issue", 
            "arguments": {"issue_iid": 123}
        },
        {
            "name": "fix",
            "tool": "gitlab_create_commit",
            "arguments": {
                "branch": "fix-issue-{{issue.iid}}",
                "commit_message": "Fix: {{issue.title}}",
                "actions": [{
                    "action": "update",
                    "file_path": "src/bug.py",
                    "content": "# Fixed code here"
                }]
            }
        },
        {
            "name": "mr",
            "tool": "gitlab_create_merge_request",
            "arguments": {
                "source_branch": "fix-issue-{{issue.iid}}",
                "target_branch": "main",
                "title": "Fix: {{issue.title}}",
                "description": "Fixes #{{issue.iid}}"
            }
        }
    ]
})

📚 詳細文檔

可用工具

認證與用戶信息

• gitlab_get_current_user：獲取當前認證用戶的個人資料信息。

{}

返回的綜合信息包括：

• 基本信息：ID、用戶名、姓名、電子郵件。

• 個人資料詳情：簡介、組織、職位。

• 賬戶狀態：狀態、創建日期、管理員狀態。

• 權限：是否可以創建組、是否可以創建項目。

• 安全信息：是否啟用雙因素認證、外部狀態。

• gitlab_get_user：按 ID 或用戶名獲取特定用戶的詳細信息。

{
  "user_id": 12345
}

或

{
  "username": "johndoe"
}

返回的用戶信息包括：

• 基本信息：ID、用戶名、姓名。
• 個人資料：頭像 URL、網頁 URL、簡介。
• 組織詳情：公司、職位。
• 賬戶狀態和創建日期。

項目管理

• gitlab_list_projects：列出可訪問的 GitLab 項目，並支持分頁和搜索。

{
  "owned": false,
  "search": "my-project",
  "per_page": 20,
  "page": 1
}

• gitlab_get_project：獲取特定項目的詳細信息。

{
  "project_id": "group/project"
}

• gitlab_get_current_project：從當前的 git 倉庫獲取 GitLab 項目信息。

{
  "path": "."
}

問題管理

• gitlab_list_issues：列出項目問題，並支持狀態過濾。

{
  "project_id": "group/project",
  "state": "opened",
  "per_page": 20
}

• gitlab_get_issue：獲取單個問題的完整詳細信息。

{
  "project_id": "group/project",
  "issue_iid": 123
}

• gitlab_add_issue_comment：為問題添加評論。

{
  "project_id": "group/project",
  "issue_iid": 123,
  "body": "Thanks for reporting this!"
}

合併請求管理

• gitlab_list_merge_requests：列出合併請求，並支持過濾選項。

{
  "project_id": "group/project",
  "state": "opened"
}

• gitlab_get_merge_request：獲取合併請求的詳細信息。

{
  "project_id": "group/project",
  "mr_iid": 456
}

• gitlab_update_merge_request：更新合併請求的字段。

{
  "project_id": "group/project",
  "mr_iid": 456,
  "title": "Updated title",
  "description": "New description",
  "labels": "bug,priority"
}

• gitlab_merge_merge_request：合併合併請求，並支持選項設置。

{
  "project_id": "group/project",
  "mr_iid": 456,
  "squash": true,
  "should_remove_source_branch": true
}

• gitlab_approve_merge_request：批准合併請求。

{
  "project_id": "group/project",
  "mr_iid": 456
}

倉庫操作

• gitlab_get_file_content：從倉庫讀取文件內容。

{
  "project_id": "group/project",
  "file_path": "src/main.py",
  "ref": "main"
}

• gitlab_create_commit：創建包含多個文件更改的提交。

{
  "project_id": "group/project",
  "branch": "feature-branch",
  "commit_message": "Add new features",
  "actions": [
    {
      "action": "create",
      "file_path": "new_file.py",
      "content": "print('Hello')"
    },
    {
      "action": "update",
      "file_path": "existing.py",
      "content": "# Updated content"
    }
  ]
}

• gitlab_compare_refs：比較兩個分支、標籤或提交。

{
  "project_id": "group/project",
  "from_ref": "main",
  "to_ref": "feature-branch"
}

CI/CD 作業和工件

• gitlab_list_pipeline_jobs：列出特定 CI/CD 管道中的作業。

{
  "project_id": "group/project",
  "pipeline_id": 789,
  "per_page": 20,
  "page": 1
}

• gitlab_list_project_jobs：列出項目的作業，並支持可選的範圍過濾。

{
  "project_id": "group/project",
  "scope": "failed",
  "per_page": 25
}

• gitlab_download_job_artifact：獲取作業工件的信息（安全說明：內容不會下載）。

{
  "project_id": "group/project",
  "job_id": 456,
  "artifact_path": "build.zip"
}

高級工具

• gitlab_batch_operations：原子性地執行多個操作，並支持回滾。

{
  "project_id": "group/project",
  "operations": [
    {
      "name": "get_issue",
      "tool": "gitlab_get_issue",
      "arguments": {"issue_iid": 123}
    },
    {
      "name": "create_mr",
      "tool": "gitlab_create_merge_request",
      "arguments": {
        "source_branch": "fix-{{get_issue.iid}}",
        "target_branch": "main",
        "title": "Fix: {{get_issue.title}}"
      }
    }
  ]
}

• gitlab_summarize_merge_request：生成合並請求的 AI 友好摘要。

{
  "project_id": "group/project",
  "mr_iid": 456,
  "max_length": 500
}

• gitlab_smart_diff：獲取結構化的差異比較結果，並可配置上下文和大小限制。

{
  "project_id": "group/project",
  "from_ref": "main",
  "to_ref": "feature",
  "context_lines": 3,
  "max_file_size": 50000
}

用戶與個人資料管理

• gitlab_search_user：按姓名、用戶名或電子郵件搜索 GitLab 用戶。

{
  "search": "John",
  "per_page": 10
}

• gitlab_get_user_details：獲取全面的用戶個人資料和元數據。

{
  "username": "johndoe"
}

• gitlab_get_my_profile：獲取當前認證用戶的完整個人資料。

{}

• gitlab_get_user_contributions_summary：總結用戶在問題、合併請求和提交方面的近期貢獻。

{
  "username": "johndoe",
  "since": "2024-01-01",
  "until": "2024-01-31"
}

• gitlab_get_user_activity_feed：檢索用戶的完整活動/事件時間線。

{
  "username": "johndoe", 
  "target_type": "Issue",
  "after": "2024-01-01"
}

用戶的問題與合併請求

• gitlab_get_user_open_mrs：獲取用戶發起的所有未處理合併請求。

{
  "username": "johndoe",
  "sort": "updated"
}

• gitlab_get_user_review_requests：獲取用戶被指定為審核人且有待處理操作的合併請求。

{
  "username": "johndoe",
  "priority": "high",
  "sort": "urgency"
}

• gitlab_get_user_open_issues：獲取分配給用戶的未處理問題，並按嚴重程度/SLA 排序。

{
  "username": "johndoe",
  "sla_status": "overdue",
  "sort": "priority"
}

• gitlab_get_user_reported_issues：獲取用戶報告/創建的問題。

{
  "username": "johndoe",
  "state": "opened",
  "since": "2024-01-01"
}

• gitlab_get_user_resolved_issues：獲取用戶關閉/解決的問題。

{
  "username": "johndoe",
  "since": "2024-01-01",
  "until": "2024-03-31"
}

用戶的代碼與提交

• gitlab_get_user_commits：獲取用戶在指定日期範圍或分支內的提交。

{
  "username": "johndoe", 
  "branch": "main",
  "since": "2024-01-01",
  "include_stats": true
}

完整工具列表

• 項目管理：gitlab_list_projects、gitlab_get_project、gitlab_get_current_project、gitlab_search_projects
• 問題管理：gitlab_list_issues、gitlab_get_issue、gitlab_add_issue_comment、gitlab_summarize_issue
• 合併請求管理：gitlab_list_merge_requests、gitlab_get_merge_request、gitlab_update_merge_request、gitlab_close_merge_request、gitlab_merge_merge_request、gitlab_add_merge_request_comment、gitlab_get_merge_request_notes、gitlab_approve_merge_request、gitlab_get_merge_request_approvals、gitlab_get_merge_request_discussions、gitlab_resolve_discussion、gitlab_get_merge_request_changes、gitlab_rebase_merge_request
• 倉庫管理：gitlab_get_file_content、gitlab_list_repository_tree、gitlab_list_commits、gitlab_get_commit、gitlab_get_commit_diff、gitlab_create_commit、gitlab_cherry_pick_commit、gitlab_compare_refs、gitlab_list_tags
• 分支管理：gitlab_list_branches
• 管道與作業管理：gitlab_list_pipelines、gitlab_list_pipeline_jobs、gitlab_list_project_jobs、gitlab_download_job_artifact、gitlab_summarize_pipeline
• 搜索功能：gitlab_search_projects、gitlab_search_in_project
• 用戶管理：gitlab_get_current_user、gitlab_get_user、gitlab_list_user_events、gitlab_list_project_members
• 用戶與個人資料管理：gitlab_search_user、gitlab_get_user_details、gitlab_get_my_profile、gitlab_get_user_contributions_summary、gitlab_get_user_activity_feed
• 用戶的問題與合併請求管理：gitlab_get_user_open_mrs、gitlab_get_user_review_requests、gitlab_get_user_open_issues、gitlab_get_user_reported_issues、gitlab_get_user_resolved_issues
• 用戶的代碼與提交管理：gitlab_get_user_commits
• 版本發佈管理：gitlab_list_releases
• Webhook 管理：gitlab_list_project_hooks
• AI 工具：gitlab_summarize_merge_request、gitlab_summarize_issue、gitlab_summarize_pipeline
• 高級工具：gitlab_batch_operations、gitlab_smart_diff、gitlab_safe_preview_commit

配置

環境變量

設置以下認證令牌之一：

# 私有令牌（個人使用推薦）
export GITLAB_PRIVATE_TOKEN="your-private-token"

# OAuth 令牌
export GITLAB_OAUTH_TOKEN="your-oauth-token"

# GitLab URL（可選，默認為 https://gitlab.com）
export GITLAB_URL="https://gitlab.example.com"

獲取 GitLab 令牌

1. 進入你的 GitLab 個人資料設置。
2. 導航到“訪問令牌”。
3. 創建一個具有以下作用域的新令牌：
   • api - 完整的 API 訪問權限。
   • read_repository - 讀取倉庫內容。
   • write_repository - 寫入倉庫內容（用於提交）。

使用方法

與 Claude Desktop 配合使用

添加到你的 Claude Desktop 配置中：

使用 uvx（推薦 - 無需安裝）

{
  "mcp-gitlab": {
    "command": "uvx",
    "args": ["mcp-gitlab"],
    "env": {
      "GITLAB_PRIVATE_TOKEN": "your-token-here"
    }
  }
}

使用 uv（如果你克隆了倉庫）

{
  "mcp-gitlab": {
    "command": "uv",
    "args": ["run", "mcp-gitlab"],
    "cwd": "/path/to/mcp-gitlab",
    "env": {
      "GITLAB_PRIVATE_TOKEN": "your-token-here"
    }
  }
}

將 /path/to/mcp-gitlab 替換為你克隆倉庫的完整路徑。

使用 uvx 運行

# 設置你的 GitLab 令牌
export GITLAB_PRIVATE_TOKEN="your-token-here"

# 使用 uvx 直接運行服務器
uvx mcp-gitlab

獨立使用

# 如果從源代碼運行（在 uv sync 之後）
uv run mcp-gitlab

# 或者直接運行 Python 模塊
uv run python -m mcp_gitlab

🔧 技術細節

開發

快速開始

# 安裝開發依賴
make install-dev

# 在本地運行所有檢查
make ci-local

# 格式化代碼
make format

# 運行帶覆蓋率的測試
make test-cov

CI/CD 管道

本項目使用 GitHub Actions 進行持續集成和部署：

• CI 管道：每次推送和 PR 時運行

  • 代碼檢查（Ruff、Black、isort、MyPy）
  • 測試（pytest 並帶覆蓋率）
  • 安全掃描（Bandit、Safety、pip-audit）
  • 多版本 Python 測試（3.10、3.11、3.12）

• 代碼質量：

  • SonarCloud 分析
  • CodeQL 安全分析
  • 複雜度指標（Radon、Xenon）

• 發佈管道：在版本標籤上自動發佈

  • PyPI 包發佈
  • Docker 鏡像構建和發佈
  • GitHub 版本發佈

運行測試

# 運行所有測試
uv run pytest tests/ -v

# 運行帶覆蓋率的測試
uv run pytest tests/ --cov=mcp_gitlab

# 運行特定的測試文件
uv run pytest tests/test_gitlab_client.py -v

代碼風格

項目使用以下工具進行代碼風格管理：

• Black 用於代碼格式化
• isort 用於導入排序
• flake8 用於代碼檢查
• mypy 用於類型檢查

# 格式化代碼
black src/ tests/
isort src/ tests/

# 運行代碼檢查工具
flake8 src/ tests/
mypy src/

故障排除

認證問題

• 確保你的令牌具有所需的作用域（api、read_repository、write_repository）。
• 檢查令牌的過期日期。
• 如果你使用的是自託管實例，請驗證 GitLab URL。

速率限制

GitLab API 有速率限制。服務器會優雅地處理速率限制錯誤，並返回適當的錯誤消息。

大響應

如果響應超過大小限制，會自動截斷。使用分頁參數分塊檢索數據。

貢獻

1. 分叉倉庫
2. 創建功能分支（git checkout -b feature/amazing-feature）
3. 提交你的更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打開拉取請求

📄 許可證

本項目採用 Apache 許可證 2.0 版 - 有關詳細信息，請參閱 LICENSE 文件。

致謝

• 基於 模型上下文協議 構建。
• 使用 python-gitlab 進行 GitLab API 交互。
• 受改善大語言模型與 GitLab 集成需求的啟發。