RenderDoc MCP

RenderDoc のキャプチャファイルを、Model Context Protocol（MCP） に対応する AI クライアントが直接分析できるようにします：Draw/Dispatch イベントの閲覧、パイプラインと Shader の検査、頂点・定数バッファデータのページング読み取り。

リポジトリには、実行可能な MCP stdio サービス、セッションとパスの安全境界、開発テスト用の Mock バックエンド、および qrenderdoc 1.44 に接続する実際の Replay ブリッジバックエンドが含まれています。

[!IMPORTANT] 現在は、実際のキャプチャへの接続に qrenderdoc バックエンドを推奨します。renderdoc / native バックエンドは予約実装のままです。

実際のブリッジは2つのプロセスで構成されます：モダンな 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 パスのホワイトリスト、ファイルタイプ、サイズ、セッション数の制限。

• 専用ホワイトリスト内の .exe を RenderDoc インジェクションで起動。引数は配列で渡され、シェルは実行されません。

• 安定した capture_id と明示的な event_id を使用し、暗黙的な現在選択イベントに依存しません。

• 各キャプチャへのアクセスをバックエンドで直列化し、RenderDoc ReplayController のスレッドモデルに境界を残します。

• Action のフィルタリングとカーソルページング。

• inspect_event を複合的に呼び出すことで、1回の検査のための細かい 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 を読み取ります。後者の3種類の大容量コンテンツは cursor / next_cursor でページングされます。source_file_index で組み込まれている各ソースファイルを辿れます。

• get_vertex_data はインスタンスとドロー頂点を安定したレコードに展開し、すべての 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 です。

開発時には、UI を開いた qrenderdoc で自動ロード用スクリプトを一度実行することもできます：

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 の2行に分割します。環境変数の透過は空のままにしてください。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 とキャプチャファイルテンプレートが含まれます。プログラムは RenderDoc によりインジェクト済みなので、プログラムのウィンドウで既定のキャプチャキー F12 を押すだけで取得できます。このツールはシェルコマンドや環境変数の変更を受け付けません。子プロセス側にもインジェクションが必要な場合にのみ 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 のみ起動を許可します。

• 起動引数は配列で渡されシェルを経由しません。Gateway はツールによるターゲット環境変数の変更も許可しません。

• Gateway と qrenderdoc 拡張機能の間のローカルメモリは、インストール時に生成されたランダムトークンで認証されます。

• Action、Shader、頂点、Buffer データは、ページングまたは単回読み出しの上限のいずれかのある値で保護されます。

プロジェクトの状態と次のステップ

ブリッジの主経路、Pipeline state、Shader、頂点入力、定数バッファの読み取りは実装済みです。今後は、タスク単位で Texture ツール、汎用 Buffer readback、Pixel History、artifact 管理を追加して放課です。

詳細境界は アーキテクチャ説明 を参照してください。

ライセンス

MIT