RenderDoc MCP

Ermöglicht KI-Clients, die das Model Context Protocol (MCP) unterstützen, die direkte Analyse von RenderDoc-Capture-Dateien: Draw-/Dispatch-Ereignisse durchsuchen, Pipeline und Shader prüfen sowie Vertex- und Konstantenpufferdaten seitenweise lesen.

Das Repository enthält einen lauffähigen MCP-stdio-Dienst, Sitzungs- und Pfadsicherheitsgrenzen, einen Mock-Backend für Entwicklungstests sowie ein echtes Replay-Brücken-Backend, das mit qrenderdoc 1.44 verbunden ist.

[!IMPORTANT] Aktuell wird empfohlen, das qrenderdoc-Backend für echte Captures zu verwenden; die Backends renderdoc / native sind weiterhin vorbehaltene Implementierungen.

Die echte Brücke besteht aus zwei Prozessen: einem modernen Python-3.11-MCP-Gateway und einer UI-Erweiterung, die im eingebetteten Python 3.6 von qrenderdoc läuft. Beide kommunizieren über ein natives Datei-Warteschlangen-JSON-Protokoll mit zufälligem Token; so wird das in der reduzierten Python-Umgebung von RenderDoc fehlende _socket-Modul umgangen.

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

Vorhandene Fähigkeiten

• MCP-stdio-Dienst mit strukturierten Tool-Antworten.

• Whitelist für .rdc-Pfade, Dateityp-, Größen- und Sitzungsanzahl-Beschränkungen.

• Starten von eigenständigen, in der Whitelist befindlichen .exe-Dateien über RenderDoc-Injektion; Argumente werden als Array übergeben, keine Shell-Ausführung.

• Stabile capture_id, explizite event_id, keine Abhängigkeit von versteckten aktuell ausgewählten Ereignissen.

• Serieller Backend-Zugriff pro Capture, um Grenzen für das Thread-Modell des RenderDoc-ReplayControllers zu schaffen.

• Aktionsfilterung und Cursor-Paginierung.

• inspect_event-Zusammengesetzter Aufruf, um viele feingranulare MCP-Roundtrips für eine einzelne Inspektion zu vermeiden.

• Lesen von Topologie, Viewport/Scissor, Shader, Ressourcenbindungen, Renderziele und Validierungsmeldungen des aktuellen Ereignisses.

• Einheitliche Fehlerstruktur und passives Capture-Summary-Resource.

Erste Tools:

• 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- und Pufferdaten

• get_pipeline_state gibt ohne section eine API-übergreifende allgemeine Momentaufnahme und api_specific_sections zurück; wenn man einen dieser Namen als section erneut aufruft, kann man die vollständigen Top-Level-Zustandsgruppen von D3D11, D3D12, Vulkan oder OpenGL lesen.

• get_shader liest je nach Stage reflection, disassembly, source oder raw. Die letzten drei großen Inhalte werden mit cursor / next_cursor paginiert; source_file_index kann jede eingebettete Quelldatei durchlaufen.

• get_vertex_data expandiert Instanzen und Draw-Vertex in stabile Datensätze und gibt die dekodierten Werte aller Attribute, exaktes raw_hex, tatsächliche Buffer-Offsets und Format-Metadaten zurück; uv_attributes markiert explizit UV / TEXCOORD. Durch kontinuierliches Folgen von next_cursor können alle Instanzen und Vertex abgedeckt werden.

• list_constant_buffers listet jede Shader-Stage, jeden Reflection-Block und jedes Array-Element auf; anschließend liest man mit get_constant_buffer alle dekodierten Variablen dieser Gruppe. Die zugrunde liegenden Rohbytes werden mit raw_offset / next_offset paginiert, sodass auch bei Überschreitung des Einzel-Leselimits keine Daten verloren gehen.

Related MCP server: RenderDoc MCP Server

Umgebung

• Python 3.11+

• MCP Python SDK stabile Linie >=1.27,<2

• RenderDoc/qrenderdoc 1.44 (echtes Brücken-Backend)

SDK v2 befindet sich noch in der Vorabversion, daher ist dieses Projekt vorerst auf v1.x festgelegt, um Framework-Code vor Änderungen an vorläufigen Schnittstellen zu schützen.

Schnellstart (Mock-Backend)

In 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 ist der Protokollkanal, normale Logs sollten nicht nach stdout geschrieben werden.

Mit MCP Inspector:

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

Das Mock-Backend erfordert weiterhin einen real existierenden, in der Whitelist befindlichen .rdc-Pfad, analysiert aber den Dateiinhalt nicht.

Installation der qrenderdoc-Brücke

Angenommen, RenderDoc ist unter C:\Tools\RenderDoc installiert, führen Sie im Projektverzeichnis aus:

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

Das Skript wird:

• Die Erweiterung nach %APPDATA%\qrenderdoc\extensions\renderdoc_mcp_bridge installieren;

• Ein zufälliges Token generieren und in bridge_config.json auf der Erweiterungsseite schreiben;

• Im Projektstammverzeichnis eine .renderdoc-mcp-bridge.json für das Gateway erzeugen.

Öffnen Sie anschließend C:\Tools\RenderDoc\qrenderdoc.exe, gehen Sie zu Tools → Manage Extensions, wählen Sie RenderDoc MCP Bridge, klicken Sie zuerst auf Load, und aktivieren Sie nach Erfolg Always Load. Bei Verwendung des echten Backends muss qrenderdoc geöffnet bleiben; das Warteschlangenverzeichnis ist standardmäßig das im Projekt liegende, von Git ignorierte .renderdoc-mcp-spool.

Für die Entwicklung kann qrenderdoc auch nach dem Öffnen der UI ein Ladeskript automatisch ausführen:

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

Dieser Befehl lädt nur für diese Sitzung; für den täglichen Gebrauch wird empfohlen, Always Load im Erweiterungsmanager zu aktivieren.

Beispielkonfiguration für MCP-Clients

Ersetzen Sie die Pfade durch die tatsächlichen Speicherorte:

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

Auf der grafischen Konfigurationsseite von Codex müssen die Argumente in zwei Zeilen aufgeteilt werden: -m und renderdoc_mcp. Die Umgebungsvariablen-Übergabe bleibt leer; Working directory füllen Sie mit dem Projektstammverzeichnis. Da sich bereits .renderdoc-mcp-bridge.json im Arbeitsverzeichnis befindet, muss das Token nicht manuell in die MCP-Konfiguration eingefügt werden.

Konfigurationsoptionen

Programm von RenderDoc aus starten

Fügen Sie zuerst das Projektstammverzeichnis Ihres eigenen Programms zu RENDERDOC_MCP_ALLOWED_EXECUTABLE_ROOTS hinzu, starten Sie den MCP-Dienst neu und rufen Sie dann auf:

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

Das erfolgreiche Ergebnis enthält die RenderDoc-Target-Control-ident und die Capture-Dateivorlage. Das Programm wurde von RenderDoc injiziert und kann im Programmfenster mit der Standard-Capture-Taste F12 aufgenommen werden. Dieses Tool akzeptiert keine Shell-Befehle oder Umgebungsvariablenänderungen; öffnen Sie hook_into_children, wenn auch Unterprozesse injiziert werden sollen, und api_validation, wenn die API-Validierungsschicht benötigt wird.

Tests

Nach Installation der Entwicklungsabhängigkeiten:

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

Auch ohne Installation von Drittanbieter-Testabhängigkeiten können die Kern-Servicetests ausgeführt werden:

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

Sicherheitsgrenzen

• Es können nur .rdc-Dateien unter RENDERDOC_MCP_ALLOWED_ROOTS geöffnet werden.

• launch_program ist standardmäßig deaktiviert und erlaubt nur das Starten von .exe-Dateien unter RENDERDOC_MCP_ALLOWED_EXECUTABLE_ROOTS.

• Startargumente werden als Array übergeben, nicht über eine Shell; das Gateway erlaubt keine Änderung der Umgebungsvariablen des Zielprogramms über Tools.

• Die native Nachricht zwischen Gateway und qrenderdoc-Erweiterung wird mit einem bei der Installation generierten Zufallstoken authentifiziert.

• Aktions-, Shader-, Vertex- und Pufferdaten sind durch Paginierung oder Einzel-Leselimit begrenzt.

Projektstatus und nächste Schritte

Die Hauptkette der Brücke, Pipeline-State, Shader, Vertex-Eingaben und Konstantenpuffer-Lesen sind implementiert. Als Nächstes können je nach Aufgabe Texture-Export, allgemeines Buffer-Readback, Pixel History und Artefaktverwaltung hinzugefügt werden.

Detaillierte Grenzen finden Sie in der Architekturbeschreibung.

Lizenz

MIT