Game Debug MCP

Geben Sie Ihrer KI Beweise, nicht noch einen Screenshot.

Game Debug MCP ist ein offener, engine-neutraler visueller und Performance-Debugger für die KI-gestützte Spieleentwicklung. Es verwandelt gespeicherte Framebuffer, IDs, Traces und Capture-Belege in deterministische Messungen; geht diese Beobachtungen in kausaler Reihenfolge durch; identifiziert die früheste Abweichung, die es tatsächlich beweisen kann; und teilt dem Agenten mit, welche kleinste Aufnahme die verbleibende Unsicherheit reduzieren würde.

Es funktioniert mit jeder KI über entweder einen schreibgeschützten Model Context Protocol-Server oder eine JSON-CLI. Das Modell schlägt vor und erklärt; das Werkzeug misst und lehnt unbelegte Behauptungen ab.

v0.1 ist ein Beweisanalysator und Capture-Planer. Es steuert keinen Editor, startet kein Spiel, führt keine GPU-Workload aus und behauptet nicht, dass Pixel gut aussehen. Engine- und Grafik-Debugger-Capture-Adapter sind die nächste Ebene, kein verstecktes Versprechen in dieser Version.

Warum es das gibt

Eine KI kann auf einen Beauty-Screenshot schauen und eine plausible Vermutung anstellen. Rendering-Fehler erfordern normalerweise eine bessere Frage:

• Ist Geometrie vor der Schattierung verschwunden oder wurde die endgültige Farbe später schwarz?

• Hat sich die Materialzuweisung geändert oder nur ihr Albedo-Eingang?

• Ist ein zeitliches Artefakt zuerst in Bewegungsvektoren, Tiefe, Historie-Gültigkeit oder endgültiger Farbe sichtbar?

• Wird eine 3-ms-Verbesserung auf derselben Hardware und Workload gemessen – oder nur zwei unvergleichbare Traces?

• Wurde ein Frame eingereicht, abgeschlossen, zurückgelesen, überprüft oder nur angefordert?

Game Debug MCP stellt diese Grenzen explizit dar. Eine Diagnose ist eine Kette von Messungen, kein selbstbewusster Absatz ohne Beleg.

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

Was in v0.1 enthalten ist

• Ein Analyse-Kern mit Node.js 20+ ohne Laufzeitabhängigkeiten.

• Ein 13-Tool-, schreibgeschützter MCP-Server über Standard-Eingabe/Ausgabe.

• Eine JSON-CLI für Modelle und Automatisierung, die kein MCP verwenden.

• PNG-Dekodierung mit CRC-Validierung der Chunks und NumPy-.npy-Dekodierung.

• Exakte SHA-256-Artefakt-Siegel plus ein kanonisches Manifest-Integritätssiegel.

• Farb-, Skalar-, Masken-, kategoriale-ID-, Normalen- und Vektorpuffer-Analyse.

• Pixeldifferenzen, MAE, RMSE, farb-only PSNR und gekacheltes SSIM, erste abweichende Koordinate, Differenzgrenzen, ID-Übergänge, normaler Winkelfehler, Masken und Heatmaps. Nicht-finite Abweichungen invalidieren aggregierte Fehlermetriken, anstatt eine falsche Null zu erzeugen.

• Kausale Workflows für leere Frames, fehlende Geometrie, falsche Materialien, flache Beleuchtung, falsche Schatten, zeitliche Defekte und Performance-Untersuchungen.

• Frame-Zeit-Verteilungen, Budget-Überschreitungen, Top-GPU-Pass-Zusammenfassungen und identitätsgeprüfte Trace-Vergleiche.

• Synthetische Fixtures für eine Material-Eingangs-Regression und fehlende Geometrie.

• Ein eigenständiger HTML-Evidenzbericht mit Baseline, Kandidat, Heatmap, kausalem Durchlauf, strukturierten Messungen und einem expliziten Zustand „ausstehende menschliche Überprüfung“.

Der Kern läuft lokal und stellt keine Netzwerkanfragen.

Schnellstart

Klonen und Quellcode prüfen:

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

Deterministische Demo in einem Wegwerf-Verzeichnis erzeugen:

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

Fragen, wo der Fall mit falschem Material zuerst abweicht:

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

Der wichtige Teil des Ergebnisses ist:

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

Einen überprüfbaren Bericht erzeugen:

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

Die Demo ist synthetisch. Sie validiert den Produktworkflow, ohne eine Engine oder einen GPU-Job zu starten.

Ein KI-Host verbinden

Jeder MCP-kompatible Host hat seine eigene Konfigurationsoberfläche. Der zugrunde liegende Befehl ist:

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

Eine übliche MCP-Konfigurationsform ist:

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

Das Projektstammverzeichnis wird beim Serverstart festgelegt. Einzelne MCP-Aufrufe können keinen Pfad oder Befehl liefern. Eine sinnvolle erste Agentenanweisung ist:

Beginnen Sie mit get_project_status. Behandeln Sie gespeicherte Artefaktanalyse, GPU-Einreichung, GPU-Abschluss, Pixel-Rücklesen, Performance und menschliche visuelle Genehmigung als separate Beweisachsen. Verwenden Sie plan_capture, wenn eine kausale Beobachtung fehlt.

Für einen Agenten ohne MCP führen Sie die CLI aus und konsumieren Sie deren JSON-Ausgabe. Der Messvertrag ist derselbe.

Die 13 MCP-Tools

Alle 13 tragen MCP-Anmerkungen für schreibgeschützt, nicht-destruktiv, idempotent und geschlossene Welt. Der Katalog und seine Paritätsbehauptung werden aus demselben Laufzeitvertrag generiert.

Beweis-Layout

Ein Projekt initialisieren:

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

Dies erstellt:

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

Ein minimales Manifest sieht so aus, bevor die Aufnahme Hashes und bundle_seal hinzufügt:

{
  "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" }
  }
}

Bereiten Sie dieses Manifest und seine relativen Artefakte außerhalb des Projekts vor und nehmen Sie es dann explizit über die CLI auf:

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

Die Aufnahme kopiert reguläre Dateien in ein frisches Bundle, berechnet jeden Artefakt-Hash und versiegelt das kanonische Manifest. Sie weigert sich, ein vorhandenes Bundle zu ersetzen.

Siehe das Beweismodell für den vollständigen Vertrag und die JSON-Schemas für maschinenlesbare Struktur.

Standard-Semantische Puffer

Der eingebaute Katalog umfasst:

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

Adapter können custom.<name> mit einer expliziten Art hinzufügen. Stabile Bedeutung ist wichtiger als Engine-Vokabular: Dokumentieren Sie Einheiten, Koordinatenraum, Kodierung, gültigen Bereich und Identitätsregeln.

PNG ist nützlich für überprüfbare Farb- und kodierte Debug-Ansichten. NPY bewahrt Gleitkommawerte und große kategoriale IDs ohne Visualisierungsverlust. Ein aufgenommenes Beauty-Bild und ein analytischer Puffer können im selben Bundle koexistieren. Farbvergleiche erfordern denselben expliziten color_space auf beiden Artefakten; v0.1 misst den deklarierten kodierten Abtastraum und konvertiert nicht stillschweigend zwischen sRGB, linear, HDR oder benutzerdefinierten Räumen.

Wie die Erste-Abweichungs-Diagnose funktioniert

Jedes Symptom ist einem geordneten kausalen Workflow zugeordnet. Für wrong_material prüft v0.1:

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

Für jede verfügbare Beobachtung:

1. verifiziert der Analyzer Bundle-Identität und Artefakt-Hashes, wie vom Aufruf gefordert;

2. dekodiert den Puffer mit expliziten Dimensionen und Kanälen und verbindet dann seine Dimensionen mit der Identität des enthaltenden Manifests;

3. berechnet deterministische Statistiken und invariante Befunde;

4. vergleicht Baseline und Kandidat an derselben semantischen Grenze;

5. zeichnet die erste Koordinate jenseits des gewählten Schwellenwerts auf; und

6. gibt die früheste abweichende Semantik im Workflow zurück.

Wenn eine frühere Semantik fehlt, sagt das Ergebnis, dass die Abweichung beobachtet, aber nicht begrenzt wurde. Wenn der Workflow kein abweichendes gespeichertes Artefakt hat, sagt es das. Es füllt niemals einen fehlenden Puffer mit einer Vermutung.

Was es anders macht

Dies ist komplementär zu Editor-Steuerungs-MCPs, kein Ersatz für sie. Lassen Sie einen Editor-Agenten die Änderung vornehmen; lassen Sie Game Debug MCP testen, ob sich die Beweise an der erwarteten Grenze bewegt haben.

Es ist auch darauf ausgelegt, mit etablierten Capture- und Inspektionswerkzeugen zu komponieren, anstatt sie neu zu implementieren. Potenzielle Adapter können Daten von RenderDoc, Open Image Debugger, Perfetto, GFXReconstruct, Metal programmatic capture, PIX programmatic capture oder Nsight Graphics CLI capture in einen Beweisvertrag übersetzen. Diese Adapter sind Roadmap-Arbeit; keine solche Integration wird in v0.1 beansprucht.

Sicherheit und Vertrauen

Der MCP-Server:

• ist schreibgeschützt;

• ist an ein Startprojekt-Stammverzeichnis gebunden;

• gibt Identifikatoren statt Pfaden aus;

• lehnt Pfad-Traversal und symbolische Link-Artefakte ab;

• begrenzt Dateibytes, dekodierte Elemente, dekodierte Bytes, gleichzeitig verglichene Bytes, eindeutige IDs, Bundle-Anzahl, Protokollnachrichtengröße und Vorschaugröße;

• validiert PNG-CRCs, Nutzlastdimensionen, SHA-256-Digests und Manifest-Siegel; und

• startet niemals eine Engine, ein ausführbares Programm, einen Debugger, einen Editor oder eine GPU-Workload.

Integrität ist nicht Authentizität. Ein Bundle-Siegel beweist, dass die Bytes jetzt mit dem Manifest übereinstimmen; es beweist nicht, wer sie erzeugt hat, dass eine GPU sie abgeschlossen hat oder dass ein Mensch sie genehmigt hat. Siehe SECURITY.md und docs/EVIDENCE_MODEL.md.

Die standardmäßige harte Grenze beträgt 64 MiB pro Artefakt, 64 MiB pro dekodiertem Tensor, 128 MiB dekodierter Tensoren in einem Vergleich und 16 MiB pro Trace-JSON-Datei. Trace-Zeilen und Identifikatorlängen haben separate strukturelle Grenzen. Die Projektkonfiguration kann sie senken, aber nicht erhöhen.

Architektur

Das Paket hat bewusst drei Schichten:

1. Capture-Adapter exportieren enginespezifischen Zustand in das öffentliche Beweisschema. Keine sind in v0.1 enthalten.

2. Der deterministische Kern lädt, validiert, misst, vergleicht, diagnostiziert und berichtet. Er kennt Semantik, nicht Engines oder Modelle.

3. Dünne Schnittstellen exponieren denselben Kern über MCP und die JSON-CLI.

Diese Grenze verhindert, dass ein Adapter-Fehler zur Berechtigung für beliebige Arbeit wird, und hält eine modellspezifische Integration davon ab, die Diagnoselogik zu besitzen. Lies docs/ARCHITECTURE.md und docs/ADAPTERS.md, bevor du eine neue Integration hinzufügst.

Entwicklung

JSON-erzeugende CLI-Befehle akzeptieren --compact für einzeilige Ausgabe. Optionen und Positionsargumente sind strikt, sodass ein falsch geschriebener Schwellenwert oder Set-Name einen Fehler verursacht, anstatt stillschweigend einen Standard auszuwählen.

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

npm run smoke startet nur den lokalen MCP-Prozess mit synthetischen Fixtures. Es startet weder ein Spiel noch eine Grafik-API.

Beiträge sollten ein falsifizierendes Fixture enthalten, nicht nur einen Happy Path. Siehe CONTRIBUTING.md.

Roadmap

Die nächste sinnvolle Arbeit ist Adapter-Breite und stärkere Bildformate, nicht mehr Agenten-Prosa:

• ein dokumentiertes Adapter-SDK und eine Konformitäts-Suite;

• OpenEXR über eine optionale, separat lizenzierte Decoder-Grenze;

• Übersetzer für gängige Frame-Capture- und Trace-Werkzeuge;

• Engine-Vorlagen für den Export standardmäßiger Semantik;

• Suite-Verlauf und Baseline-Förderung mit expliziter menschlicher Freigabe;

• signierte Produzenten-Belege und Härtung des remoten Schreibschutz-Transports; und

• perzeptuelle Metriken, die deterministisch und lokal reproduzierbar bleiben.

Siehe docs/ROADMAP.md für Release-Gates. Aktuelle Behauptungen enden bei dem, was v0.1-Tests abdecken.

Lizenz

Apache-2.0. Siehe LICENSE.