Game Debug MCP

AIに証拠を。また別のスクリーンショットではなく。

Game Debug MCPは、AI支援によるゲーム開発のための、オープンでエンジンに依存しないビジュアルおよびパフォーマンスデバッガです。保存されたフレームバッファ、ID、トレース、キャプチャ受領情報を決定的な測定値に変換し、それらの観測結果を因果順に辿り、実際に証明できる最も早い分岐点を特定し、残る不確実性を減らすために必要な最小のキャプチャをエージェントに指示します。

読み取り専用のModel Context ProtocolサーバーまたはJSON CLIを通じて、あらゆるAIと連携します。モデルは提案と説明を行い、ツールは測定し、裏付けのない主張を拒否します。

v0.1は証拠分析器でありキャプチャプランナーです。エディタを操作したり、ゲームを起動したり、GPUワークロードを実行したり、ピクセルが美しく見えると主張したりすることはありません。エンジンおよびグラフィックスデバッガ向けのキャプチャアダプタは次のレイヤーであり、今回のリリースに暗に含まれる約束ではありません。

なぜ存在するのか

AIは、美しいスクリーンショットを見てそれらしい推測をすることができます。しかし、レンダリングの欠陥には、通常より適切な問いが必要です：

• ジオメトリはシェーディングより前に消えたのか、それとも最終色が後で黒くなったのか？

• マテリアル割り当てが変わったのか、それともアルベド入力だけが変わったのか？

• 時間的アーティファクトは、モーションベクター、深度、履歴の有効性、最終色のうち、どこで最初に見えるのか？

• 3msの改善は、同じハードウェアとワークロードで測定されたのか、それとも単に比較不能な2つのトレースに過ぎないのか？

• フレームは送信されたのか、完了したのか、読み戻されたのか、レビューされたのか、それとも単に要求されただけなのか？

Game Debug MCPは、それらの境界を明示的に表現します。診断は測定の連鎖であり、裏付けのない自信に満ちた段落ではありません。

flowchart LR
  A[Game or capture adapter] -->|PNG, NPY, trace JSON, receipts| B[Sealed frame bundle]
  B --> C[Deterministic analyzers]
  C --> D[First-divergence workflow]
  D --> E[MCP-compatible AI host]
  D --> F[JSON CLI or CI]
  D --> G[Self-contained HTML report]
  D -->|missing evidence| H[Smallest next-capture plan]

Related MCP server: spector-agent-mcp

v0.1に含まれるもの

• ランタイム依存関係ゼロのNode.js 20+分析コア。

• 標準入出力で動作する13ツールの読み取り専用MCPサーバー。

• MCPを使用しないモデルと自動化のためのJSON CLI。

• チャンクCRC検証付きPNGデコードとNumPy .npy デコード。

• 正確なSHA-256アーティファクトシールに加え、標準マニフェスト整合性シール。

• 色、スカラー、マスク、カテゴリID、法線、ベクターバッファの分析。

• ピクセル差分、MAE、RMSE、色のみのPSNR、タイル化SSIM、最初の差分座標、差分境界、ID遷移、法線角度誤差、マスク、ヒートマップ。非有限値の不一致は、偽のゼロを生成する代わりに、集計エラーメトリクスを無効にします。

• 空白フレーム、欠落ジオメトリ、誤ったマテリアル、フラットな照明、誤ったシャドウ、時間的欠陥、パフォーマンス調査のための因果ワークフロー。

• フレーム時間分布、予算超過、上位GPUパス要約、アイデンティティで制限されたトレース比較。

• マテリアル入力回帰と欠落ジオメトリのための合成フィクスチャ。

• ベースライン、候補、ヒートマップ、因果ウォーク、構造化測定、明示的な保留中の人間レビュー状態を含む自己完結型HTML証拠レポート。

コアはローカルで実行され、ネットワークリクエストを行いません。

クイックスタート

リポジトリをクローンしてソースを確認します：

git clone https://github.com/theisegoria/game-debug-mcp.git
cd game-debug-mcp
npm install --ignore-scripts
npm run check

使い捨てのディレクトリに決定的デモを生成します：

node bin/game-debug.mjs demo /tmp/game-debug-demo

誤ったマテリアルのケースが最初に分岐する箇所を尋ねます：

node bin/game-debug.mjs diagnose \
  baseline-material-shift \
  candidate-material-shift \
  wrong_material \
  --project /tmp/game-debug-demo

結果の重要な部分は次のとおりです：

{
  "first_divergence": {
    "semantic": "albedo",
    "workflow_position": 3,
    "pixel": {
      "x": 32,
      "y": 14
    }
  },
  "confidence": "bounded_first_divergence",
  "next_observation": null
}

レビュー可能なレポートを生成します：

node bin/game-debug.mjs report \
  baseline-material-shift \
  candidate-material-shift \
  wrong_material \
  --out /tmp/material-report.html \
  --project /tmp/game-debug-demo

デモは合成です。エンジンやGPUジョブを起動せずに製品ワークフローを検証します。

AIホストを接続する

MCP互換の各ホストには独自の設定画面があります。基盤となるコマンドは次のとおりです：

node /absolute/path/to/game-debug-mcp/bin/game-debug-mcp.mjs \
  --project /absolute/path/to/your-game

一般的なMCP設定の形は次のとおりです：

{
  "mcpServers": {
    "game-debug": {
      "command": "node",
      "args": [
        "/absolute/path/to/game-debug-mcp/bin/game-debug-mcp.mjs",
        "--project",
        "/absolute/path/to/your-game"
      ]
    }
  }
}

サーバー起動時にプロジェクトルートは固定されます。個々のMCP呼び出しでパスやコマンドを指定することはできません。合理的な最初のエージェント指示は次のとおりです：

まずget_project_statusから始めてください。保存されたアーティファクト分析、GPU送信、GPU完了、ピクセル読み戻し、パフォーマンス、人間による視覚承認を、別々の証明軸として扱ってください。因果観測が欠けている場合はplan_captureを使用してください。

MCPを使わないエージェントの場合は、CLIを実行してそのJSON出力を利用してください。測定契約は同じです。

13のMCPツール

13個すべてが、MCPの読み取り専用、非破壊的、冪等、クローズドワールド注釈を持ちます。カタログとそのパリティ表明は、同じランタイム契約から生成されます。

証拠レイアウト

プロジェクトを初期化します：

node /path/to/game-debug-mcp/bin/game-debug.mjs init /path/to/your-game

これにより以下が作成されます：

your-game/
└── .game-debug/
    ├── config.json
    └── evidence/
        └── candidate-town-night/
            ├── manifest.json
            ├── buffers/
            │   ├── beauty.png
            │   ├── coverage.npy
            │   ├── material_id.npy
            │   └── albedo.png
            └── trace.json

取り込みがハッシュとbundle_sealを追加する前の最小マニフェストは次のようになります：

{
  "schema": "org.gamedebug.frame_bundle.v1",
  "bundle_id": "candidate-town-night",
  "suite_id": "lighting-regression",
  "set_id": "candidate",
  "case_id": "town-night",
  "identity": {
    "source_revision": "change-under-test",
    "workload_id": "town-night-script-v2",
    "frame_index": 480,
    "backend": "your-backend",
    "hardware_id": "your-device-profile",
    "width": 1920,
    "height": 1080,
    "render_scale": 1,
    "settings_hash": "quality-profile-v4",
    "camera_hash": "camera-pose-17"
  },
  "buffers": [
    { "semantic": "beauty", "path": "buffers/beauty.png", "color_space": "srgb" },
    { "semantic": "coverage", "path": "buffers/coverage.npy" },
    { "semantic": "material_id", "path": "buffers/material_id.npy" },
    { "semantic": "albedo", "path": "buffers/albedo.png", "color_space": "srgb" }
  ],
  "evidence": {
    "gpu_submission": { "status": "unproven" },
    "gpu_completion": { "status": "unproven" },
    "pixel_readback": { "status": "unproven" },
    "performance": { "status": "unproven" },
    "human_review": { "status": "unproven" }
  }
}

そのマニフェストと関連する相対アーティファクトをプロジェクト外で準備し、CLIを通じて明示的に取り込みます：

node bin/game-debug.mjs ingest /path/to/export/manifest.json --project /path/to/your-game

取り込みは通常のファイルを新しいバンドルにコピーし、すべてのアーティファクトハッシュを計算し、標準マニフェストをシールします。既存のバンドルを置き換えることは拒否されます。

完全な契約については証拠モデルを、機械可読な構造についてはJSONスキーマを参照してください。

標準セマンティックバッファ

組み込みカタログには以下が含まれます：

beauty                 coverage              object_id
material_id            albedo                normal
roughness              metalness             ao
depth                  motion                direct_light
indirect_light         shadow_visibility     history_validity
overdraw               lod                   residency

アダプタは、明示的な種類を持つcustom.<name>を追加できます。安定した意味はエンジンの語彙よりも重要です。単位、座標空間、エンコーディング、有効範囲、アイデンティティ規則を文書化してください。

PNGは、検査可能な色とエンコードされたデバッグビューに役立ちます。NPYは、可視化の損失なしに浮動小数点値と大きなカテゴリIDを保持します。キャプチャされたビューティーイメージと分析用バッファは、同じバンドル内に共存できます。色比較では、両方のアーティファクトに同じ明示的なcolor_spaceが必要です。v0.1は宣言されたエンコード済みサンプル空間を測定し、sRGB、リニア、HDR、カスタム空間の間で暗黙的に変換しません。

最初の分岐診断の仕組み

各症状は順序付けられた因果ワークフローに対応付けられます。wrong_materialの場合、v0.1は以下を確認します：

material_id → residency → albedo → normal → roughness → ao → beauty

利用可能な各観測について、分析器は：

1. 呼び出しで要求されたとおりに、バンドルIDとアーティファクトハッシュを検証します。

2. 明示的な次元とチャネルでバッファをデコードし、その次元を包含するマニフェストIDに結合します。

3. 決定的な統計と不変的な所見を計算します。

4. 同じセマンティック境界でベースラインと候補を比較します。

5. 選択したしきい値を超える最初の座標を記録します。

6. ワークフロー内で最も早い分岐セマンティックを返します。

より前のセマンティックが存在しない場合、結果は、分岐が観測されたが範囲を特定できなかったと示します。ワークフローに分岐した保存アーティファクトがない場合も、そのように示します。欠落したバッファを推測で埋めることは決してありません。

何が違うのか

これはエディタ制御MCPを補完するものであり、置き換えるものではありません。エディタエージェントに変更をさせ、Game Debug MCPに証拠が期待した境界で動いたかどうかをテストさせてください。

また、既存のキャプチャおよび検査ツールを再実装するのではなく、それらと組み合わせるように設計されています。潜在的なアダプタは、RenderDoc、Open Image Debugger、Perfetto、GFXReconstruct、Metal programmatic capture、PIX programmatic capture、または Nsight Graphics CLI capture からのデータを単一の証拠契約に変換できます。これらのアダプタはロードマップ作業であり、v0.1でそのような統合が主張されることはありません。

安全性と信頼

MCPサーバーは：

• 読み取り専用です。

• 1つの起動時プロジェクトルートにバインドされます。

• パスではなく識別子を公開します。

• パストラバーサルとシンボリックリンクのアーティファクトを拒否します。

• ファイルバイト数、デコード済み要素数、デコード済みバイト数、同時比較バイト数、一意のID、バンドル数、プロトコルメッセージサイズ、プレビューサイズに上限を設定します。

• PNG CRC、ペイロード次元、SHA-256ダイジェスト、マニフェストシールを検証します。

• エンジン、実行可能ファイル、デバッガ、エディタ、GPUワークロードを決して起動しません。

整合性は真正性ではありません。バンドルシールは、バイトが現在マニフェストと一致することを証明しますが、誰がそれらを生成したか、GPUがそれらを完了したか、人間がそれらを承認したかを証明するものではありません。SECURITY.md と docs/EVIDENCE_MODEL.md を参照してください。

デフォルトのハードリミットは、アーティファクトあたり64MiB、デコード済みテンソルあたり64MiB、1回の比較におけるデコード済みテンソル合計128MiB、トレースJSONファイルあたり16MiBです。トレース行と識別子の長さには、それぞれ別の構造的制限があります。プロジェクト設定はこれらを引き下げることはできますが、引き上げることはできません。

アーキテクチャ

このパッケージは意図的に3つのレイヤーを持っています：

1. キャプチャアダプタは、エンジン固有の状態を公開された証拠スキーマにエクスポートします。v0.1には同梱されていません。

2. 決定的コアは、読み込み、検証、測定、比較、診断、レポートを行います。エンジンやモデルではなくセマンティクスを認識します。

3. 薄いインターフェースは、MCPとJSON CLIを通じて同じコアを公開します。

{"type": "text"}

その境界線により、アダプタのバグが任意の処理を実行する権限にはならず、モデル固有の統合が診断ロジックを所有することもなくなります。新しい統合を追加する前に、docs/ARCHITECTURE.md と docs/ADAPTERS.md をお読みください。

開発

JSON を生成する CLI コマンドは、単一行出力用に --compact を受け付けます。オプションと位置引数の数は厳密にチェックされるため、しきい値やセット名のスペルを間違えると、暗黙のデフォルトが選択されるのではなく、失敗します。

npm run format:check
npm test
npm run smoke
npm run scan:private
npm run check

npm run smoke は、合成フィクスチャに対してローカルの MCP プロセスのみを起動します。ゲームやグラフィックス API は起動しません。

コントリビューションには、ハッピーパスだけでなく、反証となるフィクスチャを含める必要があります。CONTRIBUTING.md を参照してください。

ロードマップ

次に価値のある作業は、エージェントの散文ではなく、アダプタの幅と、より強力な画像フォーマットへの対応です。

• 文書化されたアダプタ SDK と適合性テストスイート。

• オプションの、個別ライセンスのデコーダ境界を介した OpenEXR。

• 一般的なフレームキャプチャツールとトレースツール用のトランスレータ。

• 標準セマンティクスをエクスポートするためのエンジンテンプレート。

• 明示的な人間の承認を伴うスイート履歴とベースラインのプロモーション。

• 署名されたプロデューサー領収書と、リモート読み取り専用トランスポートの堅牢化。

• 決定的でローカルに再現可能な知覚メトリクス。

リリースゲートについては、docs/ROADMAP.md を参照してください。現在の主張は、v0.1 のテストがカバーする範囲に限定されています。

ライセンス

Apache-2.0。 LICENSE を参照してください。