comfyui-animatool 0.1.0__tar.gz

comfyui_animatool-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: comfyui-animatool
+Version: 0.1.0
+Summary: Standalone MCP server + client for generating Anima-style images via a remote/local ComfyUI Server API.
+Author: Moeblack
+License: MIT
+Project-URL: Homepage, https://github.com/Moeblack/ComfyUI-AnimaTool
+Project-URL: Repository, https://github.com/Moeblack/ComfyUI-AnimaTool
+Keywords: comfyui,anima,mcp,tool-use,ai-agent,cursor
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: requests>=2.31
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == "server"
+Requires-Dist: uvicorn[standard]>=0.27; extra == "server"
+Requires-Dist: pydantic>=2.6; extra == "server"
+
+# animatool-mcp
+
+一个**独立的 MCP Server + Python 客户端**：通过**标准 ComfyUI Server API**（`/prompt`、`/history/<id>`、`/view?...`）在本地或云端 ComfyUI 上执行 Anima 工作流，并把生成图片以 **base64** 形式返回给 Cursor/Claude 等 MCP 客户端原生显示。
+
+> 重要：本项目不需要安装到 `ComfyUI/custom_nodes/`。但你仍然需要一台可访问的 ComfyUI Server（本机或云端），并且云端已经把模型权重放到 `models/` 下（按文件名加载）。
+
+---
+
+## 安装
+
+```bash
+pip install comfyui-animatool
+```
+
+---
+
+## Cursor 配置（MCP）
+
+在你的项目中创建/编辑 `.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "animatool": {
+      "command": "animatool-mcp",
+      "env": {
+        "COMFYUI_URL": "http://127.0.0.1:8188"
+      }
+    }
+  }
+}
+```
+
+然后重启 Cursor，确保 MCP 状态为 Running。
+
+---
+
+## 云端/远程 ComfyUI（推荐做法）
+
+### COMFYUI_URL 该填什么？
+
+- **本机默认**：`http://127.0.0.1:8188`
+- **带路径前缀的反代**：例如 `https://example.com/comfy/`（注意建议以 `/` 结尾，避免丢路径前缀）
+
+### 1) 最佳实践：用隧道/VPN 让 ComfyUI 变成“内网可达”
+
+ComfyUI 默认几乎没有鉴权能力，把它直接暴露到公网非常危险。建议使用：
+
+- Tailscale / ZeroTier / Cloudflare Tunnel / 自建 VPN
+- 或者反向代理 + HTTPS + 鉴权（Bearer / Basic / 自定义 Header）
+
+### 2) 配置鉴权（可选）
+
+本项目支持“有些云端需要、有些不需要”的混合场景。你可以在 `.cursor/mcp.json` 里通过 `env` 注入：
+
+#### Bearer Token
+
+```json
+{
+  "mcpServers": {
+    "animatool": {
+      "command": "animatool-mcp",
+      "env": {
+        "COMFYUI_URL": "https://your-host.example.com:8188",
+        "ANIMATOOL_BEARER_TOKEN": "YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+#### Basic Auth
+
+```json
+{
+  "mcpServers": {
+    "animatool": {
+      "command": "animatool-mcp",
+      "env": {
+        "COMFYUI_URL": "https://your-host.example.com:8188",
+        "ANIMATOOL_BASIC_USER": "user",
+        "ANIMATOOL_BASIC_PASS": "pass"
+      }
+    }
+  }
+}
+```
+
+#### 自定义 Header（通用，推荐）
+
+```json
+{
+  "mcpServers": {
+    "animatool": {
+      "command": "animatool-mcp",
+      "env": {
+        "COMFYUI_URL": "https://your-host.example.com:8188",
+        "ANIMATOOL_HEADERS_JSON": "{\"X-API-Key\":\"xxx\",\"CF-Access-Client-Id\":\"...\",\"CF-Access-Client-Secret\":\"...\"}"
+      }
+    }
+  }
+}
+```
+
+> Windows/JSON 转义提示：`ANIMATOOL_HEADERS_JSON` 本身是一个 JSON 字符串，所以内部的双引号需要转义（如上所示）。
+
+### 3) 自签名证书/SSL 校验
+
+如果你的云端是自签名证书，可以临时关闭校验（不推荐长期使用）：
+
+```json
+{
+  "mcpServers": {
+    "animatool": {
+      "command": "animatool-mcp",
+      "env": {
+        "COMFYUI_URL": "https://your-host.example.com:8188",
+        "ANIMATOOL_SSL_VERIFY": "false"
+      }
+    }
+  }
+}
+```
+
+---
+
+## CLI（可选）
+
+用于本地自测（不依赖 MCP 客户端）：
+
+```bash
+animatool-generate --comfyui-url http://127.0.0.1:8188 --json-file payload.json
+```
+
+---
+
+## 环境变量速查
+
+| 环境变量 | 说明 | 默认值 |
+|---|---|---|
+| `COMFYUI_URL` | ComfyUI Server base URL | `http://127.0.0.1:8188` |
+| `ANIMATOOL_TIMEOUT` | 请求超时秒 | `600` |
+| `ANIMATOOL_POLL_INTERVAL` | 轮询间隔秒 | `1` |
+| `ANIMATOOL_SSL_VERIFY` | SSL 校验 | `true` |
+| `ANIMATOOL_BEARER_TOKEN` | Bearer Token | *(空)* |
+| `ANIMATOOL_BASIC_USER` / `ANIMATOOL_BASIC_PASS` | Basic Auth | *(空)* |
+| `ANIMATOOL_HEADERS_JSON` | 自定义 Header JSON | *(空)* |
+| `ANIMATOOL_DOWNLOAD_IMAGES` | 是否保存图片到本地 | `false` |
+| `ANIMATOOL_OUTPUT_DIR` | 本地保存目录 | `./animatool_outputs` |
+| `COMFYUI_MODELS_DIR` | models 目录（用于本机预检查） | *(空)* |
+| `ANIMATOOL_CHECK_MODELS` | 是否启用预检查 | `true` |
+
+## 常见问题
+
+### Q: 报错连接不上 /prompt？
+
+- 检查 `COMFYUI_URL` 是否可达（云端建议先在浏览器访问 `COMFYUI_URL/system_stats`）
+- 如果有鉴权，请确认 `/prompt`、`/history`、`/view` 都在同一套鉴权规则下
+  - 常见坑：反代只给 `/prompt` 放行了，但 `/view` 被 401/403 拦住，会导致“生成成功但取图失败”
+
+### Q: 报错找不到模型？
+
+本工具提交的是一个包含 `UNETLoader/CLIPLoader/VAELoader` 的工作流模板，加载的是云端磁盘上的文件名。请确认云端 `models/` 下至少存在：
+
+- `models/diffusion_models/anima-preview.safetensors`
+- `models/text_encoders/qwen_3_06b_base.safetensors`
+- `models/vae/qwen_image_vae.safetensors`
+

comfyui_animatool-0.1.0/README.md

@@ -0,0 +1,168 @@
+# animatool-mcp
+
+一个**独立的 MCP Server + Python 客户端**：通过**标准 ComfyUI Server API**（`/prompt`、`/history/<id>`、`/view?...`）在本地或云端 ComfyUI 上执行 Anima 工作流，并把生成图片以 **base64** 形式返回给 Cursor/Claude 等 MCP 客户端原生显示。
+
+> 重要：本项目不需要安装到 `ComfyUI/custom_nodes/`。但你仍然需要一台可访问的 ComfyUI Server（本机或云端），并且云端已经把模型权重放到 `models/` 下（按文件名加载）。
+
+---
+
+## 安装
+
+```bash
+pip install comfyui-animatool
+```
+
+---
+
+## Cursor 配置（MCP）
+
+在你的项目中创建/编辑 `.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "animatool": {
+      "command": "animatool-mcp",
+      "env": {
+        "COMFYUI_URL": "http://127.0.0.1:8188"
+      }
+    }
+  }
+}
+```
+
+然后重启 Cursor，确保 MCP 状态为 Running。
+
+---
+
+## 云端/远程 ComfyUI（推荐做法）
+
+### COMFYUI_URL 该填什么？
+
+- **本机默认**：`http://127.0.0.1:8188`
+- **带路径前缀的反代**：例如 `https://example.com/comfy/`（注意建议以 `/` 结尾，避免丢路径前缀）
+
+### 1) 最佳实践：用隧道/VPN 让 ComfyUI 变成“内网可达”
+
+ComfyUI 默认几乎没有鉴权能力，把它直接暴露到公网非常危险。建议使用：
+
+- Tailscale / ZeroTier / Cloudflare Tunnel / 自建 VPN
+- 或者反向代理 + HTTPS + 鉴权（Bearer / Basic / 自定义 Header）
+
+### 2) 配置鉴权（可选）
+
+本项目支持“有些云端需要、有些不需要”的混合场景。你可以在 `.cursor/mcp.json` 里通过 `env` 注入：
+
+#### Bearer Token
+
+```json
+{
+  "mcpServers": {
+    "animatool": {
+      "command": "animatool-mcp",
+      "env": {
+        "COMFYUI_URL": "https://your-host.example.com:8188",
+        "ANIMATOOL_BEARER_TOKEN": "YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+#### Basic Auth
+
+```json
+{
+  "mcpServers": {
+    "animatool": {
+      "command": "animatool-mcp",
+      "env": {
+        "COMFYUI_URL": "https://your-host.example.com:8188",
+        "ANIMATOOL_BASIC_USER": "user",
+        "ANIMATOOL_BASIC_PASS": "pass"
+      }
+    }
+  }
+}
+```
+
+#### 自定义 Header（通用，推荐）
+
+```json
+{
+  "mcpServers": {
+    "animatool": {
+      "command": "animatool-mcp",
+      "env": {
+        "COMFYUI_URL": "https://your-host.example.com:8188",
+        "ANIMATOOL_HEADERS_JSON": "{\"X-API-Key\":\"xxx\",\"CF-Access-Client-Id\":\"...\",\"CF-Access-Client-Secret\":\"...\"}"
+      }
+    }
+  }
+}
+```
+
+> Windows/JSON 转义提示：`ANIMATOOL_HEADERS_JSON` 本身是一个 JSON 字符串，所以内部的双引号需要转义（如上所示）。
+
+### 3) 自签名证书/SSL 校验
+
+如果你的云端是自签名证书，可以临时关闭校验（不推荐长期使用）：
+
+```json
+{
+  "mcpServers": {
+    "animatool": {
+      "command": "animatool-mcp",
+      "env": {
+        "COMFYUI_URL": "https://your-host.example.com:8188",
+        "ANIMATOOL_SSL_VERIFY": "false"
+      }
+    }
+  }
+}
+```
+
+---
+
+## CLI（可选）
+
+用于本地自测（不依赖 MCP 客户端）：
+
+```bash
+animatool-generate --comfyui-url http://127.0.0.1:8188 --json-file payload.json
+```
+
+---
+
+## 环境变量速查
+
+| 环境变量 | 说明 | 默认值 |
+|---|---|---|
+| `COMFYUI_URL` | ComfyUI Server base URL | `http://127.0.0.1:8188` |
+| `ANIMATOOL_TIMEOUT` | 请求超时秒 | `600` |
+| `ANIMATOOL_POLL_INTERVAL` | 轮询间隔秒 | `1` |
+| `ANIMATOOL_SSL_VERIFY` | SSL 校验 | `true` |
+| `ANIMATOOL_BEARER_TOKEN` | Bearer Token | *(空)* |
+| `ANIMATOOL_BASIC_USER` / `ANIMATOOL_BASIC_PASS` | Basic Auth | *(空)* |
+| `ANIMATOOL_HEADERS_JSON` | 自定义 Header JSON | *(空)* |
+| `ANIMATOOL_DOWNLOAD_IMAGES` | 是否保存图片到本地 | `false` |
+| `ANIMATOOL_OUTPUT_DIR` | 本地保存目录 | `./animatool_outputs` |
+| `COMFYUI_MODELS_DIR` | models 目录（用于本机预检查） | *(空)* |
+| `ANIMATOOL_CHECK_MODELS` | 是否启用预检查 | `true` |
+
+## 常见问题
+
+### Q: 报错连接不上 /prompt？
+
+- 检查 `COMFYUI_URL` 是否可达（云端建议先在浏览器访问 `COMFYUI_URL/system_stats`）
+- 如果有鉴权，请确认 `/prompt`、`/history`、`/view` 都在同一套鉴权规则下
+  - 常见坑：反代只给 `/prompt` 放行了，但 `/view` 被 401/403 拦住，会导致“生成成功但取图失败”
+
+### Q: 报错找不到模型？
+
+本工具提交的是一个包含 `UNETLoader/CLIPLoader/VAELoader` 的工作流模板，加载的是云端磁盘上的文件名。请确认云端 `models/` 下至少存在：
+
+- `models/diffusion_models/anima-preview.safetensors`
+- `models/text_encoders/qwen_3_06b_base.safetensors`
+- `models/vae/qwen_image_vae.safetensors`
+

comfyui_animatool-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "comfyui-animatool"
+version = "0.1.0"
+description = "Standalone MCP server + client for generating Anima-style images via a remote/local ComfyUI Server API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Moeblack" }]
+keywords = ["comfyui", "anima", "mcp", "tool-use", "ai-agent", "cursor"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Multimedia :: Graphics",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "mcp>=1.0.0",
+  "requests>=2.31",
+]
+
+[project.optional-dependencies]
+server = [
+  "fastapi>=0.110",
+  "uvicorn[standard]>=0.27",
+  "pydantic>=2.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/Moeblack/ComfyUI-AnimaTool"
+Repository = "https://github.com/Moeblack/ComfyUI-AnimaTool"
+
+[project.scripts]
+animatool-mcp = "animatool_mcp.mcp_server:main"
+animatool-generate = "animatool_mcp.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+animatool_mcp = [
+  "resources/schemas/*.json",
+  "resources/workflow/*.json",
+  "resources/knowledge/*.md",
+]
+

comfyui_animatool-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

comfyui_animatool-0.1.0/src/animatool_mcp/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"
+

comfyui_animatool-0.1.0/src/animatool_mcp/cli.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .client import AnimaExecutor
+from .config import AnimaToolConfig
+
+
+def _load_json_arg(s: str) -> Dict[str, Any]:
+    try:
+        obj = json.loads(s)
+    except Exception as e:
+        raise SystemExit(f"--json 解析失败：{e}") from e
+    if not isinstance(obj, dict):
+        raise SystemExit("--json 必须是一个 JSON object")
+    return obj
+
+
+def _load_json_file(path: str) -> Dict[str, Any]:
+    p = Path(path)
+    if not p.exists():
+        raise SystemExit(f"找不到文件：{p}")
+    obj = json.loads(p.read_text(encoding="utf-8"))
+    if not isinstance(obj, dict):
+        raise SystemExit("--json-file 内容必须是一个 JSON object")
+    return obj
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description="animatool-mcp CLI (ComfyUI Server client)")
+
+    parser.add_argument("--comfyui-url", default=None, help="ComfyUI base URL（覆盖 COMFYUI_URL）")
+    parser.add_argument("--bearer-token", default=None, help="Bearer token（覆盖 ANIMATOOL_BEARER_TOKEN）")
+    parser.add_argument("--headers-json", default=None, help="自定义 headers JSON（覆盖 ANIMATOOL_HEADERS_JSON）")
+    parser.add_argument("--basic-user", default=None, help="Basic auth user（覆盖 ANIMATOOL_BASIC_USER）")
+    parser.add_argument("--basic-pass", default=None, help="Basic auth pass（覆盖 ANIMATOOL_BASIC_PASS）")
+    parser.add_argument(
+        "--ssl-verify",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="SSL 校验（覆盖 ANIMATOOL_SSL_VERIFY）",
+    )
+    parser.add_argument(
+        "--download-images",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="是否把图片保存到本地（覆盖 ANIMATOOL_DOWNLOAD_IMAGES）",
+    )
+    parser.add_argument("--output-dir", default=None, help="保存目录（覆盖 ANIMATOOL_OUTPUT_DIR）")
+
+    parser.add_argument("--json", default=None, help="直接传入 JSON object 字符串")
+    parser.add_argument("--json-file", default=None, help="从文件读取 JSON object")
+
+    args = parser.parse_args(argv)
+
+    if not args.json and not args.json_file:
+        raise SystemExit("必须提供 --json 或 --json-file")
+    if args.json and args.json_file:
+        raise SystemExit("只能二选一：--json 或 --json-file")
+
+    payload = _load_json_arg(args.json) if args.json else _load_json_file(args.json_file)
+
+    cfg_kwargs: Dict[str, Any] = {}
+    if args.comfyui_url:
+        cfg_kwargs["comfyui_url"] = str(args.comfyui_url)
+    if args.bearer_token:
+        cfg_kwargs["bearer_token"] = str(args.bearer_token)
+    if args.headers_json:
+        cfg_kwargs["headers_json"] = str(args.headers_json)
+    if args.basic_user is not None:
+        cfg_kwargs["basic_user"] = str(args.basic_user)
+    if args.basic_pass is not None:
+        cfg_kwargs["basic_pass"] = str(args.basic_pass)
+    if args.ssl_verify is not None:
+        cfg_kwargs["ssl_verify"] = bool(args.ssl_verify)
+    if args.download_images is not None:
+        cfg_kwargs["download_images"] = bool(args.download_images)
+    if args.output_dir:
+        cfg_kwargs["output_dir"] = Path(args.output_dir)
+
+    cfg = AnimaToolConfig(**cfg_kwargs)
+    ex = AnimaExecutor(config=cfg)
+    result = ex.generate(payload)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+