MCP Comfy Ui Builder

🚀 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

構建與運行

1. 構建（構建後會從種子填充知識）

npm run build
npm run mcp

2. 在代碼中使用知識

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註冊表快速入門進行發佈。

🔧 技術細節

命令說明

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上發佈

1. 在GitHub上創建一個新倉庫：名稱為mcp-comfy-ui-builder，可見性為公開（或私有）。不要使用README、.gitignore或許可證進行初始化（項目已經有這些文件）。
2. 添加遠程倉庫並推送：

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

3. 如果你分叉了這個倉庫，請在上述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許可證。