JIRA MCP Server 🚀

JIRA MCP Server 🚀

JIRA Cloud REST API と連携する Model Context Protocol（MCP）を実装した柔軟な Go サーバーです。LLM／ツールと JIRA プロジェクトをシームレスに統合できます。

これは何ですか？ 🤔

このプロジェクトは、Model Context Protocol（特定の AI アシスタントや開発ツールなど）を利用するシステムと、強力な JIRA Cloud API の橋渡しをします。標準化された MCP インターフェースを通じて、一般的な JIRA 操作（課題の作成、検索、詳細の取得）をプログラムから実行できます。これにより、JIRA API を直接呼び出す複雑さを抽象化します。

✨ 特長

• MCP インターフェース： 標準の MCP エンドポイントを通じて JIRA 操作を提供します。
• JIRA Cloud 連携： 課題の作成、JQL による検索、課題の詳細取得、エピック内の課題の取得ができます。
• 柔軟な設定： Viper を使用し、環境変数、設定ファイル、またはデフォルト値から設定できます。
• Docker サポート： Docker と Docker Compose を使用したコンテナーデプロイに対応しています。
• 堅牢なテスト： 包括的な単体テストと統合テストが含まれています。
• 構造化ログ： slog を使用して、明確な構造化ログを出力します。
• 依存性注入： wire を使用した依存性注入など、クリーンアーキテクチャの原則に基づいて構築されています。

前提条件

• Go 1.20+（ローカルでのビルド／実行用）
• Docker と Docker Compose（任意、コンテナーデプロイ用）
• JIRA Cloud インスタンス
• ユーザーのメールアドレスに紐づいた JIRA API トークン

🚀 はじめに

1. リポジトリをクローンします：

   git clone https://github.com/karolswdev/jira-mcp-server.git # TODO: Replace with actual URL
   cd jira-mcp-server # e.g., cd jira-mcp
   

2. サーバーディレクトリに移動します：

   cd jira-mcp-server
   

   ➡️ 重要： 以降のコマンド（make ...、go run ...、docker ...）は、jira-mcp-server/ ディレクトリ内で実行してください。

3. サーバーを設定します： 必須の環境変数を設定するか、config.yaml を作成します。詳しくは、以下の設定セクションをご覧ください。

4. サーバーを実行します： 詳しくは、以下のサーバーの実行セクションをご覧ください。

⚙️ 設定

設定はViperを使用して管理され、以下のソースから優先順位の高い順に読み込まれます。

1. 環境変数： JIRA_MCP_ を接頭辞として指定します（例：JIRA_MCP_JIRA_URL）。最優先です。
2. 設定ファイル： jira-mcp-server/ ディレクトリ内にある config.yaml（または .json、.toml）。構造とすべてのオプションについては、config.yaml.exampleを参照してください。
3. デフォルト値： アプリケーションコード内で定義されているデフォルト値です。

必須の設定：

以下の値は、環境変数または設定ファイルで指定する必要があります。

• JIRA_MCP_JIRA_URL：JIRA Cloud インスタンスのベース URL（例：https://your-domain.atlassian.net）。
• JIRA_MCP_JIRA_USER_EMAIL：API トークンに関連付けられた JIRA ユーザーのメールアドレス。
• JIRA_MCP_JIRA_API_TOKEN：JIRA API トークンです。パスワードと同様に取り扱ってください！

任意の設定：

• JIRA_MCP_PORT：サーバーがリッスンするポート（デフォルト：8080）。
• JIRA_MCP_LOG_LEVEL：ログレベル（debug、info、warn、error）（デフォルト：info）。
• JIRA_MCP_EPIC_LINK_FIELD_ID：JIRA インスタンスの「Epic Link」のカスタムフィールド ID（例：customfield_10014）。/jira_epic/{epicKey}/issues エンドポイントを正しく動作させるために必須です。この ID は JIRA API または管理設定から確認できます。

例（環境変数）：

export JIRA_MCP_JIRA_URL="https://your-domain.atlassian.net"
export JIRA_MCP_JIRA_USER_EMAIL="[email protected]"
export JIRA_MCP_JIRA_API_TOKEN="your-api-token-secret"
export JIRA_MCP_PORT="9000" # Optional
export JIRA_MCP_EPIC_LINK_FIELD_ID="customfield_10014" # Optional but needed for Epic endpoint

▶️ サーバーの実行

jira-mcp-server/ ディレクトリ内に移動し、必須の設定が済んでいることを確認してください。

オプション 1：直接実行（Go を使用）

# Ensure required JIRA_MCP_... environment variables are set
make run
# Or: go run ./cmd/main.go

サーバーは、設定されたポート（デフォルトは 8080）でリッスンを開始します。

オプション 2：Docker で実行

1. Docker イメージをビルドします：

   make docker-build
   

2. .env ファイルを作成します： jira-mcp-server/ ディレクトリ内に .env という名前のファイルを作成し、JIRA_MCP_ 環境変数を記述します（1 行に 1 つ。例：JIRA_MCP_JIRA_URL=...）。

   # .env file content example
   JIRA_MCP_JIRA_URL=https://your-domain.atlassian.net
   [email protected]
   JIRA_MCP_JIRA_API_TOKEN=your-api-token-secret
   JIRA_MCP_PORT=8080 # Optional, ensure it matches docker-compose.yml mapping if changed
   JIRA_MCP_EPIC_LINK_FIELD_ID=customfield_10014 # Optional
   

3. Docker Compose を使用して実行します：

   make docker-run
   # This command uses docker-compose up -d
   

   コンテナを停止するには、docker-compose down を実行します。

🔌 API エンドポイント

サーバーは、以下の主要なエンドポイントを公開します。

• POST /create_jira_issue：新しい JIRA 課題を作成します。
• POST /search_jira_issues：JQL を使用して JIRA 課題を検索します。
• GET /jira_issue/{issueKey}：指定した JIRA 課題の詳細を取得します。
• GET /jira_epic/{epicKey}/issues：指定したエピックに属するすべての課題を取得します（JIRA_MCP_EPIC_LINK_FIELD_ID の設定が必要です）。

リクエストとレスポンスの例

各エンドポイントの詳細なリクエストとレスポンスの例については、以下を参照してください。

➡️ API_EXAMPLES.md

✅ テスト

このプロジェクトには、ユニットテストと統合テストの両方が含まれています。jira-mcp-server/ ディレクトリから以下のコマンドを実行してください。

• ユニットテストを実行： 各コンポーネントを個別にテストします（JIRA API をモックします）。

  make test
  

• 統合テストを実行： モック JIRA サーバーを使用して HTTP API レイヤーをテストします。

  make test-integration
  

• ユニットテストのカバレッジを表示： coverage.html を生成してブラウザーで開きます。

  make coverage
  

• 統合テストのカバレッジを表示： coverage-integration.html を生成してブラウザーで開きます。

  make coverage-integration
  

🏗️ アーキテクチャ

このサーバーはクリーンアーキテクチャの原則に従い、依存性注入（wire）、構造化ログ（slog）、関心事の階層的な分離（ハンドラー、JIRA クライアント、コアロジック）を採用しています。

詳しい説明については、**アーキテクチャドキュメント**をご覧ください。

🤝 貢献

貢献を歓迎しており、大変感謝しています！バグの報告、機能の提案、ドキュメントの改善、プルリクエストの提出など、皆さまの協力がこのプロジェクトをより良いものにします。

始める前に、**貢献ガイドライン**をお読みください。

また、このプロジェクトには**コントリビューター行動規範**が適用されていることにご留意ください。このプロジェクトに参加することで、その規約に従うことに同意したものとみなされます。

📜 ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については、**LICENSE**ファイルをご覧ください。

⚠️ セキュリティに関する注意

JIRA API トークンやその他の機密性の高い認証情報を、バージョン管理下のコードや設定ファイルに直接コミットしないでください。 特に本番環境へのデプロイでは、環境変数または安全なシークレット管理システムを使用してください。Docker で .env ファイルを使用する場合は、そのファイルが .gitignore に含まれていることを確認してください。