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 分页，因此即使超过单次读取上限也不会丢失数据。

环境

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_MCP_BACKEND`	`mock`	`mock`、`qrenderdoc`（真实 UI 桥接）或 `renderdoc`（预留原生后端）
`RENDERDOC_MCP_ALLOWED_ROOTS`	当前目录	可打开 capture 的目录；多个目录用系统 path separator 分隔
`RENDERDOC_MCP_ALLOWED_EXECUTABLE_ROOTS`	空（禁止启动）	`launch_program` 可启动的 `.exe` 及工作目录根路径；多个目录用系统 path separator 分隔
`RENDERDOC_MCP_ARTIFACT_ROOT`	`./artifacts`	后续生成 PNG、Shader、JSON 等 artifact 的目录
`RENDERDOC_MCP_MAX_SESSIONS`	`2`	最大并发 capture 会话数；qrenderdoc 后端固定收紧为 1
`RENDERDOC_MCP_MAX_CAPTURE_BYTES`	`8589934592`	单个 capture 大小上限
`RENDERDOC_MCP_MAX_PAGE_SIZE`	`100`	Action 单页硬上限
`RENDERDOC_MCP_MAX_BUFFER_READ_BYTES`	`65536`	单页顶点、常量缓冲与 Shader 内容读取硬上限；可用游标续读
`RENDERDOC_MCP_RENDERDOC_ROOT`	配置文件值	RenderDoc 安装目录，例如 `E:\RenderDoc`
`RENDERDOC_MCP_BRIDGE_CONFIG`	`./.renderdoc-mcp-bridge.json`	Gateway 桥接配置文件
`RENDERDOC_MCP_BRIDGE_SPOOL_DIR`	配置文件值	本机桥接请求/响应队列目录
`RENDERDOC_MCP_BRIDGE_TOKEN`	配置文件值	可选环境变量覆盖；通常无需手工配置
`RENDERDOC_MCP_BRIDGE_TIMEOUT_SECONDS`	`120`	单次桥接请求超时

从 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