Metadata-Version: 2.4
Name: renderdoc-mcp
Version: 0.2.7
Summary: MCP server for RenderDoc graphics debugger - enables AI-assisted frame capture analysis
Requires-Python: ==3.13.*
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]>=1.0.0

<h1 align="center">renderdoc-mcp</h1>

<p align="center">
  <img src="docs/fmk.png" alt="renderdoc-mcp 架构图" width="800"/>
</p>

[RenderDoc](https://renderdoc.org/) 的 MCP 服务器 —— 让 AI 助手直接分析 GPU 帧捕获文件（`.rdc`），用于图形调试和性能分析。

> **平台**：Windows x64、Linux x64（含 WSL2）。
> **数据本地处理**：`.rdc` 文件不离开本机，分析在本地 GPU 上回放完成。

## 前置条件

- **uv** — [docs.astral.sh/uv/getting-started/installation](https://docs.astral.sh/uv/getting-started/installation/)

`uvx` 首次运行时会自动下载 Python 3.13 并创建隔离环境，无需手动安装 Python。

```bash
uv --version       # uv 0.x.x
```

## 配置

将以下内容添加到 MCP 客户端配置文件中，`uvx` 会自动下载并运行服务器：

```json
{
  "command": "uvx",
  "args": ["--python", "3.13", "renderdoc-mcp"]
}
```

> ⚠️ **`--python 3.13` 必须带上。** 捆绑的 RenderDoc 模块仅编译给 Python 3.13，省略该参数会导致运行时 ABI 不匹配或导入失败。

**VS Code**（`mcp.json`）：
```json
{
  "servers": {
    "renderdoc": {
      "command": "uvx",
      "args": ["--python", "3.13", "renderdoc-mcp"]
    }
  }
}
```

**Claude Desktop**（`claude_desktop_config.json`）：
```json
{
  "mcpServers": {
    "renderdoc": {
      "command": "uvx",
      "args": ["--python", "3.13", "renderdoc-mcp"]
    }
  }
}
```

## 使用方式

直接与 AI 助手对话：

> "打开 frame.rdc，看看这一帧的渲染流程"

> "找到渲染角色模型的 draw call，检查它的管线状态"

> "为什么阴影贴图是黑的？检查深度 pass"

> "分析性能，有没有冗余的 draw call 或状态切换？"

> "这个材质反射不对，对比原始物体和反射 pass 的差异"

## 能做什么（按场景）

| 场景 | 示例 |
|------|------|
| **打开捕获** | 打开 `.rdc` 文件，获取帧概览、API 类型、分辨率 |
| **遍历 draw call** | 列出所有 draw call、搜索名称、导航到指定事件 |
| **检查管线状态** | 查看当前 draw call 的 shader、blend、depth、cull、顶点输入 |
| **分析 shader** | 反编译 shader、查看反射信息、读取常量缓冲区 |
| **查看资源** | 枚举纹理/buffer、查看纹理像素值、读取 buffer 原始数据 |
| **导出数据** | 保存纹理为图片、导出 mesh 为 OBJ、导出 draw call 绑定的所有纹理 |
| **排查渲染问题** | 像素历史追溯、逐像素 shader 调试、draw call 对比 |
| **性能分析** | render pass 分析、overdraw、带宽估算、状态切换统计、pass 耗时 |
| **自动诊断** | 检测负值/NaN/Inf、精度问题、反射不匹配、移动端 GPU 风险 |

## 常见问题

**`ImportError: DLL load failed`** — 检查杀毒软件是否拦截了捆绑的 DLL。

**服务器无法启动** — 查看 MCP 客户端日志；检查 uv 输出中的 Python 下载/安装信息。首次启动时 uv 会自动下载 Python 3.13，可能需要等待几分钟。

## 许可证

MIT
