fusion-pm-mcp

Fusion PM MCP のセットアップガイド

使用する場面

ユーザーから次のような質問があった場合に使用します。

• Fusion PM MCP とは何か
• インストール方法や設定方法
• 動作していることを確認する方法
• セットアップの失敗や、古い結果／レート制限の問題のトラブルシューティング方法

よくある質問：

• 「fusion pm mcp とは何ですか」
• 「fusion pm mcp のセットアップを手伝ってください」
• 「レート制限にかからずに GitHub の issue／PR を Copilot に取り込むにはどうすればよいですか」

使用しない場面

• fusion-pm-mcp サービスのソースコードの実装や変更 — それはリポジトリ自体で行います
• Fusion Framework／ドキュメント／EDS／バックエンドコード全般の取得 — fusion-mcp を使用します
• GitHub の issue／PR の作成、トリアージ、レビュー — MCP ツールが利用可能になったら、fusion-issue-authoring またはリポジトリ固有のレビュー用スキルを使用します
• ユーザーに確認せず、環境に破壊的な変更を加えること

必要な入力

セットアップ手順を提案する前に、次の情報を確認します。

• GitHub トークンを利用できるか（gh auth token、または repo スコープを持つ PAT） — 設定には保存せず、リクエストごとに渡します
• 対象のクライアント（主な対象は VS Code）

詳細が不明な場合は、まず簡潔な確認質問をします。

手順

1. この MCP サーバーが提供する機能を説明します。
   • GitHub REST API のキャッシュプロキシを MCP ツールとして公開することで、エージェントは呼び出しのたびに GitHub のレート制限に達することなく、プロジェクトデータを読み取れます。
   • マネージドサービスとしてホストされているため、ほとんどのユーザーはローカルのインフラストラクチャを用意する必要がありません。
   • ツール（tools/list で実際のツール名を確認してください。古いドキュメントよりも、サーバーの実際のソースを正とします）：api_get_issue、api_get_parent_issue、api_get_child_issues、api_get_issue_comments、api_list_milestones、api_get_milestone、api_upsert_issue、api_close、api_get_metadata_schema、api_get_pull_request、api_get_pr_comments、api_get_pr_reviews、api_get_pr_review、api_get_review_comments、api_resolve_review_comment
   • レスポンスはキャッシュされます（デフォルトの TTL は 300 秒）。キャッシュを無効化するツールはありません。古い結果は TTL の経過後に自動的に解消されます。
2. ホスト型の本番サーバーをセットアップするよう案内します。推奨する方法はこれだけです。
   • Docker、ローカルのクローン、管理が必要な環境変数は不要です。
   • VS Code は Microsoft Entra（Equinor アカウント）を使って MCP 接続を認証します。
   • 呼び出し元は、リクエストごとに X-GitHub-Token ヘッダーで自身の GitHub トークンも渡します（各ユーザーが自身の ID とレート制限を維持します。共有トークンやサービス用トークンは推奨しないでください）。
   • references/vscode-mcp-config.md の手動設定を使用してください。このサーバーにはワンクリックのインストールリンクは公開されていません。
   • ローカルの stdio や Docker の開発環境一式は推奨しないでください。これらは fusion-pm-mcp サービス自体の開発に取り組むコントリビューター向けです。セットアップ手順をここに記載する代わりに、そのリポジトリの CONTRIBUTING.md を案内してください。
3. 認証フローを説明します。
   • 初回のツール呼び出し時に、VS Code から Equinor の Entra アカウントでサインインするよう求められます（この認証は MCP サーバー自体へのアクセスを制御します）。
   • これとは別に、X-GitHub-Token ヘッダーで呼び出し元自身の GitHub PAT をすべてのリクエストに付けて API に渡します。
   • 両方が有効である必要があります。どちらの認証レイヤーでも 401 が発生する可能性があります。
4. 検証チェックリストを提示します。
   • initialize を実行し、正常なレスポンスが返ることを確認します。
   • tools/list を実行し、実際に返されたツール名と照合します。ツール一覧は以前変更されたことがあるため、固定の一覧だと決めつけないでください。
   • 破壊的でない tools/call を 1 つ（例：api_list_milestones または api_get_issue）実行し、空でない結果が返ることを確認します。
5. ドキュメントに記載された順序でトラブルシューティングを行います。
   • 認証されていない／すぐにレート制限に達する → X-GitHub-Token ヘッダーが設定されていません。未認証の呼び出しは 1 時間あたり 60 リクエストに制限されます。
   • 401 またはサインインのプロンプトが繰り返し表示される → VS Code で再認証してください（サインアウトしてからサインインするか、MCP サーバーを再読み込みします）。解決しない場合は、既知の一時的な問題ではなく、セットアップの不具合として扱ってください。
   • 結果が古いように見える → キャッシュを無効化するツールはありません。結果はキャッシュ TTL（数分）の経過後に自動的に解消されます。
6. セットアップに失敗した場合、またはユーザーがバグ報告を依頼した場合は、assets/bug-report-template.md を使ってバグ報告の下書きを作成します。
   • デフォルトの対象リポジトリ：equinor/fusion-pm-mcp
   • 具体的な再現手順、期待される動作と実際の動作、すでに試したトラブルシューティングを含めます。
   • 機密情報を含まない環境情報のみ（OS、VS Code のバージョン）を記載します。
   • GitHub トークン、PAT、Entra の認証情報は絶対に記載しないでください。
7. 不確かな点やリポジトリ固有の制約がある場合は、前提を明示し、推測せずに信頼できるドキュメントへのリンクを提示します。

期待される出力

以下を返します。

• Fusion PM MCP の簡潔な説明と、利用する場面
• ユーザーの環境に合わせたホスト型サーバーのセットアップ手順
• 検証チェックリスト：initialize、tools/list（実際に返されたツール名と照合）、tools/call を 1 つ（空でない結果を確認）
• 観測された症状に対応するトラブルシューティング手順
• セットアップに失敗した場合、問題が発生した場合、またはユーザーから依頼された場合のバグ報告の下書き。assets/bug-report-template.md を使い、デフォルトの対象リポジトリは equinor/fusion-pm-mcp とします。
• 前提と不足している情報の明示

参考資料

• references/vscode-mcp-config.md
• assets/bug-report-template.md

安全性と制約

禁止事項：

• GitHub トークン、PAT、Entra 認証情報を要求または公開すること
• プロジェクトのドキュメントでサポートされていないセットアップコマンドを作成すること
• 検証結果を示さずに、セットアップが成功したと主張すること
• ホスト型のマルチユーザー環境で、共有の GitHub トークンを1つだけ使用するよう提案すること
• ユーザーの明示的な確認なしに、破壊的なコマンドを実行すること

必ず行うこと：

• 公式リポジトリのドキュメントを信頼できる情報源として優先すること
• ホスト型の本番サーバーを利用するよう案内すること。サービス自体に貢献する場合を除き、ローカルの stdio や Docker のセットアップを提案しないこと。サービス自体に貢献する場合は、セットアップ手順を記載する代わりに、そのリポジトリの CONTRIBUTING.md へのリンクを案内すること
• 共有トークンよりも、リクエストごとの X-GitHub-Token 認証を推奨すること
• 確認済みの事実と推測を区別すること