comfyui-mcp 0.9.2 → 0.9.3

package/llms-install.md

@@ -0,0 +1,139 @@
+# comfyui-mcp — Install Guide for AI Agents
+
+This document tells an AI agent (Cline, Claude Code, Cursor, etc.) how to
+install and configure **comfyui-mcp** in one shot. It is a focused subset of
+the project [README](./README.md) — see that file for full documentation.
+
+## What you are installing
+
+An MCP server that lets the user's AI assistant drive
+[ComfyUI](https://github.com/comfyanonymous/ComfyUI): generate images, run and
+author workflows, manage models and custom nodes, and control the server.
+**86 MCP tools** across the categories shown in
+[docs/tools/](https://comfyui-mcp.artokun.io/docs/tools/image-generation).
+
+## Prerequisites
+
+- **Node.js ≥ 22.** Confirm with `node --version`; install via
+  [nodejs.org](https://nodejs.org/) or `nvm` if missing.
+- The package is published to npm as **`comfyui-mcp`** and runs via `npx` — no
+  global install required.
+- The server needs a ComfyUI to talk to. **Three options**, pick one with the
+  user (ask if unclear):
+
+  1. **Local ComfyUI** — the user is running ComfyUI on the same machine. The
+     server auto-detects the install path and port (8188 → 8000 fallback). No
+     extra config needed.
+  2. **Remote ComfyUI** — the user runs ComfyUI on a different host
+     (RunPod, VPS, LAN box). Pass `--comfyui-url <url>` or set
+     `COMFYUI_URL` env. When the host is non-loopback, local-FS auto-detection
+     is suppressed.
+  3. **Comfy Cloud** — the user has a [cloud.comfy.org](https://cloud.comfy.org)
+     API key. Set `COMFYUI_API_KEY` env. The server routes HTTP primitives to
+     the cloud; local-only tools throw `CLOUD_UNSUPPORTED`.
+
+## Add to the MCP client config
+
+### Claude Code / Claude Desktop (`~/.claude/settings.json`)
+
+**Local ComfyUI** (most common):
+
+```json
+{
+  "mcpServers": {
+    "comfyui": {
+      "command": "npx",
+      "args": ["-y", "comfyui-mcp"]
+    }
+  }
+}
+```
+
+**Remote ComfyUI:**
+
+```json
+{
+  "mcpServers": {
+    "comfyui": {
+      "command": "npx",
+      "args": ["-y", "comfyui-mcp", "--comfyui-url", "https://my-comfy.example.com"]
+    }
+  }
+}
+```
+
+**Comfy Cloud:**
+
+```json
+{
+  "mcpServers": {
+    "comfyui": {
+      "command": "npx",
+      "args": ["-y", "comfyui-mcp"],
+      "env": {
+        "COMFYUI_API_KEY": "<ask the user for their cloud.comfy.org key>"
+      }
+    }
+  }
+}
+```
+
+### Cline / Cursor / generic MCP
+
+Use the same `command` + `args` shape (Cline expects `command` + `args` in
+its `cline_mcp_settings.json`; Cursor expects similar in its MCP settings
+panel).
+
+## Optional environment variables
+
+Set in the `env` block above. None are required for the local-default flow.
+
+- `COMFYUI_HOST` / `COMFYUI_PORT` — override host/port (defaults: auto-detect)
+- `COMFYUI_PATH` — explicit ComfyUI install path (auto-detected on Mac / Linux
+  / Windows when unset)
+- `COMFYUI_DOWNLOAD_CACHE_DIR` — model download cache (default
+  `~/.comfyui-mcp/cache`)
+- `COMFYUI_LRU_CACHE_SIZE_GB` — cap the cache; `0` disables eviction
+- `CIVITAI_API_TOKEN`, `HUGGINGFACE_TOKEN`, `GITHUB_TOKEN` — for gated
+  downloads and higher API rate limits
+- `REGISTRY_ACCESS_TOKEN` — Comfy Registry API key for `publish_custom_node`
+- `COMFY_API_KEY` — comfy.org API key for hosted partner nodes (different
+  from `COMFYUI_API_KEY`, which is for Comfy Cloud)
+- `COMFYUI_CLOUD_URL` — override the Comfy Cloud endpoint
+  (default `https://cloud.comfy.org`)
+
+Full reference: [docs/configuration](https://comfyui-mcp.artokun.io/docs/configuration).
+
+## Verify
+
+After updating the settings file, **restart the MCP client** (Claude Code: run
+`/mcp` to reconnect; Cline: toggle the server). Then ask the assistant:
+
+> What ComfyUI tools do you have?
+
+It should list ~86 tools across generation, workflow execution/authoring,
+models, custom nodes, etc. If the user wants a quick smoke test, ask:
+
+> Generate a 1024×1024 image of a red apple on a wooden table.
+
+That exercises the `generate_image` tool end-to-end (auto-selects a local
+checkpoint or uses defaults; returns an `asset_id` you can `view_image` to
+see).
+
+## Common issues
+
+- **"ComfyUI not detected on ports 8188, 8000"** — ComfyUI isn't running. Tell
+  the user to start it (Desktop app or `python main.py`).
+- **`CLOUD_UNSUPPORTED` errors** — `COMFYUI_API_KEY` is set, so the server is
+  in cloud mode and a local-only tool was called. Either unset the key (to
+  use a local install) or stick to cloud-compatible tools.
+- **Empty model lists** — `extra_model_paths.yaml` is misconfigured. Run
+  `health_check` for a diagnostic.
+
+## License + repo
+
+- **License:** [MIT](./LICENSE)
+- **Repo:** https://github.com/artokun/comfyui-mcp
+- **npm:** https://www.npmjs.com/package/comfyui-mcp
+- **Docs:** https://comfyui-mcp.artokun.io/docs
+- **Issues:** https://github.com/artokun/comfyui-mcp/issues

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comfyui-mcp",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "mcpName": "io.github.artokun/comfyui-mcp",
   "description": "MCP server for ComfyUI — workflow execution, visualization, composition, registry, and skill generation",
   "homepage": "https://comfyui-mcp.artokun.io/docs",