Game Debug MCP

AI에게 또 다른 스크린샷이 아니라 증거를 주세요.

Game Debug MCP는 AI 기반 게임 개발을 위한 오픈소스 엔진 중립적 시각·성능 디버거입니다. 저장된 프레임 버퍼, ID, 트레이스, 캡처 영수증을 결정적 측정값으로 변환하고, 그 관측값들을 인과 순서대로 추적하며, 실제로 증명할 수 있는 가장 이른 분기점을 식별하고, 남은 불확실성을 줄이는 데 필요한 최소 캡처가 무엇인지 에이전트에게 알려줍니다.

읽기 전용 Model Context Protocol 서버 또는 JSON CLI를 통해 모든 AI와 함께 작동합니다. 모델이 제안하고 설명하며, 도구가 측정하고 근거 없는 주장을 거부합니다.

v0.1은 증거 분석기이자 캡처 플래너입니다. 에디터를 제어하거나, 게임을 실행하거나, GPU 워크로드를 실행하거나, 픽셀이 보기 좋다고 주장하지 않습니다. 엔진 및 그래픽 디버거 캡처 어댑터는 다음 레이어이며, 이번 릴리스에 숨겨진 약속이 아닙니다.

왜 필요한가

AI는 아름다운 스크린샷을 보고 그럴듯한 추측을 할 수 있습니다. 렌더링 결함은 보통 더 나은 질문이 필요합니다:

• 지오메트리가 셰이딩 전에 사라졌는가, 아니면 최종 색상이 나중에 검게 변했는가?

• 머티리얼 할당이 바뀌었는가, 아니면 알베도 입력만 바뀌었는가?

• 시간적 아티팩트가 모션 벡터, 깊이, 히스토리 유효성, 최종 색상 중 어디에서 먼저 보이는가?

• 3ms 개선이 동일한 하드웨어와 워크로드에서 측정된 것인가, 아니면 단지 비교 불가능한 두 트레이스인가?

• 프레임이 제출되었는가, 완료되었는가, 읽혀졌는가, 검토되었는가, 아니면 단지 요청되었는가?

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 아티팩트 실(seal) 및 표준 매니페스트 무결성 실.

• 색상, 스칼라, 마스크, 범주형 ID, 법선, 벡터 버퍼 분석.

• 픽셀 차이, MAE, RMSE, 색상 전용 PSNR 및 타일 SSIM, 첫 차이 좌표, 차이 경계, ID 전이, 법선 각도 오차, 마스크, 히트맵. 비유한 값 불일치는 잘못된 0을 생성하는 대신 집계 오류 메트릭을 무효화합니다.

• 빈 프레임, 누락된 지오메트리, 잘못된 머티리얼, 평평한 조명, 잘못된 그림자, 시간적 결함, 성능 조사를 위한 인과 워크플로우.

• 프레임 시간 분포, 예산 위반, 상위 GPU 패스 요약, ID 기반 트레이스 비교.

• 머티리얼 입력 회귀 및 누락된 지오메트리에 대한 합성 픽스처.

• 기준선, 후보, 히트맵, 인과 추적, 구조화된 측정값, 명시적 대기 중인 인간 검토 상태를 포함한 자체 포함 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>을 추가할 수 있습니다. 안정적인 의미가 엔진 어휘보다 중요합니다: 단위, 좌표 공간, 인코딩, 유효 범위, ID 규칙을 문서화하세요.

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 서버는:

• 읽기 전용입니다;

• 하나의 시작 프로젝트 루트에 바인딩됩니다;

• 경로 대신 식별자를 노출합니다;

• 경로 탐색 및 심볼릭 링크 아티팩트를 거부합니다;

• 파일 바이트, 디코딩된 요소, 디코딩된 바이트, 동시 비교 바이트, 고유 ID, 번들 수, 프로토콜 메시지 크기, 미리보기 크기를 제한합니다;

• PNG CRC, 페이로드 차원, SHA-256 다이제스트, 매니페스트 실을 검증합니다;

• 엔진, 실행 파일, 디버거, 에디터 또는 GPU 워크로드를 시작하지 않습니다.

무결성은 진정성이 아닙니다. 번들 실은 바이트가 지금 매니페스트와 일치한다는 것을 증명합니다; 누가 생성했는지, GPU가 완료했는지, 인간이 승인했는지는 증명하지 않습니다. SECURITY.md 및 docs/EVIDENCE_MODEL.md를 참조하세요.

기본 하드 엔벨로프는 아티팩트당 64MiB, 디코딩된 텐서당 64MiB, 한 비교에서 디코딩된 텐서 128MiB, 트레이스 JSON 파일당 16MiB입니다. 트레이스 행과 식별자 길이에는 별도의 구조적 제한이 있습니다. 프로젝트 구성은 낮출 수 있지만 높일 수 없습니다.

아키텍처

패키지는 의도적으로 세 개의 레이어를 가집니다:

1. 캡처 어댑터는 엔진별 상태를 공개 증거 스키마로 내보냅니다. v0.1에는 없습니다.

2. 결정적 코어는 로드, 검증, 측정, 비교, 진단, 보고를 수행합니다. 의미론을 알지만 엔진이나 모델은 모릅니다.

3. 얇은 인터페이스는 MCP와 JSON CLI를 통해 동일한 코어를 노출합니다.

개발

JSON을 생성하는 CLI 명령어는 단일 라인 출력을 위해 --compact를 허용합니다. 옵션과 위치 인자는 엄격하게 검증되므로, 철자가 틀린 임계값이나 세트 이름은 기본값을 조용히 선택하는 대신 실패합니다.

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

npm run smoke는 합성 픽스처에 대해서만 로컬 MCP 프로세스를 시작합니다. 게임이나 그래픽 API를 시작하지 않습니다.

기여에는 행복한 경로( happy path)만이 아니라 반증 픽스처(falsifying fixture)가 포함되어야 합니다. CONTRIBUTING.md를 참조하세요.

로드맵

다음으로 유용한 작업은 어댑터 범위와 더 강력한 이미지 형식이며, 더 많은 에이전트 산문(prose)이 아닙니다:

• 문서화된 어댑터 SDK 및 적합성 테스트 스위트;

• 선택적이고 별도 라이선스가 적용되는 디코더 경계를 통한 OpenEXR 지원;

• 일반적인 프레임 캡처 및 트레이스 도구를 위한 변환기;

• 표준 의미론을 내보내기 위한 엔진 템플릿;

• 명시적인 인간 승인을 통한 스위트 히스토리 및 기준선 승격;

• 서명된 프로듀서 영수증 및 원격 읽기 전용 전송 강화; 그리고

• 결정적이고 로컬에서 재현 가능한 지각 메트릭.

릴리스 게이트에 대해서는 docs/ROADMAP.md를 참조하세요. 현재 주장은 v0.1 테스트가 검증하는 범위까지만 유효합니다.

라이선스

Apache-2.0. LICENSE를 참조하세요.