OpenImageDebugger MCP

oid-mcp

MCP 服务可让 AI Agent 在实时 gdb/lldb 会话中查看 OpenImageDebugger 缓冲区：在断点处列出可观测符号、查看渲染结果、读取精确值、转储无损 .npy 副本，并将缓冲区同步到人工查看器中。

⚠️ 实验性功能。 这是一项全新的实验性功能——控制协议、工具界面和行为可能随时更改，且尚无任何稳定性保证。此功能需显式启用 （OID_AGENT=1），并会向本地进程开放被调试程序的内存；仅在可信的本地开发环境中启用。 欢迎反馈。

工作原理

两个协作组件通过本地主机套接字连接：

• 调试器内端点（属于 OID 的 oid.py，仅依赖标准库） 会在设置 OID_AGENT=1 后，于调试器内嵌的 Python 中启动。它会将每个会话的发现文件（主机、端口、随机令牌）写入私有的用户目录。
• oid-mcp 服务（本软件包）由 MCP 客户端启动，读取发现文件，使用令牌建立连接，并在脆弱的调试器进程之外完成繁重工作（解码、PNG 渲染、统计、.npy）。

你运行调试器；MCP 客户端运行 oid-mcp。二者通过发现目录找到彼此，因此双方都必须能够读取同一目录（请参阅故障排除）。

前置条件

• 已构建并安装 OpenImageDebugger，且已部署 oid.py。 请参阅顶层 README 中的构建 Open Image Debugger。
• 内嵌 Python 的调试器：gdb，或（在 macOS 上）Homebrew lldb——也就是你平时与 OID 一起使用的调试器。
• uv——在托管的虚拟环境中运行服务，无需手动执行 pip install。使用 curl -LsSf https://astral.sh/uv/install.sh | sh 安装（或执行 brew install uv）。
• 支持 MCP 的客户端（例如 Claude Code）。

部署

1. 验证服务是否启动（可选，但建议执行）。在 shell 中运行：

   uv run --directory /path/to/OpenImageDebugger/resources/oidmcp oid-mcp
   

   首次运行会将 mcp/numpy/pillow 解析到本地 venv。它会向 stderr 输出实验性/安全警告，然后等待来自 stdin 的 MCP 流量——这种阻塞等待 表示它已正确启动。按 Ctrl-C 退出。

2. **在 MCP 客户端中注册它。**所有 stdio MCP 客户端都使用相同的 mcpServers 架构——只有文件位置不同。每个客户端都会启动 自己的 oid-mcp 进程，因此你可以同时在多个客户端中注册它；它们都会发现同一个调试会话。

   Claude Code — 单行命令：

   claude mcp add oid -- \
     uv run --directory /path/to/OpenImageDebugger/resources/oidmcp oid-mcp
   

   或将其添加到 .mcp.json：

   {
     "mcpServers": {
       "oid": {
         "command": "uv",
         "args": ["run", "--directory",
                  "/path/to/OpenImageDebugger/resources/oidmcp",
                  "oid-mcp"]
       }
     }
   }
   

   Cursor — 将相同条目放入 ~/.cursor/mcp.json（全局，适用于所有 项目）或 <workspace>/.cursor/mcp.json（单个项目）。设置 → MCP / Tools & Integrations → Add new MCP server 会打开该文件。 这些工具只能在 Cursor 的 Agent 聊天中使用。

   {
     "mcpServers": {
       "oid": {
         "command": "/absolute/path/to/uv",
         "args": ["run", "--directory",
                  "/path/to/OpenImageDebugger/resources/oidmcp",
                  "oid-mcp"]
       }
     }
   }
   

   **在桌面编辑器中使用绝对 command 路径。**Cursor 和 其他 GUI IDE 不会继承你的 shell PATH，因此直接使用 "uv" 通常无法启动。请使用 command -v uv 的输出（例如，Apple Silicon Homebrew 对应的 /opt/homebrew/bin/uv）。对于客户端无法自行解析的任何解释器，也需要这样处理。

   可选环境变量（通过客户端的 env 字段在服务条目中设置；对于 OID_AGENT_DIR，也要在调试器中设置）：

   变量	默认值	用途
   OID_MCP_MAX_BYTES	268435456（256 MiB）	传输前拒绝大于此大小的缓冲区
   OID_AGENT_DIR	~/.oid-agent/（Windows 上为 %LOCALAPPDATA%\oid-agent）	调试器和服务共享的发现目录

   **发现位置。**默认目录根据你的主目录（通过密码数据库）确定，因此由 GUI 启动的 oid-mcp 和终端调试器会解析到相同路径，不受 $TMPDIR/$HOME 影响。 若要更改位置，请在两个环境中将 OID_AGENT_DIR 设置为相同的 绝对路径（不会展开 ~）。

使用

1. 启用端点并加载 OID 后启动调试器：

   OID_AGENT=1 gdb ./your-program
   (gdb) source /path/to/OpenImageDebugger/oid.py
   

   lldb 的用法相同：

   OID_AGENT=1 lldb ./your-program
   (lldb) command script import /path/to/OpenImageDebugger/oid.py
   

   （如果 oid.py 已在你的 ~/.gdbinit / ~/.lldbinit 中，只需在 环境中设置 OID_AGENT=1 后启动调试器即可。）

2. **运行到断点。**端点会在首次暂停时激活并发布其发现文件。OID 查看器窗口也会像往常一样打开——plot 需要它，其他工具则不需要。

3. **通过 Agent 操作。**典型流程如下：

   list_sessions()                       # confirm the server sees your debugger
   list_buffers()                        # what's observable at this stop
   view("frame")                         # look at the whole buffer
   view("frame", region=[100,100,64,64]) # zoom into a suspicious spot
   stats("frame")                        # min/max/mean/std, NaN/Inf/zero counts
   values("frame", x=100, y=100, w=4, h=4)  # exact numbers for a tiny crop
   dump("frame")                         # lossless .npy for offline analysis
   plot("frame")                         # mirror it into the human's viewer
   

   每个工具都接受 session=<pid>，以指定目标调试器（当有多个调试器运行时）；默认使用最近启动的会话。

查看器会话

像素工具（view、stats、values、dump、list_buffers）完全不需要调试器。启用了 Agent 端点后单独启动的查看器：

OID_AGENT=1 oidwindow --open path/to/image.png

即使没有连接调试器，也会公开相同的端点，因此 Agent 可以检查用户当前在查看器中打开的内容。

如果查看器是由调试器启动的，该查看器会话会携带指向调试器的 debugger_pid 回指针，因此 set_view/get_view 接受查看器自身的 pid 或其调试器的 pid 来定位该窗口。（像素工具——view/stats/values/dump/list_buffers——在收到调试器 pid 时优先使用调试器自身的缓冲区；只有不存在运行中的调试器会话时才回退到查看器。）list_sessions() 会报告此关联关系（见下文）。

set_view/get_view 始终以查看器为目标（没有查看器时，调试器中没有可移动的对象），解析方式相同：使用查看器 pid，或与运行中的查看器配对的调试器 pid。

工具

工具	用途
list_sessions()	{"debuggers": [...], "viewers": [...]} — 实时调试会话和查看器窗口（所有工具都接受 session=<pid>）；每个查看器条目都会显示配对的 debugger_pid（独立查看器为 null）
list_buffers()	当前停止位置（调试器或查看器会话）的可观测缓冲区符号
view(symbol, region?, channel?, vmin?, vmax?, max_px?)	PNG 渲染；region 是无状态缩放
stats(symbol, region?)	每个通道的最小值/最大值/平均值/标准差，以及 NaN/Inf/零值计数
values(symbol, x, y, w, h, channel?)	精确数值（每次调用 ≤1024 个）
dump(symbol, path?, overwrite?)	将无损 .npy 转储到每用户转储目录；path 是该目录中的文件名（不能是任意路径）；若文件已存在则拒绝覆盖，除非 overwrite=true
plot(symbol)	镜像到人工查看器窗口中
set_view(session?, buffer?, center?, zoom?, rotation_deg?, channel?, auto_contrast?)	绝对地设置查看器视图（幂等——它设置状态，而不是微调）；省略的字段保留当前值；channel 为 0、1、2 或 "all"；auto_contrast 是查看器的全局开关，不是针对单个缓冲区的
get_view(session?)	读取查看器当前的 buffer/center/zoom/rotation_deg/channel/auto_contrast

注意事项

• 只有设置了 OID_AGENT=1 才会启动端点；端点会绑定到 localhost，并使用每个会话各自的令牌（发现文件位于 ~/.oid-agent/ 下，可通过 OID_AGENT_DIR 覆盖）。它会向能够读取这些文件的本地进程公开被调试程序的内存——这些进程与你的用户帐户处于同一信任域。
• 缓冲区会在每次停止后首次访问时完整传输并缓存；上限由 OID_MCP_MAX_BYTES 控制（默认为 256 MiB）。
• 求值符号时，被调试程序必须处于停止状态；运行期间，工具会返回可重试错误。
• 查看器窗口仍会在调试器首次停止时打开（OID 的正常行为）；plot 需要该窗口，其他工具不需要。

故障排除

• no live OID debug session found — 服务看不到会话。请依次检查：调试器环境中是否设置了 OID_AGENT=1；是否实际加载/导入了 oid.py；被调试程序是否至少在断点处停止过一次；以及调试器与 oid-mcp 是否使用相同的发现目录。如果它们使用不同的 TMPDIR 值（macOS 上很常见，因为每个进程可能会获得自己的每用户临时目录），请在两端都将 OID_AGENT_DIR 设置为相同的绝对路径。
• Refusing to read OID discovery files from …（标准错误）——发现目录是符号链接、不归你所有，或可被组用户/所有人访问，因此无法信任其中的令牌。请将 OID_AGENT_DIR 指向你拥有且权限为 0700 的私有目录。
• The debuggee is running — 请在断点处暂停（或单步执行到断点）；只能在停止时求值符号，然后重试。
• Buffer exceeds the transfer cap — 在服务条目中提高 OID_MCP_MAX_BYTES（字节），或缩小获取范围。