Game Debug MCP

Dale a tu IA evidencia, no otra captura de pantalla.

Game Debug MCP es un depurador visual y de rendimiento de código abierto e independiente del motor para el desarrollo de juegos asistido por IA. Convierte búferes de fotograma guardados, IDs, trazas y recibos de captura en mediciones deterministas; recorre esas observaciones en orden causal; identifica la divergencia más temprana que realmente puede probar; y le indica al agente cuál es la captura más pequeña que reduciría la incertidumbre restante.

Funciona con cualquier IA mediante un servidor de solo lectura del Model Context Protocol o una CLI JSON. El modelo propone y explica; la herramienta mide y rechaza afirmaciones no respaldadas.

v0.1 es un analizador de evidencia y un planificador de capturas. No controla un editor, no inicia un juego, no ejecuta una carga de trabajo de GPU ni afirma que los píxeles se vean bien. Los adaptadores de captura de motores y depuradores gráficos son la siguiente capa, no una promesa oculta en esta versión.

Por qué existe

Una IA puede mirar una captura de pantalla de belleza y hacer una suposición plausible. Los defectos de renderizado normalmente requieren una pregunta mejor:

• ¿Desapareció la geometría antes del sombreado, o el color final se volvió negro más tarde?

• ¿Cambió la asignación de material, o solo su entrada de albedo?

• ¿Es un artefacto temporal visible por primera vez en vectores de movimiento, profundidad, validez de historial o color final?

• ¿Se mide una mejora de 3 ms en el mismo hardware y carga de trabajo, o se trata simplemente de dos trazas incomparables?

• ¿Se envió un fotograma, se completó, se leyó de vuelta, se revisó, o solo se solicitó?

Game Debug MCP representa esos límites explícitamente. Un diagnóstico es una cadena de mediciones, no un párrafo confiado sin recibo.

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

Qué incluye v0.1

• Un núcleo de análisis Node.js 20+ sin dependencias en tiempo de ejecución.

• Un servidor MCP de solo lectura con 13 herramientas sobre entrada/salida estándar.

• Una CLI JSON para modelos y automatizaciones que no usan MCP.

• Decodificación de PNG con validación CRC de bloques y decodificación de .npy de NumPy.

• Sellos de artefacto SHA-256 exactos más un sello canónico de integridad de manifiesto.

• Análisis de color, escalar, máscara, ID categórico, normal y búfer de vectores.

• Diferencias de píxeles, MAE, RMSE, PSNR solo de color y SSIM por teselas, primera coordenada diferente, límites de diferencia, transiciones de ID, error angular de normales, máscaras y mapas de calor. Los desajustes no finitos invalidan las métricas de error agregadas en lugar de producir un falso cero.

• Flujos de trabajo causales para fotogramas en blanco, geometría faltante, materiales incorrectos, iluminación plana, sombras incorrectas, defectos temporales e investigaciones de rendimiento.

• Distribuciones de tiempo de fotograma, incumplimientos de presupuesto, resúmenes de los principales pases de GPU y comparaciones de trazas con comprobación de identidad.

• Datos de prueba sintéticos para una regresión de entrada de material y geometría faltante.

• Un informe de evidencia HTML autónomo con línea base, candidato, mapa de calor, recorrido causal, mediciones estructuradas y un estado explícito de revisión humana pendiente.

El núcleo se ejecuta localmente y no realiza ninguna solicitud de red.

Inicio rápido

Clona y revisa el código fuente:

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

Genera la demo determinista en un directorio desechable:

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

Pregunta dónde diverge por primera vez el caso de material incorrecto:

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

La parte importante del resultado es:

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

Genera un informe revisable:

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

La demo es sintética. Valida el flujo de trabajo del producto sin iniciar un motor ni un trabajo de GPU.

Conectar un host de IA

Cada host compatible con MCP tiene su propia superficie de configuración. El comando subyacente es:

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

Una forma común de configuración de MCP es:

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

La raíz del proyecto se fija cuando se inicia el servidor. Las llamadas MCP individuales no pueden proporcionar una ruta ni un comando. Una primera instrucción sensata para el agente es:

Comienza con get_project_status. Trata el análisis de artefactos guardados, el envío de GPU, la finalización de GPU, la lectura de píxeles, el rendimiento y la aprobación visual humana como ejes de prueba separados. Usa plan_capture cuando falte una observación causal.

Para un agente sin MCP, ejecuta la CLI y consume su salida JSON. El contrato de medición es el mismo.

Las 13 herramientas de MCP

Las 13 llevan anotaciones MCP de solo lectura, no destructivas, idempotentes y de mundo cerrado. El catálogo y su aserción de paridad se generan a partir del mismo contrato de ejecución.

Estructura de evidencia

Inicializa un proyecto:

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

Esto crea:

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

Un manifiesto mínimo tiene este aspecto antes de que la ingesta añada hashes y 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" }
  }
}

Prepara ese manifiesto y sus artefactos relativos fuera del proyecto y luego ingiérelo explícitamente a través de la CLI:

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

La ingesta copia archivos regulares a un paquete nuevo, calcula el hash de cada artefacto y sella el manifiesto canónico. Se niega a reemplazar un paquete existente.

Consulta el modelo de evidencia para conocer el contrato completo y los esquemas JSON para la estructura legible por máquina.

Búferes semánticos estándar

El catálogo integrado incluye:

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

Los adaptadores pueden añadir custom.<name> con un tipo explícito. El significado estable importa más que el vocabulario del motor: documenta las unidades, el espacio de coordenadas, la codificación, el rango válido y las reglas de identidad.

PNG es útil para color inspeccionable y vistas de depuración codificadas. NPY conserva valores de coma flotante e IDs categóricos grandes sin pérdida de visualización. Una imagen de belleza capturada y un búfer analítico pueden coexistir en el mismo paquete. Las comparaciones de color requieren el mismo color_space explícito en ambos artefactos; v0.1 mide el espacio de muestras codificado declarado y no convierte silenciosamente entre espacios sRGB, lineales, HDR o personalizados.

Cómo funciona el diagnóstico de la primera divergencia

Cada síntoma se asigna a un flujo de trabajo causal ordenado. Para wrong_material, v0.1 comprueba:

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

Para cada observación disponible, el analizador:

1. verifica la identidad del paquete y los hashes de los artefactos según lo requerido por la llamada;

2. decodifica el búfer con dimensiones y canales explícitos y luego une sus dimensiones a la identidad del manifiesto contenedor;

3. calcula estadísticas deterministas y hallazgos invariantes;

4. compara la línea base y el candidato en el mismo límite semántico;

5. registra la primera coordenada más allá del umbral seleccionado; y

6. devuelve la semántica divergente más temprana en el flujo de trabajo.

Si falta una semántica anterior, el resultado indica que se observó la divergencia pero no se acotó. Si el flujo de trabajo no tiene ningún artefacto guardado divergente, lo dice. Nunca rellena un búfer faltante con una suposición.

Qué lo hace diferente

Esto es complementario a los MCP de control de editor, no un reemplazo. Deja que un agente de editor haga el cambio; deja que Game Debug MCP compruebe si la evidencia se movió en el límite esperado.

También está diseñado para componerse con herramientas establecidas de captura e inspección en lugar de reimplementarlas. Los adaptadores potenciales pueden traducir datos de RenderDoc, Open Image Debugger, Perfetto, GFXReconstruct, captura programática de Metal, captura programática de PIX o captura CLI de Nsight Graphics a un único contrato de evidencia. Esos adaptadores son trabajo de hoja de ruta; ninguna integración de ese tipo se reivindica en v0.1.

Seguridad y confianza

El servidor MCP:

• es de solo lectura;

• está vinculado a una única raíz de proyecto de inicio;

• expone identificadores en lugar de rutas;

• rechaza el recorrido de rutas y los artefactos de enlaces simbólicos;

• limita los bytes de archivo, los elementos decodificados, los bytes decodificados, los bytes comparados simultáneamente, los IDs únicos, el número de paquetes, el tamaño de los mensajes del protocolo y el tamaño de la vista previa;

• valida los CRC de PNG, las dimensiones de la carga útil, los resúmenes SHA-256 y los sellos de manifiesto; y

• nunca inicia un motor, ejecutable, depurador, editor ni carga de trabajo de GPU.

La integridad no es autenticidad. Un sello de paquete demuestra que los bytes coinciden ahora con el manifiesto; no demuestra quién los produjo, que una GPU los completó ni que un humano los aprobó. Consulta SECURITY.md y docs/EVIDENCE_MODEL.md.

El límite máximo predeterminado es de 64 MiB por artefacto, 64 MiB por tensor decodificado, 128 MiB de tensores decodificados en una comparación y 16 MiB por archivo JSON de traza. Las filas de traza y las longitudes de identificador tienen límites estructurales separados. La configuración del proyecto puede reducirlos, pero no aumentarlos.

Arquitectura

El paquete tiene deliberadamente tres capas:

1. Adaptadores de captura exportan el estado específico del motor al esquema de evidencia público. Ninguno se incluye en v0.1.

2. El núcleo determinista carga, valida, mide, compara, diagnostica e informa. Conoce semánticas, no motores ni modelos.

3. Interfaces ligeras exponen el mismo núcleo a través de MCP y la CLI JSON.

Ese límite evita que un error del adaptador se convierta en permiso para ejecutar trabajo arbitrario, y evita que una integración específica de un modelo controle la lógica de diagnóstico. Lea docs/ARCHITECTURE.md y docs/ADAPTERS.md antes de añadir una nueva integración.

Desarrollo

Los comandos CLI que producen JSON aceptan --compact para salida en una sola línea. Las opciones y la aridad posicional son estrictas, por lo que un umbral o nombre de conjunto mal escrito falla en lugar de seleccionar silenciosamente un valor predeterminado.

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

npm run smoke inicia únicamente el proceso MCP local contra fixtures sintéticos. No inicia un juego ni una API de gráficos.

Las contribuciones deben incluir un fixture falsificador, no solo un camino feliz. Véase CONTRIBUTING.md.

Hoja de ruta

El siguiente trabajo útil es la amplitud de adaptadores y formatos de imagen más robustos, no más prosa de agentes:

• un SDK de adaptador documentado y una suite de conformidad;

• OpenEXR mediante un límite de descodificador opcional con licencia separada;

• traductores para herramientas comunes de captura de fotogramas y trazas;

• plantillas de motor para exportar semántica estándar;

• historial de suites y promoción de líneas base con aprobación humana explícita;

• recibos de productor firmados y endurecimiento del transporte remoto de solo lectura; y

• métricas perceptivas que sigan siendo deterministas y reproducibles localmente.

Véase docs/ROADMAP.md para los criterios de publicación. Las afirmaciones actuales se limitan a lo que prueban los tests de v0.1.

Licencia

Apache-2.0. Véase LICENSE.