心智模型
ComfyUI MCP 是盖在正在运行的 ComfyUI 实例上面的一层薄、描述清楚的封装。大多数工具 通过它的 HTTP/WebSocket API 交谈，所以无论 ComfyUI 在本地、远程（--comfyui-url）还是
Comfy Cloud（COMFYUI_API_KEY），行为都一样。
1
生成与工作流 → ComfyUI HTTP API
generate_image、enqueue_workflow、队列 / 历史 / 系统状态，以及工作流编写工具，
都会调用 ComfyUI 的 /prompt、/queue、/history、/object_info 等。入队是
fire-and-forget：你立刻拿到一个 prompt_id，结果通过完成通知到达。云端模式下，
另一套 cloud-client 把同样的操作用 X-API-Key 派发到 cloud.comfy.org。2
自定义节点与模型 → ComfyUI-Manager（HTTP），并带回退到子进程
节点安装 / 更新 / 快照 / 二分，以及工作流依赖安装，优先走
ComfyUI-Manager HTTP API
（因此对远程实例也能用），API 做不到的部分再回退到对着本地安装跑
cm-cli / git /
pip/uv。3
安装与文件系统操作 → 仅本地
安装 ComfyUI、更新核心、删除模型文件、读服务器日志、列出输出目录，都作用在本地
文件系统上。它们需要已知的
COMFYUI_PATH，在远程或云端模式下会返回明确错误。4
WebSocket → 本地 + 远程，不含云端
任务完成通知在可用时挂到 ComfyUI 的 WebSocket。Comfy Cloud 没有 WebSocket ——
任务监视器会落到已有的 HTTP 轮询路径。
经验法则：任何读取或运行已连接服务器的事情，三种模式都能用；任何安装软件或
碰磁盘上文件的事情，都需要本地安装。完整功能对照表见
配置 → 部署模式。
自愈：队列 / 渲染监视狗
以前，一个卡住的高分辨率采样步骤会让智能体在它看不见也杀不掉的僵尸渲染后面继续堆任务。 三道尽力而为的护栏补上这个缺口，于是智能体不会再对着卡住的渲染盲目重入队：- 背压 —— 已经有渲染在跑时，
panel_run会在结果里追加一条 QUEUE WARNING， 这样智能体就不会再往后面堆。 - 停滞检测 —— 一条被动 WebSocket 跟踪正在跑的 prompt / 节点 / 进度；某一步超过
阈值还没推进
（
COMFYUI_MCP_STALL_S，默认 180 秒） 时，会在智能体下一轮前面预置一行 STALL/BACKLOG 说明。 - 升级取消 ——
queue（action:“cancel”）会中断、核实任务确实停了 （在COMFYUI_MCP_INTERRUPT_S内，默认 30 秒）， 然后升级到/free，如果它还不肯死就报告渲染 WEDGED（并建议restart_comfyui）；clear_pending在同一次调用里丢掉所有待处理任务。
get_image (action:"analyze_color") 在不走视觉往返的情况下推理一张图的颜色
（主色板、平均 + 亮度统计、对比度检查）。
工具分类
图像生成
工作流执行
工作流编写
工作流库
资源与图像
模型
自定义节点
API 节点
安装与环境
进程控制
默认值、统计与技能
工具参考由实时 MCP 工具 schema 生成（
npm run docs:gen），所以它不会和代码脱节。