ComfyUI-Roundabout

一个 ComfyUI custom node：把本地工作流包装成 OpenAI 兼容 REST API + MCP 工具（12 个），让 AI agent / 脚本 / 任意 OpenAI 客户端直接调用你本机的图像与视频生成。

不碰画布、不改代码。 你在 ComfyUI 里搭好的流程，导出一个 JSON、在 models.yaml 写一段参数映射，就变成了一个可被任意客户端调用的 model。

设计目的

1. 让 ComfyUI 成为 agent 的 AIGC 后端

ComfyUI 已经有模型、显存和队列，缺的只是一层 agent 能听懂的接口。Roundabout 把它包成 OpenAI 兼容 REST（base_url 指过来即可，任何 OpenAI SDK / 客户端零改动接入）和 MCP 服务（agent 直接调工具）。本地算力因此变成一个私有、按次调用不计费的图像 / 视频后端。

2. 嵌入 ComfyUI，无需额外维护

它是一个 custom node，不是一套要单独部署的服务：

• 随 ComfyUI 启动自动加载、随 ComfyUI 退出而结束，没有独立进程

• MCP 端点挂在 ComfyUI 自己的端口（/mcp），不额外占端口

• 复用 ComfyUI 的 Python 解释器与依赖（纯 REST 场景零新增依赖）

• 配置只有 models.yaml（模型）与 .env（可选）两个文件，改完热加载

没有 docker、没有守护进程、没有第二份 registry 要同步。

3. 不把 workflow 交给 agent，精准传参省 token

agent 全程看不到也用不着工作流 JSON。它只传语义参数，节点字段的写入由网关在本地按 models.yaml 的映射完成。

本仓库自带工作流的实测体积（按 字符÷3 粗估 token）：

对应的 Roundabout 调用：

{"model":"z-image-turbo","prompt":"一只戴宇航头盔的柴犬","size":"1024x1024"}

约 30 tokens —— 单次生成请求携带的载荷差 40~90 倍，且工作流越复杂（视频、多参考图）差距越大。

Related MCP server: ComfyUI-MCP-Server-Python

文档分工

功能

两套接入层，共享同一个引擎

• OpenAI 兼容 REST：/v1/images/generations（文生图 / 图生图）、/v1/images/edits（multipart 标准编辑）、/v1/images/remove-background（去背景）、/v1/videos/generations（视频，支持异步）。返回格式可选 b64_json / url / file / path，可直接替换 OpenAI 官方地址使用。

• MCP 服务（12 个工具）：生成类 generate_image / edit_image / remove_background / generate_video，查询类 list_models / get_task / cancel_task / queue_status / get_workflow / health，运维类 reload / get_view_url。agent 用一组工具就能完成「查模型 → 生成 → 跟踪进度 → 拿产物」全流程。

• 共享端口：MCP 端点 /mcp 直接挂在 ComfyUI 同一端口（http://<comfyui>:8188/mcp），不用额外开端口、不用另起进程；REST 与 MCP 共用同一份注册表、生成链路与任务表。

声明式模型注册

• models.yaml 登记模型：工作流文件 + 参数绑定路径 + 默认值 + 别名 + 能力（文生图 / 图生图 / 视频）。

• 新增、修改模型只改 YAML，POST /admin/reload 热加载，不用重启 ComfyUI、不用写代码。

• 内置 15 个开箱可用的工作流（11 图像 + 4 视频），也全部可以作为你写映射时的参照。

看得见、管得了

• 可视化页面 http://<comfyui>:8188/roundabout/view：浏览 input/ output/ 资源（缩略图分批懒加载、自适应分页、产物自动同步），右下角悬浮任务面板实时显示 ComfyUI 队列 + 网关任务表，产物一键弹层预览。

• ComfyUI 内管理面板：菜单「Roundabout」提供工作流管理（上传 / 校验 / 删除）、模型配置（结构化编辑）、队列监控（含 seed，便于区分批量提交）。

• 任务留痕：同步与异步生成都记一条（状态 / 耗时 / seed / 产物地址），终态记录保留 6 小时。

安装

方式一 · 用 ComfyUI-Manager 从 Git URL 安装（推荐）——装好 ComfyUI-Manager 后，打开 Custom Nodes Manager，右上角菜单选 Install via Git URL，填入：

https://github.com/0c0/ComfyUI-Roundabout

装完点 Restart。节点包已按 Comfy Registry 规范声明元数据（pyproject.toml），ComfyUI-Manager 能从中识别名称与版本；因为是 git 仓库，之后也可以直接在 Manager 里检查/拉取更新。

本仓库未发布到 Comfy Registry，所以搜索框里搜不到、也没有 comfy node install 这条命令，请走上面的 Git URL 安装。

方式二 · 手动克隆：

1. 放进 ComfyUI 的 custom_nodes/ 目录：

   cd ComfyUI/custom_nodes
   git clone https://github.com/0c0/ComfyUI-Roundabout.git

2. 安装依赖 —— MCP 网关默认开启，所以默认需要这一步：

   <ComfyUI>/python/python.exe -m pip install -r custom_nodes/ComfyUI-Roundabout/requirements.txt
   # 即 mcp>=2.0.0（必须 2.x，1.x 的 FastMCP API 不兼容） + uvicorn>=0.30.0

   只要 REST、不要 MCP：在 .env 写 MCP_ENABLED=false，这两个包可以不装。

3. 配置（可选）：把 .env.example 复制成 .env，按需修改。MCP 默认已启用，不用额外设置；要关掉就把 MCP_ENABLED 改成 false。

4. 准备模型权重：内置工作流用到的文件见下方权重清单，仓库不含权重。

5. 重启 ComfyUI。启动日志出现 OpenAI gateway routes registered ... models=... 即成功。

使用方式

1. ComfyUI 面板（人在 ComfyUI 里操作）

菜单栏 Roundabout →

2. REST 接口（脚本 / OpenAI 客户端）

下面是四个最常用的最小示例；完整字段表、响应结构与错误码见 API.md。

文生图

curl -X POST http://127.0.0.1:8188/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{"model":"z-image-turbo","prompt":"一只戴宇航头盔的柴犬，赛博朋克霓虹灯背景","size":"1024x1024","response_format":"path"}'

编辑图片（换背景 / 换材质 / 图内写字）

curl -X POST http://127.0.0.1:8188/v1/images/edits \
  -F model=flux2-klein-image-edit-turbo \
  -F 'prompt=把背景换成星空，保留主体不变' \
  -F response_format=path \
  -F image=@input/source.png

去背景（透明 PNG，无需提示词）

curl -X POST http://127.0.0.1:8188/v1/images/remove-background \
  -F image=@input/source.png -F response_format=path

视频（长任务建议异步，再轮询任务）

# 提交
curl -X POST http://127.0.0.1:8188/v1/videos/generations \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax-h3-turbo","prompt":"a cat walking in rain","duration":5,"background":"pending"}'
# 查结果（id 来自上一步返回）
curl http://127.0.0.1:8188/v1/videos/tasks/<id>

size 支持档位预设 <tier>p-<ratio>：tier ∈ 480p / 720p / 768p / 1080p，ratio ∈ 1:1 / 3:4 / 4:3 / 16:9 / 9:16（如 768p-16:9 = 1360×768、1080p-16:9 = 1920×1088）；也接受反向写法 <ratio>@<tier>p（如 9:16@768p）与直接 WxH。不传或 auto 用模型默认。

3. MCP（给 agent 用）

MCP 默认启用——装好依赖、重启 ComfyUI，端点就在 http://<comfyui>:8188/mcp，无需任何配置。

Streamable HTTP（推荐，走 ComfyUI 同端口，无独立进程）：

{
  "mcpServers": {
    "comfyui-roundabout": {
      "type": "streamable_http",
      "url": "http://127.0.0.1:8188/mcp"
    }
  }
}

stdio（由 MCP 客户端拉起进程，适合不支持 HTTP 的客户端）：

{
  "mcpServers": {
    "comfyui-roundabout": {
      "command": "<ComfyUI>/python/python.exe",
      "args": ["<ComfyUI>/custom_nodes/ComfyUI-Roundabout/mcp_server.py"]
    }
  }
}

URL 里的主机端口 = 你访问 ComfyUI 的地址，路径固定 /mcp。远程访问换成 http://192.168.1.10:20003/mcp 即可，其余不变。 工具参数、完成推送（notifications/message）与助手侧注意事项见 API.md §7。

agent 典型流程：list_models 看有什么 → generate_image / generate_video 生成 → 异步任务用 get_task 或等服务端推送 → 产物地址交给用户 → get_view_url 给出可视化页面。

4. 可视化页面

浏览器打开 http://<comfyui>:8188/roundabout/view（MCP 工具 get_view_url 也会返回这个地址）：

• 浏览 input/ 与 output/（按修改时间倒序、自适应分页、缩略图分批懒加载）

• 有新产物自动提示刷新，不打断你正在看的图

• 右下角「任务进度」悬浮面板：ComfyUI 队列 + 网关任务 + 一键查看产物

内置模型

默认 default_model = z-image-turbo。model 可传注册名或任一别名（不区分大小写）；不传则用默认模型。

• 编辑类模型必须传 image；输出尺寸跟随输入图（工作流内缩放到 1MP），size 不生效。

• 给文生图模型传 image 会被拒绝，错误信息里会列出所有支持输入图的模型名。

• 别名、绑定路径与实测耗时见 models.yaml 与 API.md §5.4。

权重清单（内置工作流的全部依赖）

本仓库不包含任何权重文件（体积与许可原因）。内置工作流引用的 24 个文件如下，放到 ComfyUI 对应目录即可；缺文件时报错是 value not in list: <字段>: <文件名>。

这些工作流用到的节点全部来自 ComfyUI 核心（comfy_extras/），不需要装任何第三方 custom node 包；但 ComfyUI 版本太老会缺 MiniMaxH3ReferenceToVideo / LoadBackgroundRemovalModel / Flux2Scheduler 等节点。 上述权重多为 int8_convrot 量化版，只在你已具备同名权重的机器上开箱即用；换成自己的模型时，同步改工作流 JSON 里的文件名即可。

接入自己的工作流

内置工作流只是样本，随时可以删。接入自己的流程 = 导出 API 格式 JSON + 在 models.yaml 写一段参数映射，支持热加载，不用改代码。

三步：

1. ComfyUI 画布 → Workflow → Export (API)（必须是 API 格式，不是普通 Export）→ 存进 workflows/

2. 在 models.yaml 加一条：workflow / mode / capabilities / output_node / bindings（接口参数 → 节点路径）

3. POST /admin/reload 或面板点「重新加载」，然后打一发接口验证

完整指南见 WORKFLOWS.md —— 参数白名单、常见落点表、找路径的方法、三条铁律（尤其：别绑被连线覆盖的 input）、models.yaml 全字段、references 段、排错表。

最小可跑参考样本：workflows/example_txt2img.json（CheckpointLoaderSimple + KSampler + SaveImage，把 ckpt_name 换成你自己的即可）。 另有三种落地路径（面板 / REST / Agent）的逐步说明。

配置

完整环境变量清单见 API.md §2.3，常用项：

同机跑多个 ComfyUI 实例

Roundabout 随 ComfyUI 进程启动，每个实例都有自己的 MCP 后端。如果想让端口可预期（防火墙放行、日志好认），用映射表把「ComfyUI 端口 → Roundabout 端口」一一对上：

MCP_PORT_MAP=[8188,888],[8189,999]

于是 --port 8188 的实例用 888、--port 8189 的实例用 999，互不干扰。不配映射也不会冲突（自动分配空闲端口），配了映射更可控；映射端口恰好被别的程序占用时会自动回落到空闲端口并在日志里告警，端点不会因此失效。

目录结构

ComfyUI-Roundabout/
├── __init__.py            # ComfyUI 节点入口（启动网关、加载模型）
├── mcp_server.py          # MCP 服务（12 工具）+ 共享端口嵌入启动
├── gateway/               # REST 网关
│   ├── config.py          # 配置（.env / 环境变量）
│   ├── registry.py        # models.yaml 解析、绑定校验、热加载
│   ├── pipeline.py        # 生成链路（参数校验 → 工作流渲染 → 提交 → 收集产物）
│   ├── handlers.py        # REST 端点
│   ├── routes.py          # 路由表
│   ├── admin.py           # 工作流 / 模型配置管理端点
│   ├── viewer.py          # 资源浏览与任务进度页面后端
│   ├── analyze.py         # 上传工作流时的参数映射自动分析
│   ├── tasks.py           # 任务表
│   ├── log_filters.py     # 把 aiohttp「客户端断开」的 ERROR 降级为 DEBUG
│   └── ...
├── web/                   # 前端（可视化页面 + 设置面板）
├── workflows/             # API 格式工作流（example_txt2img.json 为接入样本）
├── models.yaml            # 模型注册表
├── pyproject.toml         # 节点包元数据（供 ComfyUI-Manager 等抓取识别）
├── requirements.txt       # mcp + uvicorn（MCP 默认启用故默认需要；关掉 MCP 可不装）
├── test_*.py / test_*.cjs # 测试（分发时由 .comfyignore 排除）
├── WORKFLOWS.md           # 接入自己的工作流
└── API.md                 # 完整接口文档

测试

# 离线自测（不需要 ComfyUI 在跑，全部用系统分配的临时端口）
<ComfyUI>/python/python.exe test_mcp_proxy_disconnect.py    # /mcp 代理的断开与不可达兜底
<ComfyUI>/python/python.exe test_aiohttp_error_noise.py     # Error handling request 降噪
<ComfyUI>/python/python.exe test_mcp_stateless.py           # MCP_STATELESS 开关（重启无感）
<ComfyUI>/python/python.exe test_mcp_import_identity.py
<ComfyUI>/python/python.exe test_port_map.py
<ComfyUI>/python/python.exe test_video_size.py

# 需 ComfyUI 在跑
<ComfyUI>/python/python.exe test_viewer_smoke.py
<ComfyUI>/python/python.exe test_removebg_e2e.py     # 去背景独立实例 e2e
# 前端 jsdom（需 node + jsdom）
node test_view_frontend.cjs

许可

MIT