RenderDoc MCP

Permite que los clientes de IA que admiten el Model Context Protocol (MCP) analicen directamente archivos de captura de RenderDoc: explorar eventos Draw/Dispatch, inspeccionar el pipeline y los Shaders, y leer datos de vértices y buffers de constantes paginados.

El repositorio incluye un servicio MCP stdio ejecutable, límites de seguridad de sesión y ruta, un backend Mock para pruebas de desarrollo y un backend de puente Replay real que se conecta a qrenderdoc 1.44.

[!IMPORTANT] Actualmente se recomienda usar el backend qrenderdoc para conectarse a capturas reales; los backends renderdoc / native siguen siendo implementaciones reservadas.

El puente real consta de dos procesos: un Gateway MCP moderno en Python 3.11 y una extensión de UI que se ejecuta en el Python 3.6 integrado de qrenderdoc. Ambos se comunican mediante un protocolo JSON de cola de archivos local con token aleatorio; esto evita depender del módulo _socket que falta en el Python reducido de RenderDoc.

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

Capacidades existentes

• Servicio MCP stdio y respuestas de herramientas estructuradas.

• Lista blanca de rutas .rdc, restricciones de tipo de archivo, tamaño y número de sesiones.

• Inicia .exe dentro de una lista blanca independiente mediante inyección de RenderDoc; los argumentos se pasan como array, sin ejecutar shell.

• capture_id estable, event_id explícito, sin depender del evento seleccionado actual oculto.

• Acceso serial al backend por cada captura, dejando margen para el modelo de hilos de RenderDoc ReplayController.

• Filtrado de acciones y paginación con cursor.

• Llamada compuesta inspect_event para evitar muchos viajes MCP de grano fino para una sola inspección.

• Lee topología, viewport/scissor, Shader, enlaces de recursos, objetivos de renderizado y mensajes de validación del evento actual.

• Estructura de error unificada y recurso de resumen de captura pasivo.

Primeras herramientas:

• 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

Datos de Pipeline, Shader y Buffer

• get_pipeline_state sin section devuelve una instantánea genérica entre APIs y api_specific_sections; al llamar de nuevo con cualquiera de esos nombres como section, se pueden leer los grupos de estado de nivel superior completos de D3D11, D3D12, Vulkan u OpenGL.

• get_shader lee reflection, disassembly, source o raw según la etapa. Los tres últimos tipos de contenido grande se paginan con cursor / next_cursor; source_file_index permite recorrer cada archivo de código fuente incrustado.

• get_vertex_data expande instancias y vértices de draw en registros estables, devolviendo valores decodificados de todos los atributos, raw_hex exacto, offset real del buffer y metadatos de formato; uv_attributes marca explícitamente UV / TEXCOORD. Siguiendo next_cursor se cubren todas las instancias y vértices.

• list_constant_buffers enumera cada etapa de shader, bloque de reflexión y elemento de array; luego se usa get_constant_buffer para leer todas las variables decodificadas de ese grupo. Los bytes brutos subyacentes se paginan con raw_offset / next_offset, por lo que no se pierden datos incluso si se supera el límite de lectura única.

Related MCP server: RenderDoc MCP Server

Entorno

• Python 3.11+

• Línea estable del SDK de Python MCP >=1.27,<2

• RenderDoc/qrenderdoc 1.44 (backend de puente real)

El SDK v2 aún está en fase de prelanzamiento, por lo que este proyecto se fija temporalmente en v1.x para evitar que el código del framework cambie con interfaces de prelanzamiento.

Inicio rápido (backend Mock)

En 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 es el canal de protocolo; no escribas registros normales en stdout.

Usando MCP Inspector:

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

El backend Mock aún requiere una ruta .rdc real y en la lista blanca, pero no analiza el contenido del archivo.

Instalación del puente qrenderdoc

Suponiendo que RenderDoc está instalado en C:\Tools\RenderDoc, ejecuta en el directorio del proyecto:

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

El script:

• Instala la extensión en %APPDATA%\qrenderdoc\extensions\renderdoc_mcp_bridge;

• Genera un token aleatorio y lo escribe en bridge_config.json del lado de la extensión;

• Genera el .renderdoc-mcp-bridge.json usado por el Gateway en la raíz del proyecto.

Luego abre C:\Tools\RenderDoc\qrenderdoc.exe, ve a Tools → Manage Extensions, selecciona RenderDoc MCP Bridge, haz clic en Load primero y, si tiene éxito, marca Always Load. Al usar el backend real, qrenderdoc debe permanecer en ejecución; el directorio de cola por defecto es .renderdoc-mcp-spool, ignorado por Git dentro del proyecto.

Durante el desarrollo, también puedes hacer que qrenderdoc ejecute automáticamente un script de carga después de abrir la UI:

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

Este comando solo se encarga de la carga actual; para uso diario se recomienda marcar Always Load en el administrador de extensiones.

Ejemplo de configuración de cliente MCP

Reemplaza las rutas con las ubicaciones reales:

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

En la página de configuración gráfica de Codex, los argumentos deben dividirse en dos líneas: -m y renderdoc_mcp. Deja en blanco la transferencia de variables de entorno; en Working directory pon la raíz del proyecto. Como el directorio de trabajo ya contiene .renderdoc-mcp-bridge.json, no es necesario pegar manualmente el token en la configuración de MCP.

Configuración

Iniciar un programa desde RenderDoc

Primero agrega la raíz del proyecto de tu programa a RENDERDOC_MCP_ALLOWED_EXECUTABLE_ROOTS, reinicia el servicio MCP y luego llama:

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

El resultado exitoso incluye el ident de control de destino de RenderDoc y la plantilla de archivo de captura. El programa ya está inyectado por RenderDoc; puedes presionar la tecla de captura predeterminada F12 en la ventana del programa. Esta herramienta no acepta comandos de shell ni modificaciones de variables de entorno; abre hook_into_children solo si necesitas que los subprocesos también se inyecten, y api_validation solo si necesitas la capa de validación de API.

Pruebas

Después de instalar las dependencias de desarrollo:

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

También puedes ejecutar las pruebas del servicio principal sin instalar dependencias de prueba de terceros:

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

Límites de seguridad

• Solo se pueden abrir archivos .rdc dentro de RENDERDOC_MCP_ALLOWED_ROOTS.

• launch_program está deshabilitado por defecto; solo permite iniciar .exe dentro de RENDERDOC_MCP_ALLOWED_EXECUTABLE_ROOTS.

• Los argumentos de inicio se pasan como array, sin pasar por shell; el Gateway no permite modificar las variables de entorno del programa objetivo a través de herramientas.

• Los mensajes locales entre el Gateway y la extensión de qrenderdoc se autentican con un token aleatorio generado en la instalación.

• Los datos de Action, Shader, vértices y Buffer están sujetos a paginación o límites de lectura única.

Estado del proyecto y próximos pasos

El enlace principal del puente, el estado del pipeline, el Shader, la entrada de vértices y la lectura de buffers de constantes ya están implementados. A continuación, es adecuado continuar agregando exportación de texturas, readback de buffers genéricos, Pixel History y gestión de artefactos por tareas.

Para más detalles, consulta Descripción de la arquitectura.

Licencia

MIT