MCP Gitlab Jira

🚀 MCP GitLab Jira Server

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

🚀 快速開始

本 MCP 服務器可幫助 AI 代理與 GitLab 和 Jira 實例交互。以下是快速開始使用它的步驟：

1. 確保滿足所有前置條件。
2. 完成安裝步驟，包括全局安裝包和設置環境變量。
3. 手動測試服務器是否能正常啟動。
4. 配置 MCP 客戶端以使用該服務器。

如果你想使用 Docker 運行服務器，可按照 Docker 相關部分的步驟操作。

✨ 主要特性

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": {}
    }
  }
}

💻 使用示例

基礎用法

以下是手動測試服務器啟動的示例：

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | mcp-gitlab-jira

高級用法

使用 Docker 持久化容器與 MCP 客戶端配合使用

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

使用 Docker 一次性執行與 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": {}
    }
  }
}

📚 詳細文檔

可用工具

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 工單轉換到新狀態。

🔧 技術細節

項目結構

• 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 重新構建項目。

本地 Docker 開發

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

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

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

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

📄 許可證

本項目採用 ISC 許可證。

🔧 故障排除

常見問題

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