mcp-management

Codex 互換性に関する注意：

• Codex でリポジトリのスキルを呼び出すときは $skill-name を使用します。このミラーコピーでは、従来の Claude の /skill-name 参照を書き換えています。
• タスクトラッカーの必須事項：ワークフローまたはスキルの手順を実行する前に、すべての手順のタスク追跡を作成または更新し、進捗に応じて同期してください。
• ユーザーへの質問を促す指示がある場合は、Codex でユーザーに直接質問してください。
• Claude 固有のモード切り替え指示がある場合は無視してください。
• 厳格な実行契約：ユーザーがスキルを明示的に呼び出した場合、そのスキルのプロトコルを記載どおりに実行してください。
• サブエージェントの使用許可：スキルがユーザーによって呼び出された場合、または AI によって検出され、そのプロトコルでサブエージェントが必要とされる場合、そのスキルの有効化により、そのタスクで必要な spawn_agent サブエージェントを使用することが許可されます。
• ユーザーが事前に逸脱を明示的に承認しない限り、プロトコルの手順を省略、並べ替え、統合しないでください。
• ワークフロースキルでは、列挙された子スキルの各手順を明示的に実行し、手順ごとの証拠を報告してください。
• 必須の手順またはツールをこの環境で実行できない場合は、適応する前に中止してユーザーに確認してください。

Codex のプロジェクト参照資料の読み込み（フックなし）

Codex では、Claude のフックによるドキュメントの自動挿入は行われません。 コーディング、計画、デバッグ、テスト、レビューの際は、以下の参照先に従ってプロジェクトのドキュメントを明示的に開いてください。

必ず読むこと：

• docs/project-config.json（プロジェクト固有のパス、コマンド、モジュール、ワークフローとテストの設定）
• docs/project-reference/docs-index-reference.md（docs/project-reference/* の全カタログへの参照先）
• docs/project-reference/lessons.md（常に適用されるガードレールとアンチパターン）

状況に応じたドキュメント：

• バックエンド／CQRS／API／ドメイン／エンティティの変更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
• フロントエンド／UI／スタイリング／デザインシステム：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 仕様／テストケースの計画または TC のマッピング：feature-docs-reference.md
• 統合テストの実装／レビュー：integration-test-reference.md
• E2E テストの実装／レビュー：e2e-test-reference.md
• コードレビュー／監査作業：code-review-rules.md と、変更ファイルに応じた上記のドメインドキュメント

ドキュメントをむやみにすべて読まないでください。まず docs-index-reference.md を確認し、タスクに関連するファイルだけを開いてください。

クイックサマリー

目標： 設定済みサーバーの MCP ツール／プロンプト／リソースを、メインコンテキストを汚染せずに検出、分析、実行します。

ワークフロー：

1. 設定管理 — .claude/.mcp.json を使用し、Gemini CLI 用に .gemini/settings.json へシンボリックリンクを作成します
2. 機能の検出 — npx tsx scripts/cli.ts list-tools で assets/tools.json に保存します
3. 適切な選択 — LLM が tools.json を分析し、タスクに関連する機能を選択します
4. 実行 — 優先：Gemini CLI で標準入力からパイプ。次点：直接スクリプトを実行。フォールバック：汎用サブエージェント

主なルール：

• Gemini CLI を優先：標準入力からパイプします（echo "task" | gemini）。-p フラグは使用しないでください（MCP の初期化がスキップされます）
• GEMINI.md の自動読み込み：プロジェクトルートのファイルにより、Gemini から構造化された JSON 形式で回答が返されます
• 段階的な情報開示：必要な機能だけを読み込み、検出はサブエージェントが担当します
• 永続カタログ：list-tools は完全なスキーマを assets/tools.json に保存するため、すばやく参照できます

懐疑的になり、批判的思考と逐次的思考を適用してください。すべての主張には、追跡可能な証拠と確信度（パーセンテージ）が必要です（Idea は 80％を超える必要があります）。

MCP 管理

Model Context Protocol（MCP）サーバーを管理し、操作するためのスキルです。

前提条件

実行前に references/configuration.md と references/gemini-cli-integration.md を**⚠️ 必ず注意して読むこと**。以下の「コア機能」および「実装パターン」セクションで必要となる、MCP サーバーの設定形式、Gemini CLI の設定、実行パターン、トラブルシューティングが記載されています。プロトコルの内部仕様については、references/mcp-protocol.md も**⚠️ 必ず注意して読むこと**。

概要

MCP は、AI エージェントが外部のツールやデータソースに接続するためのオープンプロトコルです。このスキルでは、メインのコンテキストウィンドウを汚染せずに、設定済みサーバーの MCP 機能を検出、分析、実行するためのスクリプトとユーティリティを提供します。

主なメリット：

• MCP 機能を段階的に開示します（必要なものだけを読み込みます）
• タスク要件に基づいてツール／プロンプト／リソースをインテリジェントに選択します
• 1 つの設定ファイルから複数のサーバーを管理します
• コンテキスト効率に優れています。サブエージェントが MCP の検出と実行を担います
• ツールカタログを永続化します。検出したツールを JSON に自動保存し、すばやく参照できます

このスキルを使用する場面

次のような場合にこのスキルを使用します。

1. MCP 機能の検出：設定済みサーバーで利用可能なツール／プロンプト／リソースを一覧表示する必要がある場合
2. タスクに基づくツール選択：特定のタスクに関連する MCP ツールを分析する場合
3. MCP ツールの実行：適切にパラメーターを処理しながら、MCP ツールをプログラムから呼び出す場合
4. MCP の統合：MCP クライアントの実装を構築またはデバッグする場合
5. コンテキスト管理：MCP 操作をサブエージェントに委任して、コンテキストの汚染を防ぐ場合

主な機能

1. 設定管理

MCP サーバーは .claude/.mcp.json で設定します。

Gemini CLI との統合（推奨）：.gemini/settings.json へのシンボリックリンクを作成します。

mkdir -p .gemini && ln -sf .claude/.mcp.json .gemini/settings.json

references/configuration.md と references/gemini-cli-integration.md を参照してください。

GEMINI.md の応答形式：プロジェクトルートに GEMINI.md を置くと、Gemini CLI が自動的に読み込み、構造化された JSON 応答を強制できます。

{"server":"name","tool":"name","success":true,"result":<data>,"error":null}

これにより、予測できない自然言語ではなく、解析可能で一貫性のある出力が得られます。このファイルでは次の内容を定義します。

• JSON のみで応答する必須形式（Markdown と説明は禁止）
• 応答の最大文字数（500 文字）
• エラー処理の構造
• 利用可能な MCP サーバーの参照情報

メリット：プログラムで解析可能な出力、一貫性のあるエラー報告、DRY な設定（形式を一度だけ定義）、コンテキスト効率の向上（Gemini CLI が自動読み込み）。

2. 機能の検出

npx tsx scripts/cli.ts list-tools  # Saves to assets/tools.json
npx tsx scripts/cli.ts list-prompts
npx tsx scripts/cli.ts list-resources

サーバーを識別したうえで、複数のサーバーの機能を集約します。

3. インテリジェントなツール分析

LLM が assets/tools.json を直接分析します。キーワードマッチングアルゴリズムよりも優れています。

4. ツールの実行

主な方法：Gemini CLI（利用可能な場合）

# IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
echo "Take a screenshot of https://example.com" | gemini -y -m gemini-2.5-flash

次の方法：直接スクリプト

npx tsx scripts/cli.ts call-tool memory create_entities '{"entities":[...]}'

フォールバック：汎用サブエージェント

完全な例については、references/gemini-cli-integration.md を参照してください。

実装パターン

パターン 1：Gemini CLI による自動実行（主な方法）

Gemini CLI を使用して、ツールの検出と実行を自動化します。Gemini CLI はプロジェクトルートから GEMINI.md を自動的に読み込み、構造化された JSON 応答を強制します。

簡単な例：

# IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
# Add "Return JSON only per GEMINI.md instructions" to enforce structured output
echo "Take a screenshot of https://example.com. Return JSON only per GEMINI.md instructions." | gemini -y -m gemini-2.5-flash

期待される出力：

{ "server": "puppeteer", "tool": "screenshot", "success": true, "result": "screenshot.png", "error": null }

メリット：

• ツールを自動的に検出します
• 構造化された JSON 応答（Claude で解析可能）
• GEMINI.md が自動読み込みされ、形式の一貫性を保てます
• サブエージェントのオーケストレーションよりも高速です
• 自然言語による曖昧さがありません

詳しいガイドについては、references/gemini-cli-integration.md を参照してください。

パターン 2：サブエージェントによる実行（フォールバック）

Gemini CLI が利用できない場合は、general-purpose エージェントを使用します。サブエージェントがツールを検出し、関連するものを選択してタスクを実行し、結果を報告します。

メリット：メインコンテキストをクリーンな状態に保ち、必要な場合にのみ関連するツール定義を読み込みます。

パターン 3：LLM 主導のツール選択

LLM が assets/tools.json を読み込み、コンテキストの理解、類義語、意図の認識を活用して、関連するツールをインテリジェントに選択します。

パターン 4：複数サーバーのオーケストレーション

複数のサーバーにまたがるツールを連携させます。各ツールは適切にルーティングできるよう、接続元のサーバーを認識します。

スクリプトリファレンス

scripts/mcp-client.ts

MCP クライアントの中核となる管理クラスです。以下を処理します。

• .claude/.mcp.json からの設定の読み込み
• 複数の MCP サーバーへの接続
• すべてのサーバーにわたるツール／プロンプト／リソースの一覧表示
• 適切なエラー処理を伴うツールの実行
• 接続ライフサイクルの管理

scripts/cli.ts

MCP 操作のためのコマンドラインインターフェースです。コマンド：

• list-tools - すべてのツールを表示し、assets/tools.json に保存します
• list-prompts - すべてのプロンプトを表示します
• list-resources - すべてのリソースを表示します
• call-tool <server> <tool> <json> - ツールを実行します

注：list-tools は、素早く参照したり、オフラインで閲覧したり、バージョン管理したりできるよう、完全なスキーマを含むツールカタログを assets/tools.json に保存します。

クイックスタート

方法 1：Gemini CLI（推奨）

npm install -g gemini-cli
mkdir -p .gemini && ln -sf .claude/.mcp.json .gemini/settings.json
# IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
# GEMINI.md auto-loads to enforce JSON responses
echo "Take a screenshot of https://example.com. Return JSON only per GEMINI.md instructions." | gemini -y -m gemini-2.5-flash

構造化された JSON を返します：{"server":"puppeteer","tool":"screenshot","success":true,"result":"screenshot.png","error":null}

方法 2：スクリプト

cd .claude/skills/mcp-management/scripts && npm install
npx tsx cli.ts list-tools  # Saves to assets/tools.json
npx tsx cli.ts call-tool memory create_entities '{"entities":[...]}'

方法 3：汎用サブエージェント

完全なガイドについては、references/gemini-cli-integration.md を参照してください。

技術的な詳細

以下については、references/mcp-protocol.md を参照してください。

• JSON-RPC プロトコルの詳細
• メッセージの種類と形式
• エラーコードと処理
• トランスポート方式（stdio、HTTP+SSE）
• ベストプラクティス

統合戦略

実行の優先順位

1. Gemini CLI（優先）：高速、自動、インテリジェントなツール選択

   • 確認：command -v gemini
   • 実行：echo "<task>" | gemini -y -m gemini-2.5-flash
   • 重要：-p フラグ（非推奨で、MCP の初期化をスキップします）ではなく、stdin にパイプしてください
   • 最適な用途：利用可能な場合、すべてのタスク

2. 直接 CLI スクリプト（次点）：ツールを手動で指定

   • 使用する場合：特定のツール／サーバーを制御する必要があるとき
   • 実行：npx tsx scripts/cli.ts call-tool <server> <tool> <args>

3. 汎用サブエージェント（フォールバック）：コンテキスト効率のよい委任

   • 使用する場合：Gemini が利用できない、または失敗したとき
   • メインコンテキストをすっきり保ちます

エージェントとの統合

general-purpose エージェントは、このスキルを使用して以下を行います。

• 最初に Gemini CLI が利用可能か確認する
• 利用可能な場合は gemini コマンドで実行する
• 失敗した場合は直接スクリプトの実行に切り替える
• MCP の機能をメインコンテキストに読み込まずに確認する
• 結果をメインエージェントに報告する

これにより、メインエージェントのコンテキストをすっきり保ちながら、効率的な MCP 統合を実現できます。

関連

• mcp-builder
• claude-code

---

[IMPORTANT] 作業を始める前に、タスク管理を使ってすべての作業を小さなタスクに分割してください。各ファイルを読むタスクも含めてください。長いファイルによるコンテキストの喪失を防げます。簡単なタスクの場合は、AI は必ずユーザーにスキップするかどうかを尋ねてください。

AI のミス防止 — あらゆるタスクで避けるべき失敗パターン： 削除前に、後続の参照先を確認してください。 コンポーネントを削除すると、ドキュメントやコードに古い情報が残る連鎖が発生します。削除する前に、参照しているファイルをすべて洗い出してください。 AI が生成した内容を実際のコードと照合してください。 AI は API、クラス名、メソッドシグネチャを幻覚することがあります。ドキュメントに記載したり参照したりする前に、必ず grep で実在を確認してください。 編集後は依存関係を最後までたどってください。 定義を変更しても、そこから派生する下流の変数や利用箇所が見落とされることがあります。必ず依存関係の全体をたどってください。 正しさを検証するときは、コードパスをすべてたどってください。 コードが存在することの確認は、実行されることの確認ではありません。正常系だけでなく、早期リターン、エラー分岐、条件付きのスキップも必ずたどってください。 デバッグ時は、修正前に「どちらの責任か」を確認してください。 バグが呼び出し元（誤ったデータ）にあるのか、呼び出し先（誤った処理）にあるのかをたどってください。責任のあるレイヤーで修正し、症状が現れる箇所だけを修正しないでください。 既存の値には意図があると考え、変更前に理由を確認してください。 定数、上限、フラグ、パターンを変更する前に、コメントを読み、git blame を確認し、周辺のコードを調べてください。 最初の出力だけでなく、影響を受ける出力をすべて検証してください。 複数のスタックに影響する変更では、すべての出力を検証する必要があります。チェックが 1 つ成功しても、すべてのチェックが成功したことにはなりません。 デバッグは全体像から始め、最も目につく箇所に飛びつかないでください。 失敗を調査するときは、まず前提条件（設定、環境変数、DB 名、エンドポイント、DI 登録、データの前提条件）をすべて列挙し、コードレイヤーの仮説を立てる前に、それぞれを根拠と照合してください。 変更は最小限にし、差分テストを適用してください。 バグ修正では、変更するすべての行がそのバグに直接関係している必要があります。隣接するコードのスタイル変更や改善はしないでください。機能強化のタスクでは、改善を実装し、その内容を明示してください。 実装前に曖昧さを明らかにし、黙って解釈を決めないでください。 依頼に複数の解釈がある場合は、それぞれの作業量の見積もりを示して質問してください。すべてのレコードを対象とする方法、ファイルベースの方法、より複雑な方法を、決して前提にしないでください。

批判的思考の姿勢 — 批判的思考と順序立てた思考を適用してください。すべての主張には追跡可能な証拠が必要です。確信度が 80% を超える場合にのみ行動してください。 幻覚の防止： 推測を事実として述べないでください。あらゆる主張の根拠を示し、不確かな場合は率直に認め、出力に誤りがないか自分で確認し、独立して相互参照し、自分の確信を疑ってください。証拠のない確信が、あらゆる幻覚の根本原因です。

必ず注意 批判的思考を適用してください。すべての主張には追跡可能な証拠が必要です。確信度が 80% を超える場合にのみ行動してください。幻覚の防止：推測を事実として述べないでください。

必ず注意 AI のミス防止策を適用してください。全体像からデバッグし、責任のあるレイヤーで修正し、実装前に曖昧さを明らかにし、コンパクション後にファイルを読み直してください。

最後に確認すること

重要・必ず注意 作業を始める前に、タスク管理を使って作業を小さな ToDo タスクに分割してください 重要・必ず注意 新しいコードを作成する前に、コードベースで類似パターンを 3 つ以上検索してください 重要・必ず注意 あらゆる主張について、file:line 形式の根拠を示してください（確信度が 80% を超える場合にのみ行動） 重要・必ず注意 作業の品質を検証するため、最後にレビューの ToDo タスクを追加してください 必須・重要・必ず注意 作業を始める前に、次のファイルを読んでください： 重要・必ず注意 作業を始める前に references/configuration.md を読んでください 重要・必ず注意 作業を始める前に references/mcp-protocol.md を読んでください

[TASK-PLANNING] 行動する前に、タスクの範囲を分析し、タスク管理を使って体系的に小さな ToDo タスクとサブタスクに分割してください。

フックレス・プロンプト・プロトコルのミラー（自動同期）

ソース：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] ワークフロー実行プロトコル — 必須・重要・厳守。いかなる理由があっても省略しないでください。

汎用的な移植性の境界： 再利用可能なスキルとプロトコルのテキストはプロジェクトに依存しないものとします。プロジェクト固有の規約は、docs/project-config.json と docs/project-reference/ から確認してください。shared/sdd-artifact-contract.md の共通 AI-SDD を適用します。docs/project-config.json と docs/project-reference/docs-index-reference.md を読み、そこに記載されているプロジェクト参照ドキュメントを開いてください。この共通コンテキストとローカルドキュメントを利用できる場合は、サポートされている任意の AI ツールで実行できます。

1. 検出： プロンプトをワークフローカタログと照合します
2. 分析： 最適なワークフローを見つけ、カスタムのステップ構成のほうが適しているかどうかも評価します
3. 確認（必須形式）： ユーザーが明示的にワークフロー／スキルを呼び出し、かつローカルプロトコルで明示的な呼び出しを確認とみなす場合を除き、次の構成でユーザーに直接質問します
   • 質問："どのワークフローを有効にしますか？"
   • 選択肢 1："[最適なワークフロー] を有効にする（推奨）"
   • 選択肢 2："カスタムワークフローを有効にする：[step1 → step2 → ...]"（1 行で理由を記載）
4. 有効化（確認後）： 標準ワークフローの場合は $workflow-start <workflowId> を呼び出し、カスタムステップの場合は手動で順に実行します
5. タスクを作成： ワークフローのすべてのステップについてタスク追跡を行います
6. 実行： 各ステップを順番に実行します [CRITICAL-THINKING-MINDSET] 批判的思考と段階的思考を適用します。すべての主張には追跡可能な根拠が必要であり、確信度が 80% を超える場合にのみ行動します。 ハルシネーション防止の原則： 推測を事実として提示しないでください。すべての主張に出典を示し、不確実な点は率直に認め、出力に誤りがないか自己確認し、独立した情報源と照合し、自分の確信を疑ってください。根拠のない確信こそが、あらゆるハルシネーションの根本原因です。 AI の注意力に関する原則（初頭効果・新近効果）： 長いプロンプト／プロトコルでは、指示の順守が長いコンテキストウィンドウでも保たれるよう、最も重要な 3 つのルールを冒頭と末尾の両方に配置します。 目標主導の実行： まず成功基準を定義し、検証が完了するまで繰り返し、観察可能なチェックに合格した場合にのみ終了します。 テストで意図を検証： テストでは、現在の挙動をなぞるだけでなく、ビジネスルール／不変条件を保護し、保護対象の意図が損なわれた場合に失敗するようにします。

[LESSON-LEARNED-REMINDER] [BLOCKING] タスク計画と継続的改善 — 必須。省略しないでください。

作業を始める前に、作業を小さなタスクに分割し、タスク追跡を行います。最後のタスクとして「AI のミスと教訓を分析する」を追加します。

教訓の抽出 — 症状への対処ではなく、根本原因のみ：

1. 症状ではなく、失敗モード（推論／前提の誤り）を特定します。「誤った列挙値を使った」ではなく、「ソースを読まずに API が存在すると仮定した」とします。
2. 一般性を検証します。この失敗モードは 3 つ以上のコンテキスト／コードベースに当てはまりますか？ 当てはまらない場合は、抽象度を 1 段階上げます。
3. 普遍的なルールとして記述します。プロジェクト固有の名前／パス／クラスを除き、どのコードベースでも役立つ内容にします。
4. 統合します。同じ失敗モードを共有する複数のミスは、1 つの教訓にまとめます。
5. 再発判定：「この注意書きがなければ、今後のセッションで再発するか？」いいえの場合は $learn を省略します。
6. 自動修正判定：「$code-review／$code-simplifier／$security／$lint で検出できるか？」はいの場合は、代わりにレビュー用スキルを改善します。
7. 両方の判定を通過した場合： $learn を実行するようユーザーに依頼します。 [TASK-PLANNING] [MANDATORY] ワークフローまたはスキルのステップを実行する前に、予定されているすべてのステップのタスク追跡を作成／更新し、各ステップの開始時と完了時に内容を同期してください。