JinDaGe - mcp-comfy-ui-builder MCP Details

article

README

🚀 mcp-comfy-ui-builder

ComfyUI节点发现 — 为Cursor/Claude提供种子知识库和MCP工具。可通过server.json和mcpName发布到MCP注册表。

🚀 快速开始

安装

npm install mcp-comfy-ui-builder

或者从源代码安装：

git clone https://github.com/MIt9/mcp-comfy-ui-builder.git && cd mcp-comfy-ui-builder && npm install

构建与运行

构建（构建后会从种子填充知识）

npm run build
npm run mcp

在代码中使用知识

import baseNodes from './knowledge/base-nodes.json' assert { type: 'json' };

✨ 主要特性

知识库：从捆绑数据中生成knowledge/base-nodes.json和node-compatibility.json（62个种子节点；同步后100 - 600+个）。建议/构建时无需外部服务。
同步：从ComfyUI-Manager获取自定义包；通过sync-nodes CLI或在MCP启动时从运行中的ComfyUI同步节点。
MCP服务器（50+工具）：节点发现、动态工作流构建器、9个模板（txt2img、txt2img_flux、img2img等）、WebSocket实时执行、批量/链式操作、模型管理、插件系统。
实时执行：通过WebSocket实现亚秒级进度更新，自动轮询作为后备；批量运行时网络流量减少约90%。

📦 安装指南

从npm安装

npm install mcp-comfy-ui-builder

从源代码安装

git clone https://github.com/MIt9/mcp-comfy-ui-builder.git
cd mcp-comfy-ui-builder
npm install

💻 使用示例

基础用法

# 构建项目
npm run build
# 启动MCP服务器
npm run mcp

高级用法

// 在代码中使用知识库
import baseNodes from './knowledge/base-nodes.json' assert { type: 'json' };

📚 详细文档

单一入口点 — 面向任务的导航：

doc/README.md — 从这里开始，基于任务的导航
doc/INDEX.md — 完整的文档列表和链接
doc/QUICK-REFERENCE.md — 命令、示例、故障排除
doc/GETTING-STARTED.md — 快速开始
doc/MCP-SETUP.md — 在Cursor/Claude中连接MCP
doc/DOCKER-SETUP.md — docker pull siniidrozd/mcp-comfy-ui-builder | MCP + ComfyUI的docker-compose
知识库：knowledge/README.md，doc/knowledge-base-usage-guide.md
工作流构建器：doc/workflow-builder.md — 模板、参数、保存/加载、ComfyUI格式
规划：ROADMAP.md，NEXT-STEPS.md，TODO.md — 当前v2.3.x，下一阶段10（QoL）
贡献：CONTRIBUTING.md
MCP注册表：server.json和package.json中的mcpName；发布npm publish后，可参考MCP注册表快速入门进行发布。

🔧 技术细节

命令说明

| 命令 | 描述 | |------|------| | npm run seed | 从种子填充知识。使用--force覆盖。 | | npm run sync-manager | 从ComfyUI-Manager更新自定义包列表 | | npm run sync-nodes | 从运行中的ComfyUI同步节点到知识库（需要COMFYUI_HOST） | | npm test | 运行测试（vitest） | | npm run mcp | 启动MCP服务器（在npm run build之后） |

MCP服务器功能

核心功能

节点发现：
- list_node_types、get_node_info、check_compatibility、suggest_nodes
- discover_nodes_live、search_nodes、sync_nodes_to_knowledge
动态工作流构建器：
- create_workflow、add_node、connect_nodes、validate_workflow
- 无需JSON操作即可以编程方式构建工作流
模板和宏：
- list_templates、build_workflow — 预构建模板（txt2img、img2img、inpainting、upscale、LoRA、ControlNet、batch）
- create_template、apply_template — 参数化模板
- list_macros、insert_macro — 可重复使用的子工作流
实时执行 📡：
- execute_workflow_sync — 通过WebSocket进度流执行（亚秒级更新）
- execute_workflow_stream — 完整事件历史收集（仅WebSocket）
- get_execution_progress — 具有节点级粒度的实时进度
- execute_batch — 并发执行，网络流量减少90%
- execute_chain — 具有数据传递的顺序工作流
资源和模型管理：
- get_system_resources — GPU/VRAM/RAM + 建议（最大分辨率、模型大小、批量大小）；在构建工作流之前首先调用以避免OOM
- list_models、check_model_exists、get_workflow_models
- 支持checkpoint、lora、vae、controlnet、upscale、embedding、clip
输出和队列：
- list_outputs、download_output、download_all_outputs
- list_queue、interrupt_execution、clear_queue
插件：
- list_plugins、reload_plugins — 仅数据的插件系统
安装（需要COMFYUI_PATH）：
- install_custom_node、install_model — 通过ComfyUI-Manager安装节点和模型

WebSocket特性

<100ms延迟用于进度更新（对比1.5s轮询）
节点级跟踪：准确查看正在执行的节点及其进度百分比
自动回退：如果WebSocket不可用，优雅地回退到轮询
共享连接：批量/链式执行使用单个WebSocket（网络流量减少90%）

设置COMFYUI_HOST环境变量以使用执行/模型/输出工具：

export COMFYUI_HOST="http://localhost:8188"

完整工具列表请参考doc/MCP-SETUP.md，实时特性请参考doc/WEBSOCKET-GUIDE.md。

运行MCP

从项目根目录，先构建项目，然后启动服务器：

npm run build
npm run mcp

或者不使用npm：node dist/mcp-server.js。服务器通过stdio（stdin/stdout）工作。更多细节 → doc/MCP-SETUP.md。

连接MCP（Cursor / Claude）

所需条件：Node.js 18+，一次性构建（npm run build），dist/mcp-server.js的绝对路径，配置更改后重启。如果服务器启动失败并显示**«spawn node ENOENT»，在command中使用node的完整路径**（运行which node并使用该路径）。请参考doc/MCP-SETUP.md → 故障排除。
最小配置（仅知识库和工作流工具）：

{
  "mcpServers": {
    "comfy-ui-builder": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/mcp-comfy-ui-builder/dist/mcp-server.js"]
    }
  }
}

如果Cursor/IDE报告«spawn node ENOENT»，在command中使用完整路径（例如"/opt/homebrew/bin/node"）。

使用ComfyUI执行（execute_workflow、get_execution_status、list_outputs等）：在服务器块中添加"env": { "COMFYUI_HOST": "http://127.0.0.1:8188" }。完整清单、可选环境变量（COMFYUI_PATH、COMFYUI_KNOWLEDGE_DIR）和故障排除请参考doc/MCP-SETUP.md。

在GitHub上发布

在GitHub上创建一个新仓库：名称为mcp-comfy-ui-builder，可见性为公开（或私有）。不要使用README、.gitignore或许可证进行初始化（项目已经有这些文件）。
添加远程仓库并推送：

git remote add origin https://github.com/MIt9/mcp-comfy-ui-builder.git
git branch -M main
git push -u origin main

如果你分叉了这个仓库，请在上述URL中用你的GitHub用户名替换MIt9。

Cursor：设置 → MCP；Claude Desktop：配置文件~/Library/Application Support/Claude/claude_desktop_config.json（macOS）。将路径替换为dist/mcp-server.js的绝对路径，然后重启应用。完整指南：doc/MCP-SETUP.md。

📄 许可证

本项目采用MIT许可证。

mcp-comfy-ui-builder