Mcp Probe Kit

mcp-probe-kit — コンテキストを把握し、今この瞬間に活かす

---

口で言うのは簡単です。コンテキストで示してください。

mcp-probe-kit は、AI にプロジェクトの意図を理解させ、適切なワークフローを選択させ、内部処理でモデルを圧倒することなく検証済みの経験を保持したい開発者向けに設計された、プロトコルレベルのツールキットです。

言語: English | 简体中文 | 日本語 | 한국어 | Español | Français | Deutsch | Português (BR)

🚀 AI 搭載の包括的な開発ツールキット — 開発ライフサイクル全体を網羅

強力な MCP（Model Context Protocol）サーバーです。デフォルトではモデルから見えるツールが29 個（基本 24 個＋履歴セッション 5 個）あり、MCP_HISTORY_SESSION=0 で履歴を無効化できます。Memory も設定すると35 個になり、MCP_TOOLSET=full では39 個のツールに対応する互換性インターフェースを利用できます。製品分析から最終リリースまでのワークフロー全体を網羅し、構造化出力をサポートします。

🎉 v4 安定版リリース: ネイティブ MCP Apps、中断後に再開できるプラン、エビデンスの収束、管理対象の GitNexus Sidecar、親子仕様、バージョン固定の CLI フォールバックを追加しました。

すべての MCP クライアントに対応: Cursor、Claude Desktop、Cline、Continue など

プロトコルサポート: 従来型 MCP（2025 年代）＋最新 MCP 2026-07-28 · SDK: 分割された TypeScript SDK v2 パッケージ

ランタイム: Node.js 20 以降。デフォルトは MCP_PROTOCOL_MODE=auto です。互換性の診断時のみ legacy または modern を使用してください。

---

🎬 v4 の動作

v4 は、委任されたエージェントの作業を、可視化・検証可能なデリバリーループに変えます。以下のアニメーションは、npm パッケージに同梱されているものと同じ MCP App のソースからレンダリングされたものであり、別途作成されたマーケティング用のモックアップではありません。

Feature Workbench — 親子仕様、アクティブなステップ、出力、エビデンス、セッションをまたいだ復旧を確認できます。

Memory Center — セマンティック検索、コンテンツ全体の確認、ライフサイクル状態、エビデンス、古い項目のマーク、削除の確認に対応します。

Convergence Gate — ステップ、または要件／仕様／実装／テスト／レビューのエビデンスが不完全な場合、完了をブロックします。

• ネイティブ MCP Apps 5 種：Memory Center、Feature Workbench、Bug Workbench、Product Workbench、Convergence Gate。
• History Session（デフォルトで ON）：docs/history-session/ にロスレスでローカルチャットを引き継ぎます — bootstrap → checkpoint → search/read。ベクトル DB は不要です。
• 再開可能な委任プラン：plan_heartbeat が実際の進捗を永続化し、resume_plan が次に実行可能なステップを復元します。
• エビデンスベースの収束：converge がデリバリーと長期 Memory 書き込みを制御します。
• 管理された GitNexus Sidecar：バージョン／プラットフォーム／アーキテクチャ／Node の分離、整合性検証、実際の FTS プローブ、安全な機能縮退に対応します。
• バージョン固定の CLI フォールバック：ホストが MCP ツールのリースを失効させた場合でも、プロジェクトローカルの probe ラッパーを通じて同じ Tool Registry にアクセスできます。
• 親子仕様：複雑なリリースを、巨大な 1 つの仕様にまとめるのではなく、分解して再帰的に検証します。

ライブの読み取り専用 MCP App デモ 5 種を見る

v4 安定版： [email protected] は現在の安定版リリースであり、npm の latest チャンネルです。

---

📚 ドキュメント一覧

👉 https://mcp-probe-kit.bytezonex.com

• クイックスタート - 5 分でセットアップ
• ローカル Memory スタック（Qdrant + Nomic Embed） - Docker Compose、ポート 50008 ／ 50012、MCP env
• 全ツール - デフォルト（＋ History）、条件付き Memory、App 専用、完全な互換性サーフェス
• ベストプラクティス - 開発ワークフローの完全ガイド
• v3 → v4 移行ガイド - ツールのサーフェス、プロトコル、Apps、プラン状態、Memory、互換性
• MCP Apps ライブデモ - 同梱の App ソースから生成された、実際の読み取り専用ワークベンチ 5 種

---

✨ 主な機能

📦 ツールの提供範囲

デフォルトの compact サーフェスでは、個別に役立つワークフローをすべて維持しながら、モデルコンテキストと競合する内部用およびメンテナンス用の項目を除外します。

• 🧭 ルーティング (1) — workflow
• 🔁 計画の状態と収束 (3) — plan_heartbeat, resume_plan, converge
• 🔄 ワークフローのオーケストレーション (6) — start_feature, start_bugfix, start_onboard, start_ui, start_product, start_ralph
• 📦 プロジェクトと仕様 (4) — init_project, init_project_context, check_spec, estimate
• 🏗️ アーキテクチャ (1) — architecture
• 🔍 コード、テスト、Git (6) — code_insight, gentest, code_review, refactor, gencommit, git_work_report
• 🎨 UI/UX ユーティリティ (2) — ui_design_system, ui_search
• 🗣️ 構造化インタビュー (1) — interview

これで 24 個の基本的な compact ツールに加え、デフォルトで 5 個の History Session ツール（history_session_bootstrap|checkpoint|validate|search|read）が加わり、モデルに公開されるツールは合計 29 個になります。History を非表示にするには、MCP_HISTORY_SESSION=0|false|off を設定します。Memory スタック全体が設定されている場合は、Memory ツールが動的に 6 個追加され、モデルに公開されるツールは合計 35 個になります（History がオフの場合は 30 個）。

search_memory, read_memory_asset, memorize_asset, update_memory_asset, delete_memory_asset, scan_and_extract_patterns

互換性と診断のために、MCP_TOOLSET=full を設定すると、39 個すべてのモデルツールが復元されます。compact サーフェスでは、add_feature、fix_bug、sync_ui_data、ask_user を意図的に除外しています。これらの実装は、オーケストレーション、メンテナンススクリプト、または完全互換モードから引き続き利用できます。

workflow はフォールバック用のツール選択ガイドであり、自然言語の意図分類器ではありません。通常、Agent は現在の会話、Skill、ツールの説明に基づいて適切な MCP ツールを直接選択します。scenario=auto はガイダンスのみを返し（firstTool=null）、明示的な scenario は Agent がすでに選択したシナリオに対して決定論的なガイダンスを返します。

📜 History Session（デフォルトで有効）— 損失のないプロジェクト引き継ぎ

チャットホストは会話を忘れてしまいます。History Session はプロジェクト内に損失なく保存するアーカイブを維持するため、次のエージェントのターン（または新しい会話）で、チャット全体をプロンプトに詰め込むことなく、実際のユーザーの表現、決定事項、未完了の項目を引き継いで再開できます。

重要な理由

• ホストのコンテキストウィンドウや「新しいチャット」によるリセットでは、以前の調査結果が失われます。History はそれらを docs/history-session/ 内に Markdown として保持します。
• デフォルトで有効で、Qdrant／埋め込みスタックは不要です。24 個の基本コンパクトツールと併せて、すぐに利用できます（モデルから見えるツールは合計 29 個）。
• 他のレイヤーを補完しますが、置き換えるものではありません。

レイヤー	役割	代表的なツール
History Session	このプロジェクトの会話の引き継ぎ、ユーザー入力の逐語記録、ターンごとのチェックポイント	history_session_*
Delegated Plan	再開可能な手順、根拠、収束ゲート	plan_heartbeat / resume_plan / converge
Memory	リポジトリをまたいで再利用できる経験（MEMORY_* が必要）	search_memory / memorize_asset

エージェントでの使用方法

1. 会話の開始時 — initial_user_input=<user’s first message> を指定して history_session_bootstrap を呼び出します。プラットフォームセッションのないホストでは、session_key を一度だけ省略します。サーバーが hs_<uuid> を生成し、新しいアーカイブを開きます（project-active は共有しません）。後続の呼び出しでは、そのハンドルを使用します。キーを独自に作成しないでください。
2. 最終回答の前 — bootstrap 時の session_key と expected_path に加え、このターンの raw_user_input／user_intent を指定して history_session_checkpoint を呼び出します。Skill の最低限のチェックリスト（findings、decisions、files_changed、tests、runtime_state、next_actions）を記入します。空の配列で埋めないでください。
3. 過去の事実が必要なとき — history_session_search → history_session_read（next_cursor に従います）。まず範囲を限定した bootstrap の state を優先し、デフォルトでは履歴全体を読み込まないでください。
4. 番号付け／インデックスの破損 — history_session_validate を使用します（必要に応じて repair=true）。

運用上の詳細

• アーカイブが MCP_HISTORY_MAX_LINES／MCP_HISTORY_MAX_BYTES（デフォルトはそれぞれ 800／131072）を超えた場合、ソフトローテーションします。checkpoint は新しい expected_path を返します。ローテーション後のアーカイブには、最新の initial_user_input が引き継がれます。
• アーカイブされたテキスト内の一般的なシークレットを秘匿し、checkpoint はコンテンツのフィンガープリントによって冪等になります。
• MCP_HISTORY_SESSION=0|false|off で無効にできます（5 つのツールが非表示になります）。
• docs/history-session/ はコミットしないでください。.gitignore に追加してください（ローカルでの引き継ぎ専用で、npm パッケージには含まれません）。

Skill と AGENTS.md には読み書きのタイミングに関するルールが記載されています。All Tools カタログには、各 history_session_* ツールを呼び出すための一行プロンプトが掲載されています。

🔁 委任プランの状態、復旧、収束

• すべての v4 委任プランでは executionStatePolicy が宣言され、エージェントに最初のステップでローカルチェックポイントを作成するよう指示します。
• plan_heartbeat は、完了／スキップしたステップ、未解決の項目、根拠、最後に検証されたリビジョンを .mcp-probe-kit/plans/ に保存します。
• 中断、再起動、エージェントの引き継ぎ後、resume_plan は保存された依存関係から、実行可能なステップとブロックされているステップを再計算します。
• converge は、ステップ、未解決の項目、または要件／仕様／実装／テスト／レビューの根拠が不完全な場合、完了を拒否します。正式な長期メモリへの書き込みは、収束の確認に合格した後にのみ許可されます。
• これらのツールはエージェントの実行を追跡して検証します。ファイル、シェル、Git、実装に関する作業を MCP サーバーに移すものではありません。

🛡️ 品質制約（信頼できる唯一の情報源）

すべての厳格な品質ルールは、1つのモジュール（src/lib/quality-constraints.ts）で管理され、code_review、add_feature タスクテンプレート、UI ツールに適用されます。一度変更すれば、すべてに反映されます。taste-skill と impeccable に着想を得ています。

• コードの上限：単一ファイルは500行以下（超える場合はモジュール／コンポーネントに分割）、関数は50行以下、ネストは4階層以下、パラメーターは3つ以下です。
• 不完全な出力のブラックリスト：code_review は、プレースホルダー／省略パターン（// ...、// TODO、// rest of code、単独の ...）を重大な問題として検出します。「不完全な出力は、壊れた出力です」。
• 手抜きを防ぐタスクテンプレート：add_feature タスクには、Scope-lockによる成果物数、コードを書く前に読むことを必須とするエビデンスブロック、ファイルごとの行数上限、プレースホルダーを一切許容しない二者択一のルールが追加されています。check_spec はこれらを検証します（Scope-lockがない場合はエラー、エビデンスのない不十分なタスクは警告）。
• UIの厳格な基準：数値で定義され、機械で検証可能なルールです。4pt間隔スケール、WCAGコントラスト（4.5/3/3）、1.25以上の文字サイズスケール、ヒーローのフォントサイズは6rem以下、OKLCH、8種類のインタラクション状態、認知負荷は4以下、モーションは150～300msです。
• UIの禁止リストとPre-Flightチェックリスト：AIらしい粗雑なデザインに対する照合・拒否型のブラックリスト（デフォルトのInter／Roboto、AI風の紫青グラデーション、グラデーション文字、画一的なカードグリッド、emダッシュ、クリーム色／ベージュの本文背景、入れ子のカード）に加え、納品前のセルフチェックマトリックスを備えています。

🧠 コードグラフブリッジ（GitNexus）

• code_insight は、クエリ／コンテキスト／影響分析にGitNexusをデフォルトで利用します。
• ブリッジは、明示的に設定されたGitNexus CLIまたはシステムのGitNexus CLIを優先し、次にバージョンが固定されたマネージドSidecarを使用します。GitNexusはメインパッケージにバンドルされず、グローバルにもインストールされません。
• init_project_context は、docs/graph-insights/ にベースラインのグラフドキュメントを生成します。すでに docs/project-context.md が存在する場合は、既存のコンテキストドキュメントを保持し、グラフドキュメントとインデックス項目のみを補完します。
• start_feature はGitNexusインデックスを更新し、仕様の生成前にタスク単位で query/context/impact の絞り込みを実行して、スコープが広がりすぎないようにします。
• start_bugfix はGitNexusインデックスを更新し、TBP RCAの前にタスク単位のグラフ分析を実行して、障害の境界と影響範囲を絞り込みます。
• project-context.md はあるもののグラフドキュメントがない既存プロジェクトは、init_project_context のステップを通じて自動的に初期化されます。
• GitNexusが利用できない場合、オーケストレーションを中断することなく、サーバーが自動的にフォールバックします。
• 実際のグラフクエリは .gitnexus インデックスを読み込みます。docs/graph-insights/latest.md|json は、人間とAI エージェントが参照できるスナップショットです。
• MCP クライアントの設定に表示されるMCPリソースは2件です（probe://status、probe://project/bootstrap）。グラフランタイムのスナップショット（probe://graph/latest など）と probe://project/skill|agents|context|graph は、ツールがURIを公開している場合、resources/read から引き続き読み込めます。
• グラフのスナップショットは .mcp-probe-kit/graph-snapshots に保存されます（MCP_GRAPH_SNAPSHOT_DIR で変更可能）。
• ツールのレスポンスには、スナップショットURIとローカルのJSON／Markdownファイルパスを含む _meta.graph が含まれます。

🐛 SRC-8 バグ根本原因ワークフロー（TBP に着想）

• SRC-8 Methodology（中文: src8-methodology.zh-CN.md）— トヨタ TBP／PDCA に着想を得て、コードと AI エージェント向けに調整した、ソフトウェアの根本原因分析のための 8 ステッププロトコルです
• start_bugfix はグラフの絞り込みを実行し、その後、修正とテストの前に 委任された SRC-8 計画（metadata.plan.steps src8-1~8）を実行します
• fix_bug は 委任された計画（src8-1~8）、src8Checklist、rootCauseWorksheet（ステップ 4 の中核）、および厳格なゲート（根本原因ワークシートが完了するまでコードを変更しない）を返します
• 製造業向け TBP との主な違い：再現条件の取り決め、原因の帰属レイヤー（agent_behavior を含む）、寄与要因、リポジトリをまたいだ学習のための memorize_asset

トヨタ TBP から受け継いだもの： ギャップ思考、実行前の計画、根本原因分析への早急な移行を避けること、事実に基づく調査、症状ではなく対策を重視すること、評価後の標準化。

当プロジェクトでの発展： 現地現物をコード／ログ／再現による調査へ適用、ステップ 4 のワークシート、エージェントの実行中に規律を促すガイダンス専用 MCP。

🧠 メモリ検索

• メモリツールはベクトルデータベースのバックエンドとして Qdrant を使用します
• 埋め込みサービスは次の 2 つのモードに対応しています：
  • ollama
  • openai-compatible

メモリツール：

• search_memory - 共有メモリプールをセマンティック検索します（任意で type / tags を優先できます）。テキスト出力には id、score、要約、説明、および --- content --- の本文が含まれます（MEMORY_SEARCH_CONTENT_MAX_CHARS により、デフォルトで最大 1500 文字）
• memorize_asset - 検証済みの MemoryCandidate をベクトルメモリに保存します。委任されたワークフローでは、converge の成功後にのみ呼び出してください
• read_memory_asset - asset_id を指定してアセットの全文を読み取ります（テキスト出力には content の全文が含まれます）
• update_memory_asset - asset_id を指定して既存のアセットを更新します（ID は保持され、content を変更すると再埋め込みされます）
• delete_memory_asset - asset_id を指定して共有プールからアセットを削除します
• scan_and_extract_patterns - 保存するかどうかを決める前に、コード／ファイル／ディレクトリから再利用可能なパターンを抽出します

リポジトリ間で共有するメモリプール： 共有検索では source_project / source_path に頼らず、ファイルパスを content に記載してください。検索結果への注入では、MEMORY_REPO_ID が一致するか MEMORY_SEARCH_SHOW_SOURCE=true の場合を除き、他リポジトリの sourcePath は非表示になります。

メモリのバックエンドと埋め込みの設定：

• ベクトルデータベース：Qdrant
• 推奨ローカル構成： Qdrant (port 50008) + Infinity / nomic-embed (port 50012) — Ollama より軽量です。ローカルメモリスタックガイド を参照してください（中文: memory-local-setup.zh-CN.md）
• 対応する埋め込みプロバイダー：
  • ollama
  • openai-compatible（Infinity、OpenAI など）
• メモリの書き込み／検索に必要な環境変数：
  • MEMORY_QDRANT_URL
  • MEMORY_EMBEDDING_URL
  • MEMORY_EMBEDDING_MODEL
• 任意の環境変数：
  • MEMORY_QDRANT_API_KEY
  • MEMORY_QDRANT_COLLECTION（デフォルト：mcp_probe_memory）
  • MEMORY_EMBEDDING_API_KEY
  • MEMORY_EMBEDDING_PROVIDER（デフォルトは ollama）
  • MEMORY_SEARCH_LIMIT（デフォルト：3）
  • MEMORY_SUMMARY_MAX_CHARS（デフォルト：280）
  • MEMORY_SEARCH_MIN_SCORE（デフォルト：0 = 無効。ノイズの多いプールでは 0.72 をお試しください）
  • MEMORY_SEARCH_SHOW_SOURCE（デフォルト：false）
  • MEMORY_REPO_ID（任意。sourceProject が一致する場合にのみ sourcePath を表示します）
  • MEMORY_INJECTION_CONTENT_MAX_CHARS（デフォルト：1500。start_* ガイドに注入する検索結果ごとのコンテンツ最大文字数）
• 動作に関する注意：
  • メモリへの読み取り専用アクセスには MEMORY_QDRANT_URL のみが必要です
  • メモリへの書き込みは、MEMORY_QDRANT_URL、MEMORY_EMBEDDING_URL、MEMORY_EMBEDDING_MODEL がすべて設定されている場合にのみ有効になります
  • Qdrant コレクションは初回の書き込み時に自動作成され、ベクトルの次元数は最初の埋め込みレスポンスから推定されます

推奨ローカルメモリ構成（Qdrant + Nomic Embed / Infinity）：

Docker Compose 全体、ポート、トラブルシューティングについては、docs/memory-local-setup.md を参照してください。

{
  "mcpServers": {
    "mcp-probe-kit": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "MEMORY_QDRANT_URL": "http://127.0.0.1:50008",
        "MEMORY_QDRANT_API_KEY": "your-qdrant-api-key",
        "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
        "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:50012/embeddings",
        "MEMORY_EMBEDDING_MODEL": "nomic-ai/nomic-embed-text-v1.5",
        "MEMORY_EMBEDDING_API_KEY": "your-infinity-api-key",
        "MEMORY_SEARCH_LIMIT": "3",
        "MEMORY_SUMMARY_MAX_CHARS": "280"
      }
    }
  }
}

代替構成：Qdrant + Ollama（すでに Ollama を実行している場合）：

docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
ollama pull nomic-embed-text

"MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
"MEMORY_EMBEDDING_PROVIDER": "ollama",
"MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
"MEMORY_EMBEDDING_MODEL": "nomic-embed-text"

OpenAI 互換の埋め込み（ホスト型 API）：

{
  "mcpServers": {
    "mcp-probe-kit": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
        "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
        "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
        "MEMORY_EMBEDDING_URL": "https://your-embedding-endpoint/v1/embeddings",
        "MEMORY_EMBEDDING_API_KEY": "your-api-key",
        "MEMORY_EMBEDDING_MODEL": "text-embedding-3-small"
      }
    }
  }
}

🎯 構造化出力

コアツールとオーケストレーションツールは構造化出力に対応しており、機械可読な JSON データを返します。これにより AI の解析精度が向上し、ツールの連携や状態の追跡が可能になります。

⏱️ ネイティブタスク、進捗、キャンセル

• SDK に依存しない内部タスクランタイムを使用し、現在の SDK タスクプロトコルはレガシーアダプターを通じて公開されます。
• タスクのライフサイクルエンドポイントをサポートします：tasks/get、tasks/result、tasks/list、tasks/cancel
• capabilities.tasks.requests.tools.call を通知し、クライアントが tools/call のタスクを作成できるようにします。
• プロトコルのタスクストレージを利用できない場合は、同期実行にフォールバックします。
• クライアントが _meta.progressToken を指定した場合、notifications/progress を送信します。
• 終了後に届いた進捗通知は無視します。ツール／タスクの結果が最終完了シグナルになります。
• AbortSignal によるリクエストのキャンセルを処理し、明確な cancelled 状態を維持します。
• 長時間実行されるオーケストレーションツール（start_*）と sync_ui_data は、協調的なキャンセル／進捗コールバックをサポートします。
• 内部タスクの永続化は、デフォルトでメモリを使用します。.mcp-probe-kit/tasks.json を使用するには MCP_TASK_STORE=json を設定し、別の JSON パスを選ぶには MCP_TASK_STORE_PATH を設定します。実行プログラムを再構築できない中断済みタスクは、再起動時に引き続き実行中として報告されるのではなく、明示的に失敗としてマークされます。

🔌 公式 MCP Apps と Memory Center

v4.0.0 では、公式の @modelcontextprotocol/ext-apps SDK と安定版の io.modelcontextprotocol/ui 拡張を使用します。

• MCP Apps はデフォルトで有効です。MCP_ENABLE_UI_APPS=0 で無効にできます。
• UI メタデータと ui:// リソースは、クライアントが text/html;profile=mcp-app のサポートを通知した後にのみ公開されます。
• 安定版の Apps が 5 つ含まれています：Memory Center、Feature Workbench、Bug Workbench、Product Workbench、Convergence Gate。
• Memory Center はレスポンシブなマスター・ディテールレイアウトを使用し、過去のデータの閲覧、セマンティック検索、コンテンツ全体の確認、ライフサイクル状態、エビデンス、古いデータのマーク付け、確認後の削除に対応します。
• Feature Workbench と Bug Workbench は、リアルタイムの計画ステッパーを表示します。App は表示中に resume_plan をポーリングし、Agent が plan_heartbeat を通じて実際のステップ状態を記録した後にのみ進捗が進みます。
• Product Workbench と Convergence Gate は、納品パス、ブロッカー、エビデンスの不足を表示するため、同じ開発者コンソールのデザインシステムを使用します。
• list_memory_assets は App 専用のアクションで、_meta.ui.visibility=["app"] が設定されています。Apps 対応ホストの生の tools/list レスポンスには表示される場合がありますが、準拠ホストはモデルに提示してはなりません。モデルから見える数は、デフォルトで 24、Memory を有効にすると 30 のままです。
• MCP Apps に対応していないクライアントにも、通常のテキストレスポンスと structuredContent レスポンスが引き続き返されます。既存のワークフローに GUI 機能は必要ありません。
• トレースメタデータのパススルーは、引き続き MCP_ENABLE_EXTENSIONS_CAPABILITY=1 で利用できます。

🧪 ツールと実 Agent の契約検証

# Deterministic server-side audit across compact, Memory, full, App-only, and Legacy surfaces
npm run audit:tools

# Optional real-host audit: Claude Code calls and evaluates all 34 model tools
npm run audit:tools:agent

直接監査では、読み取り可能なテキストが空でないこと、structuredContent があること、参照されるすべての MCP ツールがアクティブなサーフェス上に存在することを検証します。実 Agent の監査ではさらに、Agent が各ツールを理解し、返されたガイダンスに従えること、テキストと構造化データの間に矛盾がないこと、記載された次のステップを実行できることを確認します。設定済みの Claude Code アカウントが必要で、モデルの利用が発生するため、この監査は意図的に release:verify とは分けられています。

🧭 委譲オーケストレーションプロトコル

すべての start_* オーケストレーションツールは、structuredContent.metadata.plan に実行計画を返します。
ツールが内部で実行するのではなく、AI がツールをステップごとに呼び出し、ファイルを永続化する必要があります。

計画スキーマ（コアフィールド）：

{
  "mode": "delegated",
  "steps": [
    {
      "id": "spec",
      "tool": "add_feature",
      "args": { "feature_name": "user-auth", "description": "User authentication feature" },
      "outputs": ["docs/specs/user-auth/requirements.md"]
    }
  ]
}

フィールドの説明：

• mode：delegated に固定
• steps：実行ステップの配列
• tool：ツール名（例：add_feature）
• action：ツールがない場合の手動アクションの説明（例：update_project_context）
• args：ツールのパラメーター
• outputs：想定される成果物
• when/dependsOn/note：任意の条件と注記

🧩 構造化出力フィールドの仕様（主なフィールド）

オーケストレーションツールとアトミックツールは、共通フィールドを含む structuredContent を返します。

• summary：1 行の要約
• status：ステータス（pending/success/failed/partial）
• steps：実行手順（オーケストレーションツール）
• artifacts：成果物リスト（パス＋用途）
• metadata.plan：委任された実行計画（start_* のみ）
• specArtifacts：仕様成果物（start_feature）
• estimate：見積もり結果（start_feature / estimate）

🧠 要件の明確化モード（Requirements Loop）

要件が不明確な場合は、start_feature / start_bugfix / start_ui で requirements_mode=loop を使用してください。
このモードでは、仕様・修正・UI の実行に入る前に、構造化された明確化を 1～2 回行います。

例：

{
  "feature_name": "user-auth",
  "description": "User authentication feature",
  "requirements_mode": "loop",
  "loop_max_rounds": 2,
  "loop_question_budget": 5
}

🧩 テンプレートシステム（一般的なモデル向け）

add_feature はテンプレートプロファイルに対応しています。デフォルトの auto はプロファイルを自動選択します。要件が不完全な場合は、詳細な記入ルールとチェックリストを含む guided を優先し、要件がそろっている場合は、より簡潔な構成で、高性能モデルやアーカイブ用途に適した strict を選択します。

例：

{
  "description": "Add user authentication feature",
  "template_profile": "auto"
}

対象ツール：

• start_feature は template_profile を add_feature に渡します
• start_bugfix / start_ui も、ガイダンスの強さを制御する template_profile に対応しています（auto/guided/strict）

テンプレートプロファイルの使い分け：

• guided：要件情報が不足または不完全な場合に、一般的なモデル向けに優先します
• strict：要件が構造化されている場合に、より簡潔なガイダンスを優先します
• auto：デフォルトの推奨設定で、guided/strict を自動選択します

親子仕様

バージョン単位またはエピック単位の作業では、start_feature はデフォルトで spec_layout: "auto" を使用し、要件が複数のモジュール、段階、または機能領域にまたがる場合は parent-child を選択します。子仕様の境界がまだ分からない場合、委任された計画ではまず decompose-spec ステップが返されます。flat または parent-child を明示的に渡すこともできます。add_feature は引き続きアトミックツールであり、レイアウトと subspecs がすでに定義されていない限り、デフォルトで flat を使用します。MCP サーバーはテンプレートと pendingFiles を返し、呼び出し元の Agent がレビュー後に親仕様、spec-manifest.json、子仕様を作成します。その後、check_spec が階層全体を再帰的に検証します。

start_feature は、クエリ専用の GitNexus 絞り込みを 8 秒の縮退予算で使用するため、グラフのコールドスタートによって仕様計画が妨げられることはありません。インデックスの自動更新はデフォルトで無効です。グラフクエリの前に MCP プロセスでインデックスを更新する場合は、MCP_GITNEXUS_AUTO_REFRESH=1 を設定してください。

{
  "feature_name": "commerce-v2",
  "description": "Upgrade the commerce domain while preserving v1 compatibility",
  "spec_layout": "parent-child",
  "subspecs": [
    { "id": "01-foundation", "title": "Data foundation", "fr": ["FR-1"] },
    { "id": "06-inventory-ledger", "title": "Inventory ledger", "fr": ["FR-2"], "dependsOn": ["01-foundation"] }
  ]
}

🔄 ワークフローのオーケストレーション

複雑な開発ワークフローをワンクリックで実行できるよう、複数の基本ツールを自動的に組み合わせる 6 つのインテリジェントなオーケストレーションツール：

• start_feature - 新機能の開発（要件 → 設計 → 見積もり）
• start_bugfix - バグ修正（SRC-8 RCA → 修正 → テスト）
• start_onboard - プロジェクトのオンボーディング（プロジェクトのコンテキストドキュメントを生成）
• start_ui - UI 開発（デザインシステム → コンポーネント → コード）
• start_product - プロダクト設計（PRD → プロトタイプ → デザインシステム → HTML）
• start_ralph - Ralph Loop（目標達成まで反復的に開発）

🚀 プロダクト設計ワークフロー

start_product は、要件からインタラクティブなプロトタイプまでを扱う、プロダクト設計のための完全なオーケストレーションツールです。

ワークフロー：

1. 要件分析 - 標準的な PRD を生成します（プロダクト概要、機能要件、ページ一覧）
2. プロトタイプ設計 - 各ページの詳細なプロトタイプドキュメントを生成します
3. デザインシステム - プロダクトの種類に基づいてデザイン仕様を生成します
4. HTML プロトタイプ - ブラウザーで表示できるインタラクティブなプロトタイプを生成します
5. プロジェクトのコンテキスト - プロジェクトドキュメントを自動更新します

構造化出力の追加項目：

• start_product.structuredContent.artifacts：成果物リスト（PRD、プロトタイプ、デザインシステムなど）
• interview.structuredContent.mode：usage / questions / record

🎨 UI/UX Pro Max

start_ui を統一エントリーポイントとする 4 つの UI/UX ツール：

• start_ui - ワンクリックで UI を開発（インテリジェントモードに対応）（オーケストレーションツール）
• ui_design_system - インテリジェントなデザインシステム生成
• ui_search - UI/UX データ検索（BM25 アルゴリズム）
• sync_ui_data - 最新の UI/UX データをローカルに同期

注：start_ui は ui_design_system と ui_search を自動的に呼び出すため、個別に呼び出す必要はありません。

参考資料：

• ui-ux-pro-max-skill - UI/UX デザインシステムの理念
• json-render - JSON テンプレートレンダリングエンジン

UI/PRD ワークフロー向けのスキルブリッジ：

• start_ui と start_product のガイダンス、および structuredContent.metadata.skills にスキルブリッジのセクションが追加されました。
• 推奨されるスキル呼び出し順序：ui-ux-pro-max → interaction-design → frontend-design。
• 一部のスキルが利用できない場合も、MCP のメインプランでワークフローを続行し、利用できないスキルをメタデータに記録します。

sync_ui_data を使う理由

start_ui ツールは、高品質なデザインシステムとコードを生成するために、豊富な UI/UX データベース（色、アイコン、チャート、コンポーネント、デザインパターンなど）を利用します。このデータは npm パッケージ uipro-cli に由来し、以下が含まれます。

• 🎨 カラースキーム（主要ブランドカラー、カラーパレット）
• 🔣 アイコンライブラリ（React Icons、Heroicons など）
• 📊 チャートコンポーネント（Recharts、Chart.js など）
• 🎯 ランディングページのテンプレート（SaaS、eコマース、政府機関など）
• 📐 デザイン仕様（余白、フォント、シャドウなど）

データ同期戦略：

1. 組み込みデータ：ビルド時に同期され、オフラインで動作します
2. バックグラウンド自動同期：現在のセッションの出力を変更せずに、最新データを ~/.mcp-probe-kit/ui-ux-data/ にダウンロードします
3. 次回起動時に適用：新しくダウンロードしたデータは次回のプロセス起動時に適用されます（現在のセッションの決定性を維持します）
4. 手動同期：sync_ui_data を使ってキャッシュをすぐに強制更新します（デフォルトでは次回起動時に適用されます）

これにより、オフラインでも start_ui でプロフェッショナル品質の UI コードを生成できます。

🎤 要件ヒアリング

開発前に要件を明確にする 2 つのヒアリングツール：

• interview - 構造化された要件ヒアリング
• ask_user - AI による積極的な質問

---

🧭 ツール選択ガイド

オーケストレーションツールと個別ツールの使い分け

オーケストレーションツール（start_*）を使う場合：

• ✅ 一連のワークフローが必要（複数のステップ）
• ✅ 複数のタスクを自動化したい
• ✅ 複数の成果物（ドキュメント、コード、テストなど）を生成する必要がある

個別ツールを使う場合：

• ✅ 特定の機能だけが必要
• ✅ プロジェクトのコンテキストドキュメントがすでにある
• ✅ より細かな制御が必要

よくあるシナリオでのツール選択

シナリオ	推奨ツール	理由
新機能の開発（一連のフロー）	start_feature	自動完了：仕様策定→見積もり
機能仕様書だけが必要	add_feature	より軽量で、ドキュメントのみを生成
バグ修正（一連のフロー）	start_bugfix	SRC-8 プラン（src8-1~8）に委任 → 修正 → テスト → ナレッジ化
バグ分析だけが必要	fix_bug	SRC-8 プランへの委任と根本原因分析ワークシート（手法：docs）
デザインシステムの生成	ui_design_system	デザイン仕様を直接生成
UI コンポーネントの開発	start_ui	一連のフロー：設計→コンポーネント→コード
プロダクト設計（要件からプロトタイプまで）	start_product	ワンクリック：PRD→プロトタイプ→HTML
1 文での要件分析	init_project	プロジェクト仕様書一式を生成
プロジェクト導入ドキュメント	init_project_context	技術スタック／アーキテクチャ／規約を生成

---

🚀 クイックスタート

方法 1：npx で直接使う（推奨）

インストールは不要で、最新バージョンをそのまま使えます。

Cursor / Cline の設定

設定ファイルの場所：

• Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• macOS: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

設定内容：

{
  "mcpServers": {
    "mcp-probe-kit": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

スキルと AGENTS の自動ブートストラップ（v3.6.3+）：すべての MCP ツール呼び出しで .agents/skills/mcp-probe-kit/SKILL.md が書き込まれ、mcp-probe:context ブロックが AGENTS.md にマージされます。ワークスペースのルートは自動検出されます（Cursor は WORKSPACE_FOLDER_PATHS を注入し、OpenCode のプロジェクト opencode.json は cwd を設定します）。グローバル MCP でワークスペースを解決できない場合を除き、クライアントごとに MCP_PROJECT_ROOT を設定する必要はありません。その場合は MCP_PROJECT_ROOT を設定するか、ツール引数に project_root を渡してください。

複数ハーネス向けアダプター（v3.6.8+）：AGENTS.md と正規のスキルが、単一のルールソースとして維持されます。プロジェクトに .trae/、.lingma/、.comate/、.codebuddy/、または .claude/ がすでにある場合は、対応する薄いアダプター（スキルミラーまたはルールポインター）が自動的に書き込まれます。環境変数は不要です。

バージョン固定 CLI フォールバック（v4.0.0+）：ブートストラップでは .mcp-probe-kit/bin/probe.cmd|probe.ps1|probe と .mcp-probe-kit/runtime.json も書き込まれます。変更されたホストやサードパーティの Agent プロバイダーが MCP サーバーに接続しても、そのツールを Agent セッションに含めない場合、生成されたスキルと Cursor ルールに従い、Agent はプロジェクトのラッパーを通じて同じ Tool Registry を呼び出します。ラッパーは MCP パッケージの正確なバージョンを固定し、グローバルにはインストールせず、プロジェクトの package.json も変更しません。

CLI フォールバック用のメモリ：install-agent は .mcp-probe-kit/local.env（および local.env.example）も作成します。CLI フォールバックのパス（probe.* exec ...）は IDE の mcp.json の env を継承しません。local.env を編集して、同じ MEMORY_* キーを設定してください。

CLI の直接実行例：

# JSON from stdin is the most portable option
printf '%s' '{"intent":"build a task board","scenario":"feature","project_root":"."}' \
  | ./.mcp-probe-kit/bin/probe exec workflow --stdin

# Repair or install the project wrappers without a working MCP tool lease
npx --yes mcp-probe-kit@<exact-version> install-agent --project-root .

Claude Desktop の設定

設定ファイルの場所：

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

設定内容：

{
  "mcpServers": {
    "mcp-probe-kit": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

OpenCode の設定

設定ファイルの場所：

• プロジェクトレベル：プロジェクトルートにある opencode.json
• グローバル：~/.config/opencode/opencode.json

設定内容：

{
  "mcp": {
    "mcp-probe-kit": {
      "type": "local",
      "command": ["npx", "-y", "[email protected]"],
      "enabled": true
    }
  }
}

注： OpenCode は、Cursor／Claude Desktop とは異なるスキーマの opencode.json を使用します。キーは mcpServers ではなく mcp で、command は配列、type: "local" は必須です。また、環境変数には env ではなく environment を使用します。詳しくは OpenCode MCP ドキュメント を参照してください。

方法 2：プロジェクトローカルの Agent フォールバック

npx --yes [email protected] install-agent --project-root .

これにより、バージョンが固定された .mcp-probe-kit/bin/probe.* ランチャーが書き込まれます。ネイティブ MCP を優先してください。ホストがツールを注入しない場合は、Agent がこれらのラッパーを使用します。パッケージをグローバルにインストールしないでください。

オプションのメモリーシステムのセットアップ

memorize_asset、update_memory_asset、read_memory_asset、delete_memory_asset、scan_and_extract_patterns を使用する場合は、次のように設定してください。

• Qdrant のみ（MEMORY_QDRANT_URL）：read_memory_asset、delete_memory_asset
• Qdrant + 埋め込み（3 つすべての MEMORY_* 書き込み／検索変数）：search_memory、memorize_asset、update_memory_asset
• メモリーバックエンドなし：scan_and_extract_patterns（ローカルスキャンのみ。準備ができたら memorize_asset で永続化します）

完全な書き込み／検索機能を利用するには、次の両方が必要です。

1. Qdrant ベクトルデータベース
2. ollama または openai-compatible モードの埋め込みサービス

注（CLI フォールバック）：ネイティブ MCP の代わりにプロジェクトラッパー（./.mcp-probe-kit/bin/probe* exec ...）を実行する場合、メモリー環境変数は .mcp-probe-kit/local.env（install-agent によって作成）から読み込まれます。

詳細ガイド（Qdrant + Infinity 用 Docker Compose、ポート 50008／50012、MCP 環境変数、スモークテスト）：

• 英語：docs/memory-local-setup.md
• 中国語：docs/memory-local-setup.zh-CN.md

オプション A：Qdrant + Nomic Embed / Infinity（推奨）

軽量なローカルスタックで、Ollama は不要です。Docker Compose で Qdrant と nomic-embed をデプロイし（ガイドを参照）、次のように設定します。

{
  "mcpServers": {
    "mcp-probe-kit": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "MEMORY_QDRANT_URL": "http://127.0.0.1:50008",
        "MEMORY_QDRANT_API_KEY": "your-qdrant-api-key",
        "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
        "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:50012/embeddings",
        "MEMORY_EMBEDDING_MODEL": "nomic-ai/nomic-embed-text-v1.5",
        "MEMORY_EMBEDDING_API_KEY": "your-infinity-api-key",
        "MEMORY_SEARCH_LIMIT": "3",
        "MEMORY_SUMMARY_MAX_CHARS": "280"
      }
    }
  }
}

埋め込み URL は /embeddings である必要があります（/v1/embeddings ではありません）。QDRANT__SERVICE__API_KEY が設定されている場合、Qdrant には api-key が必要です。

オプション B：Qdrant + Ollama

docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
ollama pull nomic-embed-text

"MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
"MEMORY_EMBEDDING_PROVIDER": "ollama",
"MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
"MEMORY_EMBEDDING_MODEL": "nomic-embed-text"

オプション C：Qdrant + ホスト型 OpenAI 互換 API

"MEMORY_QDRANT_URL": "http://127.0.0.1:50008",
"MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
"MEMORY_EMBEDDING_URL": "https://your-embedding-endpoint/v1/embeddings",
"MEMORY_EMBEDDING_API_KEY": "your-api-key",
"MEMORY_EMBEDDING_MODEL": "text-embedding-3-small"

履歴セッションの環境変数

• MCP_HISTORY_SESSION：デフォルトは ON です。0|false|off を設定すると、5 つの history_session_* ツールが非表示になります
• MCP_HISTORY_MAX_LINES：ソフトローテーションの行数しきい値（デフォルトは 800）
• MCP_HISTORY_MAX_BYTES：ソフトローテーションのバイト数しきい値（デフォルトは 131072）

メモリーの環境変数

• MEMORY_QDRANT_URL：Qdrant のベース URL。すべてのメモリー機能で必須です
• MEMORY_QDRANT_API_KEY：Qdrant の API キー（任意）
• MEMORY_QDRANT_COLLECTION：コレクション名。デフォルトは mcp_probe_memory
• MEMORY_EMBEDDING_PROVIDER：ollama または openai-compatible
• MEMORY_EMBEDDING_URL：埋め込みエンドポイントの URL
• MEMORY_EMBEDDING_API_KEY：Ollama では任意ですが、ホスト型の OpenAI 互換プロバイダーでは通常必要です
• MEMORY_EMBEDDING_MODEL：デフォルトは nomic-embed-text です
• MEMORY_SEARCH_LIMIT：検索結果のデフォルト件数は 3 です
• MEMORY_SUMMARY_MAX_CHARS：要約のデフォルト切り捨て文字数は 280 です

注意事項

• メモリーへの書き込み機能は、MEMORY_QDRANT_URL、MEMORY_EMBEDDING_URL、MEMORY_EMBEDDING_MODEL が設定されている場合にのみ有効になります
• メモリーの読み取り機能に必要なのは MEMORY_QDRANT_URL のみです
• Qdrant コレクションは、初回の書き込み時に距離関数 Cosine で自動作成されます
• ベクトルサイズは、最初の埋め込みレスポンスから推定されます

GitNexus のマネージドランタイム

code_insight、start_feature、start_bugfix、init_project_context に適用されます。

GitNexus にはプラットフォーム固有のネイティブ依存関係が含まれ、PolyForm Noncommercial ライセンスが適用されるため、mcp-probe-kit の npm tarball には同梱されていません。ランタイムのポリシーは次のとおりです。

1. 明示的に設定されている場合は MCP_GITNEXUS_COMMAND を使用します。
2. それ以外の場合は、mcp-probe-kit のユーザーキャッシュにある、すでに検証済みのマネージド Sidecar を再利用します。
3. それ以外の場合は、PATH 上で利用できる互換性のある gitnexus CLI を使用します。
4. ランタイムがインストールされていない場合、グラフ分析はメインのワークフローをブロックせず、ただちに縮退します。エージェントは doctor gitnexus --install を実行して、自動的に再試行できます。

互換性の検証結果：

Node.js	マネージド GitNexus
20-21	マネージド Sidecar は無効です。システムの GitNexus CLI を使用するか、縮退モードを使用してください
22+ / Windows、macOS、Linux	1.6.9

各マネージドインストールは、GitNexus のバージョン、オペレーティングシステム、CPU アーキテクチャ、Node.js のメジャーバージョンごとに分離されています。ランタイムの使用を許可する前に、固定されたリリースメタデータに照らして npm の整合性を検証します。その後、インストーラーは gitnexus doctor と実際の TypeScript インデックス作成プローブを実行し、FTS/BM25 検索が無効になったままのランタイムを拒否します。

プロジェクトランチャーからマネージド Sidecar をインストールまたは修復します。

# Windows
& ./.mcp-probe-kit/bin/probe.cmd doctor gitnexus --install

# macOS / Linux
./.mcp-probe-kit/bin/probe doctor gitnexus --install

GitNexus にはネイティブパーサー、LadybugDB、ONNX Runtime、インストール後の文法ビルドが含まれるため、初回のインストールには数分かかる場合があります。プロジェクト外で実行され、プロジェクトの package.json や node_modules は変更されません。

利用可能なモード：

• MCP_GITNEXUS_MODE=auto — デフォルトです。明示的に指定されたランタイム／システムのランタイム／既存のマネージドランタイムを使用し、それ以外の場合はすばやく縮退します。
• MCP_GITNEXUS_MODE=managed — マネージド Sidecar を必須とし、グラフのリクエスト中にインストールできるようにします。
• MCP_GITNEXUS_MODE=system — 明示的に指定された GitNexus またはシステムの GitNexus のみを使用し、インストールは行いません。
• MCP_GITNEXUS_MODE=off — GitNexus を無効にします。
• MCP_GITNEXUS_AUTO_INSTALL=1 — auto モードで同期インストールを許可します。レイテンシーに敏感なクライアントでは推奨されません。

一部の GitNexus 依存関係はネイティブモジュールを使用します。Windows では、LadybugDB FTS に Git for Windows に同梱されている OpenSSL ランタイムも必要です。mcp-probe-kit はその mingw64/bin ディレクトリを検出し、マネージド子プロセスにのみ公開します。Git が標準以外の場所にインストールされている場合は、MCP_GITNEXUS_WINDOWS_RUNTIME_BIN に同等のディレクトリを設定してください。ビルド済みバイナリのダウンロードに失敗した場合は、C++ ワークロードを含む Visual Studio Build Tools が必要になることがあります。インストールに失敗しても、mcp-probe-kit のワークフローは縮退モードで続行されます。

インストール済みの gitnexus CLI を使用する設定例：

{
  "mcpServers": {
    "mcp-probe-kit": {
      "command": "mcp-probe-kit",
      "env": {
        "MCP_GITNEXUS_MODE": "system",
        "MCP_GITNEXUS_COMMAND": "gitnexus",
        "MCP_GITNEXUS_ARGS": "mcp",
        "MCP_GITNEXUS_CONNECT_TIMEOUT_MS": "30000",
        "MCP_GITNEXUS_TIMEOUT_MS": "45000"
      }
    }
  }
}

クライアントを再起動する

設定後は、MCP クライアントを完全に終了してから再起動してください。

👉 詳細なインストールガイド

---

💡 使用例

日常の開発

code_review @feature.ts    # Code review
gentest @feature.ts         # Generate tests
gencommit                   # Generate commit message

新機能の開発

start_feature user-auth "User authentication feature"
# Auto-complete: Requirements analysis → Design → Effort estimation

バグ修正

start_bugfix
# Then paste error message
# Auto-complete: Problem location → Fix solution → Test code

プロダクトデザイン

start_product "Online Education Platform" --product_type=SaaS
# Auto-complete: PRD → Prototype → Design system → HTML prototype

UI 開発

start_ui "Login Page" --mode=auto
# Auto-complete: Design system → Component generation → Code output

プロジェクトコンテキストのドキュメント化

# Single file mode (default) - Generate a complete project-context.md
init_project_context

# Modular mode - Generate 6 category docs (suitable for large projects)
init_project_context --mode=modular
# Generates: project-context.md (index) + 5 category docs

Git 作業レポート

# Generate daily report
git_work_report --date 2026-02-03

# Generate weekly report
git_work_report --start_date 2026-02-01 --end_date 2026-02-07

# Save to file
git_work_report --date 2026-02-03 --output_file daily-report.md
# Auto-analyze Git diff, generate concise professional report
# If direct command fails, auto-provides temp script solution (auto-deletes after execution)

👉 その他の使用例

---

❓ FAQ

Q1：ツールが動作しない、またはエラーが発生する場合は？

詳細なログを確認してください。

Windows（PowerShell）：

npx -y [email protected] 2>&1 | Tee-Object -FilePath .\mcp-probe-kit.log

macOS/Linux：

npx -y [email protected] 2>&1 | tee ./mcp-probe-kit.log

Q2：設定後、クライアントがツールを認識しない場合は？

1. クライアントを再起動する（完全に終了してから再起動）
2. 設定ファイルのパスが正しいことを確認します
3. JSON 形式が正しく、構文エラーがないことを確認します
4. クライアントの開発者ツールまたはログでエラーメッセージを確認します

Q2b：Cursor では接続済みと表示されるのにツールが 0 個／エージェントに「MCP サーバーがありません」と表示される場合

これは既知のCursor 側の問題です。stderr には有効なコンパクトなツールセットが報告される一方、Mcp FileSystem Writer には lease returned 0 tools と toolCount=0 が表示されます。Agent のリース層でツール一覧が通知なく破棄されています。

一般的な原因：

ログに表示される症状	考えられる原因
tools/list ≈ 50+ KB の後に lease returned 0 tools	Cursor 内部のペイロードサイズ上限（一覧全体が通知なく破棄される）
latched shared-process MCP routing disabled ＋ ipcReady タイムアウト	Windows の mcpProcess ユーティリティが失敗。レガシーフォールバックではツールが検出されるものの、Agent のリースは空のまま
設定では緑色の点、Agent では No MCP servers available	このセッションでは Renderer ↔ shared-process 間の MCP ルーティングが接続されていない

こちらの対応： tools/list では既定で outputSchema を省略しており、既定のコンパクトなモデルセットは 29 個のツール（基本ツール 24 個 ＋ History Session 5 個）です。構造化出力は引き続き tools/call の structuredContent で利用できます。MCP_INCLUDE_OUTPUT_SCHEMA=1 で出力スキーマを復元するか、MCP_TOOLSET=full で互換性のある 39 個のツールセットを復元してください。

試せること：

1. MCP を再読み込みするか、Cursor を完全に終了して（ウィンドウを閉じるだけではなく）再起動する
2. Output → MCP で lease returned 0 tools ／ ipcReady ／ MessagePort を確認する
3. Composer でツールパネルを開き、サーバーの切り替えがオンになっていることを確認する（バージョンによっては既定でオフになっています）
4. Cursor をアップグレードする（3.7.36 以降では Windows の ipcReady に関するリグレッションがありました。最新版を試すか、問題なく動作することが確認済みのビルドに戻してください）
5. サーバーを更新しても問題が解決しない場合は、connected=true、stderr のツール数、リースの toolCount=0、shared-process MCP routing disabled を添えて Cursor に報告する

ホストエージェントの経路が置き換えられた場合、または MCP ツールがブリッジされない場合のフォールバック：

MCP パネルとツールキャッシュは正常でも、実際のエージェントリクエストが MCP ツールブリッジを持たないサードパーティープロバイダーによって処理される場合、サーバーを再起動してもその経路は修正されません。bootstrap で生成されたプロジェクトラッパーを使用してください。

# Windows
'{"intent":"continue the current feature","scenario":"feature","project_root":"."}' |
  .\.mcp-probe-kit\bin\probe.cmd exec workflow --stdin

# macOS / Linux
printf '%s' '{"intent":"continue the current feature","scenario":"feature","project_root":"."}' \
  | ./.mcp-probe-kit/bin/probe exec workflow --stdin

ネイティブ MCP ツールがない場合、Skill はこの経路を自動的に選択します。plan_heartbeat、resume_plan、converge は、別々の CLI プロセスとネイティブ MCP セッション間で同じプロジェクトファイルを使用します。

診断：.cursor/projects/<project>/mcps/user-mcp-probe-kit/

このフォルダーは mcp-probe-kit ではなく、Cursor によって書き込まれます（Mcp FileSystem Writer）。ツールのリースが成功すると、次の内容が表示されます。

mcps/user-mcp-probe-kit/
├── SERVER_METADATA.json
├── STATUS.md
├── tools/           ← one JSON per model-visible tool (~24 by default); Agent reads these for CallMcpTool
│   ├── init_project.json
│   └── ...
└── resources/       ← from resources/list (may exist even when tools/ is empty)

状態	意味
resources/ は存在するが、tools/ がない、または空	resources/list は成功したが、ツールのリースに失敗（lease returned 0 tools と一致）
tools/ のエントリ数が、選択したモデルセット（既定は 24 個、Memory 有効時は 30 個、full では 34 個）より少ない	書き込みが一部のみ、またはセッションが中断された。MCP を再読み込みしてください
STATUS.md にサーバーエラーが記載されている	設定では緑色でも、Cursor が Agent に対してサーバーを異常と判定した

正常なセッションでは、MCP 接続後、数秒以内に tools/ が自動的に作成されます。手動設定もリポジトリ設定も不要です。

Q3：現在の安定版に更新するには？

MCP 設定で正確な指定子 [email protected] を固定します。次に、プロジェクトローカルのフォールバックを更新します。

npx --yes [email protected] install-agent --project-root .

@next、変動する @latest 指定子、グローバルな npm install -g は使用しないでください。

Q4：GitNexus の初回インストールに時間がかかるのはなぜですか？

GitNexus には、ネイティブパーサー、グラフデータベース、ONNX Runtime、インストール後の文法ビルドが含まれています。初回の管理対象インストールには数分かかる場合があり、特に Windows やネットワークが遅い環境では時間がかかります。

通常の機能開発やバグ修正のワークフローでは、デフォルトの auto モードでこのインストールを待つ必要はありません。構造化された managed_install_required の縮退結果を返し、エージェントが自動的に次のコマンドを実行できます。

& ./.mcp-probe-kit/bin/probe.cmd doctor gitnexus --install

インストール先は mcp-probe-kit のユーザーキャッシュです。互換性のあるバージョンを正確に指定し、npm の整合性チェック用ピンを使用するため、ビジネスプロジェクトは変更されません。ネイティブインストールに失敗した場合、グラフ分析は縮退した状態になりますが、ワークフローの残りの部分は通常どおり続行されます。

👉 その他の FAQ

---

🤝 貢献

Issue やプルリクエストを歓迎します！

改善の提案：

• 便利なツールを追加する
• 既存のツールのプロンプトを最適化する
• ドキュメントやサンプルを改善する
• バグを修正する

---

📄 ライセンス

MIT License

---

🔗 関連リンク

• 作者：Kyle (小墨)
• GitHub：mcp-probe-kit
• npm：mcp-probe-kit
• ドキュメント：https://mcp-probe-kit.bytezonex.com

関連プロジェクト：

• Model Context Protocol (MCP) - MCP の公式プロトコルドキュメント
• GitHub Spec-Kit - GitHub の仕様駆動開発ツールキット
• ui-ux-pro-max-skill - UI/UX デザインシステムの理念の情報源
• json-render - JSON テンプレートレンダリングエンジンのインスピレーション
• uipro-cli - UI/UX のデータソース

---

AI を活用した開発のために ❤️ を込めて作成

---

謝辞

プロジェクトの普及を支援し、フィードバックを提供してくださった Linux.do コミュニティに感謝します。