AI-assisted graphics debugging for RenderDoc via the Model Context Protocol.
MIT License
______________________________________________________________________
agent RenderDoc允许AI代理直接访问实时RenderDoc回放会话。可以指示代理检查绘制调用、读回缓冲区和纹理数据、查询管道状态、事件之间的差异状态，并通过自然语言导航RenderDoc UI。
为什么
图形调试是有条不紊的。您捕获一帧，遍历事件列表，检查管道状态，读回缓冲区，比较绘图。一个可以访问应用程序源和捕获的GPU状态的AI代理可以比单独处理任何一个更快、更彻底地完成这项工作。
建筑
Claude (MCP client)
| stdio (JSON-RPC)
v
MCP Server (Python, FastMCP)
| TCP socket (JSON-lines, localhost)
v
RenderDoc Extension (Python, inside RenderDoc)
| renderdoc / qrenderdoc modules
v
RenderDoc replay engine通过TCP环回连接的两个进程。MCP服务器由客户端作为子进程（stdio传输）生成。该扩展在RenderDoc的嵌入式Python解释器中运行，并在本地主机（端口范围19876-19885）上托管TCP服务器。
工具
| 工具 | 目的 |
|---|---|
| 评估 | 在RenderDoc重播会话中执行Python。所有检查、分析和调试的主要界面。 |
| 搜索API | 搜索RenderDoc Python API引用。通过反思生活而建立 renderdoc 模块，因此它始终与运行版本匹配。 |
| 例子 | 列出、连接到或断开与正在运行的RenderDoc实例的连接。首次使用时自动连接。 |
预加载实用程序
在Eval代码中作为函数提供，而不是单独的工具。
inspect(obj)-检查任何RenderDoc对象。方法、属性、文档字符串。diff_state(eid_a, eid_b)-两个事件之间的管道状态不同。get_resource_name(resource_id)-查找人类可读的资源名称。interpret_buffer(data, fmt)-将原始缓冲区字节解码为类型值。summarize_data(values)-数值数据的最小/最大/平均/NaN/Inf统计。action_flags(flags)-将ActionFlags位掩码解码为标志名称。goto_event(eid)/view_texture(id)/highlight_drawcall(eid)-导航RenderDoc UI。
设置
需求
- Python 3.10+
- 渲染文档
1.安装RenderDoc扩展
复制 src/extension/ 进入RenderDoc的扩展目录 agentic_renderdoc:
Linux：
cp -r src/extension ~/.local/share/qrenderdoc/extensions/agentic_renderdocmacOS：
cp -r src/extension ~/Library/Application\ Support/qrenderdoc/extensions/agentic_renderdocWindows（PowerShell）：
Copy-Item -Recurse src\extension "$env:APPDATA\qrenderdoc\extensions\agentic_renderdoc"然后在RenderDoc中： 工具>管理扩展，启用 agentic-renderdoc，然后重新启动。
2.安装MCP服务器
python scripts/install.py这将构建一个轮子，pip将安装MCP服务器。它不会安装扩展（步骤1）。
3.配置您的MCP客户端
将此添加到您的MCP客户端配置中：
{
"mcpServers": {
"renderdoc": {
"command": "agentic-renderdoc"
}
}
}配置文件位置：
| 客户端 | 文件 |
|---|---|
| 克劳德代码（项目） | .mcp.json 在项目根目录中 |
| 克劳德代码（用户） | ~/.claude.json |
| 克劳德桌面（Windows） | %APPDATA%\Claude\claude_desktop_config.json |
| 克劳德桌面（macOS） | ~/Library/Application Support/Claude/claude_desktop_config.json |
| 克劳德桌面（Linux） | ~/.config/Claude/claude_desktop_config.json |
发展
项目结构
两半：
src/extension/-在RenderDoc的嵌入式Python中运行。托管TCP服务器，处理命令，序列化RenderDoc类型。src/server/-客户端生成的MCP服务器。定义三个工具并通过TCP连接到扩展。scripts/-安装、测试和打包实用程序。
测试
probe.py 通过TCP直接连接到扩展，绕过MCP服务器：
python scripts/probe.py # Run health checks
python scripts/probe.py reload # Hot-reload extension modules热重新加载
这 reload 命令在不重新启动RenderDoc的情况下重新加载处理程序模块。更改为 __init__.py 仍然需要重新启动。
开发扩展安装
对于扩展的主动开发，请使用符号链接而不是复制，以便立即进行编辑：
Windows（PowerShell）：
New-Item -ItemType Junction `
-Path "$env:APPDATA\qrenderdoc\extensions\agentic_renderdoc" `
-Target "\src\extension"Linux/macOS：
ln -s /src/extension ~/.local/share/qrenderdoc/extensions/agentic_renderdoc为什么这个设计
V1暴露了70个工具。在实践中，代理忽略了其中的大多数，直接进入Python eval处理程序，并在变得高效之前花了大约6次迭代摸索RenderDoc API。每次会议。代理还经常犯错误，并在解释渲染文档吐出的原始数据时遇到困难。
V2减少到三个具有丰富描述的工具。工具说明 *是* 提示工程。它对访问模型、对象图、游标语义和工作模式进行编码，以便代理在第一次调用时编写正确的RenderDoc Python。
这种方法得到了以下支持 张等，“一个工具就够了”：更少的、基于语义的工具胜过大型工具套件，即使在模型大小差距上也是如此。我们在构建此工具时观察到了相同的行为。
这是如何建造的
Agent RenderDoc的V1和V2都完全由AI（Claude）编写。我（Techgeek1）的贡献是设计、架构决策、实时捕获测试和迭代指导。没有代码是手写的。
V2的过程大致如下：
- 设计。 我在人工智能的帮助下编写了设计文档（见
docs/DESIGN.md).这是通过观察V1在几个实际调试用例中的故障模式得出的。V1是用一个类似的过程编写的，但构建AI工具的经验要少得多。 - 实施。 AI在两个版本中编写了所有代码。MCP服务器、RenderDoc扩展、序列化、实用程序、桥接协议。我审查和指导。
- 战斗测试。 我使用该工具对来自无绑定Vulkan渲染器的真实GPU捕获进行了运行，并反馈了详细的结果。每一轮都会出现工具描述不准确、API误解、死锁和可用性摩擦。
- 迭代。 人工智能解决了问题，人类再次测试。在工具第一次接触到猎物时，它已经可靠地生产了五轮。
创建此工具的最大问题不在于代码，而在于工具描述。错误的类型名称、丢失的访问器路径或未记录的API间隙将导致代理编写看似合理但不正确的代码，或者需要更长的时间才能找到所需的信息。这些描述经历了与实施一样多的修订周期。
这个项目部分是人工智能驱动的开发工作流程的实验，部分是我们想要存在的实用工具。这两个目标都很好地实现了，该工具本身比手动检查有了显著改进。
我希望通过描述这个过程，其他开发人员可以从我的发现中学习，并学习为常见的工作流程构建类似或更好的工具。