ComfyUI Connector（WorkBuddy）

为腾讯 WorkBuddy 生态开发的 ComfyUI 连接器：MCP stdio + 用户自填 Token 模式 （规范 06 / 06D 附录C），让 AI 通过自然语言运行 ComfyUI 工作流并取回生成的图片。

目录结构

comfyui/
├── connector-meta.json   # 连接器元信息（type: mcp, auth_mode: token, minWorkbuddyVersion: 4.24.0）
├── mcp.json              # MCP Server 连接配置（stdio，凭证经 env 注入）
├── token-schema.json     # 用户自填 Token 表单（COMFY_URL + 可选 COMFY_TOKEN）
├── comfy_mcp_server/     # MCP Server（Python，官方 mcp SDK FastMCP）
│   ├── __init__.py
│   ├── __main__.py       # python -m comfy_mcp_server 入口
│   └── server.py         # 5 个 tool：list_checkpoints / list_samplers / run_workflow / get_status / get_image
├── skills/
│   └── SKILL.md          # Skill 文件（按 05 规范，教 AI 如何使用工具）
├── icon.svg              # 连接器图标
├── tests_smoke.py        # 冒烟测试（MCP stdio 客户端调工具，验证错误路径）
├── pyproject.toml        # hatchling 打包（PyPI 包名 workbuddy-mcp-comfyui）
└── README.md

依赖仅 mcp（v1，FastMCP）+ httpx（Python ≥ 3.10）。

工具一览

标准链路：list_checkpoints 确认模型名 → run_workflow 提交 → 轮询 get_status → 用 history outputs 里的 filename/subfolder/type 三元组调 get_image。

COMFY_TOKEN 仅在用户加了反向代理鉴权时才填；非空时 server 自动附加 Authorization: Bearer 头，原生 ComfyUI 留空。httpx 超时 30s。

本地测试

cd <项目目录>/connectors/comfyui

# 1. 语法与 JSON 校验
python3 -m py_compile comfy_mcp_server/*.py
for f in connector-meta.json mcp.json token-schema.json; do python3 -m json.tool "$f" > /dev/null && echo "$f OK"; done

# 2. 起本地构建的 server 并调用工具（ComfyUI 未运行时验证错误路径）
#    server 经 uvx --from 本地目录构建；客户端复用 home-assistant/.venv 里的 mcp 包
export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
export COMFY_URL="http://127.0.0.1:8188"
../home-assistant/.venv/bin/python tests_smoke.py

错误处理约定

• 连接失败 → 提示检查 COMFY_URL / ComfyUI 是否启动 / 网络可达性
• 401 → 仅反代鉴权场景出现，提示更新 COMFY_TOKEN
• run_workflow 400 → 摘要 ComfyUI 的 node_errors，并提示「Export (API)」导出 API 格式
• get_status 找不到任务 → 对照 /queue 区分排队中与任务不存在
• get_image 404 → 提示从 get_status 的 outputs 取有效三元组
• 缺环境变量 / 超时 / 非 200 均返回可读中文错误，不会抛栈给 AI

正式提交前 TODO

• 发布 PyPI 包：mcp.json 已按 uvx workbuddy-mcp-comfyui 编写，需把 workbuddy-mcp-comfyui 发布到 PyPI 后用户方可直接使用（骨架阶段用 uvx --from <本目录> 或 python -m comfy_mcp_server 本地运行）。

• 压测报告：按 06 规范 2.2.5 完成压测并附报告——QPS ≥ 50、P50 ≤ 500ms、 P99 ≤ 3000ms、超时率 < 1%、错误率 ≤ 0.5%（stdio 形态需覆盖基础混合调用 + 突发流量 2×QPS 30s 场景；locust/k6 均可）。

• 用真实运行的 ComfyUI 跑通全部 5 个 tool 的正路径 （list → run → 轮询 → 取图；当前仅验证了连接失败错误路径）。

• 准备一个最小 API 格式示例工作流放入 README/SKILL 示例，便于用户对照。

• 提交前对照 06D 第 13.8 提交检查清单逐项复核。

• 按灵感模块 08 规范：提交 Skill 时必须同步提交 3~5 个灵感案例（case.json + output 单文件 + cover.png 720×400）。参考 <项目目录>/playbooks/asr-feishu-pipeline/ 的 case 结构