# RenderDoc MCP

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
[RenderDoc](https://renderdoc.org) capture analysis to AI clients
(CodeMaker, Claude Desktop, etc.).

> Clone 即用：RenderDoc 1.43 二进制已 vendored 进仓库，无需任何外部依赖。

---

## 工具一览（14 个）

### 离线分析（不需要 RenderDoc GUI 开着）

| 工具 | 功能 |
|---|---|
| `open_capture(path)` | 打开 .rdc 文件 |
| `close_capture()` | 关闭当前 capture |
| `get_capture_info()` | API 类型、vendor、action 数 |
| `list_actions(parent_eid, max_depth)` | 遍历 action 树 |
| `get_action_detail(eid)` | 单个 action 详情 |
| `get_pipeline_state(eid)` | 拿到指定 eid 的全套绑定（VS/HS/DS/GS/PS/CS、SRV/UAV、采样器、RT/Depth） |
| `summarize_render_passes(eid_range, marker_depth, depth, include_mermaid, mermaid_grouping)` | 整帧 render pass 总览，可选返回 Mermaid 流程图（`flat` 或 `subgraph` 嵌套分组） |
| `list_resources(kind, limit)` | 列 texture / buffer / shader |
| `get_resource_info(rid)` | 单个资源详情 |
| `dump_texture(rid, output_path, eid, mip, slice, fmt)` | 导出贴图为 png/jpg/bmp/tga |
| `get_shader(rid, entry_index, target)` | shader 反汇编（DXBC/DXIL/SPIR-V，支持选 ISA target）+ reflection |

### GUI 联动（需要 RenderDoc GUI 开着 + 加载 .rdc）

| 工具 | 速度 | 功能 |
|---|---|---|
| `get_renderdoc_gui_state()` | ~590ms | 全部 GUI 状态（选中 eid + 像素 + RT 信息等） |
| `get_renderdoc_selected_eid()` | ~480ms | 只读用户当前选中的 eid |
| `get_renderdoc_pixel()` | ~210ms | 只读 hover / right-click 的 pixel + UV + 颜色 |

GUI 联动通过 Windows UI Automation 读 RenderDoc 主窗口；
**不能** 读 Texture Viewer 渲染区里的任意像素，只能读 RenderDoc 自己显示出来的内容。

---

## 关键约束

| 项 | 值 |
|---|---|
| **Python** | **必须 3.11.x 64-bit**（`renderdoc.pyd` 绑死 CPython 3.11 ABI，3.10/3.12 都会 ImportError） |
| OS | Windows（`uiautomation` 仅 Windows） |
| Session | 单 capture 单例（open 新自动关旧） |
| MCP 传输 | stdio（stdout 归 JSON-RPC，所有日志走 stderr） |

---

## 快速上手

```bat
:: 1. 创建 Python 3.11 venv
py -3.11 -m venv .venv
.venv\Scripts\activate

:: 2. 安装
pip install -e .

:: 3. 环境自检
python scripts\check_env.py

:: 4. 启动 MCP server（stdio 模式）
python -m renderdoc_mcp.server
:: 或装好后直接：
renderdoc-mcp
```

冒烟测试（需要 .rdc 文件）：

```bat
:: Phase 1：会话 + action 树
python scripts\smoke_phase1.py "path\to\your.rdc"

:: Phase 2：资源 / 贴图导出 / shader 反汇编 / pipeline state
python scripts\smoke_phase2.py "path\to\your.rdc"

:: Phase 4.1：summarize_render_passes（默认 medium 采样 + flat Mermaid）
python scripts\smoke_phase4_1.py "path\to\your.rdc"
:: 也可以指定采样档位 + Mermaid 分组：
python scripts\smoke_phase4_1.py "path\to\your.rdc" medium subgraph

:: 纯 Python 校验 Mermaid subgraph 渲染（无 RenderDoc 依赖，离线跑）
python scripts\check_subgraph.py
```

---

## CodeMaker / Claude Desktop 集成

在 `mcp_settings.json` 中加入：

```json
{
  "mcpServers": {
    "renderdoc": {
      "command": "<repo-root>\\.venv\\Scripts\\renderdoc-mcp.exe"
    }
  }
}
```

> 二进制已 vendored，**不需要** 设置 `RENDERDOC_RELEASE_DIR`。
> 仅当想覆盖到本地新编译的 RenderDoc 时，可在 `env` 节点加
> `"RENDERDOC_RELEASE_DIR": "...\\x64\\Release"`。

---

## 加载顺序（rd_loader）

`renderdoc.pyd` / `renderdoc.dll` 的查找优先级：

1. `setup_renderdoc(release_dir=...)` 显式传入参数
2. `RENDERDOC_RELEASE_DIR` 环境变量（开发态覆盖）
3. `src/renderdoc_mcp/_vendor/`（默认，仓库自带）

---

## 进一步阅读

- **`PLAN.md`** — 项目完整计划、Phase 进度、技术决策、UIA 探测结论、本机环境信息等