RenderDoc MCP

Model Context Protocol(MCP)을 지원하는 AI 클라이언트가 RenderDoc 캡처 파일을 직접 분석할 수 있게 합니다: Draw/Dispatch 이벤트 탐색, 파이프라인과 Shader 검사, 정점 및 상수 버퍼 데이터를 페이지네이션으로 읽기.

저장소에는 실행 가능한 MCP stdio 서비스, 세션 및 경로 보안 경계, 개발 테스트용 Mock 백엔드, 그리고 qrenderdoc 1.44에 연결되는 실제 Replay 브리지 백엔드가 포함되어 있습니다.

[!IMPORTANT] 현재는 qrenderdoc 백엔드로 실제 캡처에 연결하는 것을 권장합니다. renderdoc / native 백엔드는 아직 예약 구현입니다.

실제 브리지는 두 프로세스로 구성됩니다: 최신 Python 3.11 MCP Gateway와 qrenderdoc 내장 Python 3.6에서 실행되는 UI 확장입니다. 두 프로세스는 임의 토큰이 포함된 로컬 파일 큐 JSON 프로토콜로 통신하므로 RenderDoc의 축소된 Python에 없는 _socket 모듈에 의존하지 않습니다.

MCP Client  <-- stdio -->  Python 3.11 Gateway
                                  |
                         authenticated JSON spool
                                  |
                           qrenderdoc extension
                                  |
                         RenderDoc ReplayController

제공 기능

• MCP stdio 서비스 및 구조화된 도구 응답.

• .rdc 경로 화이트리스트, 파일 유형, 크기 및 세션 수 제한.

• RenderDoc 인젝션을 통해 별도 화이트리스트 내의 .exe 시작. 인자는 배열로 전달되며 shell을 실행하지 않습니다.

• 안정적인 capture_id, 명시적 event_id를 사용하며 숨겨진 현재 선택 이벤트에 의존하지 않습니다.

• 각 capture는 백엔드에 직렬로 접근하여 RenderDoc ReplayController의 스레드 모델에 경계를 둡니다.

• Action 필터링 및 커서 페이지네이션.

• inspect_event 복합 호출로 한 번의 검사에 과도한 세분화된 MCP 왕복을 방지합니다.

• 현재 이벤트의 토폴로지, viewport/scissor, Shader, 리소스 바인딩, 렌더 타깃 및 검증 메시지를 읽습니다.

• 통일된 오류 구조와 수동형 capture summary Resource.

첫 번째 도구:

• health

• launch_program

• open_capture

• close_capture

• get_capture_summary

• list_actions

• get_event

• inspect_event

• get_pipeline_state

• get_shader

• get_vertex_data

• list_constant_buffers

• get_constant_buffer

Pipeline, Shader 및 Buffer 데이터

• get_pipeline_state는 section을 전달하지 않으면 API 전반의 공통 스냅샷과 api_specific_sections를 반환합니다. 그중 아무 이름이나 section으로 다시 호출하면 D3D11, D3D12, Vulkan 또는 OpenGL의 전체 최상위 상태 그룹을 읽을 수 있습니다.

• get_shader는 stage별로 reflection, disassembly, source 또는 raw를 읽습니다. 뒤의 세 가지 큰 콘텐츠는 cursor / next_cursor로 페이지네이션되며, source_file_index로 포함된 각 소스 파일을 순회할 수 있습니다.

• get_vertex_data는 인스턴스와 draw 정점을 안정적인 레코드로 펼쳐 모든 attribute의 디코딩된 값, 정확한 raw_hex, 실제 buffer offset 및 형식 메타데이터를 반환합니다. uv_attributes는 UV / TEXCOORD를 명확히 표시합니다. next_cursor를 계속 따라가면 모든 인스턴스와 정점을 빠짐없이 읽을 수 있습니다.

• list_constant_buffers는 각 shader stage, reflection block 및 array element를 열거합니다. 그런 다음 get_constant_buffer로 해당 그룹의 모든 디코딩된 변수를 읽습니다. 기본 원시 바이트는 raw_offset / next_offset으로 페이지네이션되므로 단일 읽기 상한을 초과해도 데이터가 손실되지 않습니다.

Related MCP server: RenderDoc MCP Server

환경

• Python 3.11+

• MCP Python SDK 안정 버전 라인 >=1.27,<2

• RenderDoc/qrenderdoc 1.44(실제 브리지 백엔드)

SDK v2는 아직 사전 릴리스 단계에 있으므로 이 프로젝트는 현재 v1.x로 고정하여 프레임워크 코드가 사전 릴리스 인터페이스 변경을 따라가지 않도록 합니다.

빠른 시작(Mock 백엔드)

PowerShell에서:

python -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"
$env:RENDERDOC_MCP_BACKEND = "mock"
$env:RENDERDOC_MCP_ALLOWED_ROOTS = (Get-Location).Path
.venv\Scripts\python -m renderdoc_mcp

stdio는 프로토콜 채널이므로 일반 로그를 stdout에 쓰지 마세요.

MCP Inspector 사용:

.venv\Scripts\mcp dev src\renderdoc_mcp\server.py

Mock 백엔드는 여전히 실제로 존재하고 화이트리스트에 있는 .rdc 경로를 전달해야 하지만 파일 내용은 파싱하지 않습니다.

qrenderdoc 브리지 설치

RenderDoc이 C:\Tools\RenderDoc에 설치되어 있다고 가정하고 프로젝트 디렉터리에서 실행하세요:

powershell -ExecutionPolicy Bypass -File .\scripts\install_qrenderdoc_bridge.ps1 `
  -RenderDocRoot C:\Tools\RenderDoc

스크립트는 다음을 수행합니다:

• 확장을 %APPDATA%\qrenderdoc\extensions\renderdoc_mcp_bridge에 설치합니다.

• 임의 토큰을 생성하여 확장 쪽 bridge_config.json에 기록합니다.

• 프로젝트 루트에 Gateway가 사용하는 .renderdoc-mcp-bridge.json을 생성합니다.

그런 다음 C:\Tools\RenderDoc\qrenderdoc.exe를 열고 Tools → Manage Extensions로 이동하여 RenderDoc MCP Bridge를 선택한 뒤 Load를 클릭하고, 성공하면 Always Load를 체크합니다. 실제 백엔드를 사용할 때는 qrenderdoc이 계속 실행 중이어야 합니다. 큐 디렉터리는 기본적으로 프로젝트 내에서 Git이 무시하는 .renderdoc-mcp-spool입니다.

개발 중에는 qrenderdoc이 UI가 열린 후 로드 스크립트를 자동으로 한 번 실행하도록 할 수도 있습니다:

C:\Tools\RenderDoc\qrenderdoc.exe --ui-python .\scripts\load_qrenderdoc_bridge.py

이 명령은 이번 로드만 담당합니다. 일상적인 사용에서는 확장 관리자에서 Always Load를 체크하는 것이 좋습니다.

MCP 클라이언트 구성 예시

경로를 실제 위치로 교체하세요:

{
  "mcpServers": {
    "renderdoc": {
      "command": "C:\\path\\to\\RenderDoc_MCP\\.venv\\Scripts\\python.exe",
      "args": ["-m", "renderdoc_mcp"],
      "env": {
        "RENDERDOC_MCP_BACKEND": "qrenderdoc",
        "RENDERDOC_MCP_ALLOWED_ROOTS": "C:\\captures",
        "RENDERDOC_MCP_ALLOWED_EXECUTABLE_ROOTS": "C:\\projects\\my-renderer",
        "RENDERDOC_MCP_ARTIFACT_ROOT": "C:\\path\\to\\RenderDoc_MCP\\artifacts",
        "RENDERDOC_MCP_RENDERDOC_ROOT": "C:\\Tools\\RenderDoc"
      },
      "cwd": "C:\\path\\to\\RenderDoc_MCP"
    }
  }
}

Codex의 그래픽 구성 페이지에서 인자는 -m과 renderdoc_mcp 두 줄로 나누어야 합니다. 환경 변수 전달은 비워 두고, Working directory는 프로젝트 루트를 입력합니다. 작업 디렉터리에 이미 .renderdoc-mcp-bridge.json이 있으므로 토큰을 MCP 구성에 수동으로 붙여넣을 필요가 없습니다.

구성 항목

RenderDoc에서 프로그램 시작

먼저 자신의 프로그램이 있는 프로젝트 루트를 RENDERDOC_MCP_ALLOWED_EXECUTABLE_ROOTS에 추가하고 MCP 서비스를 재시작한 다음 호출하세요:

{
  "executable": "C:\\projects\\my-renderer\\bin\\renderer.exe",
  "arguments": ["--scene", "C:\\projects\\my-renderer\\scenes\\demo.json"],
  "working_directory": "C:\\projects\\my-renderer",
  "hook_into_children": false,
  "api_validation": false
}

성공 결과에는 RenderDoc target-control ident와 capture 파일 템플릿이 포함됩니다. 프로그램은 RenderDoc에 의해 이미 인젝션되었으므로 프로그램 창에서 기본 프레임 캡처 단축키 F12를 누르면 됩니다. 이 도구는 shell 명령이나 환경 변수 수정을 허용하지 않습니다. 하위 프로세스도 인젝션해야 하는 경우에만 hook_into_children을 켜고, API 검증 계층이 필요한 경우에만 api_validation을 켭니다.

테스트

개발 의존성을 설치한 후:

.venv\Scripts\python -m pytest
.venv\Scripts\ruff check .

타사 테스트 의존성을 설치하지 않고도 핵심 서비스 테스트를 실행할 수 있습니다:

$env:PYTHONPATH = "src"
python -m unittest discover -s tests -v

보안 경계

• RENDERDOC_MCP_ALLOWED_ROOTS 아래의 .rdc 파일만 열 수 있습니다.

• launch_program은 기본적으로 비활성화되어 있으며 RENDERDOC_MCP_ALLOWED_EXECUTABLE_ROOTS 아래의 .exe만 시작할 수 있습니다.

• 시작 인자는 배열로 전달되며 shell을 거치지 않습니다. Gateway는 도구를 통한 대상 프로그램 환경 변수 수정을 허용하지 않습니다.

• Gateway와 qrenderdoc 확장 간의 로컬 메시지는 설치 시 생성된 임의 토큰으로 인증됩니다.

• Action, Shader, 정점 및 Buffer 데이터는 모두 페이지네이션 또는 단일 읽기 상한의 제약을 받습니다.

프로젝트 상태 및 다음 단계

브리지 메인 경로, Pipeline state, Shader, 정점 입력 및 상수 버퍼 읽기가 이미 구현되었습니다. 이후에는 작업 단위로 Texture 내보내기, 일반 Buffer readback, Pixel History 및 artifact 관리를 계속 추가하는 것이 적합합니다.

자세한 경계는 아키텍처 설명을 참조하세요.

라이선스

MIT