RenderDoc MCP

让支持 Model Context Protocol（MCP） 的 AI 客户端直接分析 RenderDoc 捕获文件：浏览 Draw/Dispatch 事件、检查管线与 Shader，并分页读取顶点和常量缓冲数据。

仓库包含可运行的 MCP stdio 服务、会话与路径安全边界、用于开发测试的 Mock 后端，以及连接 qrenderdoc 1.44 的真实 Replay 桥接后端。

真实桥接由两个进程组成：现代 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 管理。

详细边界见 架构说明。

License

MIT