MCP Gitlab Jira

🚀 MCP GitLab Jira 服務器

這是一個用於集成 GitLab 和 Jira 的模型上下文協議（MCP）服務器。該服務器允許像 gemini-cli 這樣的 AI 代理與你的 GitLab 和 Jira 實例進行交互。

🚀 快速開始

本 MCP 服務器可助力 AI 代理與 GitLab 和 Jira 實例交互。以下將為你介紹其特性、安裝、使用及開發等相關內容。

✨ 主要特性

GitLab

• 項目管理：可列出所有可訪問的項目，也能按名稱篩選項目。
• 合併請求操作：列出項目的合併請求，獲取詳細信息（包括差異比較），添加評論並分配審核人員。
• 文件獲取：獲取指定 SHA 版本下特定文件的內容。
• 版本發佈管理：列出項目的所有版本發佈，或篩選自特定版本以來的發佈。
• 用戶管理：列出項目成員，通過用戶名獲取用戶 ID，並獲取用戶活動信息。

Jira

• 工單管理：獲取工單的詳細信息、評論，添加評論，使用 JQL 搜索工單，創建新工單，獲取可用的轉換操作，更新工單並將工單轉換到新狀態。

📦 安裝指南

前提條件

• Node.js 18 及以上版本
• 具有 API 訪問權限的 GitLab 個人訪問令牌
• Jira API 令牌
• 可訪問的 GitLab 實例（本地部署或 GitLab.com）
• 可訪問的 Jira 實例

安裝步驟

1. 全局安裝軟件包：

npm i -g mcp-gitlab-jira

2. 設置環境變量：

# GitLab
export GITLAB_URL="https://your-gitlab-instance.com"
export GITLAB_ACCESS_TOKEN="your-personal-access-token"

# Jira
export ATLASSIAN_SITE_NAME="your-atlassian-site-name"
export ATLASSIAN_USER_EMAIL="your-email@example.com"
export ATLASSIAN_API_TOKEN="your-jira-api-token"

3. 手動測試服務器：

# 測試服務器是否能正常啟動
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | mcp-gitlab-jira

服務器應啟動並在 stderr 中記錄 “GitLab/Jira MCP server started”。

與 MCP 客戶端配合使用

gemini-cli 或其他 MCP 客戶端的配置

創建或更新你的 MCP 配置文件（通常為 ~/.mcp/config.json 或類似文件）：

{
  "mcpServers": {
    "gitlab-jira-mcp": {
      "command": "mcp-gitlab-jira",
      "env": {
        "GITLAB_URL": "https://your-gitlab-instance.com",
        "GITLAB_ACCESS_TOKEN": "your-personal-access-token",
        "ATLASSIAN_SITE_NAME": "your-atlassian-site-name",
        "ATLASSIAN_USER_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "your-jira-api-token"
      }
    }
  }
}

🐳 使用 Docker 運行

你也可以使用 Docker Hub 上的預構建鏡像，在 Docker 容器中運行此 MCP 服務器。

可用的 Docker 鏡像

Docker 鏡像會為每個版本自動構建併發布到 Docker Hub：

• 最新版本：hainanzhao/mcp-gitlab-jira:latest
• 特定版本：hainanzhao/mcp-gitlab-jira:v0.1.2、hainanzhao/mcp-gitlab-jira:v0.1.1 等。
• 查看所有可用標籤：Docker Hub - mcp-gitlab-jira

這些鏡像支持多種架構：linux/amd64 和 linux/arm64（兼容 Apple Silicon）。

使用方法

1. 拉取並運行 Docker 容器：

docker run -d --name mcp-gitlab-jira-container \
  -e GITLAB_URL="https://your-gitlab-instance.com" \
  -e GITLAB_ACCESS_TOKEN="your-personal-access-token" \
  -e ATLASSIAN_SITE_NAME="your-atlassian-site-name" \
  -e ATLASSIAN_USER_EMAIL="your-email@example.com" \
  -e ATLASSIAN_API_TOKEN="your-jira-api-token" \
  hainanzhao/mcp-gitlab-jira:latest

2. 替代方案：無持久化容器運行（一次性執行）：

docker run --rm -i \
  -e GITLAB_URL="https://your-gitlab-instance.com" \
  -e GITLAB_ACCESS_TOKEN="your-personal-access-token" \
  -e ATLASSIAN_SITE_NAME="your-atlassian-site-name" \
  -e ATLASSIAN_USER_EMAIL="your-email@example.com" \
  -e ATLASSIAN_API_TOKEN="your-jira-api-token" \
  hainanzhao/mcp-gitlab-jira:latest

與 MCP 客戶端配合使用（Docker 方式）

你可以通過以下兩種方式將 Docker 容器與 MCP 客戶端配合使用：

方案 1：使用持久化容器（推薦）

首先，按上述方法啟動容器，然後更新你的 MCP 配置文件。由於必要的環境變量已通過 docker run 命令的 -e 標誌直接傳遞給容器，因此 env 塊為空。

{
  "mcpServers": {
    "gitlab-jira-mcp": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-gitlab-jira-container", "npm", "start"],
      "env": {}
    }
  }
}

方案 2：使用一次性執行

此方法會為每個 MCP 會話運行一個新容器：

{
  "mcpServers": {
    "gitlab-jira-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITLAB_URL=https://your-gitlab-instance.com",
        "-e", "GITLAB_ACCESS_TOKEN=your-personal-access-token",
        "-e", "ATLASSIAN_SITE_NAME=your-atlassian-site-name",
        "-e", "ATLASSIAN_USER_EMAIL=your-email@example.com",
        "-e", "ATLASSIAN_API_TOKEN=your-jira-api-token",
        "hainanzhao/mcp-gitlab-jira:latest"
      ],
      "env": {}
    }
  }
}

💻 使用示例

基礎用法

以下是使用 MCP 服務器與 GitLab 和 Jira 交互的示例：

# 測試服務器啟動
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | mcp-gitlab-jira

高級用法

使用 Docker 運行

# 拉取並運行 Docker 容器
docker run -d --name mcp-gitlab-jira-container \
  -e GITLAB_URL="https://your-gitlab-instance.com" \
  -e GITLAB_ACCESS_TOKEN="your-personal-access-token" \
  -e ATLASSIAN_SITE_NAME="your-atlassian-site-name" \
  -e ATLASSIAN_USER_EMAIL="your-email@example.com" \
  -e ATLASSIAN_API_TOKEN="your-jira-api-token" \
  hainanzhao/mcp-gitlab-jira:latest

📚 詳細文檔

可用工具

GitLab 工具

• gitlab_get_merge_request_details：獲取 GitLab 合併請求的詳細信息，包括文件差異比較。
• gitlab_get_file_content：獲取 GitLab 項目中指定 SHA 版本下特定文件的內容。
• gitlab_add_comment_to_merge_request：向 GitLab 合併請求添加評論。可以是普通評論、對現有討論的回覆或特定行的內聯評論。
• gitlab_list_merge_requests：列出給定 GitLab 項目的合併請求。
• gitlab_assign_reviewers_to_merge_request：為 GitLab 合併請求分配審核人員。
• gitlab_list_project_members：列出給定 GitLab 項目的所有成員（貢獻者）。
• gitlab_list_project_members_by_project_name：按項目名稱列出給定 GitLab 項目的所有成員（貢獻者）。
• gitlab_list_projects_by_name：使用模糊、不區分大小寫的匹配方式按名稱篩選 GitLab 項目。
• gitlab_list_all_projects：列出所有可訪問的 GitLab 項目。
• gitlab_list_all_releases：獲取給定 GitLab 項目的版本發佈信息。
• gitlab_list_releases_since_version：篩選自特定版本以來給定 GitLab 項目的版本發佈。
• gitlab_get_user_id_by_username：根據用戶名獲取 GitLab 用戶 ID。
• gitlab_get_user_activities：根據用戶名獲取給定 GitLab 用戶的活動信息，可選擇按日期篩選。

Jira 工具

• jira_get_jira_ticket_details：獲取 Jira 工單的詳細信息。
• jira_get_jira_ticket_comments：獲取 Jira 工單的評論。
• jira_add_comment_to_ticket：向 Jira 工單添加評論。
• jira_search_tickets_by_jql：使用 JQL（Jira 查詢語言）字符串搜索 Jira 工單。
• jira_create_ticket：使用給定字段創建新的 Jira 工單。
• jira_get_available_transitions：獲取 Jira 工單的可用轉換操作。
• jira_update_ticket：更新 Jira 工單的摘要、描述和標籤。
• jira_update_custom_fields：更新 Jira 工單的自定義字段。
• jira_transition_ticket：將 Jira 工單轉換到新狀態。

故障排除

常見問題

1. “Cannot find module” 錯誤：如果你在本地開發，請確保已運行 npm install 和 npm run build。
2. 認證錯誤：驗證你的 GITLAB_ACCESS_TOKEN、ATLASSIAN_USER_EMAIL 和 ATLASSIAN_API_TOKEN 是否具有必要的權限。
3. 連接錯誤：確保你的 GITLAB_URL 和 ATLASSIAN_SITE_NAME 正確且可訪問。
4. 服務器無響應：檢查 MCP 服務器進程是否正在運行，以及配置文件中的路徑是否正確。

調試模式

若要查看詳細日誌，可直接運行服務器：

export GITLAB_URL="your-url"
export GITLAB_ACCESS_TOKEN="your-token"
export ATLASSIAN_SITE_NAME="your-atlassian-site-name"
export ATLASSIAN_USER_EMAIL="your-email@example.com"
export ATLASSIAN_API_TOKEN="your-jira-api-token"
mcp-gitlab-jira

開發相關

本地開發

若要進行開發，請克隆倉庫並安裝依賴：

npm install
npm run build

本地 Docker 開發

在推送之前，可在本地測試 Docker 構建：

# 在本地構建並測試 Docker 鏡像
./scripts/build-docker-local.sh

此腳本將構建 Docker 鏡像並運行基本測試，以確保其正常工作。

維護人員注意：有關設置自動化 Docker Hub 發佈的信息，請參閱 Docker 設置指南。

項目結構

• src/index.ts：主 MCP 服務器實現
• src/gitlab.service.ts：GitLab API 客戶端
• src/gitlab.ts：GitLab 類型定義
• src/jira.service.ts：Jira API 客戶端
• src/jira.ts：Jira 類型定義
• dist/：編譯後的 JavaScript 輸出

添加新功能

1. 向 GitLabService 或 JiraService 類添加新方法。
2. 在 index.ts 的 allTools 數組中定義新工具。
3. 在 index.ts 的工具處理程序中添加相應的 case 語句。
4. 使用 npm run build 重新構建項目。

🔧 技術細節

本項目使用 Node.js 實現 MCP 服務器，通過 src/gitlab.service.ts 和 src/jira.service.ts 分別與 GitLab 和 Jira 的 API 進行交互。項目使用 TypeScript 編寫，在 src 目錄下定義類型和服務，編譯後的 JavaScript 文件輸出到 dist 目錄。通過 npm run build 命令將 TypeScript 代碼編譯為 JavaScript 代碼。

📄 許可證

本項目採用 ISC 許可證。