ComfyUI

ComfyUI (local)

ComfyUI is a node-graph engine for diffusion and generative media. This bundle reaches the HTTP API on the user's machine through MCPBundles Desktop — not a hosted ComfyUI cloud.

Runtime requirements

• ComfyUI Desktop or a ComfyUI server must be running locally with the HTTP API enabled.
• ComfyUI Desktop defaults to 127.0.0.1:8000; CLI/portable installs often use 8188.
• MCPBundles Desktop must be running on the same machine so the backend can forward HTTP to localhost.

Workflow shape

ComfyUI executes API prompt JSON: a map of string node ids to [node_class, {inputs}]. Example node classes: CheckpointLoaderSimple, CLIPTextEncode, KSampler, VAEDecode, SaveImage.

Typical generation flow:

1. Optionally list checkpoints under the checkpoints models folder.
2. Validate the graph before queueing — validation reports missing_models when weights are absent; it never auto-downloads.
3. Manager-listed weights: search the ComfyUI-Manager catalog, then queue install with the exact catalog fields (name, type, base, save_path, filename, url).
4. Weights not in Manager (ACE-Step, Stable Audio, template-only HuggingFace assets): download each missing file explicitly into the correct models/{folder}/ path.
5. Probe one node class at a time when building graphs — the full object-info catalog is huge.
6. Queue the graph; the response includes prompt_id.
7. Wait for execution history for that prompt_id until status=success and output_files is populated.
8. Pull each output using output_files[].fetch_tool and fetch_params — follow each entry's fetch hint (history media fetch for videos, gifs-bucket media, and audio; model file read for safetensors and other on-disk weights).
9. Never guess filenames from Save node filename_prefix alone — paths include ComfyUI suffixes (_00001, nested subfolders).
10. Upload datasets or small files under input/, output/, or models/ only (put is capped at 100 MB).

Output pull workflow (mandatory)

The root cause of “invisible” outputs is skipping history metadata and guessing paths. The correct chain:

• output_files is authoritative for MCP-queued runs. Each entry includes fetch_tool, fetch_params, and path.
• Local directory listing via Desktop walks folders on the user's machine — useful for browsing datasets on disk before queueing, not as a substitute for output_files after a fresh queue.
• file_path is accepted as an alias for path on model file reads.
• Model file reads fall back to HTTP /view when desktop disk read fails; on miss they retry exact candidate paths when disk listing finds them.
• Caller-side persistence (saving bytes to a project folder) stays outside this provider. A future chained sync job may combine queue → wait → pull in one call.

LoRA training (kohya through ComfyUI)

Kohya sd-scripts runs inside ComfyUI via custom node packs (for example Kijai's ComfyUI-FluxTrainer with InitFluxLoRATraining, FluxTrainLoop, FluxTrainSave). Queue training like any other graph — there is no separate kohya server.

Training setup order:

1. Confirm training node classes are registered on the instance.
2. If missing: search the Manager custom-node catalog, install the pack, then install pip requirements for that pack.
3. Place checkpoint and dataset files via Manager install or file upload.
4. After a failed or OOM run: interrupt if needed, free GPU memory (optionally wait until free VRAM rises), reboot through Manager only when unload is not enough.
5. Queue the FluxTrainer workflow, poll history, pull the .safetensors output from disk.

ComfyUI's built-in TrainLoraNode is a different trainer — not kohya. Prefer FluxTrainer nodes for kohya-style training and memory options such as blocks_to_swap on constrained GPUs.

Queue, memory, and recovery

After a failed or OOM run:

1. Interrupt stops the in-progress job only — it does not clear pending queue items.
2. Clear the queue to drop pending jobs that would re-run on stale VRAM.
3. Free memory unloads models on the next idle tick; optional VRAM polling reads system stats from the ComfyUI server.
4. Manager reboot is the hard reset when the free-memory unload action is not enough.

Long jobs (LoRA training, 15–60+ minutes): prefer HTTP polling with a long timeout, or loop queue + history until the LoRA appears under models/loras/.

Validation, templates, and Manager installs

• Live validation checks wires, paths, registered node classes, and missing weights on disk.
• Workflow templates ship starter API prompts for common graphs (for example built-in WAN).
• List local files to confirm datasets and checkpoints on disk before queueing.
• Output discovery on Desktop: local directory listing on the ComfyUI output folder path walks on-disk output via MCPBundles Desktop — use before queueing to confirm datasets, not as a substitute for output_files after MCP-queued runs.
• Wait-for-history can use WebSocket progress when available, then fall back to HTTP poll without failing the turn on stream parse misses.
• Install missing custom nodes for unregistered classes in a workflow via Manager.
• Import-fail diagnostics explain packs that installed but failed to load.
• Node schema probes return registered: false when a class is not loaded.

Manager catalog and direct downloads

• Model catalog search reads the Manager external-model catalog; installs use Manager's download queue (not arbitrary URLs). Idempotent when the file is already visible in the models list.
• Custom-node catalog may be empty on ComfyUI Desktop until the database channel is set correctly — read Manager channel config (selected channel, db_mode) when search returns zero; probe the Manager custom-node catalog with remote mode via the generic local HTTP request escape hatch when needed.
• The install snapshot lists git custom node packs with enabled/disabled flags when the installed-pack route returns sparse rows on Desktop V4 builds.
• List all model folder types (not only checkpoints/loras) before searching niche weight paths such as ipadapter or diffusion_models.
• Manager install rejections often return HTTP 400; use allow_error_response on that escape hatch to read the raw body. Set expect_json=false for plain-text Manager policy routes.
• Git URL custom-node installs are blocked when Manager security policy is strict — lower security in Desktop settings or install from the Manager UI.
• Large checkpoints may still download after install returns in_progress; poll install status or list models.
• Direct HuggingFace/Civitai downloads into models/{save_dir}/ when validation reports missing_models and the weight is not catalog-listed. Use background download (default) for multi-GB files, then poll download status or list models — blocking downloads hold the MCP SSE stream open and fail after ~15–20 minutes even though the ComfyUI host may still be downloading on disk.

Gotchas

• Local GPU time: Runs on the user's hardware; large graphs can take minutes.
• No built-in auth: Default ComfyUI binds to localhost only. Do not expose the port to the public internet.
• History outputs: Always pull via output_files from the wait-for-history step using each entry's fetch_tool. Videos/gifs/audio use history media fetch; safetensors use model file read.
• node_errors: Invalid graphs return structured errors from the queue endpoint; fix inputs and retry.
• Windows paths: Validation and queue normalize path separators to the host before running.
• Large local files: Multi‑MB .safetensors may return a download link (spillover) instead of inline base64.