Metadata-Version: 2.5
Name: workbuddy-mcp-comfyui
Version: 1.0.1
Summary: WorkBuddy Connector MCP server for ComfyUI (stdio, auth_mode: token)
Author: dangsys
License: MIT
Keywords: comfyui,image generation,mcp,model-context-protocol,workbuddy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.2
Description-Content-Type: text/markdown

# ComfyUI Connector（WorkBuddy）

为腾讯 WorkBuddy 生态开发的 ComfyUI 连接器：MCP stdio + 用户自填 Token 模式
（规范 06 / 06D 附录C），让 AI 通过自然语言运行 ComfyUI 工作流并取回生成的图片。

## 目录结构

```
comfyui/
├── connector-meta.json   # 连接器元信息（type: mcp, auth_mode: token, minWorkbuddyVersion: 4.24.0）
├── mcp.json              # MCP Server 连接配置（stdio，凭证经 env 注入）
├── token-schema.json     # 用户自填 Token 表单（COMFY_URL + 可选 COMFY_TOKEN）
├── comfy_mcp_server/     # MCP Server（Python，官方 mcp SDK FastMCP）
│   ├── __init__.py
│   ├── __main__.py       # python -m comfy_mcp_server 入口
│   └── server.py         # 5 个 tool：list_checkpoints / list_samplers / run_workflow / get_status / get_image
├── skills/
│   └── SKILL.md          # Skill 文件（按 05 规范，教 AI 如何使用工具）
├── icon.svg              # 连接器图标
├── tests_smoke.py        # 冒烟测试（MCP stdio 客户端调工具，验证错误路径）
├── pyproject.toml        # hatchling 打包（PyPI 包名 workbuddy-mcp-comfyui）
└── README.md
```

依赖仅 `mcp`（v1，FastMCP）+ `httpx`（Python ≥ 3.10）。

## 工具一览

| Tool | 用途 |
|---|---|
| `list_checkpoints()` | 列出 checkpoint 模型（GET /object_info/CheckpointLoaderSimple） |
| `list_samplers()` | 列出采样器与调度器（GET /object_info/KSampler） |
| `run_workflow(workflow)` | 提交 API 格式工作流（POST /prompt），返回 prompt_id，只提交不等待 |
| `get_status(prompt_id)` | 查询进度与输出（GET /history/{id}，未完成时对照 GET /queue） |
| `get_image(filename, subfolder?, type?)` | 取回图片（GET /view），以 MCP ImageContent 返回 |

标准链路：`list_checkpoints` 确认模型名 → `run_workflow` 提交 → 轮询
`get_status` → 用 history outputs 里的 filename/subfolder/type 三元组调 `get_image`。

COMFY_TOKEN 仅在用户加了反向代理鉴权时才填；非空时 server 自动附加
`Authorization: Bearer` 头，原生 ComfyUI 留空。httpx 超时 30s。

## 本地测试

```bash
cd <项目目录>/connectors/comfyui

# 1. 语法与 JSON 校验
python3 -m py_compile comfy_mcp_server/*.py
for f in connector-meta.json mcp.json token-schema.json; do python3 -m json.tool "$f" > /dev/null && echo "$f OK"; done

# 2. 起本地构建的 server 并调用工具（ComfyUI 未运行时验证错误路径）
#    server 经 uvx --from 本地目录构建；客户端复用 home-assistant/.venv 里的 mcp 包
export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
export COMFY_URL="http://127.0.0.1:8188"
../home-assistant/.venv/bin/python tests_smoke.py
```

## 错误处理约定

- 连接失败 → 提示检查 COMFY_URL / ComfyUI 是否启动 / 网络可达性
- 401 → 仅反代鉴权场景出现，提示更新 COMFY_TOKEN
- run_workflow 400 → 摘要 ComfyUI 的 node_errors，并提示「Export (API)」导出 API 格式
- get_status 找不到任务 → 对照 /queue 区分排队中与任务不存在
- get_image 404 → 提示从 get_status 的 outputs 取有效三元组
- 缺环境变量 / 超时 / 非 200 均返回可读中文错误，不会抛栈给 AI

## 正式提交前 TODO

- [ ] **发布 PyPI 包**：`mcp.json` 已按 `uvx workbuddy-mcp-comfyui` 编写，需把
      `workbuddy-mcp-comfyui` 发布到 PyPI 后用户方可直接使用（骨架阶段用
      `uvx --from <本目录>` 或 `python -m comfy_mcp_server` 本地运行）。
- [ ] **压测报告**：按 06 规范 2.2.5 完成压测并附报告——QPS ≥ 50、P50 ≤ 500ms、
      P99 ≤ 3000ms、超时率 < 1%、错误率 ≤ 0.5%（stdio 形态需覆盖基础混合调用 +
      突发流量 2×QPS 30s 场景；locust/k6 均可）。
- [ ] 用真实运行的 ComfyUI 跑通全部 5 个 tool 的正路径
      （list → run → 轮询 → 取图；当前仅验证了连接失败错误路径）。
- [ ] 准备一个最小 API 格式示例工作流放入 README/SKILL 示例，便于用户对照。
- [ ] 提交前对照 06D 第 13.8 提交检查清单逐项复核。

- [ ] 按灵感模块 08 规范：**提交 Skill 时必须同步提交 3~5 个灵感案例**（case.json +
      output 单文件 + cover.png 720×400）。参考 <项目目录>/playbooks/asr-feishu-pipeline/ 的 case 结构
