# RenderDoc MCP

让支持 [Model Context Protocol（MCP）](https://modelcontextprotocol.io/) 的 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` 模块。

```text
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 中：

```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：

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

Mock 后端仍要求传入一个真实存在、位于白名单中的 `.rdc` 路径，但不会解析文件内容。

## 安装 qrenderdoc 桥接

假设 RenderDoc 安装在 `C:\Tools\RenderDoc`，在项目目录运行：

```powershell
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 打开后自动执行一次加载脚本：

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

这个命令只负责本次加载；日常使用仍建议在扩展管理器中勾选 **Always Load**。

## MCP 客户端配置示例

把路径替换为实际位置：

```json
{
  "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
服务，然后调用：

```json
{
  "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`。

## 测试

安装开发依赖后：

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

不安装第三方测试依赖也可以运行核心服务测试：

```powershell
$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 管理。

详细边界见 [架构说明](docs/architecture.md)。

## License

[MIT](LICENSE)