OpenBio Comfy MCP

English | 简体中文

OpenBio Comfy MCP 是一个本地 Model Context Protocol 服务器和 ComfyUI V3 扩展，用于检查和编辑当前在实时 ComfyUI 画布上打开的工作流。它使用 ComfyUI 原生的图、选择、分组、脏状态和撤销行为；它绝不会自动排队、执行或保存工作流。

[!IMPORTANT] 已发布版本可通过 ComfyUI Manager 安装。Registry 软件包包含捆绑的 MCP 服务器，因此 Manager 用户无需运行 npm ci。

功能特性

• 以紧凑、结构化的 MCP 输出检查活动画布。

• 搜索已连接 ComfyUI 实例中安装的所有节点类型。

• 检查精确节点类型的完整原生 schema。

• 选择并聚焦原生节点或分组，而不修改工作流。

• 添加、移除、连接、断开、配置和移动节点。

• 添加、更新、适配、移动和移除原生 ComfyUI 分组。

• 将一批操作作为一个原子化、可撤销的原生 ComfyUI 事务应用。

• 在更改实时图之前拒绝过期或无效的补丁。

• 保持 MCP 传输为本地：stdio 服务器不打开监听端口，中继仅接受来自回环的画布命令。

Related MCP server: comfy-mcp

架构

MCP host application (Codex or another local host)
        | MCP over stdio
        v
Node.js MCP server
        | ComfyUI HTTP
        v
Python V3 extension relay
        | ComfyUI WebSocket event
        v
Browser page extension -> active app.canvas.graph

浏览器页面是实时图的权威来源。Python 扩展将请求与已连接的页面关联，而 Node.js stdio 服务器不保留权威的工作流副本。该扩展不注册任何 ComfyUI 执行节点，也不会修补 ComfyUI Core、ComfyUI_frontend、Desktop 或工作流文件格式。

系统要求

• ComfyUI 0.33.0 或更高版本

• ComfyUI 运行时中的 Python 3.10 或更高版本

• Node.js 20 或更高版本

• 支持本地 stdio 服务器的 MCP 主机应用

• 使用工具期间保持打开的 ComfyUI 浏览器或 Desktop 页面

ComfyUI 扩展没有额外的 Python 包依赖。Registry 发布版包含预构建的 MCP 服务器。对于源代码和开发签出，npm ci 仅安装 Node.js 依赖并构建该服务器；它不会修改 ComfyUI Python 环境。

安装

ComfyUI Manager（推荐）

打开 ComfyUI Manager，搜索 OpenBio Comfy MCP 或 openbio-comfy-mcp，选择 Install，然后重启 ComfyUI。安装的 MCP 入口点为：

<ComfyUI>/custom_nodes/openbio-comfy-mcp/dist/openbio-comfy-mcp.mjs

Registry 安装无需执行 npm ci 步骤。

标准源代码安装

将仓库直接克隆到 ComfyUI 的 custom_nodes 目录中，然后安装 MCP 服务器依赖并构建捆绑的入口点。

Windows PowerShell：

$ComfyRoot = "C:\path\to\ComfyUI"
Set-Location "$ComfyRoot\custom_nodes"
git clone https://github.com/Open-Bio/openbio-comfy-mcp.git
Set-Location .\openbio-comfy-mcp
npm ci

Linux 或 macOS：

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/Open-Bio/openbio-comfy-mcp.git
cd openbio-comfy-mcp
npm ci

安装后重启 ComfyUI，在浏览器中打开其 UI，并验证扩展路由可用：

Invoke-RestMethod http://127.0.0.1:8188/openbio-comfy-mcp/health

预期响应是 { "ok": true }。

用于开发的同级签出

如果你希望编辑内容保留在独立仓库中，请将 Git 签出放在 ComfyUI 外部，并通过链接将其暴露给 ComfyUI。

Windows PowerShell：

$ComfyRoot = "C:\path\to\ComfyUI"
$Repo = "C:\path\to\openbio-comfy-mcp"

New-Item -ItemType Junction `
  -Path "$ComfyRoot\custom_nodes\openbio-comfy-mcp" `
  -Target $Repo

Set-Location $Repo
npm ci

Linux 或 macOS：

ln -s /path/to/openbio-comfy-mcp /path/to/ComfyUI/custom_nodes/openbio-comfy-mcp
cd /path/to/openbio-comfy-mcp
npm ci

不要通过多个 custom-node 根目录暴露同一个签出。

连接 MCP 主机

Codex

使用绝对路径注册本地 stdio 服务器：

$Repo = (Resolve-Path "C:\path\to\openbio-comfy-mcp").Path

codex mcp add openbio-comfy-mcp `
  --env OPENBIO_COMFY_URL=http://127.0.0.1:8188 `
  -- node "$Repo\dist\openbio-comfy-mcp.mjs"

codex mcp get openbio-comfy-mcp --json
codex mcp list --json

添加服务器后，重启 Codex 客户端。Codex Desktop、CLI 和 IDE 扩展在同一个 Codex 主机上共享 MCP 配置。请参阅 Codex MCP 官方文档。

其他 stdio MCP 主机

对于使用 mcpServers JSON 配置的主机，请使用绝对路径调整此示例：

{
  "mcpServers": {
    "openbio-comfy-mcp": {
      "command": "node",
      "args": ["C:\\path\\to\\openbio-comfy-mcp\\dist\\openbio-comfy-mcp.mjs"],
      "env": {
        "OPENBIO_COMFY_URL": "http://127.0.0.1:8188"
      }
    }
  }
}

配置键因主机而异。命令必须以 dist/openbio-comfy-mcp.mjs 开头，且 OPENBIO_COMFY_URL 必须指向本地 ComfyUI 服务器。

配置

工具

推荐的编辑流程：

1. 调用 inspect_canvas，并保留返回的 canvas_id 和 revision。

2. 在添加不熟悉的节点类型之前，使用 search_nodes 和 inspect_node_type。

3. 发送一个 apply_canvas_patch，将检查得到的 canvas_id 和 revision 作为 base_revision。

4. 可选地调用 present_canvas 选择并聚焦更改后的项。

5. 再次检查。如果结果不理想，使用 ComfyUI 原生的撤销命令。

有关确切的公共行为和操作集，请参阅 docs/spec.md。

前端开发说明

独立的 ComfyUI_frontend Vite 开发服务器（pnpm dev，通常端口 5173）不会加载自定义节点提供的 JavaScript 扩展。因此，OpenBio Comfy MCP 无法连接到仅由该开发服务器提供的画布。请使用 ComfyUI 本身提供的前端，或构建前端并以该构建作为前端根目录启动 ComfyUI。

安装或更新此仓库后，重启 ComfyUI 并重新加载浏览器页面，以便加载页面扩展。

安全与隐私

• 仅从你信任的来源安装 MCP 服务器。此本地服务器以启动它的 MCP 主机应用相同的操作系统权限运行。

• 将 apply_canvas_patch 视为具有写入能力的工具，并在 MCP 主机中审查或批准其使用。它会更改当前在所选页面中打开的工作流，尽管整个补丁可以通过一次原生撤销来还原。

• stdio MCP 服务器不打开网络监听器。它调用已配置的 ComfyUI HTTP 服务器，默认地址为 http://127.0.0.1:8188。

• 画布命令请求仅接受来自回环的连接。此限制并非 ComfyUI 的通用身份验证层；请勿将未经身份验证的 ComfyUI 服务器暴露给不受信任的网络。

• 桥接器暴露的是带类型的图操作，而非任意 JavaScript、DOM 访问、文件系统访问、shell 命令、工作流排队或执行。

• 画布检查可能包含工作流名称、路径、节点标题、提示词、文件名、样本标识符和组件值。任何后续处理都遵循你所连接的 MCP 主机和模型提供商的隐私政策与配置。

• 断开的页面返回 NO_LIVE_CANVAS；系统绝不会回退到在后台编辑工作流文件。

故障排查

• NO_LIVE_CANVAS：打开或重新加载 ComfyUI 页面并保持连接。

• 主机中缺少工具：验证 dist/openbio-comfy-mcp.mjs 的绝对路径，然后重启 MCP 主机应用。如果是源代码签出，请先运行 npm ci。

• 缺少健康检查端点：验证仓库直接位于 custom_nodes 下或已链接到该目录，然后重启 ComfyUI 并检查其控制台中的导入错误。

• STALE_CANVAS：再次调用 inspect_canvas，并根据返回的 revision 构建新补丁。

• 多个页面处于打开状态：最近聚焦的 ComfyUI 页面是默认目标；如果无法消解歧义，将报告而不是猜测。

• 端口 5173 的开发页面无法连接：请按上述说明使用由 ComfyUI 后端提供的前端。

更新与卸载

更新源代码安装及其锁定的 Node.js 依赖：

git pull --ff-only
npm ci

更新后重启 ComfyUI 并重新加载其浏览器页面。

要卸载，请先移除 MCP 主机注册。对于 Codex：

codex mcp remove openbio-comfy-mcp

然后从 ComfyUI/custom_nodes 中移除克隆的 openbio-comfy-mcp 目录——或仅移除同级开发签出的 Junction/符号链接——并重启 ComfyUI。

开发

安装 Node.js 依赖并运行 MCP/页面扩展测试：

npm ci
npm test

使用与 ComfyUI 相同的解释器运行 Python 中继测试：

C:\path\to\ComfyUI\.venv\Scripts\python.exe `
  -m pytest --rootdir=tests -c pyproject.toml tests -q

仓库布局：

dist/                     Bundled, dependency-free Registry MCP entry point
mcp_host/                 Node.js stdio MCP server
openbio_comfy_mcp/        ComfyUI V3 Python relay extension
scripts/                  Reproducible MCP bundle build
web/                      Live page extension and canvas bridge
tests/                    Node.js and Python tests
docs/spec.md              Public behavior and safety boundaries

欢迎提交 Issue 和 pull request。请将更改保持在项目记录的实时画布和本地传输边界内，并在提交前运行两个测试套件。

许可证

OpenBio Comfy MCP 根据 MIT 许可证 发布。

本项目使用官方的 Model Context Protocol TypeScript SDK，以及 ComfyUI 文档中介绍的 V3 扩展 和 JavaScript 扩展 机制。