MCP Gitlab Jira

🚀 MCP GitLab Jira Server

このサーバーは、GitLabとJiraを統合するためのModel Context Protocol (MCP) サーバーです。gemini-cliなどのAIエージェントがGitLabとJiraインスタンスとやり取りできるようにします。

✨ 主な機能

GitLab

• プロジェクト：アクセス可能なすべてのプロジェクトをリストするか、名前でフィルタリングします。
• マージリクエスト：プロジェクトのマージリクエストをリストし、詳細情報（差分を含む）を取得し、コメントを追加し、レビュアーを割り当てます。
• ファイル：指定されたSHAの特定のファイルの内容を取得します。
• リリース：プロジェクトのすべてのリリースをリストするか、特定のバージョン以降のものをフィルタリングします。
• ユーザー：プロジェクトメンバーをリストし、ユーザー名からユーザーIDを取得し、ユーザーのアクティビティを取得します。

Jira

• チケット：チケットの詳細情報を取得し、コメントを取得し、コメントを追加し、JQLを使用してチケットを検索し、新しいチケットを作成し、利用可能なトランジションを取得し、チケットを更新し、チケットのステータスを変更します。

📦 インストール

前提条件

• Node.js 18以上
• APIアクセス権限のあるGitLab Personal Access Token
• Jira API Token
• 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の事前構築済みイメージを使用して、この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）

MCPクライアントでDockerコンテナを使用するには、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": {}
    }
  }
}

💻 利用可能なツール

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