# ComfyUI MCP 服务器

这是一个 Model Context Protocol (MCP) 服务器，用于动态加载和执行 ComfyUI 工作流。它会自动扫描指定文件夹中的工作流，并将每个工作流作为独立的工具暴露给大模型。

## 功能特点

- 动态加载 ComfyUI 工作流文件夹
- 基于描述文件的参数映射系统
- 通过 WebSocket 监听工作流执行进度
- 支持 WSL2 环境（自动绕过代理）
- 灵活的参数配置和默认值
- 支持自定义输出目录

## 快速开始

### 1. 安装和构建

```bash
# 克隆或进入项目目录
cd comfyui-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 记录当前目录的绝对路径（后续配置需要）
pwd  # 例如：/home/username/comfyui-mcp
```

### 2. 配置环境

#### WSL2 用户：检测 Windows 主机 IP

```bash
bash scripts/detect-wsl2-host.sh
```

#### 创建配置文件

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
# ComfyUI 工作流文件夹路径
WORKFLOWS_DIR=./workflows

# ComfyUI 服务器配置
COMFYUI_HOST=172.22.240.1  # WSL2 中的 Windows 主机 IP
COMFYUI_PORT=8000

# 绕过系统代理（WSL2 环境建议开启）
BYPASS_PROXY=true
```

### 3. 测试连接

```bash
node test-connection.js
```

### 4. 在 Claude Desktop 中配置

编辑 Claude Desktop 配置文件：

- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`  
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

添加 MCP 服务器配置（使用绝对路径）：

```json
{
  "mcpServers": {
    "comfyui": {
      "command": "npx",
      "args": ["/absolute/path/to/comfyui-mcp"],
      "env": {
        "WORKFLOWS_DIR": "/absolute/path/to/comfyui-mcp/workflows",
        "COMFYUI_HOST": "172.22.240.1",
        "COMFYUI_PORT": "8000",
        "BYPASS_PROXY": "true"
      }
    }
  }
}
```

**示例配置（WSL2）**：
```json
{
  "mcpServers": {
    "comfyui": {
      "command": "npx",
      "args": ["/home/yarnb/xcan/comfyui-mcp"],
      "env": {
        "WORKFLOWS_DIR": "/home/yarnb/xcan/comfyui-mcp/workflows",
        "COMFYUI_HOST": "172.22.240.1",
        "COMFYUI_PORT": "8000",
        "BYPASS_PROXY": "true"
      }
    }
  }
}
```

**注意事项**：
- `WORKFLOWS_DIR` 必须是绝对路径
- `COMFYUI_HOST` 使用检测脚本获取的 IP
- 配置后需要重启 Claude Desktop

### 5. 验证安装

重启 Claude Desktop 后，在对话中输入：
```
使用 Qwen 模型生成一张中国山水画
```

Claude 会自动识别并调用对应的工具。

### 6. 使用自定义输出目录

所有工具都支持指定输出目录参数：
```
使用 run_text_to_image_workflow_flux_schnell 工具生成图片，
prompt: "beautiful sunset", 
output_dir: "/home/username/my_images"
```

如果不指定 `output_dir`，文件将保存到默认的 `outputs` 目录。

## 工作流组织结构

工作流按照功能分类组织，每个工作流都在独立的文件夹中：

```
workflows/
├── text-to-image/                      # 文本生成图像
│   └── image_qwen_image/               # Qwen 视觉语言模型
├── image-to-image/                     # 图像转图像/编辑
│   ├── omnigen2_image_edit/            # OmniGen2 智能编辑
│   ├── qwen_image_edit/                # Qwen 图像编辑
│   ├── qwen_image_controlnet_patch/    # Qwen + ControlNet Patch
│   ├── qwen_image_instantx_controlnet/ # Qwen + InstantX ControlNet
│   ├── qwen_image_union_control/       # Qwen + Union Control
│   ├── rmbg_multiple_models/           # 多模型背景移除
│   └── yolo_cropper/                   # YOLO 智能裁剪
├── image-to-video/                     # 图像生成视频
│   ├── wan2_2_14b_i2v/                 # WAN 2.2 14B 图生视频
│   └── wan2_2_14b_flf2v/               # WAN 2.2 14B 首尾帧插值
├── text-to-video/                      # 文本生成视频
│   └── wan2_2_14b_t2v/                 # WAN 2.2 14B 文生视频
├── text-to-audio/                      # 文本生成音频
│   ├── audio_ace_step_1_t2a_instrumentals/ # ACE 纯器乐生成
│   └── audio_ace_step_1_t2a_song/      # ACE 带歌词音乐生成
└── audio-to-audio/                     # 音频编辑
    └── audio_ace_step_1_a2a_editing/   # ACE 音频编辑

每个工作流文件夹包含：
├── workflow.json                       # ComfyUI 导出的工作流 JSON（统一命名）
├── descriptor.json                     # 参数描述文件（包含分类信息）
└── README.md                           # 工作流详细说明（可选）
```

### 描述文件格式

`descriptor.json` 定义了工作流的参数及其在 JSON 中的路径：

```json
{
  "description": "工作流的描述",
  "parameters": [
    {
      "name": "prompt",           // 参数名称
      "type": "string",           // 参数类型（string/number/boolean）
      "subtype": "image",         // 子类型（可选，用于标识特殊参数如图片）
      "description": "描述词",    // 参数说明
      "required": true,           // 是否必需
      "path": "6.inputs.text",    // JSON 路径
      "default": "默认值"         // 默认值（可选）
    }
  ]
}
```

### 参数路径说明

`path` 字段使用点号分隔的路径来定位 JSON 中的值：
- `"6.inputs.text"` 对应 `workflow[6].inputs.text`
- `"3.inputs.seed"` 对应 `workflow[3].inputs.seed`

## 添加新工作流

### 步骤 1：导出 ComfyUI 工作流

1. 在 ComfyUI 中创建或打开工作流
2. 点击菜单 → Save (API Format)
3. 保存 JSON 文件

### 步骤 2：创建工作流文件夹

根据工作流类型选择正确的分类目录：
- `text-to-image/` - 文本生成图像
- `image-to-image/` - 图像编辑、转换、处理
- `image-to-video/` - 图像生成视频
- `text-to-video/` - 文本生成视频
- `text-to-audio/` - 文本生成音频/音乐
- `audio-to-audio/` - 音频编辑、风格转换

```bash
# 例如添加一个新的文生图工作流
mkdir workflows/text-to-image/my_workflow

# 复制工作流文件（必须命名为 workflow.json）
cp path/to/exported.json workflows/text-to-image/my_workflow/workflow.json
```

### 步骤 3：创建描述文件 (descriptor.json)

创建 `workflows/[category]/my_workflow/descriptor.json`：

```json
{
  "description": "详细的工具能力描述（参考下方编写指南）",
  "category": "text-to-image",
  "parameters": [
    {
      "name": "prompt",
      "type": "string",
      "description": "参数的详细说明，包含使用建议",
      "required": true,
      "path": "6.inputs.text",
      "default": "默认值示例"
    },
    {
      "name": "input_image",
      "type": "string",
      "subtype": "image",  // 标记为图片参数，系统会自动处理上传
      "description": "输入图片路径",
      "required": true,
      "path": "10.inputs.image",
      "default": ""
    }
  ]
}
```

### 📝 描述文件编写指南

#### 1. 工具描述 (description) 编写要点

**必须包含的信息：**
- **核心功能**：这个工具能做什么
- **技术特点**：使用什么模型/技术，有何独特优势
- **应用场景**：适合什么场景使用
- **关键参数**：重要的参数说明（如分辨率、时长等）
- **特殊要求**：如必须提供的输入

**⚠️ 重要：参数默认值处理规则**
- **必填参数（required: true）**：
  - 不应设置默认值，或设置为空字符串 `""`
  - 用户必须明确提供输入值
  - 例如：正面提示词、输入图片路径、音频描述等
- **非必填参数（required: false）**：
  - 影响创作结果的参数（如负面提示词）应设为 `null` 而非具体值
  - 技术参数（如 steps、cfg、seed）可以有合理的默认值
  - 避免预设内容影响用户的创作意图

**好的描述示例：**
```json
{
  "description": "使用 FLUX.1 Schnell 极速版模型，仅需4步即可生成高质量图像，是速度最快的文生图模型。特别优化了生成速度，适合需要快速预览、实时交互或批量生成的场景。虽然步数少但质量依然出色，支持1024x1024及更高分辨率。是快速原型设计的首选。"
}
```

**描述模板：**
```
使用 [模型名称] [核心功能描述]。[技术特点说明]。[适用场景列举]。[关键能力或限制]。[特殊说明]。
```

#### 2. 参数描述 (parameter description) 编写要点

**必须说明的内容：**
- 参数的作用
- 可接受的值或范围
- 对结果的影响
- 使用建议

**参数描述示例：**

```json
{
  "parameters": [
    {
      "name": "prompt",
      "description": "描述想要生成的图像内容，支持中英文，越详细效果越好"
    },
    {
      "name": "denoise", 
      "description": "去噪强度 (0-1)：0.1-0.3轻微修改，0.4-0.7中等变化，0.8-1.0大幅重绘"
    },
    {
      "name": "duration",
      "description": "音频时长（秒）：1-5秒短音效，10-30秒音乐片段，30-180秒完整作品"
    },
    {
      "name": "input_image",
      "type": "string",
      "subtype": "image",  // 重要：图片参数必须添加此标记
      "description": "输入图片的绝对路径，支持 jpg/png 等常见格式"
    }
  ]
}
```

**特殊参数类型说明：**

- **图片参数**：必须添加 `"subtype": "image"` 标记
  - 系统会自动检测并处理图片上传
  - 支持本地文件路径（自动上传）或已上传的文件名
  - 支持多个图片输入（如 start_image、end_image）

- **输出目录参数**（自动添加到所有工具）：
  - 参数名：`output_dir`
  - 类型：string（可选）
  - 功能：指定生成文件的保存位置
  - 示例：`"/home/username/project/assets"`
  - 默认：项目根目录下的 `outputs` 文件夹

#### 3. 分类选择指南

| 分类 | 说明 | 工具名称格式 |
|------|------|------------|
| text-to-image | 根据文本生成图像 | run_text_to_image_workflow_[name] |
| image-to-image | 修改或转换现有图像 | run_image_to_image_workflow_[name] |
| image-to-video | 静态图像转动态视频 | run_image_to_video_workflow_[name] |
| text-to-video | 根据文本生成视频 | run_text_to_video_workflow_[name] |
| text-to-audio | 根据文本生成音频/音乐 | run_text_to_audio_workflow_[name] |
| audio-to-audio | 编辑或转换现有音频 | run_audio_to_audio_workflow_[name] |

### 步骤 4：创建 README.md（可选但推荐）

为工作流创建详细文档 `workflows/[category]/my_workflow/README.md`：

```markdown
# 工作流名称

## 概述
工作流的详细介绍

## 工作流特点
- 特点1
- 特点2

## 主要参数
详细的参数说明

## 使用示例
具体的使用案例

## 注意事项
使用时的注意点
```

### 步骤 5：查找参数路径

1. 打开工作流 JSON 文件
2. 找到需要暴露的参数节点
3. 记录节点 ID 和输入字段名
4. 组合成路径格式：`节点ID.inputs.字段名`

例如，在 JSON 中找到：
```json
{
  "6": {
    "inputs": {
      "text": "提示词内容"
    }
  }
}
```
对应路径为：`6.inputs.text`

### 步骤 6：重启 Claude Desktop

添加新工作流后，需要重启 Claude Desktop 以重新加载工作流。

## 📚 描述编写最佳实践

### 让 AI 更好理解你的工具

#### ✅ 好的工具描述
```json
"description": "基于现有图像进行智能修改和风格转换的强大工具。可以将照片转换为不同艺术风格（油画、水彩、动漫等），修改图像内容（更换背景、改变季节、调整光线），或增强图像质量。通过调节去噪强度(denoise)精确控制修改程度，从轻微调整到完全重绘。必须提供输入图片路径。"
```

**为什么好？**
- 明确说明了工具的**核心能力**（修改、转换）
- 列举了**具体功能**（风格转换、内容修改、质量增强）
- 提供了**关键参数**说明（denoise）
- 强调了**必需输入**（图片路径）

#### ❌ 差的工具描述
```json
"description": "图生图工作流"
```

**为什么差？**
- 太简短，AI 不知道具体能做什么
- 没有说明使用场景
- 缺少技术特点

### 参数描述技巧

#### 1. 对于数值参数，提供范围和效果说明
```json
{
  "name": "cfg",
  "description": "CFG强度(1-20)：1-3创意自由，4-7平衡效果，8-20严格遵循提示"
}
```

#### 2. 对于文件路径，说明格式要求
```json
{
  "name": "input_image",
  "description": "输入图片的绝对路径，支持 jpg/png/webp 格式，建议分辨率不低于512x512"
}
```

#### 3. 对于选择型参数，列出所有选项
```json
{
  "name": "style",
  "description": "艺术风格：realistic(写实)、anime(动漫)、oil_painting(油画)、watercolor(水彩)"
}
```

#### 4. 对于复杂参数，提供示例
```json
{
  "name": "prompt",
  "description": "图像描述，示例：'阳光明媚的海滩，椰子树，蓝天白云，4K高清，专业摄影'"
}
```

### 常用描述词汇参考

**技术特点词汇：**
- 极速生成、高质量、专业级、优化版、增强版
- 智能识别、精确控制、自动优化、实时处理
- 支持批量、多格式兼容、高分辨率

**应用场景词汇：**
- 适合...场景、特别擅长...、专为...优化
- 创意设计、专业制作、快速原型、批量处理
- 个人创作、商业应用、教育演示

**能力描述词汇：**
- 可以...、支持...、能够...、实现...
- 生成、转换、修改、增强、优化、创建
- 自定义、调节、控制、设置

### 📖 相关文档

- [Negative Prompt 使用规范](docs/negative_prompt_guide.md) - 了解如何正确编写负向提示词

### ✔️ 添加工作流前的检查清单

在添加新工作流前，请确保：

- [ ] 工作流放在正确的分类文件夹中
- [ ] workflow.json 文件名正确
- [ ] descriptor.json 包含 category 字段
- [ ] 工具描述清晰说明了能力和使用场景
- [ ] 每个参数都有详细的描述
- [ ] 必需参数都标记为 required: true
- [ ] 提供了合理的默认值
- [ ] 参数路径 (path) 正确对应 JSON 节点
- [ ] （可选）创建了 README.md 详细文档

## 开发模式

### 本地开发

```bash
# 开发模式（自动重载）
npm run dev

# 重新构建
npm run build
```

### 直接运行

```bash
# 直接运行编译后的文件
node dist/index.js

# 或在 Claude 配置中使用
{
  "command": "node",
  "args": ["/absolute/path/to/comfyui-mcp/dist/index.js"]
}
```

## 故障排除

### Claude Desktop 无法找到工具

1. 确认项目路径正确（使用绝对路径）
2. 检查 Claude 配置文件格式是否正确
3. 查看 Claude 的开发者工具日志

### WSL2 连接问题

如果无法连接到 Windows 上的 ComfyUI：

1. 确保 ComfyUI 启动时使用 `--listen 0.0.0.0` 参数
2. 检查 Windows 防火墙是否允许端口访问
3. 运行 `scripts/detect-wsl2-host.sh` 重新检测 IP
4. 确保 `BYPASS_PROXY=true` 已设置

### 工作流加载失败

检查以下几点：
- 工作流文件夹名称与内部 JSON 文件名一致
- `descriptor.json` 格式正确
- JSON 路径与实际工作流结构匹配
- 查看控制台错误信息

### npx 执行错误

如果 `npx` 无法执行：

```bash
# 确保使用绝对路径
npx /home/username/comfyui-mcp

# 或直接使用 node
node /home/username/comfyui-mcp/dist/index.js
```

## 工作原理

1. **工作流加载**：启动时扫描 `workflows` 文件夹的分类目录，加载所有工作流
2. **工具注册**：每个工作流注册为 `run_{category}_workflow_{name}` 格式的工具
   - 例如：`run_text_to_image_workflow_flux_schnell`
   - 例如：`run_image_to_video_workflow_image_to_video_wan`
3. **参数处理**：接收输入参数，根据描述文件的路径映射修改工作流 JSON
4. **执行监控**：通过 WebSocket 连接 ComfyUI，监听执行进度
5. **结果返回**：执行完成后返回生成结果

## 示例工作流

项目包含多个分类的专业工作流：

### 文本生成图像 (text-to-image)
- `run_text_to_image_workflow_image_qwen_image` - Qwen 视觉语言模型，支持中英文提示词

### 图像编辑与处理 (image-to-image)
- `run_image_to_image_workflow_omnigen2_image_edit` - OmniGen2 多模态图像编辑
- `run_image_to_image_workflow_qwen_image_edit` - Qwen 智能图像编辑
- `run_image_to_image_workflow_qwen_image_controlnet_patch` - Qwen + ControlNet 精确控制
- `run_image_to_image_workflow_qwen_image_instantx_controlnet` - Qwen + InstantX 深度控制
- `run_image_to_image_workflow_qwen_image_union_control` - Qwen + Union Control 边缘控制
- `run_image_to_image_workflow_rmbg_multiple_models` - 多模型背景移除
- `run_image_to_image_workflow_yolo_cropper` - YOLO 智能物体检测与裁剪

### 视频生成 (image-to-video & text-to-video)
- `run_image_to_video_workflow_wan2_2_14b_i2v` - WAN 2.2 14B 图片转动态视频
- `run_image_to_video_workflow_wan2_2_14b_flf2v` - WAN 2.2 14B 首尾帧智能插值
- `run_text_to_video_workflow_wan2_2_14b_t2v` - WAN 2.2 14B 文本生成视频

### 音频与音乐生成 (text-to-audio & audio-to-audio)
- `run_text_to_audio_workflow_audio_ace_step_1_t2a_instrumentals` - ACE 纯器乐音乐生成
- `run_text_to_audio_workflow_audio_ace_step_1_t2a_song` - ACE 带歌词歌曲生成
- `run_audio_to_audio_workflow_audio_ace_step_1_a2a_editing` - ACE 音频智能编辑

使用示例：
```python
# 文本生成图像
run_text_to_image_workflow_image_qwen_image:
  prompt: "山水画，中国传统风格，青山绿水"
  width: 1024
  height: 1024
  output_dir: "/home/user/outputs"
  output_name: "chinese_painting"

# 智能图像编辑
run_image_to_image_workflow_qwen_image_edit:
  input_image: "/path/to/image.jpg"
  positive_prompt: "去除图片中的文字水印"
  output_dir: "/home/user/outputs"
  output_name: "clean_image"

# 背景移除
run_image_to_image_workflow_rmbg_multiple_models:
  input_image: "/path/to/product.jpg"
  model: "BEN2"
  output_dir: "/home/user/outputs"
  output_name: "transparent_bg"

# 图片生成视频
run_image_to_video_workflow_wan2_2_14b_i2v:
  input_image: "/path/to/landscape.jpg"
  positive_prompt: "缓慢的云朵飘动，阳光穿过云层"
  length: 81
  fps: 16
  output_dir: "/home/user/videos"
  output_name: "animated_landscape"

# 音乐生成
run_text_to_audio_workflow_audio_ace_step_1_t2a_song:
  tags: "anime, j-pop, female vocals, piano, emotional"
  lyrics: "[verse]\n春の風が吹いて\n桜の花びら舞う\n[chorus]\n君と歩いた道\n忘れない思い出"
  seconds: 120
  output_dir: "/home/user/music"
  output_name: "spring_song"
```

## 环境变量说明

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `WORKFLOWS_DIR` | 工作流文件夹路径 | `./workflows` |
| `COMFYUI_HOST` | ComfyUI 服务器地址 | `localhost` |
| `COMFYUI_PORT` | ComfyUI 服务器端口 | `8000` |
| `BYPASS_PROXY` | 是否绕过系统代理 | `true` |

## 许可证

MIT