Game Debug MCP

Дайте вашему ИИ доказательства, а не очередной скриншот.

Game Debug MCP — это открытый, не привязанный к конкретному движку отладчик визуальных эффектов и производительности для разработки игр с участием ИИ. Он превращает сохранённые кадровые буферы, идентификаторы, трассы и подтверждения захвата в детерминированные измерения; проходит по этим наблюдениям в причинно-следственном порядке; определяет самое раннее расхождение, которое может реально доказать; и сообщает агенту, какой минимальный захват уменьшит оставшуюся неопределённость.

Он работает с любым ИИ через доступный только для чтения Model Context Protocol сервер или JSON CLI. Модель предлагает и объясняет; инструмент измеряет и отклоняет неподтверждённые утверждения.

v0.1 — это анализатор доказательств и планировщик захвата. Он не управляет редактором, не запускает игру, не выполняет GPU-нагрузку и не утверждает, что пиксели выглядят хорошо. Адаптеры захвата для движков и графических отладчиков — это следующий слой, а не скрытое обещание в этом релизе.

Почему это существует

ИИ может посмотреть на красивый скриншот и сделать правдоподобное предположение. Дефекты рендеринга обычно требуют более точного вопроса:

• Исчезла ли геометрия до затенения, или итоговый цвет стал чёрным позже?

• Изменилось ли назначение материала или только его альбедо-вход?

• Впервые ли временной артефакт виден в векторах движения, глубине, валидности истории или итоговом цвете?

• Улучшение на 3 мс измерено на том же оборудовании и под той же нагрузкой — или это просто две несопоставимые трассы?

• Был ли кадр отправлен, завершён, считан обратно, просмотрен или только запрошен?

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+ без зависимостей времени выполнения.

• MCP-сервер только для чтения с 13 инструментами, работающий через стандартный ввод/вывод.

• JSON CLI для моделей и автоматизации, не использующих MCP.

• Декодирование PNG с проверкой CRC чанков и декодирование NumPy .npy.

• Точные SHA-256-печати артефактов плюс каноническая печать целостности манифеста.

• Анализ цветовых, скалярных, масочных, категориально-идентификационных, нормальных и векторных буферов.

• Попиксельные различия, 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-задачи.

Подключение ИИ-хоста

У каждого 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, linear, HDR или пользовательскими пространствами.

Как работает диагностика первого расхождения

Каждый симптом сопоставляется с упорядоченным причинно-следственным рабочим процессом. Для wrong_material v0.1 проверяет:

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

Для каждого доступного наблюдения анализатор:

1. проверяет идентичность бандла и хеши артефактов, как требует вызов;

2. декодирует буфер с явными размерами и каналами, затем связывает его размеры с идентичностью содержащего манифеста;

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-сервер:

• только для чтения;

• привязан к одному корню проекта при запуске;

• предоставляет идентификаторы, а не пути;

• отклоняет артефакты с обходом пути и символическими ссылками;

• ограничивает байты файла, декодированные элементы, декодированные байты, одновременно сравниваемые байты, уникальные ID, количество бандлов, размер сообщения протокола и размер предпросмотра;

• проверяет CRC PNG, размеры полезной нагрузки, SHA-256-дайджесты и печати манифеста; и

• никогда не запускает движок, исполняемый файл, отладчик, редактор или GPU-нагрузку.

Целостность — это не подлинность. Печать бандла доказывает, что байты в данный момент соответствуют манифесту; она не доказывает, кто их создал, что GPU завершил их или что человек их одобрил. См. SECURITY.md и docs/EVIDENCE_MODEL.md.

Жёсткие пределы по умолчанию: 64 МиБ на артефакт, 64 МиБ на декодированный тензор, 128 МиБ декодированных тензоров в одном сравнении и 16 МиБ на JSON-файл трассы. Строки трасс и длины идентификаторов имеют отдельные структурные ограничения. Конфигурация проекта может понизить, но не повысить их.

Архитектура

Пакет намеренно состоит из трёх уровней:

1. Адаптеры захвата экспортируют состояние, специфичное для движка, в публичную схему доказательств. В v0.1 они не поставляются.

2. Детерминированное ядро загружает, проверяет, измеряет, сравнивает, диагностирует и формирует отчёты. Оно знает семантику, а не движки или модели.

3. Тонкие интерфейсы предоставляют то же ядро через MCP и JSON CLI.

Эта граница не позволяет багу адаптера превратиться в разрешение на выполнение произвольной работы и не позволяет интеграции, специфичной для конкретной модели, владеть логикой диагностики. Прежде чем добавлять новую интеграцию, прочитайте docs/ARCHITECTURE.md и docs/ADAPTERS.md.

Разработка

CLI-команды, выводящие JSON, принимают --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.