@metabrain-labs/comfyui-mcp-server 1.0.0

package/.env

@@ -0,0 +1,179 @@
+# ! THE FOLLOWING ANNOTATED CONFIGURATION ITEMS ARE FEATURES NOT SUPPORTED IN THE CURRENT VERSION BUT HAVE BEEN ADDED TO THE TODO LIST.
+# ! 下述注释起来的配置项均为当前版本不支持但已列入todo-list中的功能
+
+# =============================================================================
+# ComfyUI MCP Server - Configuration
+# 配置文件说明：
+#   [User Config]   用户配置 —— 根据您的部署环境修改此区块
+#   [System Config] 系统配置 —— 保持默认即可，无需修改
+# =============================================================================
+
+
+# =============================================================================
+# [User Config] 用户配置
+# Modify this section based on your deployment environment.
+# 根据您的部署环境修改以下内容。
+# =============================================================================
+
+# Language for MCP tool descriptions.
+# MCP 工具描述的显示语言。可选值：en（英文）| zh（中文）
+LOCALE=en
+
+# -----------------------------------------------------------------------------
+# ComfyUI Server Connection / ComfyUI 服务器连接
+# -----------------------------------------------------------------------------
+
+# Full URL of your ComfyUI server. No trailing slash.
+# ComfyUI 服务器的完整地址，末尾不加斜杠。
+COMFY_UI_SERVER_IP="http://192.168.0.171:8188"
+
+# Host (without protocol) and port. Used separately for WebSocket connections.
+# 主机名（不含协议头）和端口号，WebSocket 连接时单独使用。
+COMFY_UI_SERVER_HOST="192.168.0.171"
+COMFY_UI_SERVER_PORT="8188"
+
+# -----------------------------------------------------------------------------
+# Sync Mode / 同步模式
+# -----------------------------------------------------------------------------
+
+# Controls how the server detects workflow updates from ComfyUI.
+# 控制服务器检测 ComfyUI 工作流更新的方式。
+#
+#   timed  — Background loop polls ComfyUI at a fixed interval. (default)
+#             后台循环以固定间隔轮询 ComfyUI。（默认）
+#
+#   push   — ComfyUI plugin sends real-time save events; long fallback poll as safety net.
+#             Requires COMFY_UI_INSTALL_PATH (must be on same machine as ComfyUI).
+#             ComfyUI 插件实时推送保存事件；兜底长轮询作为安全网。
+#             需要配置 COMFY_UI_INSTALL_PATH（需与 ComfyUI 同机部署）。
+#
+#   manual — No background loop. Refresh only when tools are called
+#             (get_workflows_catalog / mount_workflow / queue_prompt).
+#             无后台循环，仅在调用工具时按需刷新
+#             （get_workflows_catalog / mount_workflow / queue_prompt）。
+#
+# SYNC_MODE=manual
+
+# Polling interval in seconds for timed mode.
+# timed 模式的轮询间隔（秒）。
+# SYNC_POLL_INTERVAL_SECONDS=3
+
+# Fallback polling interval in seconds for push mode (safety net for missed events).
+# push 模式的兜底轮询间隔（秒），用于捕捉遗漏的推送事件。
+# SYNC_EVENT_FALLBACK_INTERVAL_SECONDS=300
+
+# Cooldown in seconds between manual mode refreshes.
+# Prevents excessive ComfyUI API calls when tools are called in quick succession.
+# manual 模式两次刷新之间的冷却时间（秒），防止工具短时间内连续调用时频繁请求 ComfyUI API。
+# ONDEMAND_REFRESH_COOLDOWN_SECONDS=30
+
+# -----------------------------------------------------------------------------
+# Push Mode Plugin / 推送模式插件（仅 SYNC_MODE=push 时需要）
+# -----------------------------------------------------------------------------
+
+# Absolute path to your LOCAL ComfyUI installation root directory.
+# Required when SYNC_MODE=push: MCP Server will automatically deploy a lightweight
+# backend plugin that pushes workflow save events in real-time.
+# Leave blank if ComfyUI runs on a remote machine or if using timed/manual mode.
+#
+# 本地 ComfyUI 安装目录的绝对路径。
+# 使用 SYNC_MODE=push 时必填：MCP Server 会自动部署一个超轻量推送插件，
+# 实现工作流保存后的实时推送通知。
+# 若 ComfyUI 部署在远端机器上，或使用 timed/manual 模式，请留空。
+#
+# Windows 示例 / Example: COMFY_UI_INSTALL_PATH=C:/ComfyUI
+# Linux   示例 / Example: COMFY_UI_INSTALL_PATH=/home/user/ComfyUI
+# COMFY_UI_INSTALL_PATH=
+
+# -----------------------------------------------------------------------------
+# Workflow Marker Patterns / 工作流标识符正则表达式
+# -----------------------------------------------------------------------------
+
+# Regex identifying the workflow name node (title of a PrimitiveStringMultiline node).
+# Must contain ONE capture group that extracts the MCP tool name.
+# Default matches titles like "==my_workflow=="
+# 工作流名称节点的标识正则（PrimitiveStringMultiline 节点的 title）。
+# 必须含一个捕获组提取工具名，默认匹配 ==名称== 格式。
+WORKFLOW_NAME_REGEX="==(.+?)=="
+
+# Regex identifying configurable parameter nodes.
+# Must contain ONE capture group that extracts the parameter description.
+# Default matches titles like "=>prompt text"
+# 参数节点的标识正则，必须含一个捕获组提取参数描述，默认匹配 =>描述 格式。
+WORKFLOW_PARAM_REGEX="^=>"
+
+# =============================================================================
+# [System Config] 系统配置
+# Internal settings — change only if you know what you are doing.
+# 内部运行参数，通常无需修改。
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# MCP Server / MCP 服务地址
+# -----------------------------------------------------------------------------
+
+# MCP server bind address and listening port.
+# MCP 服务器的监听地址和端口（MCP 客户端连接此处）。
+MCP_SERVER_URL="http://192.168.0.192:8189/mcp"
+MCP_SERVER_IP="192.168.0.192"
+MCP_SERVER_PORT="8189"
+
+# -----------------------------------------------------------------------------
+# Logging / 日志配置
+# -----------------------------------------------------------------------------
+
+# Minimum log level written to stderr.
+# 输出到 stderr 的最低日志级别。
+# DEBUG | INFO | WARNING | ERROR  (default: INFO)
+# LOG_LEVEL=INFO
+
+# Optional absolute path for a log file.
+# When set, logs are written to BOTH stderr and this file.
+# Leave blank to disable file logging.
+# 可选：日志文件的绝对路径。填写后同时输出到 stderr 和文件。留空则不开启文件日志。
+# LOG_FILE=
+
+# Log file rotation size. Default: 10 MB
+# 日志文件切割大小，默认 10 MB。
+# LOG_ROTATE=10 MB
+
+# Number of rotated log files to retain. Default: 7
+# 保留历史日志文件个数，默认 7。
+# LOG_RETAIN=7
+
+# -----------------------------------------------------------------------------
+# Tool Name Overrides / 工具名称覆盖（可选）
+# -----------------------------------------------------------------------------
+# Override the MCP tool names registered with the host.
+# Useful when the host enforces naming conventions or to avoid conflicts.
+# Leave commented out to use the defaults shown below.
+#
+# 覆盖注册到 MCP Host 的工具名称。
+# 可用于满足 Host 的命名规范或避免冲突，留空则使用默认值。
+
+# ---- GetCoreManual | 获取项目核心手册
+# TOOL_NAME_GET_CORE_MANUAL=get_core_manual
+# ---- GetWorkflowCatalog | 获取工作流目录
+# TOOL_NAME_GET_WORKFLOWS_CATALOG=get_workflows_catalog
+# ---- GetWorkAPI | 获取工作流详情
+# TOOL_NAME_GET_WORKFLOW_API=get_workflow_API
+# ---- MountWorkflow | 挂载工作流
+# TOOL_NAME_MOUNT_WORKFLOW=mount_workflow
+# ---- ExecuteWorkflow | 执行指定工作流
+# TOOL_NAME_QUEUE_PROMPT=queue_prompt
+# ---- ExecuteCustomWorkflow | 执行自定义工作流
+# TOOL_NAME_QUEUE_CUSTOM_PROMPT=queue_custom_prompt
+# ---- SaveCustomWorkflow | 保存自定义工作流
+# TOOL_NAME_SAVE_CUSTOM_WORKFLOW=save_custom_workflow
+# ---- SaveTaskAssets | 保存生成资产
+# TOOL_NAME_SAVE_TASK_ASSETS=save_task_assets
+# ---- UploadAssets | 上传文件
+# TOOL_NAME_UPLOAD_ASSETS=upload_assets
+# ---- InterruptPrompt | 取消任务
+# TOOL_NAME_INTERRUPT_PROMPT=interrupt_prompt
+# ---- GetPromptResult | 获取任务结果
+# TOOL_NAME_GET_PROMPT_RESULT=get_prompt_result
+# ---- GetSystemStatus | 获取系统状态
+# TOOL_NAME_GET_SYSTEM_STATUS=get_system_status
+# ---- ListModels | 检索模型文件
+# TOOL_NAME_LIST_MODELS=list_models

package/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master, develop]
+  pull_request:
+    branches: [main, master, develop]
+
+jobs:
+  test:
+    name: Test (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+      fail-fast: false
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run type check
+        run: npm run type-check
+
+      - name: Run tests
+        run: npm run test:ci
+
+      - name: Upload coverage to Codecov
+        if: matrix.node-version == '20.x'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage/lcov.info
+          fail_ci_if_error: false
+
+  build:
+    name: Build Check
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check TypeScript compilation
+        run: npx tsc --noEmit

package/.husky/pre-commit

@@ -0,0 +1,11 @@
+echo "🔍 Running pre-commit checks..."
+
+# Run type checking
+echo "📦 Running TypeScript type check..."
+npm run type-check || exit 1
+
+# Run tests (only related files with lint-staged, or full test if no staged files match)
+echo "🧪 Running tests..."
+npx lint-staged || exit 1
+
+echo "✅ Pre-commit checks passed!"

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetaBrain-Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.