v0.10.0 — paid vs free templates, and two upstream known issues cleared

search_templates rows can now tell a paid template from a free one.

Added

• An api boolean on every search_templates row. The gallery's API tag — "this template runs the model on a hosted partner API and spends your credits" — was dropped on the way out of the tool. Two templates can carry the same title and differ only by that tag (api_minimax_h3_t2v vs video_minimax_h3_t2v), so an agent reading the results could not tell them apart, and would recommend the paid one while saying no free version existed. Rows now carry a plain api: true/false, derived with the exact tag test exclude_api already used and factored into one shared helper so the flag and the filter cannot drift apart. The raw tags list stays out of the rows, so the listing is as compact as before. Additive — a caller ignoring the field sees no change — but a response-shape change, hence the minor bump.

Documentation

• The tokenized matching semantics nodes and search_models inherit from comfy-cli are documented, so a caller knows how a multi-word query is matched instead of inferring it from results.
• The comfy-cli floor's rationale records that its cheap-to-raise precedent expired once this server began publishing to PyPI. The floor itself stays at 1.14.0.

Known issues from 0.9.0 — two now fixed upstream

comfy-cli 1.16.0 resolves two of the three upstream defects 0.9.0 shipped with. Upgrade the engine (pip install --upgrade comfy-cli) to pick them up: this server needs no change, and its floor is deliberately unmoved, so an install below 1.16.0 keeps working with the old behaviour rather than being refused.

• Progress streaming works. comfy jobs watch delivered a single envelope at the end claiming no nodes had run, because it connected under a fresh client id and a local ComfyUI addresses execution events only to the session that submitted the prompt. It now attaches as the submitter and streams live progress.
• nodes(action="path") respects from_type and max_depth, and claims "exact": true only when the search actually finished. It previously returned identical rows for unrelated source types while reporting the answer as exact.
• Still open: the slot mis-pairing originating in comfy workflow slots. This server continues to detect and refuse it, but cannot repair the pairing.

Full notes in CHANGELOG.md.

v0.9.0 — seven P1 fixes, and operator-set consent for clients that cannot prompt

Seven P1 defects found by two independent QA passes (Claude Code and Codex CLI). Both clients hitting the same failures is what established them as server-side rather than client quirks.

First release published to PyPI — pip install comfy-mcp.

Fixed

• generate_image was dead. It shelled out to comfy run-template default, but default had left the gallery, so every call failed. CI never caught it because the tests asserted the same dead constant. The on-ramp now runs image_z_image_turbo; a template going missing in future yields an error naming templates that exist.
• search_templates answered the wrong rows. query was a raw substring test — MiniMax Text to Video returned nothing while MiniMax H3: Text to Video existed, and ext to imag matched 91 rows. Now a word-anchored phrase pass with an all-words fallback.
• Consent gates blamed the user for refusals nobody made. Every non-accept answer collapsed into "the user declined", including clients that never showed a prompt. Gates still fail closed.
• discover could not be called at its own default — ~63 KB from the CLI, ~109 KB pretty-printed, over a typical 25,000-token cap.
• Mis-paired workflow slots were relayed as fact. set_workflow_slot would have written into the wrong field while reporting success, with validate_workflow still reporting valid.
• update_comfyui leaked a traceback on a detached HEAD — a normal state for a version-pinned install.
• Emitted partner workflows carried no cost provenance, though the file is what gets handed to run_workflow, where billing happens.

Added

• COMFY_MCP_ASSUME_CONSENT — pre-authorize specific confirmation gates from the server's environment, for clients that cannot display a prompt. Set by whoever configures the server, in a file the model cannot edit. Spending is excluded by construction: no value, including all, reaches the credit gates.

Changed — check before upgrading

• discover() returns a schema_index instead of every schema body. Use command="<name>" for one, or schemas_only=False for the full surface.
• generate_image runs a different template and refuses checkpoint= on split-loader graphs, which are now the gallery norm.
• search_templates may return match: "all-words", flagging a widened result.

Known issues — upstream in comfy-cli

Progress streaming delivers nothing (comfy jobs watch emits one envelope at the end), nodes(action="path") ignores from_type/max_depth while claiming "exact": true, and the slot mis-pairing above originates in comfy workflow slots — this release detects and refuses it but cannot repair the pairing.

Full notes in CHANGELOG.md.

v0.8.0 — consolidated tool surface, project anchoring, 61% smaller session payload

The first release of the consolidated server. Breaking relative to 0.7.x: 17 flat tools are replaced by 3 grouped enum-action tools.

• 39 tools (was 53): job(action=status|error|wait|watch|cancel|queue), download(action=status|wait|cancel), nodes(action=search|get|list|upstream|downstream|path|types|categories) replace their flat families with byte-identical per-action behavior; every consent-bearing, spending, or destructive tool remains its own tool so clients can allowlist per verb.
• Project anchoring: set COMFY_PROJECT to an absolute project root and every comfy-cli invocation runs against it deterministically; new thin project(action=status|init) tool. Invalid roots fail closed.
• Per-session LLM payload cut 61% (≈39k → ≈14k estimated tokens): tool descriptions rewritten to agent-contract size, handshake instructions deduplicated, enforced by a ratcheting budget test.
• server.py split into six leaf modules (errors, argv, clitext, target, params, instructions) with byte-faithful moves and no behavior change.
• Fixes: credential URLs scrubbed from relayed ComfyUI log lines; the e2e suite no longer probes the network at pytest collection; routing guidance treats VRAM bands as defaults and quotes slow-but-feasible time estimates instead of refusing.
• New: a scheduled contract-test tier against the released comfy-cli binary.

Full details in the pull requests merged to main since v0.7.0.

v0.7.0 — MCP self-attribution for partner-usage metrics

Headline: every comfy-cli invocation this server makes now self-attributes with COMFY_USER_AGENT=comfy-mcp (#163), so partner-API usage driven through the MCP becomes traceable server-side once comfy-cli's usage_source derivation (its PR #690) ships.

Also in this release (v0.5.0 → v0.7.0): install_node with per-call consent, workflow_deps, update-consent gating for target=all, the cancellable async runner on upload/deps paths, the gated untracked-server kill on restart, argv-length hardening, and the credential-URL masking fix in the failure log.

v0.5.0

Thin MCP wrapper over comfy-cli for driving a local ComfyUI.

42 commits since v0.4.0. Tool count 39 to 50.

Breaking changes

Read this section before upgrading.

• The package is now comfy-mcp (#152). The distribution, the import package, the console script and the failure-log directory all move off comfy-local-mcp / comfy_local_mcp. pip install . will not finish this for you, because comfy-mcp is a new name and the old install stays on your PATH pointing at a package that no longer exists: run pip uninstall comfy-local-mcp first, reinstall, then change "command" to comfy-mcp in every MCP client config. The README carries the full migration table.
• Relicensed from Apache-2.0 to AGPL-3.0-or-later OR LicenseRef-Comfy-Commercial (#135), the same dual license Comfy Desktop is moving to. Commercial terms via licensing@comfy.org.
• Requires MCP Python SDK 2.x (mcp>=2,<3, #111). SDK 2.0 deleted mcp.server.fastmcp outright with no shim, and the elicitation types behind the spend-confirmation interlock moved with it.
• comfy-cli floor raised to >= 1.13.0 (#106), the first release carrying the login_url event auth_login blocks on. On 1.12.0 that tool started a login, sat there, and only then reported failure. Now the version guard says no on the first call instead.
• fetch_template returns {path, local_check} rather than a bare path string (#104).
• discover defaults to --schemas-only (#112). The full surface was 181 KB against a client output cap of 25k tokens, and the cap truncates rather than rejects, so the tool had been handing back JSON cut mid-structure that would not parse. It is now roughly 35 KB and actually usable.

New tools

Eleven of them, taking the surface from 39 to 50.

• node_dependencies (#155) reports each custom node pack's declared Python requirements against what is installed in the workspace venv, including for a registry pack you have not installed yet, so conflicts can be checked before installing rather than after.
• emit_partner_workflow (#113) lets the local ComfyUI execute partner nodes.
• list_partner_models and partner_model_schema (#118) discover partner models and their parameters.
• system_stats and free_memory (#116) for VRAM coordination.
• list_workflow_notes (#117) reads a template's authored notes.
• switch_comfyui_version (#126), consent gated.
• download_status, wait_for_download and cancel_download (#105), the background half of the download rework below.

Downloads stop reporting false failures

download_model now submits comfy model download --background and polls, instead of holding the MCP request open for the whole byte transfer (#105). A multi-GB checkpoint outlasts a typical client's 120s request deadline, so the client fired a timeout while the download was quietly succeeding, with no handle to check the real outcome. Bound expiry now returns {timed_out: true, download_id, status} rather than raising, because a slow download is progress, not an error. A comfy-cli without the background verbs falls back to the old synchronous path; #132 makes that fallback honor the caller's timeout and die on cancel.

Consent gates

• Network-exposing launch flags (#131). launch_comfyui and restart_comfyui forwarded extra_args verbatim, so --listen 0.0.0.0 or --enable-cors-header published an unauthenticated ComfyUI, meaning arbitrary workflow execution plus file reads and writes under the ComfyUI directory, to anything that could route to the machine. Those specific arguments now require confirmation. An ordinary launch is untouched.
• run_workflow(confirm_spend=True) (#133) forwards --allow-spend, matching partner_generate and run_template.
• switch_comfyui_version (#126) prompts on every call, since comfy-cli does not gate it at all.

Also in this release

get_template and fetch_template cross-check a template against the live install and tell you before you run it that a node class or model option is missing, which was previously a successful fetch followed by a mystifying runtime failure (#104). get_logs gained a port hint plus source and staleness metadata (#119). Server instructions now route off server_info's hardware block (#114). emit_partner_workflow gates on a comfy-cli that actually has --emit-workflow (#115).

Docs: the COMFYUI_URL / COMFY_LOCAL_URL collision is resolved (#154), SECURITY.md documents the threat model (#129), subgraph templates are written down as fully supported so agents stop refusing to run them (#107), and every catalog tool states a per-surface freshness policy (#134).

Plus routine maintenance: secret-scanning jobs (#143, #144, #145), CI pins and the groom sweep (#109, #110, #149, #150, #151), CODEOWNERS (#127, #141), and docs (#125, #128, #130, #142, #146, #147, #148, #153).

Requirements

comfy-cli >= 1.13.0, Python >= 3.10, MCP Python SDK >= 2, < 3.

Full changelog: v0.4.0...v0.5.0

v0.4.0

Thin MCP wrapper over comfy-cli for driving a local ComfyUI.

Highlights since v0.3.0

• auth_login — an agent can now get you signed in to Comfy Cloud instead of telling you to run the CLI by hand. It starts comfy cloud login --no-browser in the background and hands back the OAuth URL for you to open; confirm with auth_status. comfy-cli owns the PKCE flow and the loopback callback, so no OAuth logic lives here and no tokens ever cross the tool boundary. One sign-in at a time: calling it again mid-flow re-reports the same URL rather than racing a second listener. (#98)
• update_comfyui — wraps comfy update [all|comfy|cli]. (#92)
• Structured workflow slots — {address, value} slot items alongside the existing string form. (#100)
• run_template(wait=True) — streams live progress, matching run_workflow. (#82)
• Opt-in failure log — a local rotating log of comfy-cli failures for debugging, off by default. (#77)

Hardening

A full sweep of the argv boundary: every remaining unguarded argument site now rejects option-like and NUL input (#83, #85, #86, #87, #88, #94), download_model confines relative_path to the models tree (#89, #87), oversized and NaN timeouts are clamped rather than forwarded (#78), and a timed-out comfy-cli spawn reaps its whole process group (#97).

Plus: comfy-cli spawns are now asynchronous throughout (#102), launch guarantees COMFY_BIN's directory is on the child PATH (#96), and restart_comfyui recognizes comfy-cli's plain "nothing to stop" message (#93).

Also fixed

generate_image runs the local text-to-image template instead of the partner-only comfy generate verb (#74); get_queue no longer lists cloud-tracked jobs among the local ones (#71); a macOS Full Disk Access failure now explains the fix instead of relaying a raw PermissionError (#72); and envelope failure messages carry the stdout/stderr tails (#73).

Requirements unchanged

comfy-cli >= 1.12.0, Python >= 3.10. auth_login does not raise the floor.

Full changelog: v0.3.0...v0.4.0

v0.3.0

Thin MCP wrapper over comfy-cli for driving a local ComfyUI.

Highlights since v0.2.0

• partner_generate — partner-API generation passthrough, with per-call credit-spend confirmation via MCP elicitation (same spend-gate model as the cloud MCP). (#67, #68)
• run_template — thin passthrough to comfy run-template, the template equivalent of run_workflow. (#69)
• COMFYUI_URL — point the run/queue tools at a remote ComfyUI, including Tailscale targets; unset keeps byte-identical localhost behavior. Unblocks the evals sandbox re-pin (Comfy-Org/evals#41). (#61)
• COMFY_LOCAL_URL — documented path for a local ComfyUI on a non-default address (e.g. :8189). (#65)
• server_info — attaches a comfy-outdated freshness block. (#64)

Full changelog: v0.2.0...v0.3.0

v0.2.0

First tagged release of comfy-local-mcp: the local MCP server that lets agents drive a local ComfyUI install through comfy-cli. Everything since the initial 0.1.0 scaffold rides in here.

Highlights

Tool surface

• Run and monitor: run_workflow (streams progress via MCP progress notifications, #11), wait_for_job (#9), watch_job (#20), get_queue / cancel_job (#4), fetch_outputs with inline image return (#23)
• One-shot generation: generate_image wrapping comfy generate (#27)
• Diagnostics: get_logs (#24, line-capped in #31), get_execution_error (#22), server_info now verifies comfy-cli envelope/version compatibility (#37)
• Workflow building: slot editing via list_workflow_slots / set_workflow_slot / vary_workflow (#16), node graph introspection (#15), node and model discovery (#6), template search and fetch (#7, tightened in #41)
• Lifecycle and assets: launch_comfyui / stop_comfyui (#8) / restart_comfyui (#23), download_model (#21), upload_file and validate_workflow (#5), CLI introspection via discover / which (#18)

Reliability

• search_models passes the query via --text instead of positionally, fixing empty results (#35)
• Exit-0 comfy-cli commands without a JSON envelope now count as success for lifecycle commands (#36) and download_model (#49)
• comfy-cli timeouts surface captured stdout/stderr tails instead of failing silently (#40)
• comfy-cli file watcher suppressed via COMFY_NO_WATCH so runs terminate cleanly (#38)
• Bounded credential retry and COMFY_API_KEY documentation for partner/API nodes (#42)
• validate_workflow documents the upstream validator's known blind spots (#46)

Project

• Relicensed from GPL-3.0 to Apache-2.0 (#25)
• Requires comfy-cli >= 1.12.0 (#24)
• Install and client-configuration guide for Claude Code, Claude Desktop, and Cursor (#12)

Install

See the README for install and per-client configuration.

What's Changed

• feat: local Comfy MCP — thin Python wrapper over comfy-cli (4 tools) by @mattmillerai in #1
• ci: add GitHub Actions gate (pytest + ruff) and regression tests by @mattmillerai in #2
• ci: harden workflow (persist-credentials, job name, timeout) and cap ruff by @mattmillerai in #3
• feat: job management tools — cancel_job + get_queue by @mattmillerai in #4
• feat: add upload_file + validate_workflow passthroughs by @mattmillerai in #5
• feat: discovery tools — search_nodes / get_node / search_models by @mattmillerai in #6
• feat: template tools — search_templates / get_template / fetch_template by @mattmillerai in #7
• feat: lifecycle tools — launch_comfyui + stop_comfyui by @mattmillerai in #8
• feat: wait_for_job tool + MCP server instructions by @mattmillerai in #9
• test: e2e smoke harness for the no-model round-trip by @mattmillerai in #10
• feat: stream run_workflow progress via MCP progress notifications by @mattmillerai in #11
• chore: add day-one governance files (SECURITY, dependabot, PR template, secret-scanning, AGENTS) by @mattmillerai in #13
• docs: install & client-configuration guide (Claude Code / Desktop / Cursor) by @mattmillerai in #12
• chore(deps): bump the github-actions group with 2 updates by @dependabot[bot] in #14
• ci: add cursor-review caller (wire into shared reusable workflow) by @mattmillerai in #19
• feat: node graph-introspection tools (ls / upstream / downstream / path / types / categories) by @mattmillerai in #15
• feat: workflow slot-editing tools — list_workflow_slots / set_workflow_slot / vary_workflow by @mattmillerai in #16
• refactor: wrap comfy download --where local in fetch_outputs by @mattmillerai in #17
• feat: add watch_job tool to stream live progress for async-submitted jobs by @mattmillerai in #20
• feat: add download_model tool wrapping comfy model download by @mattmillerai in #21
• feat: add discover + which introspection tools by @mattmillerai in #18
• feat: add get_execution_error diagnostics tool (BE-2384) by @mattmillerai in #22
• ci: bump cursor-review to github-workflows@3aead23 by @cloud-code-bot[bot] in #47
• docs: public-launch polish — README beta + community health files by @mattmillerai in #26
• feat: add restart_comfyui and inline image return from fetch_outputs by @mattmillerai in #23
• feat: add generate_image tool wrapping comfy generate (BE-2536) by @mattmillerai in #27
• fix(e2e): await run_workflow — async drift broke the live smoke by @mattmillerai in #32
• fix(search_models): pass query via --text, not positional (BE-2952) by @mattmillerai in #35
• fix: treat exit-0 lifecycle commands as success when no JSON envelope (BE-2953) by @mattmillerai in #36
• fix(search_templates): filter real rows payload, compact projection, pagination + gallery-filter passthrough (BE-3342) by @mattmillerai in #41
• docs(validate_workflow): disclose known comfy-cli validator blind spots (BE-3360) by @mattmillerai in #46
• feat: add get_logs tool and require comfy-cli >= 1.12.0 by @mattmillerai in #24
• chore: relicense GPL-3.0 → Apache-2.0 by @mattmillerai in #25
• feat: verify comfy-cli envelope/version compatibility in server_info by @mattmillerai in #37
• fix: suppress comfy-cli watcher via COMFY_NO_WATCH and fix async e2e smoke (BE-3074) by @mattmillerai in #38
• fix(get_logs): cap oversized log lines to bound agent context (BE-2388) by @mattmillerai in #31
• fix(download_model): treat exit-0 no-envelope download as success (BE-3345) by @mattmillerai in #49
• fix(timeout): surface captured stdout/stderr tails on comfy-cli timeout (BE-3343) by @mattmillerai in #40
• feat(partner-auth): document COMFY_API_KEY, pass CLI hint/details verbatim, bounded credential retry by @mattmillerai in #42
• fix: remove shadowing duplicate _parse_version, unblock version-check tests (BE-3474) by @mattmillerai in #51
• chore: bump version to 0.2.0 for first tagged release by @mattmillerai in #52

New Contributors

• @dependabot[bot] made their first contribution in #14
• @cloud-code-bot[bot] made their first contribution in #47

Full Changelog: https://github.com/Comfy-Org/comfy-local-mcp/commits/v0.2.0