@fre4x/comfyui 1.1.8 → 1.1.9

package/README.md

@@ -10,10 +10,14 @@ An MCP server to interact with ComfyUI remotely. Probe server state, inspect nod
 - `comfyui_save_workflow`: Save a workflow into local `./workflows` with optional edits.
 - `comfyui_workflow_run`: Run a stored workflow with optional overrides.
 - `comfyui_wait_for_workflow`: Wait for workflow completion with a timeout.
+- `comfyui_interrupt_workflow`: Interrupt the running job and optionally clear the pending queue.
+- `comfyui_upload_image`: Upload a workspace image into ComfyUI `input` for LoadImage.
+- `comfyui_list_models`: List installed checkpoints, LoRAs, VAEs, UNets, and related files.
 
 `comfyui_discover_workflows` filters out non-workflow JSON files and distinguishes
 between API workflows and Web UI graphs whose conversion was validated against the
-live node schema.
+live node schema. Each discovered workflow also includes copy-ready override keys
+when the graph can be normalized.
 
 **Do not assume `structuredContent` is what the model actually sees.** Many MCP clients
 surface `content.text` to the model first and treat `structuredContent` as secondary
@@ -26,6 +30,10 @@ IDs, and recovery hints.
 ### Environment Variables
 
 - `COMFYUI_SERVER_URL`: The URL of your ComfyUI server (default: `http://localhost:8188`).
+- `COMFY_API_KEY`: Optional API key for Comfy Cloud or an authenticated proxy.
+- `COMFY_API_HEADER`: Header name for that key (default: `X-API-Key`; use `Authorization` for Bearer proxies).
+- `COMFYUI_DEFAULT_WORKFLOW`: Optional path, filename, or discover id used when `workflow_ref` is omitted.
+- `COMFYUI_UPLOAD_ROOT`: Extra directory allowed by `comfyui_upload_image` (workspace cwd is always allowed).
 - `MOCK`: Set to `true` to use mock data instead of a real server.
 
 ### Claude Desktop Configuration
@@ -61,71 +69,74 @@ raw graph JSON. Standard Web UI workflow JSON is also accepted and normalized
 automatically.
 
 If you want a single call that submits and waits, pass `await: true` with a
-`timeout` value in seconds to `comfyui_workflow_run`. For lower-level control,
-use `comfyui_wait_for_workflow` with `prompt_id` and `timeout`.
+short `timeout` (default **25** seconds) to `comfyui_workflow_run`. Host MCP
+clients often cut longer blocking waits — if you get a timeout, call
+`comfyui_wait_for_workflow` again with the same `prompt_id`. For lower-level
+control, set `await: false` then poll wait. Use `comfyui_interrupt_workflow`
+to stop a running job; `clear_queue` defaults to `false`.
 
-`comfyui_workflow_run` accepts either a stored workflow reference
-(`workflow_id` / `workflow_file_path`) or an inline `workflow` JSON object.
+`comfyui_workflow_run` accepts a stored workflow reference
+(`workflow_ref`, or the deprecated `workflow_id` / `workflow_file_path` aliases).
+Do not paste full workflow JSON into tool arguments. If
+`COMFYUI_DEFAULT_WORKFLOW` is set, the stored reference may be omitted.
 
 ## Stored Workflow Reuse
 
 The stored-workflow tools let you avoid re-sending large API JSON blobs and give
 agents a stable local edit loop.
 
-1. Save a workflow with `comfyui_save_workflow` into local `./workflows`
+1. Discover or point at an existing workflow with `workflow_ref`
 2. Inspect editable paths with `comfyui_get_workflow`
-3. Persist edits with `comfyui_save_workflow` overrides
+3. Persist edits with `comfyui_save_workflow` + small `overrides`
 4. Reuse it with `comfyui_workflow_run`
 
-`comfyui_workflow_run` and `comfyui_save_workflow` both accept dot-notation
-overrides in canonical `node.inputs.field` form, plus shorter aliases like
-`node.seed`, `node.text`, `node.positive_prompt`, and, for Web UI workflows,
-`node.widgets[index]`.
+Prefer unique global override keys when the graph has only one of that role:
 
 ```json
 {
-  "workflow_id": "pony-portrait-v1",
+  "workflow_ref": "pony-portrait-v1",
   "overrides": {
-    "2.seed": 67890,
-    "6.positive_prompt": "cinematic dragon portrait"
+    "positive_prompt": "cinematic dragon portrait",
+    "seed": 67890
   },
   "await": true,
   "timeout": 90
 }
 ```
 
-If your client serializes nested arguments first, `overrides` may also be sent
-as a JSON string:
+Node-scoped aliases still work: `2.seed`, `6.positive_prompt`,
+`node.inputs.field`, and Web UI `node.widgets[index]`. If a global key is
+ambiguous, the error lists the valid node-scoped paths.
 
-```json
-{
-  "workflow_id": "pony-portrait-v1",
-  "overrides": "{\"2.seed\":67890,\"6.positive_prompt\":\"cinematic dragon portrait\"}"
-}
-```
+`overrides` must be a small JSON **object** (never a stringified blob, never a
+full graph).
 
 To inspect editable inputs and semantic hints for agent editing:
 
 ```json
 {
-  "workflow_id": "pony-portrait-v1",
+  "workflow_ref": "pony-portrait-v1",
   "include_prompt": false
 }
 ```
 
+Pass `verbose: true` when you need every editable input rather than the
+high-signal subset.
+
 `comfyui_get_workflow` and `comfyui_save_workflow` both return:
 
-- `high_signal_inputs`: the most useful prompt/model/sampler controls first
+- `editable_inputs`: high-signal controls by default (full list with `verbose: true`)
+- values are truncated to `value_preview` unless `verbose: true`
 - `input_groups`: grouped counts for prompts, models, sampling, output, etc.
 - combo-backed inputs include `options_count`, `options_preview`, and `options_truncated`
-- `override_examples`: copy-ready payloads using the preferred override aliases
+- `preferred_override_paths` / truncated `override_examples` for copy-ready keys
 
-These appear in both `content.text` and `structuredContent` so agents can steer
-complex workflows without having to scan every literal widget first.
+`comfyui_discover_workflows` returns `override_keys` only (no prompt values).
 
-When `comfyui_wait_for_workflow` times out, the error now includes a queue
-snapshot in both `content.text` and `structuredContent` to show whether the
-prompt is still pending or has disappeared from the server queue.
+`comfyui_wait_for_workflow` returns at most `max_images` native images
+(default **2**, preferring `output` over `temp`). All outputs remain listed in
+`image_refs` with `source_type`/`subfolder` for `comfyui_upload_image`.
+Structured content omits the raw history prompt graph.
 
 `comfyui_workflow_run` also performs a preflight pass against the live
 `/object_info` schema before submission so invalid combo-backed values such as
@@ -136,12 +147,38 @@ To save a new or edited workflow locally:
 
 ```json
 {
-  "workflow_file_path": "pony-portrait-v1.json",
+  "workflow_ref": "pony-portrait-v1.json",
   "overrides": {
-    "6.text": "studio lighting, ultra detailed",
-    "7.filename_prefix": "pony-portrait-agent"
+    "positive_prompt": "studio lighting, ultra detailed",
+    "filename_prefix": "pony-portrait-agent"
   },
   "output_file_name": "pony-portrait-agent.json",
   "overwrite": true
 }
 ```
+
+## Image upload
+
+Image bytes never pass through the model. Provide exactly one reference:
+
+1. Previous run: `prompt_id` + `filename` from `image_refs` / wait text. The server copies ComfyUI output into `input`.
+2. Workspace file: `file_path`.
+
+```json
+{
+  "prompt_id": "77777777-7777-7777-7777-777777777777",
+  "filename": "ComfyUI_00001_.png"
+}
+```
+
+```json
+{
+  "file_path": "/path/in/workspace/source.png",
+  "filename": "source.png"
+}
+```
+
+The tool returns the LoadImage filename to use in `overrides`. `file_path`
+uploads stay inside the workspace (and optional `COMFYUI_UPLOAD_ROOT`).
+`prompt_id` sources are read from the previous run's workspace copy or
+ComfyUI `/view`.