comfyui-mcp 0.6.0 → 0.7.0

package/.codex/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bd prime"
+          }
+        ]
+      }
+    ]
+  }
+}

package/CHANGELOG.md

@@ -4,6 +4,68 @@ All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/) and the format follows
 [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.7.0] - 2026-05-25
+
+Stability + authoring release: hardens model downloads and the ComfyUI process
+lifecycle, makes failures actionable, and adds a custom-node authoring/publishing
+lifecycle. Plus a hosted docs site and an experimental embedded-agent backend.
+
+### Added
+
+- **Custom-node authoring** — `scaffold_custom_node` (generate a Python node pack
+  from a template) and `publish_custom_node` (publish to the Comfy Registry via
+  comfy-cli; key via `REGISTRY_ACCESS_TOKEN`, never logged) (#24).
+- **`install_custom_node` ref pinning** — pin a pack to a commit/branch/tag, parsed
+  from GitHub/GitLab/Bitbucket URLs or `repo@ref`, or an explicit `ref` arg.
+- **`download_model` auth** — per-request `bearer` / `basic` / `header` / `query`
+  authentication for gated/private model hosts.
+- **Model download cache** — content-addressed dedup, concurrent-download coalescing,
+  and optional LRU eviction (`COMFYUI_DOWNLOAD_CACHE_DIR`, `COMFYUI_LRU_CACHE_SIZE_GB`).
+- **ComfyUI process supervision** — bounded startup readiness checks
+  (`COMFYUI_STARTUP_CHECK_INTERVAL_S`/`_MAX_TRIES`) and opt-in bounded
+  auto-restart-on-crash (`COMFYUI_ALWAYS_RESTART`, `COMFYUI_RESTART_MAX_ATTEMPTS`,
+  `COMFYUI_RESTART_WINDOW_S`).
+- **Plugin skills** — `comfyui-frontend-extensions` (v2 `@comfyorg/extension-api`
+  authoring + v1→v2 migration) and `comfyui-node-registry` (node authoring/publishing).
+- **Hosted docs** — Mintlify site with a schema-generated tool reference at
+  [comfyui-mcp.artokun.io/docs](https://comfyui-mcp.artokun.io/docs).
+
+### Changed
+
+- **`get_job_status` + completion notifications** now surface ComfyUI
+  `execution_error` detail (node id/type, exception type/message, truncated traceback,
+  `current_inputs`, OOM flag) and optional per-node + total execution timing.
+  Additive and backward-compatible.
+
+### Security
+
+- `download_model` auth inputs are validated (reject CR/LF/control chars; HTTP-token
+  header names); query-auth secrets are redacted from logs and error details.
+- `install_custom_node` git refs are validated and run via `git checkout
+  --end-of-options <ref>`, closing an argv-option-injection vector.
+- Spawned ComfyUI children now have `error` listeners so a missing/failed executable
+  can't crash the MCP server.
+
+### Experimental
+
+- **Embedded-agent backend POC** (flag-gated via `COMFYUI_MCP_AGENT_POC`): a cloudflared
+  quick-tunnel helper + an AI SDK `/api/chat` endpoint with bearer auth, a request body
+  cap, and a server-side model allowlist. Not part of default startup. See
+  `design/embedded-agent-panel.md` and `ROADMAP.md`.
+
+### Dependencies
+
+- Added `ai` + `@ai-sdk/anthropic`/`openai`/`google` + `cloudflared` (experimental POC)
+  and declared `zod-to-json-schema` (docs generation). `npm audit`: 0 high vulnerabilities.
+
+## [0.6.1] - 2026-05-25
+
+### Added
+
+- **Media upload** — `upload_video` and `upload_audio` copy local video/audio
+  files into ComfyUI's input directory so they can be referenced as workflow
+  inputs, mirroring the existing `upload_image` (closes #12).
+
 ## [0.6.0] - 2026-05-25
 
 A large feature release that ports much of the [`comfy-cli`](https://github.com/Comfy-Org/comfy-cli)
@@ -58,4 +120,6 @@ subprocess fallback where the API can't do the job.
 
 Earlier releases predate this changelog.
 
+[0.7.0]: https://github.com/artokun/comfyui-mcp/releases/tag/v0.7.0
+[0.6.1]: https://github.com/artokun/comfyui-mcp/releases/tag/v0.6.1
 [0.6.0]: https://github.com/artokun/comfyui-mcp/releases/tag/v0.6.0

package/README.md

@@ -5,13 +5,16 @@
 [![npm version](https://img.shields.io/npm/v/comfyui-mcp)](https://www.npmjs.com/package/comfyui-mcp)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org)
 [![License](https://img.shields.io/npm/l/comfyui-mcp)](./LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-comfyui--mcp.artokun.io-2563EB?logo=readthedocs&logoColor=white)](https://comfyui-mcp.artokun.io/docs)
 
 [![comfyui-mcp MCP server](https://glama.ai/mcp/servers/artokun/comfyui-mcp/badges/card.svg)](https://glama.ai/mcp/servers/artokun/comfyui-mcp)
 [![comfyui-mcp MCP server](https://glama.ai/mcp/servers/artokun/comfyui-mcp/badges/score.svg)](https://glama.ai/mcp/servers/artokun/comfyui-mcp)
 
 Works on **macOS**, **Linux**, and **Windows**. Auto-detects your ComfyUI installation and port.
 
-**70+ MCP tools** | **10 slash commands** | **4 knowledge skills** | **3 autonomous agents** | **3 hooks**
+**80+ MCP tools** | **10 slash commands** | **6 knowledge skills** | **3 autonomous agents** | **3 hooks**
+
+📖 **Full documentation: [comfyui-mcp.artokun.io/docs](https://comfyui-mcp.artokun.io/docs)**
 
 ---
 
@@ -413,6 +416,11 @@ The server auto-detects your ComfyUI installation and port. Override with enviro
 | `CIVITAI_API_TOKEN` | | CivitAI API token for model downloads |
 | `HUGGINGFACE_TOKEN` | | HuggingFace token for higher API rate limits |
 | `GITHUB_TOKEN` | | GitHub token for skill generation (avoids rate limits) |
+| `REGISTRY_ACCESS_TOKEN` | | Comfy Registry API key for `publish_custom_node` (env-only, never logged) |
+| `COMFYUI_DOWNLOAD_CACHE_DIR` | `~/.comfyui-mcp/cache` | Content-addressed model-download cache (dedup + concurrent coalescing) |
+| `COMFYUI_LRU_CACHE_SIZE_GB` | `0` | Cap the download cache in GB; `0` disables LRU eviction |
+| `COMFYUI_STARTUP_CHECK_INTERVAL_S` / `…_MAX_TRIES` | `1` / `20` | Readiness-probe interval + max tries when starting a local ComfyUI |
+| `COMFYUI_ALWAYS_RESTART` | `false` | Auto-restart a crashed local ComfyUI (bounded by `COMFYUI_RESTART_MAX_ATTEMPTS` / `COMFYUI_RESTART_WINDOW_S`) |
 | `LOG_LEVEL` | `info` | Logging verbosity: `debug`, `info`, `warn`, `error` |
 
 ### Transports
@@ -648,6 +656,42 @@ MIT — see [LICENSE](./LICENSE) for details.
 
 ## Changelog
 
+The full, structured changelog lives in [CHANGELOG.md](./CHANGELOG.md). Recent highlights:
+
+### 0.7.0 — 2026-05-25
+
+**Stability + authoring.**
+
+- **Custom-node authoring** — `scaffold_custom_node` (template a Python node pack) and `publish_custom_node` (publish to the Comfy Registry; `REGISTRY_ACCESS_TOKEN`).
+- **`install_custom_node` ref pinning** — pin to a commit/branch/tag (URL ref or explicit `ref`).
+- **`download_model` auth** — per-request `bearer`/`basic`/`header`/`query` auth for gated/private models.
+- **Download cache** — content-addressed dedup + concurrent coalescing + optional LRU (`COMFYUI_DOWNLOAD_CACHE_DIR`, `COMFYUI_LRU_CACHE_SIZE_GB`).
+- **Process supervision** — bounded startup readiness checks + opt-in bounded crash auto-restart for local installs.
+- **Actionable failures** — `get_job_status` / completion now surface ComfyUI execution errors (OOM, traceback, node) and per-node + total timing.
+- **Security** — download-auth input validation + secret redaction; git-ref argv-injection hardening; spawn `error` listeners so a bad executable can't crash the server.
+- **Experimental** — flag-gated embedded-agent backend POC (cloudflared tunnel + AI SDK chat).
+- **Docs** — hosted Mintlify site with a schema-generated tool reference.
+
+### 0.6.1 — 2026-05-25
+
+- **`upload_video` / `upload_audio`** — copy local video/audio files into ComfyUI's input directory so they can be referenced as workflow inputs, mirroring `upload_image`.
+
+### 0.6.0 — 2026-05-25
+
+**comfy-cli capability port** — much of the [comfy-cli](https://github.com/Comfy-Org/comfy-cli) workflow is now exposed as MCP tools, preferring the ComfyUI-Manager HTTP API with a subprocess fallback:
+
+- **Custom nodes** — `install_custom_node`, `update_custom_node`, `reinstall_custom_node`, `fix_custom_node`, `list_installed_nodes`, `sync_node_dependencies`.
+- **Node snapshots** — `save_node_snapshot`, `restore_node_snapshot`, `list_node_snapshots`.
+- **Node bisect** — `bisect_start`, `bisect_good`, `bisect_bad`, `bisect_reset`, `bisect_status` to isolate a faulty custom node.
+- **Workflow dependencies** — `extract_workflow_dependencies`, `install_workflow_dependencies` (API- and UI-format workflows).
+- **Install / update** — `install_comfyui`, `update_comfyui`, `update_all`.
+- **Models** — `remove_model` (path-safe) and `download_civitai_model`.
+- **Workspace & environment** — `get_workspace`, `set_default_workspace`, `list_workspaces`, `get_environment`.
+- **API / partner nodes** — `list_api_nodes`, `get_api_node_schema`, `generate_with_api_node`.
+- **ComfyUI-Manager config** — `configure_manager`.
+- **Security** — CivitAI auth moved to an `Authorization: Bearer` header (token no longer leaks into logs/URLs); model-download filenames validated against path traversal; `COMFY_API_KEY` delivered via the `/prompt` `extra_data` payload rather than the workflow.
+- Rewrote core tool/parameter descriptions for clearer agent tool-selection; added a `Dockerfile` and the [Glama](https://glama.ai) listing.
+
 ### 0.5.0 — 2026-05-21
 
 - **Streamable-HTTP transport** — opt in with `--http` (or `MCP_TRANSPORT=http`) to serve MCP over HTTP at `/mcp` for gateways, remote, and `fetch`-based clients. stdio remains the default; `--host`/`--port` configure the bind.

package/ROADMAP.md

@@ -0,0 +1,120 @@
+# ComfyUI MCP — Roadmap
+
+**Vision:** an agent can author, run, *fix*, and *ship* ComfyUI — from a prompt, to a working
+workflow, to an in-UI assistant that edits the graph live, to a published custom node. comfyui-mcp
+is the backend tool surface; the pieces below extend it up into the ComfyUI frontend and out to the
+Comfy Registry.
+
+> Tracking: themes map to beads **epics**; items map to issues. Run `bd ready` for what's actionable.
+> This file is the human-readable map; beads is the source of truth for status.
+
+---
+
+## ✅ Shipped (0.6.x)
+- comfy-cli capability port (custom-node mgmt, snapshots, bisect, workflow deps, install/update,
+  models, workspace/env, API nodes, manager config) — tools surface ~70+.
+- `upload_video` / `upload_audio`.
+- Mintlify docs site (schema-generated tool reference) at comfyui-mcp.artokun.io/docs.
+- Glama listing + TDQS A-grade pass; blog post (TDQS case study).
+
+---
+
+## Theme A — Frontend extension authoring (enabler)
+The new ComfyUI frontend extension API (`@comfyorg/extension-api`, v2; replaces
+`app.registerExtension`) is brand-new and absent from model training data. Teach it so we (and any
+user) can write correct frontend extensions — the substrate for Theme B.
+
+- **A1 — Skill: author v2 extensions.** `defineNode`/`defineExtension`/`defineWidget`,
+  `defineSidebarTab`, `NodeHandle`/`WidgetHandle`, event namespaces (`execution`/`graph`/`server`/
+  `workbench`), `DisposableHandle` contract, identity helpers, the event+getter/setter idiom.
+- **A2 — Skill: migrate v1 → v2.** Map legacy `app.registerExtension` / prototype-patching patterns
+  to the v2 API (the ecosystem dashboard's api-diff/patterns are the source). DrJKL collaboration hook.
+  > Source: `Comfy-Org/ComfyUI_frontend` PRs #12142–#12145; `src/extension-api/`. Package not yet on npm.
+
+## Theme B — Embedded agent panel (north star)
+A ComfyUI **sidebar tab** (AI icon) hosting an [AI SDK](https://sdk.vercel.ai) chat window. You chat
+with Claude Code / Codex / Gemini and it reads + **fixes the live workflow in the UI**. Connection
+to the agent "app" is via a **cloudflared tunnel** (Ungate-style). Full design:
+[`design/embedded-agent-panel.md`](./design/embedded-agent-panel.md).
+
+- **B1 — Tunnel helper.** Port Ungate's `tunnel-manager` (the `cloudflared` npm lib:
+  `Tunnel.quick(localUrl) → public https URL`) into our server as `startQuickTunnel(port)`, behind a flag.
+- **B2 — AI SDK chat endpoint.** `POST /api/chat` → `streamText(...).toUIMessageStreamResponse()`,
+  provider registry (Anthropic/OpenAI/Google), one real server-side tool end-to-end.
+- **B3 — Sidebar panel.** `defineSidebarTab` + AI SDK `useChat` pointed at the tunnel; render stream.
+- **B4 — Live graph edits.** Graph-mutation tools (`set_widget_value`, `add_node`, `connect`, …) as
+  AI SDK **client-side tools** resolved in the panel via extension-api (`NodeHandle`/`WidgetHandle`).
+  *This is the magic — "fix it in the UI."*
+- **B5 — Wire comfyui-mcp** as the server-side tool surface via AI SDK MCP client.
+- **B6 — Provider switch + connection/key UX + ship** as a node pack.
+
+## Theme C — Custom-node authoring lifecycle (NEW)
+Create a Python custom node from a template, install + restart to test, then publish to the
+[Comfy Registry](https://docs.comfy.org/registry/overview). The full "agent builds & ships a node" loop.
+
+- **C1 — Skill: ComfyUI Registry + custom-node authoring.** Minimal node structure
+  (`__init__.py`, `NODE_CLASS_MAPPINGS`/`NODE_DISPLAY_NAME_MAPPINGS`, `INPUT_TYPES`/`RETURN_TYPES`/
+  `FUNCTION`/`CATEGORY`, optional `WEB_DIRECTORY`), `pyproject.toml` (`[project]` + `[tool.comfy]`:
+  `PublisherId`/`DisplayName`/`Icon`), publisher + API key flow, `comfy node init`/`publish`, the
+  `Comfy-Org/publish-node-action` CI workflow + `REGISTRY_ACCESS_TOKEN`.
+- **C2 — MCP `scaffold_custom_node`.** Generate a node pack into `custom_nodes/<name>/` from a
+  template (prefer `comfy node init`; fall back to our own template). Local-only.
+- **C3 — Test loop.** Install → `restart_comfyui` (have it) → verify the new `class_type` appears in
+  `/object_info` → enqueue a smoke-test workflow using it.
+- **C4 — MCP `publish_custom_node`.** `comfy node publish` with token; validate `pyproject.toml`
+  metadata first. Token via env (never in URLs/logs), like the CivitAI pattern.
+- **C5 — Template + CI scaffold.** A spawnable starter (Python node + optional v2 frontend +
+  `publish_action.yml`) so `create → restart → test → publish` is one smooth path.
+
+## Theme D — Discovery (from prior notes)
+- **D1 — `comfy-researcher` agent + skill cache.** Problem→packs research over the Registry +
+  HF + community, with a cached skill layer. (Folded in from `TODO.md`.)
+
+## Theme E — Production hardening & I/O (from [Salad's comfyui-api](https://github.com/SaladTechnologies/comfyui-api), MIT)
+Harden existing tools and add production I/O, adapting patterns from comfyui-api. We are an
+agent-facing MCP, not a horizontally-scaled web service — so we cherry-pick and skip the
+stateless-server / Salad-specific bits (replicas, deletion-cost, k8s proxy).
+
+**Harden existing tools**
+- **E1 — Download cache + dedup.** Content-address downloads (SHA-256 of URL → cache dir + sidecar
+  `.meta`, symlink to target), reuse on hit, coalesce concurrent same-URL fetches, optional LRU
+  eviction. Hardens `download_model`/`download_civitai_model`. (`remote-storage-manager.ts`, `utils.hashUrlBase64`)
+- **E2 — Download auth + storage backends.** Per-URL credential resolution (bearer/basic/header/
+  query/s3) and `s3://` / huggingface / azure-blob / http(s) sources for gated/private models.
+  (`credential-resolver.ts`, `storage-providers/*`)
+- **E3 — ComfyUI supervision.** Auto-restart-on-crash + bounded startup readiness checks
+  (interval/max-tries) + a real readiness signal. Hardens `start/stop/restart_comfyui`. (`comfy.ts`)
+- **E4 — Rich errors + execution stats.** Surface ComfyUI `execution_error` (exception_type,
+  traceback, current_inputs — e.g. OOM) and per-node timing in job results. Hardens
+  `get_job_status`/completion reporting. (`event-emitters.ts`)
+- **E7 — Custom-node ref-pinning.** Install a node pack pinned to a commit/branch/tag across
+  GitHub/GitLab/Bitbucket URL formats. Hardens `install_custom_node` (reproducibility). (`git-url-parser.ts`)
+- **E11 — Unique output filenames.** Prefix a request id to output filenames to avoid collisions.
+
+**Additive capabilities**
+- **E5 — Declarative environment manifest.** `apply_manifest` (yaml/json): apt/pip/custom_nodes/
+  models (before/after start), idempotent — reproducible setups. Pairs with Theme C + workspace.
+- **E6 — Output upload to cloud storage.** Push generated outputs to S3 / Azure / HF / HTTP and
+  return URLs. (`remote-storage-manager.ts`, `storage-providers/*`)
+- **E8 — Server-side image conversion.** `sharp` PNG↔JPEG↔WebP + quality options for compact outputs. (`image-tools.ts`)
+- **E9 — Dynamic model loading.** URL in a model-loading node → auto-download + cache before exec. (`comfy-node-preprocessors.ts`)
+- **E10 — Warmup.** Run a warmup workflow after `start_comfyui` to preload models. (`comfy.warmupComfyUI`)
+- **E12 — Outbound webhooks (later).** Signed Standard Webhooks on completion/progress + retries —
+  mainly for the headless/bridge path, not the interactive plugin. (`event-emitters.ts`)
+
+> License: comfyui-api is MIT (deps MIT/Apache-2.0; ComfyUI itself GPL-3.0). Patterns/code are safe
+> to adapt with attribution. Clone for reference: `~/code/salad-comfyui-api`.
+
+---
+
+## "Roadmap to the roadmap" — sequencing
+
+| Phase | Goal | Items |
+| --- | --- | --- |
+| **0 — now (parallel)** | Enablers + node lifecycle + panel backend POC | A1, A2, C1, C2, C4, B1, B2 |
+| **1 — prove the loop** | Live in-UI editing works | B3, B4, C3, C5, E5, E6 |
+| **2 — productionize** | Full agent panel + discovery + I/O | B5, B6, D1, E8, E9, E10, E12 |
+| **Hardening — continuous** | Reliability + I/O from comfyui-api | E1, E2, E3, E4, E7, E11 |
+
+Phase 0 ships value immediately (skills + node tooling) and de-risks the panel (tunnel + streaming)
+before any frontend work. Phase 1 needs the v2 package closer to publish for the panel UI.

package/TODO.md

@@ -0,0 +1,75 @@
+# ComfyUI MCP — Future Work
+
+## Node Discovery & Research Agent
+
+**Priority**: High — addresses discoverability gap
+
+### Problem
+Users don't know what custom node packs exist for their use case. Finding, evaluating, and understanding nodes is a manual process (browsing the registry, reading READMEs, trial and error).
+
+### Proposed Solution
+A `comfy-researcher` agent (or enhanced `comfy-explorer`) that:
+
+1. **Search phase**: Takes a user's problem description (e.g., "I need better face detail in my generations") and:
+   - Searches the ComfyUI Registry (`api.comfy.org`) for relevant node packs
+   - Cross-references with HuggingFace for related models
+   - Checks community forums/GitHub for recommendations
+
+2. **Analyze phase**: For each candidate node pack:
+   - Runs `generate_node_skill` to deep-dive into the pack
+   - Checks if it's already installed (`/object_info`)
+   - Reviews GitHub stars, last update, compatibility
+   - Evaluates if it actually solves the user's problem
+
+3. **Recommend phase**: Returns a ranked list with:
+   - Why each pack fits (or doesn't)
+   - Installation instructions
+   - Example workflow snippets showing how to integrate with the user's existing workflow
+
+### Architecture Options
+
+**Option A: Agent-only** — A Claude Code agent (`comfy-researcher.md`) that orchestrates existing tools:
+- `search_custom_nodes` (already have)
+- `get_node_pack_details` (already have)
+- `generate_node_skill` (already have)
+- WebSearch + WebFetch for community research
+- Pros: Simple, uses existing infrastructure
+- Cons: Slow (multiple API calls per session)
+
+**Option B: Agent + Cache** — Same agent but with a skill cache layer:
+- Skills generated by `generate_node_skill` are cached at `~/.claude/skills/comfyui-packs/{pack}@{version}/SKILL.md`
+- Agent checks cache first before re-analyzing
+- Cache hit = instant category/I/O lookup for visualization too
+- Compound key: `{registry_id}@{version}` or `{github_owner}/{repo}@{commit_sha}`
+- Pros: Fast repeat lookups, shared with visualizer
+- Cons: Cache invalidation, storage
+
+**Option C: MCP Resource** — Expose cached skills as MCP resources:
+- `comfyui://skills/{pack_name}` returns cached SKILL.md content
+- Claude Code auto-loads relevant skills when working with workflows
+- Pros: Deep integration, always-available context
+- Cons: More complex to implement
+
+### Skill Cache Schema
+```
+~/.claude/skills/comfyui-packs/
+├── comfyui-impact-pack@4.5.0/
+│   ├── SKILL.md
+│   └── metadata.json  # {version, category_map, output_type_map, cached_at}
+├── comfyui-kjnodes@1.2.3/
+│   ├── SKILL.md
+│   └── metadata.json
+└── index.json  # {pack_id: {version, categories: [...], node_count}}
+```
+
+### Cache Integration Points
+1. **`visualize_workflow`** — Before fetching `/object_info`, check skill cache for category maps
+2. **`generate_node_skill`** — Write to cache on generation, skip if cache hit with matching version
+3. **`comfy-researcher` agent** — Read cache for instant analysis of previously-seen packs
+4. **`comfy-explorer` agent** — Read cache to understand node context when exploring packs
+
+### Next Steps
+- [ ] Create `comfy-researcher` agent definition in `plugin/agents/researcher.md`
+- [ ] Add skill cache layer to `generate_node_skill` tool
+- [ ] Wire cache into `visualize_workflow` for category lookups
+- [ ] Add `/comfy-research "better face detail"` slash command

package/blog/comfyui-mcp-tdqs-case-study.md

@@ -0,0 +1,102 @@
+# From B to A: sharpening 70+ tool descriptions with TDQS
+
+*by [artokun](https://github.com/artokun) · May 25, 2026 · MCP, TDQS, case study*
+
+[comfyui-mcp](https://github.com/artokun/comfyui-mcp) is an MCP server that lets an AI agent
+drive [ComfyUI](https://github.com/comfyanonymous/ComfyUI) — generate images, run and author
+workflows, manage models and custom nodes. It exposes 70+ tools. When it landed on Glama, the
+dashboard gave it a **Tool Definition Quality Score of B**. Here's what fixing that taught us —
+and a few rules any MCP author can steal.
+
+## The number that actually matters
+
+[TDQS](https://glama.ai/blog/2026-04-03-tool-definition-quality-score-tdqs) blends **Tool
+Definition Quality (70%)** and **Server Coherence (30%)**. Each tool is scored 1–5 across six
+dimensions, but the part that bit us is how the per-tool scores roll up into the server score:
+
+> server definition quality = 60% × **mean** TDQS + 40% × **minimum** TDQS
+
+That 40%-on-the-minimum is the whole game. Our *average* tool was already ~4.1 — solidly A. Most
+tools scored 4.3–4.7. But the grade was a B, because our single weakest tool, `cancel_job`,
+scored **3.1** and dragged everything down with it.
+
+**One vague tool caps your whole server.** So the highest-leverage work isn't polishing your best
+tools — it's finding and fixing your worst one.
+
+## The pattern hiding in the dimensions
+
+Expanding the low scorers, the same two dimensions were weak almost everywhere — even on
+otherwise-strong tools:
+
+- **Usage Guidelines** (2/5 at worst): the description never said *when* to use this tool versus
+  a sibling that does something similar.
+- **Behavior** (2/5): it didn't disclose side effects, preconditions, or whether the tool is even
+  read-only.
+
+A third, **Parameters**, was quietly capped: our zod schemas already described every parameter,
+so when the prose merely *restated* the schema, the dimension maxed out at 3. Descriptions have to
+add something the schema can't.
+
+## What we changed
+
+We rewrote descriptions against three rules:
+
+**1. Disambiguate against siblings.** If you ship three ways to cancel things, say which is which.
+
+**2. Disclose behavior up front.** Read-only? Mutates disk? Requires a running server?
+Asynchronous (returns an id you poll later)? Local-only vs. works-against-remote? Destructive and
+irreversible?
+
+**3. Add meaning beyond the schema.** Units, valid ranges, what omitting an optional param does,
+and what comes back.
+
+Here's `cancel_job`, our 3.1, before and after:
+
+> **Before:** "Cancel or interrupt a running ComfyUI job. Optionally target by prompt_id."
+
+> **After:** "Interrupt the **currently running** ComfyUI job, optionally only when its prompt_id
+> matches. Stops in-progress execution — the partial result is discarded and not recoverable — and
+> does **not** remove pending/queued jobs. Requires a reachable ComfyUI server. Use this for the
+> job executing right now; use `cancel_queued_job` to remove one specific pending job, or
+> `clear_queue` to drop all pending jobs."
+
+Same tool, same parameters. The second version tells an agent when to reach for it, what it does
+to the world, and what *not* to use it for.
+
+## A gotcha: score what the checker actually sees
+
+One of the lowest-scoring definitions in our own audit was the template behind *auto-loaded
+workflow* tools — tools the server generates from `*.json` files a user drops in a directory. We
+almost spent time polishing it. But TDQS scores the tools the **running server actually exposes**,
+and Glama boots the server in a clean environment with no workflow files — so those tools never
+register and never get scored.
+
+Lesson: audit against the tool list your server emits on a *fresh* boot, not the theoretical
+maximum.
+
+## Keeping it from rotting
+
+Descriptions drift. To keep ours honest, the tool reference is **generated from the live schemas**
+— a script boots the server with a capturing mock, reads each tool's name, description, and zod
+schema, and emits the docs. One source of truth for both the agent and humans, so a sloppy edit
+shows up immediately. (Our [docs](https://comfyui-mcp.artokun.io/docs) are built this way.)
+
+## The result
+
+Raising the floor — `cancel_job`, `list_local_models`, `search_models`, and the rest of the
+sub-3.5 cluster — plus the cross-cutting Usage/Behavior pass took the minimum from **3.1 to ~4.0**.
+With the 60/40 split, that pulls the server out of B and into A on the next re-index.
+
+## Takeaways for MCP authors
+
+1. **Fix your worst tool first** — the 40%-minimum weighting means it sets your grade.
+2. **Every description should answer three questions:** what does this do to the world, when do I
+   use it instead of a sibling, and what do the parameters mean beyond their types?
+3. **Don't just echo the schema** — it already covers structure; prose should add intent.
+4. **Audit the fresh-boot tool list**, not your theoretical one.
+5. **Generate the reference from the schema** so quality can't silently regress.
+
+---
+
+comfyui-mcp is open source: [github.com/artokun/comfyui-mcp](https://github.com/artokun/comfyui-mcp)
+· docs at [comfyui-mcp.artokun.io/docs](https://comfyui-mcp.artokun.io/docs).

package/design/embedded-agent-panel.md

@@ -0,0 +1,118 @@
+# Embedded agent panel — Ungate extraction → AI-SDK chat inside ComfyUI
+
+> North star: a ComfyUI **sidebar tab** (AI icon) that hosts a chat window. You talk to a coding
+> agent (Claude Code / Codex / Gemini) and it **reads and fixes the live workflow in the UI**.
+> Connection to the agent "app" is set up via a **cloudflared tunnel**, modeled on how the
+> [Ungate](https://github.com/orchidfiles/ungate) VS Code extension connects Cursor to a local proxy.
+
+## 1. What Ungate is (reference architecture, MIT)
+
+Three tiers in a pnpm monorepo (`~/code/ungate`):
+
+- **`apps/extension`** (VS Code host) — lifecycle + supervision:
+  - `tunnel-manager.ts` — wraps the [`cloudflared`](https://www.npmjs.com/package/cloudflared) npm package.
+  - `api-server.ts` — spawns the local proxy as a detached child, parses its port from stdout,
+    health-checks `/health`, restarts/auto-stops.
+  - `dashboard.ts` + webview — hosts the Svelte UI, relays messages.
+- **`apps/api`** (local proxy) — Fastify server: provider OAuth (Claude/ChatGPT), Anthropic↔OpenAI
+  translation, tool-call mapping, streaming, `/health`. Listens on `0.0.0.0:PORT`, prints
+  `localhost:PORT` to stdout. This is the part that turns a **subscription** into an OpenAI-shaped endpoint.
+- **`apps/web`** (webview UI) — Svelte dashboard: tunnel panel, provider auth, analytics. Talks to
+  the host via `postMessage` (`start-tunnel` / `tunnel-status` / …).
+
+Flow: `Cursor chat → Cursor backend → Cloudflare tunnel → Ungate proxy → Provider API → back`.
+Tunnel exists because **Cursor's backend can't call `localhost`** — it needs a public HTTPS URL.
+
+## 2. The bits that matter (verbatim mechanics)
+
+### 2a. Tunnel mechanic — the crux (`tunnel-manager.ts`)
+```ts
+import { bin, install, use, Tunnel } from 'cloudflared';
+// ensure binary: if !fs.existsSync(bin) → install(<path>) then use(<path>)
+const t = Tunnel.quick(`http://localhost:${port}`, {
+  '--config': process.platform === 'win32' ? 'NUL' : '/dev/null',
+  '--edge-ip-version': '4',
+});
+t.on('url',   (url)  => { /* public https://<rand>.trycloudflare.com */ });
+t.on('stderr',(line) => { /* logs */ });
+t.on('error', (err)  => { /* error state */ });
+t.on('exit',  (code) => { /* stopped/error */ });
+t.stop();
+```
+State machine: `stopped → starting → (installing) → running → error`. Auto-stops on an interval
+when there are no live clients. **This is plain Node — it drops straight into our server; no VS Code needed.**
+
+### 2b. Local-server supervision (`api-server.ts`)
+- `cp.spawn(node, [entry], { detached: true })`, `.unref()`.
+- Detect ready by regex-matching `localhost:(\d+)` on stdout.
+- Poll `GET /health` on an interval; restart on crash; stop after a no-clients grace period.
+- Reattach to an already-running instance on `EADDRINUSE` (multi-window safe).
+
+### 2c. Connection UX + messaging (`apps/web` tunnel-store + `$shared/vscode`)
+- Reactive `TunnelState { status, url, error }` rendered in a panel.
+- Buttons post intents to the host (`start-tunnel`/`stop-tunnel`/`restart-tunnel`); host pushes
+  `tunnel-status` back. User **copies the public URL + a proxy key** into the client.
+
+### 2d. Security model (README)
+- CORS `origin: '*'` on the proxy (tunnel is the perimeter).
+- **Tunnel URL + proxy key are secrets**; anyone with both can drive your proxy. Key is rotatable.
+- OAuth/provider creds stored locally only.
+
+## 3. Mapping → our stack (AI SDK + ComfyUI extension-api)
+
+| Ungate piece | Our equivalent | Keep / Replace / New |
+| --- | --- | --- |
+| `tunnel-manager.ts` (cloudflared) | Same lib, lifted into our local app | **Keep** (port nearly verbatim) |
+| `api-server.ts` supervisor | We *are* the server (no separate child needed at first) | **Simplify** |
+| `apps/api` Fastify proxy + provider OAuth/translation | **AI SDK** `streamText` + provider registry (`@ai-sdk/anthropic`, `@ai-sdk/openai`, `@ai-sdk/google`) | **Replace** (AI SDK does translation/streaming/tools) |
+| Cursor (the client) | **ComfyUI sidebar tab** with AI SDK `useChat` | **Replace** |
+| VS Code webview + `postMessage` | ComfyUI `defineSidebarTab` (Vue) + HTTP/WS to tunnel | **Replace** |
+| Webview tunnel panel (copy URL+key) | Panel "Connection" section (paste/auto URL + key) | **Keep shape** |
+| — (Ungate has none) | **Live graph edits** via `NodeHandle`/`WidgetHandle` as AI SDK *client-side tools* | **New (the magic)** |
+| comfyui-mcp tools | Server-side tools via AI SDK MCP client (`experimental_createMCPClient`) | **Keep + wire in** |
+
+## 4. Target shape
+
+### "The app" — local bridge (we build; likely extends comfyui-mcp)
+A Node HTTP server on `localhost:PORT`:
+- `POST /api/chat` → AI SDK `streamText({ model, messages, tools }).toUIMessageStreamResponse()`.
+- **Provider registry** picks Claude / Codex(OpenAI) / Gemini per request (the pluggable "agent").
+- **Tools**:
+  - *server-side* (have `execute`): generate, search/download models, build/modify/enqueue big
+    workflows, queue mgmt — backed by **comfyui-mcp** (consumed as MCP tools).
+  - *client-side* (no `execute`; resolved in the panel): `read_graph`, `set_widget_value`,
+    `add_node`, `connect`, `move_node`, … → executed via extension-api in the browser.
+- `GET /health` for supervision; CORS open (tunnel is the perimeter); a bearer **session key**.
+- **cloudflared `Tunnel.quick`** exposes it → public HTTPS URL the ComfyUI page can reach (even when
+  ComfyUI is remote or served over HTTPS — solves mixed-content + remote installs).
+
+### ComfyUI panel — `defineSidebarTab` (AI icon)
+- AI SDK `useChat({ api: <tunnelURL>/api/chat, headers: { Authorization: Bearer <key> } })`.
+- **Connection** section: paste/auto-discover tunnel URL + key (Ungate `TunnelPanel` analog).
+- Renders streamed messages + tool-call cards.
+- `onToolCall` → for graph-mutation tools, call extension-api (`NodeHandle.setValue(...)`, etc.),
+  then `addToolResult(...)`. This is how "fix the workflow directly in the UI" happens — through the
+  same undo-able command path a human uses. Live context comes from `graph`/`execution` events.
+
+## 5. Key adaptations vs. Ungate
+- **Same tunnel direction** (expose local app over HTTPS so a remote/HTTPS ComfyUI reaches it).
+- **Drop the OAuth-subscription proxy for v1** — AI SDK + provider keys is far less code. (If we
+  later want Ungate's "use your subscription, not API tokens," `apps/api/src/auth/*` is the part to lift.)
+- **Client-side tool execution is the novel core** — Ungate only proxies; we additionally let the
+  model *act on the open graph* via extension-api.
+
+## 6. Build order
+0. **v2 authoring skill** (enabler — write the extension correctly).
+1. **Tunnel helper** — port `tunnel-manager` into our server (`startQuickTunnel(port) → url`), behind a flag.
+2. **AI SDK chat endpoint** — `/api/chat` with one server-side tool (`generate_image`) end-to-end.
+3. **Sidebar skeleton** — `defineSidebarTab` + `useChat` hitting the tunnel; render stream.
+4. **Live edit** — one client-side tool (`set_widget_value`) applied via `WidgetHandle`; prove the loop.
+5. **Wire comfyui-mcp** as the server-side tool surface (MCP client); expand client-side graph tools.
+6. **Provider switch** (Claude/Codex/Gemini) + connection/key UX + polish into a shippable node pack.
+
+## References
+- Ungate (MIT): https://github.com/orchidfiles/ungate — clone at `~/code/ungate`.
+- `cloudflared` npm: https://www.npmjs.com/package/cloudflared
+- ComfyUI v2 extension API: `Comfy-Org/ComfyUI_frontend` PRs #12142–#12145; `src/extension-api/`.
+- AI SDK: provider registry, `streamText`, `useChat`, client-side tools (`onToolCall`/`addToolResult`),
+  MCP client (`experimental_createMCPClient`).

package/dist/experimental/agent-poc.d.ts

@@ -0,0 +1,30 @@
+export interface AgentPocOptions {
+    port?: number;
+    host?: string;
+    /** Open a cloudflared quick tunnel and log the public URL. */
+    tunnel?: boolean;
+    /** Bearer token required on /api/chat. Auto-generated if omitted. */
+    token?: string;
+    /** Max accepted request body size in bytes for /api/chat (default 1 MiB). */
+    maxBodyBytes?: number;
+}
+export interface AgentPocHandle {
+    /** Local URL the chat server is listening on. */
+    localUrl: string;
+    /** Public tunnel URL, if a tunnel was opened. */
+    publicUrl: string | null;
+    /** Bearer token clients must send as `Authorization: Bearer <token>`. */
+    token: string;
+    stop(): Promise<void>;
+}
+/**
+ * Start the experimental agent POC HTTP server (and optional tunnel).
+ * Returns a handle (incl. the bearer token). Callers gate this behind the env flag.
+ */
+export declare function startAgentPoc(options?: AgentPocOptions): Promise<AgentPocHandle>;
+/**
+ * Gated bootstrap. Only starts the POC when COMFYUI_MCP_AGENT_POC is truthy.
+ * Safe to call unconditionally from a side entry; a no-op otherwise.
+ */
+export declare function maybeStartAgentPoc(): Promise<AgentPocHandle | null>;
+//# sourceMappingURL=agent-poc.d.ts.map

package/dist/experimental/agent-poc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-poc.d.ts","sourceRoot":"","sources":["../../src/experimental/agent-poc.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAiGD;;;GAGG;AACH,wBAAsB,aAAa,CACjC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CA2DzB;AAoED;;;GAGG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAOzE"}