Jira Weekly Reporter MCP Server

Jira Weekly Reporter MCP Server

このプロジェクトは、Jira インスタンス（Cloud または Server/Data Center）に接続し、課題のアクティビティに基づいて週次レポートを生成する FastMCP サーバーを提供します。Jira とのやり取りには pycontribs-jira ライブラリを利用し、生成したレポートの要約には、接続されたクライアントの LLM を任意で使用できます。

✨ 特長

• Jira 接続： .env ファイルに保存された API トークンを使用して、Jira に安全に接続します。
• MCP ツール： Model Context Protocol 経由で利用できる generate_jira_report ツールを公開します。
• 柔軟なレポート作成：
  • 直近 7 日間に更新された課題をデフォルトでレポートします。
  • カスタム JQL クエリを指定できます。
  • 特定の Jira プロジェクトキーでレポートを絞り込めます。
  • 返される結果の数を制限できます（設定可能）。
• （任意）LLM による要約： レポートの簡潔な要約を生成するために、クライアントの LLM（ctx.sample() 経由）を使用できます。
• 非同期処理： asyncio.to_thread を使用して、非同期の FastMCP サーバー内で同期的な Jira ライブラリの呼び出しを適切に処理します。

📋 前提条件

• Python 3.10 以降。
• パッケージ管理には uv（推奨）または pip。
• Jira インスタンス（Cloud、Server、または Data Center）へのアクセス。
• Jira API トークン（Server/DC の場合はパーソナルアクセストークン）。
• FastMCP CLI がインストールされ、システムの PATH から利用できること。

⚙️ セットアップ

1. リポジトリをクローンします（該当する場合）：

   git clone https://github.com/Jongryong/jira_reporter.git
   cd jira_reporter
   

2. 依存関係をインストールします： uv の使用をおすすめします：

   uv pip install fastmcp "jira[cli]" python-dotenv httpx anyio
   

   または、pip を使用します：

   pip install fastmcp "jira[cli]" python-dotenv httpx anyio
   

3. .env ファイルを作成します： jira_reporter_server.py と同じディレクトリに .env という名前のファイルを作成します。Jira の接続情報を追加してください：

   # .env
   JIRA_URL=https://your-domain.atlassian.net  # Your Jira Cloud URL or Self-Hosted URL
   [email protected]       # Your Jira login email
   JIRA_API_TOKEN=your_api_token_or_pat       # Your generated API Token or PAT
   

   • セキュリティ：
     • .env ファイルをバージョン管理に絶対にコミットしないでください！ .gitignore ファイルに .env を追加してください。
     • Jira Cloud： Atlassian アカウント設定から API トークンを生成します：API トークンを管理。
     • Jira Server/Data Center： Jira のユーザープロフィール設定からパーソナルアクセストークン（PAT）を生成します：パーソナルアクセストークンの使用。

▶️ サーバーの実行（スタンドアロン）

テストなどの目的で、サーバーを単独で実行できます：

1. Python から直接実行する：

   python jira_reporter_server.py
   

2. FastMCP CLI を使用する：

   fastmcp run jira_reporter_server.py
   

   SSE を使用して実行する場合（リモートアクセス用など）：

   fastmcp run jira_reporter_server.py --transport sse --port 8001
   

🖥️ Claude Desktop での使用

このサーバーを Claude Desktop アプリケーション内のツールとして使用できるようにするには：

1. 前提条件を確認する： 以下の設定では fastmcp コマンドを使用するため、fastmcp がインストールされ、システムの PATH から利用できることを確認してください。

2. Claude の設定ファイルを探す： claude_desktop_config.json ファイルを探します。ファイルの場所はオペレーティングシステムによって異なります：

   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows： %APPDATA%\Claude\claude_desktop_config.json（通常は C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json）
   • Linux： ~/.config/Claude/claude_desktop_config.json（または $XDG_CONFIG_HOME/Claude/）

3. 設定ファイルを編集する： テキストエディターで claude_desktop_config.json を開きます。

4. サーバー設定を追加する： JSON 内の "mcpServers" オブジェクトを探します（存在しない場合は、空のオブジェクト {} として作成します）。"path/to/your/jira_reporter_server.py" をスクリプトの絶対パスに置き換えてから、mcpServers 内に以下のエントリを追加します：

   {
     "mcpServers": {
       // ... 他のサーバーがここにある場合があります ...
   
       "jira_report": {
         "command": "fastmcp",
         "args": [
           "run",
           "/path/to/your/jira_reporter_server.py" // <-- 重要：ここでは完全な絶対パスを使用してください
         ]
       }
   
       // ... 他のサーバーがここにある場合があります ...
     }
     // ... Claude の設定の残り ...
   }
   

   • "jira_report"：これは Claude が使用する内部名です。必要に応じて変更できます。
   • "command": "fastmcp"：Claude に fastmcp コマンドラインツールを使用するよう指示します。
   • "args": [...]：Claude に fastmcp run /path/to/your/jira_reporter_server.py を実行するよう指示します。

5. 保存して再起動する： claude_desktop_config.json ファイルを保存し、Claude Desktop アプリケーションを再起動します。

6. ツールを呼び出す： これで、Python スクリプトで定義されたサーバー名（Jira Weekly Reporter）を指定して、Claude でツールを使用できるようになります。例： @Jira Weekly Reporter generate jira report for project MYPROJ and summarize it

🛠️ MCP ツールの詳細

• ツール名： generate_jira_report
• 説明： JQL クエリ（デフォルトでは最近更新されたもの）に基づいて Jira の課題レポートを生成します。必要に応じて、クライアントの LLM を使用してレポートを要約します。

パラメーター：

パラメーター	型	必須	デフォルト	説明
jql_query	string	いいえ	updated >= -7d ORDER BY updated DESC	任意の JQL クエリです。省略した場合は、デフォルトが使用されます。
project_key	string	いいえ	None	検索範囲を限定する任意の Jira プロジェクトキー（例：「PROJ」）です（project = 'KEY' AND ... として追加されます）。
max_results	integer	いいえ	50	生レポートデータに含める課題の最大数です。
summarize	boolean	いいえ	false	true の場合、サーバーは ctx.sample() を介してクライアントの LLM に要約を要求します。

📦 サーバーの依存関係

FastMCP コンストラクターには dependencies=["jira"] が含まれています。これは、fastmcp install などのツールに対し、分離された環境を作成する際に、このサーバーが正しく動作するために jira ライブラリが必要であることを伝えます。

🤝 コントリビューション

コントリビューションを歓迎します！お気軽にイシューやプルリクエストを送信してください。

📄 ライセンス

MIT ライセンス