RenderDoc MCP Fusion

RenderDoc MCP Fusion 为 MCP 客户端提供 RDC 抓帧分析工具。多个客户端可以共用一个本地后台服务。

0.1.0 提供 44 个 MCP 工具。它可以查询绘制、着色器、资源和像素，读取 GPU 性能计数器，并导出绘制包及 Unity 导入包。可用能力取决于回放后端、抓帧内容和本机环境。

运行要求

本文使用以下术语：

• 客户端：发起 MCP 请求的应用，例如 Codex 或 DeepSeek Harness。

• 连接器：由客户端启动的 stdio 进程。它向共享服务转发请求。

• 共享服务（Hub）：执行 MCP 请求和管理回放资源的后台进程。

• GUI 模式：使用 RenderDoc 窗口回放抓帧。

• headless 模式：使用无窗口引擎回放抓帧。

• 捕获句柄：open_capture 返回的 capture_id。后续请求用它指定抓帧。

Related MCP server: RenderDoc MCP

安装

1. 安装 Python。

2. 在完整项目目录中执行：

   python -m pip install .

3. 如需使用 GUI 模式，安装 RenderDoc。

安装包包含连接器、GUI 桥接和 headless 运行文件。普通安装不需要手动创建 .venv，也不需要设置 RENDERDOC_FUSION_ROOT 或 PYTHONPATH。安装后可以从任意目录启动，原源码目录可以移走。

配置客户端

客户端必须支持本地 stdio MCP。安装程序不会自动修改客户端配置。

在安装时使用的 Python 环境中，生成服务配置：

python -m renderdoc_mcp_fusion --print-config

如果 Python 的 Scripts 目录已加入 PATH，也可以执行：

rdc-mcp-fusion --print-config

追加 --output mcp-config.local.json 可保存配置。命令只创建新文件，不覆盖已有文件。

生成的配置使用当前安装的绝对路径。下面的路径仅作示例。请使用命令实际生成的路径。

{
  "mcpServers": {
    "rdc-fusion": {
      "command": "C:\\Python313\\Scripts\\rdc-mcp-fusion.exe",
      "args": []
    }
  }
}

如需通过 CC Switch 管理配置：

1. 在 MCP 面板新增自定义服务。

2. 将服务器 ID 设为 rdc-fusion。

3. 将传输类型设为 stdio。

4. 将 mcpServers.rdc-fusion 内的对象填入单个服务配置。该对象包含 command 和 args。如需指定 RenderDoc 路径等选项，添加 env。

5. 保存配置，并启用目标客户端的同步开关。

6. 在目标客户端重新连接 MCP，或重启客户端。

外层 mcpServers 用于完整配置文件。不要将外层对象填入单个服务配置。客户端使用 stdio 连接；不要在配置中填写共享服务内部的 HTTP 地址。

CC Switch 负责转换客户端配置格式。可用的同步目标取决于所安装的 CC Switch 版本。具体操作见 CC Switch MCP 管理文档。

在源码目录运行 python scripts/check_install.py，可检查两个独立 MCP 客户端是否共用一个服务。此检查不打开 RDC，也不验证所有客户端应用。

启动与共享

连接器收到 MCP 初始化请求后，自动启动或连接本机的共享服务。多个连接器同时启动时，进程锁可防止重复创建服务。

每个连接都有自己的连接器。MCP 请求和 RDC 路由由同一个共享服务处理。连接器通过带随机令牌的 Streamable HTTP 访问服务。服务只监听 127.0.0.1。请勿将此端口暴露到网络。

Windows 通过同一用户、同一会话中的 Explorer 启动共享服务。此方式用于将服务与连接器的进程回收范围分开。启动需要可用的交互桌面。桌面不可用或用户身份不一致时，启动会报错。

服务不接收聊天历史。请求结果只返回给发起请求的连接。每个连接必须取得自己的捕获句柄。

不同 RDC 使用不同回放后端。同一 RDC 在相同模式下可以共用回放资源。共用资源上的操作按顺序执行。多个连接使用同一个 GUI 时，事件选择状态也会共享。连接之间的消息隔离不提供操作系统级沙箱。

打开与分析抓帧

如果不知道文件路径，先调用 list_captures。它只列出指定目录中的 RDC 文件，不打开回放：

{"directory":"C:/Captures","offset":0,"limit":20}

确定文件后，按以下步骤打开和分析：

1. 调用 open_capture，并指定 RDC 的绝对路径：

   {"capture_path":"C:/Captures/scene.rdc","backend":"auto"}

2. 保存返回的 capture_id。

3. 在后续请求中传入这个句柄。例如，调用 list_draws：

   {"capture_id":"从 open_capture 返回值复制","limit":20}

4. 查询管线、着色器、绑定或导出数据时，按工具要求传入实际返回的 event_id。请求不依赖 GUI 当前选中的事件。

自动启动 GUI 需要启用 RENDERDOC_FUSION_GUI_AUTOSTART，且配置的 qrenderdoc.exe 路径必须存在。默认路径为 %ProgramFiles%\RenderDoc\qrenderdoc.exe。其他安装路径需用 RENDERDOC_FUSION_RENDERDOC 指定。

GUI 启动或查询失败时会返回错误，不会自动切换到 headless。指定 window_id 时，目标窗口必须已经加载桥接和目标 RDC。连接器不会替换其他窗口正在查看的文件。

每个连接都必须调用 open_capture。不要复制其他连接的句柄。出现以下情况后，请重新打开抓帧并取得新句柄：

• 客户端建立了新连接。

• 共享服务已重启。

• RDC 文件内容已变化。

• GUI 已切换抓帧，或对应窗口已关闭。

• 回放资源已被回收。

• 原生回放发生致命错误，工具返回 SESSION_LOST。

生命周期

共享服务

共享服务根据连接器的登记和心跳决定何时退出。

连接器首次请求服务时登记独立身份。之后每 5 秒发送一次心跳，为登记续期。连接空闲时也发送心跳。

客户端关闭 stdio 输入时，连接器注销并退出。连接器被强制结束时，服务等待心跳超时，再开始退出倒计时。

因此，最后一个连接器正常注销后，服务约 60 秒后开始关闭。若连接器被强制结束，服务在最后一次心跳后约 90 秒开始关闭。关闭时，HTTP 请求最多还可等待 30 秒；资源清理也需要时间。上述时间不是进程消失的硬性期限。

关闭聊天是否结束连接器，由客户端决定。桌面窗口是否仍打开不参与判定。心跳只由存活的连接器发送；连接器退出后，心跳会停止。

手动停止共享服务后，心跳不会重新启动它。下一次 MCP 请求才会启动新服务。

调用 get_backend_status 可查看生命周期状态：

回放资源

headless 回放的空闲回收与共享服务的退出倒计时分别工作。

• 默认模式为 headless_mode="persistent"。连续 300 秒没有实际操作后，服务释放回放引擎及对应句柄。

• headless_mode="on_demand" 在每次实际调用后释放回放引擎。下一次查询会重新加载。捕获句柄仍受 300 秒空闲期限限制。

• 状态查询和目录查询不延长回放资源的空闲期限。

• 正在执行或排队的操作不受空闲回收影响。

• release_capture 只释放本连接的句柄。最后一个 headless 句柄释放后，服务可停止对应回放。

• 关闭 RenderDoc 窗口会使对应 GUI 句柄失效，不影响其他 RDC。

关闭连接器或共享服务不会关闭已有的 RenderDoc 窗口。请在不再需要窗口时手动关闭它。

查看进程与更新程序

查看进程

共享服务在 Windows 任务管理器中使用以下名称：

使用新配置启动时，连接器启动文件名为 rdc-mcp-fusion.exe，其子进程可能显示为 Python。旧的 renderdoc-mcp-fusion 命令保留兼容；要使用新名称，请重新生成并更新客户端配置。RenderDoc 窗口对应 qrenderdoc.exe。请用 get_backend_status 返回的 service_pid 核对共享服务，避免把连接器退出当成共享服务退出。

共享服务使用基础 Python 的 pythonw.exe 和运行库生成专用启动文件。缓存默认位于 %LOCALAPPDATA%\RenderDocMCPFusion\shared-service\named-runtime。此过程不修改原 Python 安装。

专用启动文件的描述为 RDC MCP。Python 版本和版权信息保留。基础运行库变化后，程序会生成新缓存。RENDERDOC_FUSION_SERVICE_DIR 可更改服务状态和缓存目录。安装依赖中的 pywin32 提供 Windows 桌面启动和文件描述更新支持。

更新程序

修改源码不会更新已运行的连接器或共享服务。 普通安装还需要重新安装软件包。请在安装时使用的 Python 环境中执行以下步骤：

1. 在各客户端断开此 MCP 服务。

2. 查看旧服务状态，再停止旧服务：

   python -m renderdoc_mcp_fusion.shared_service status
   python -m renderdoc_mcp_fusion.shared_service stop

3. 在项目目录安装新版本：

   python -m pip install .

4. 关闭不再使用的旧 RenderDoc 回放窗口。

5. 在各客户端重新连接 MCP，以启动新连接器和新服务。如果工具列表仍是旧版，刷新客户端的 MCP 工具列表或重启客户端。

6. 重新调用 open_capture，取得新句柄。GUI 模式下使用新回放窗口加载新桥接。

升级 GUI 桥接后，也需要新建 RenderDoc 回放窗口。旧窗口仍运行加载时的桥接代码。请关闭不再使用的旧窗口；新服务自动启动的窗口会加载新桥接。手动指定旧 window_id 不会更新其中的代码。

停止共享服务会影响所有连接到它的客户端。重启前的捕获句柄全部失效。新旧版本不能共用同一个运行中的服务；版本不一致时会报错。

开发时可以执行 python -m pip install -e .。可编辑安装需要保留源码目录。修改代码后，仍须重启连接器和共享服务。

Fusion Bridge

GUI 模式需要 Fusion Bridge 读取 RenderDoc 数据。自动启动流程通过 qrenderdoc --python 加载桥接，无需在扩展菜单中手动开启它。

请保留安装包自带的 bridge_extension。普通安装将它放在 Python 包的 _resources 目录中。可编辑安装直接使用源码目录中的文件。

旧版手动安装可能位于 %APPDATA%\qrenderdoc\extensions\renderdoc_fusion_bridge。如果只使用自动启动流程，可以停用或移除这份旧安装。如果仍需通过扩展菜单为手动打开的窗口提供桥接，请保留它。

工具与限制

工具列表如下。

所有抓帧分析调用都需要本连接的 capture_id。顶层工具使用 event_id、resource_id、shader_id 和 output_path。原生 GUI 接口使用 eid、rid、sid 和 dest。请按工具目录中的参数说明调用，不要混用两套名称。

资源 ID 必须使用字符串，例如 "ResourceId::30588"。部分 ID 超过常见客户端的整数精度范围，不能改成 JSON 数字。

后端选择

GUI 专用调用在 headless 捕获句柄上会返回 UNSUPPORTED_OPERATION。需要这些能力时，请重新调用 open_capture 并指定 backend="gui"。工具不会自动切换后端。

调用示例

以下示例中的 capture_id 和事件编号需要替换为当前抓帧的实际值。先通过 list_draws 获取事件编号。

调用 get_shader_info，读取顶点着色器的前 100 行反汇编：

{"capture_id":"当前连接的捕获句柄","event_id":120,"stage":"vs","mode":"disasm","offset":0,"max_lines":100}

调用 identify_drawcalls，比较一个绘制前后的颜色数据。此示例将像素数上限设为 4,194,304，可容纳 1920 × 1080 的目标：

{"capture_id":"当前连接的捕获句柄","eid_min":120,"eid_max":120,"include_diff":true,"max_pixels":4194304}

调用 export_to_unity，将一个绘制导出到新目录：

{"capture_id":"当前连接的捕获句柄","event_id":120,"output_path":"C:/Exports/draw-120"}

输出目录必须尚不存在。省略 output_path 时，程序在默认输出目录下分配新路径。导出后先检查结果中的 complete、errors 和 warnings，再查看 manifest.json。

list_captures 列出指定目录中的 RDC 文件，使用 offset 和 limit 分页，不递归扫描。它不需要捕获句柄。list_instances 列出已打开的回放后端。open_capture 打开已有 RDC，不启动游戏或创建新抓帧。mode="code" 不会从机器码还原原始高级着色器源码。

数据范围和错误处理

• get_shader_info 在 GUI 中支持 reflect、disasm、source 和 code。文本用 offset 和 max_lines 分页，结果报告是否截断。缺少调试源码时，source 不会生成虚构源码。

• 资源列表和像素历史用 offset、limit 分页。原始字节以 Base64 返回。纹理字节默认最多返回 4 KiB，最高 1 MiB；原生回放仍会先读取所选子资源。3D 纹理读取整个 mip 层，不能只读取一个深度切片。

• debug_pixel 和 debug_vertex 用 max_steps 限制返回的调试步数。结果报告调试是否完成以及数据是否截断。指定像素没有着色器调用，或回放 API 不支持调试时，调用会报错。

• analyze_lighting 读取着色器、绑定和常量证据。光照模型和纹理用途是启发式判断，不是已验证的场景语义。

• identify_drawcalls 可比较每个绘制前后的颜色数据，并返回变化像素数和包围框。颜色没有变化不代表没有几何体。压缩格式、数组纹理和多重采样等不支持的情况会逐项报告。默认每次分析 16 个绘制，并限制纹理像素数。

• 着色器和资源反查返回实际绘制事件。着色器扫描达到上限时返回 next_after_eid；下一次调用将它传入 after_eid。

• 性能计数器来自回放设备。get_action_timings 使用 GPU Duration 计数器。设备不支持时返回错误，不用零值代替真实测量。

• Windows 上的 D3D12 计数器要求启用系统开发者模式。检测到该设置未启用时，调用会说明原因，不执行计数器回放。Fusion 不修改这个系统设置。原生回放发生致命错误时，捕获句柄失效；请重新打开抓帧。

• 绘制包包含完整着色器文本、纹理、管线状态、可用网格和 manifest.json。先检查 complete、errors 和 warnings。部分文件导出成功不代表整个包完整。

• Unity 包包含 OBJ、纹理、材质映射建议和 Editor 导入脚本。将包复制到 Unity 的 Assets 下，检查 material.json，再执行包内说明指定的菜单。它不恢复原始材质、骨骼、动画或场景。

• GUI 可读取实际资源绑定和常量缓冲值。

• 附带 headless 引擎的部分绑定结果只表示声明，不能当作实际纹理绑定。它不支持常量值读取。

• export_mesh 导出 GPU 变换后的数据。绘制包优先导出捕获的顶点输入；没有位置输入时可回退到绘制后的位置预览。请检查网格的坐标说明和 UV 限制。这些数据都不等于原始骨骼模型。

• 原生接口只开放工具目录中允许的操作。会绕过本服务捕获生命周期管理的操作被阻止。

• 普通安装默认将输出写入 %LOCALAPPDATA%\RenderDocMCPFusion\artifacts。源码运行默认写入项目的 artifacts 目录。程序不覆盖已有文件。

• 超出内联大小限制的响应会完整写入 JSON 文件，并返回文件大小及 SHA256。

计数器前置检查失败时，返回错误详情中的 developer_mode_required，现有回放仍可继续查询。若系统设置无法读取，程序不会假定它已启用；后续原生致命错误仍会使句柄失效。

项目文件与输出

运行时输出按需创建。artifacts/ 用于源码运行时的导出文件和大型响应；它不需要预先存在。artifacts/、/tests/、构建目录和本地运行状态均由 Git 忽略。清理生成文件后，后续调用可以重新创建所需的输出目录。

常用环境变量

许可证

本项目采用 MIT 许可证。第三方组件保留各自的版权声明和许可证。

鸣谢

感谢以下开源项目及其贡献者：

• RenderDoc：提供图形捕获、回放和调试能力。

• JiaboLi-GitHub/renderdoc-mcp：为 headless 引擎提供参考。

• Hengle/RenderDocMCP2：为查询和导出功能提供参考。

• stb：提供 headless 引擎使用的 stb_image 和 stb_image_write 图像读写库。