MCP Gitlab Jira

🚀 MCP GitLab Jira Server

このサーバーは、Model Context Protocol (MCP) を使用して、GitLab と Jira を統合するためのものです。gemini-cli などの 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
   

   サーバーが起動し、標準エラー出力に "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 の事前構築済みイメージを使用して、この MCP サーバーを Docker コンテナで実行することもできます。

利用可能な 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 クライアントで使用するには、2 つのオプションがあります。

オプション 1: 永続的なコンテナを使用する（推奨）

まず、上記のようにコンテナを起動し、次に MCP 設定ファイルを更新します。env ブロックは空になります。なぜなら、必要な環境変数は docker run コマンドの -e フラグを使用して直接コンテナに渡されるからです。

{
  "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 コンテナを使用してサーバーを実行する
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 Query Language）文字列を使用して 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 Setup Guide を参照してください。

プロジェクト構造

• 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 のツールハンドラーに対応するケースを追加します。
4. npm run build で再ビルドします。

📄 ライセンス

ISC