comfyui-mcp 0.17.0 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comfyui-mcp",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "mcpName": "io.github.artokun/comfyui-mcp",
   "description": "Claude Code plugin + MCP server for ComfyUI - 96 tools, 16 AI skills (Flux, WAN, LTX video, Qwen, Civitai), live graph editing from your Claude session. Generate images, video & audio, manage models and custom nodes.",
   "homepage": "https://comfyui-mcp.artokun.io/docs",
@@ -13,6 +13,7 @@
     "dist",
     "plugin",
     "packs",
+    "scripts",
     "model-settings.json",
     "model-settings.user.jsonc.example"
   ],
@@ -23,6 +24,7 @@
     "dev:agent-poc": "tsx src/experimental/run.ts",
     "start": "node dist/index.js",
     "test": "vitest run --passWithNoTests",
+    "smoke": "npm run build && node scripts/smoke-install.mjs",
     "test:watch": "vitest",
     "test:integration": "cross-env COMFYUI_INTEGRATION=true vitest run",
     "test:agent": "npm run build && node scripts/test-agent.mjs",

package/scripts/check-model-urls.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// Validate every model URL in every pack manifest WITHOUT downloading the file:
+//  - the link resolves (HTTP 200 via HEAD, or 206 via a 1-byte ranged GET)
+//  - Content-Length falls in a sane band for the model type (folder), so a dead
+//    link returning a small HTML error page is caught as "too small".
+//
+//   node scripts/check-model-urls.mjs            # all packs
+//   node scripts/check-model-urls.mjs packs/anima
+//
+// Exit non-zero if any URL is unreachable or implausibly sized.
+
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "yaml";
+
+const MB = 1024 * 1024;
+const GB = 1024 * MB;
+
+// Minimum plausible size per model category (top folder under models/).
+// Generous on the ceiling; the floor is the real signal (catches error pages).
+const FLOOR = {
+  diffusion_models: 100 * MB,
+  unet: 80 * MB,
+  checkpoints: 100 * MB,
+  text_encoders: 40 * MB,
+  clip: 40 * MB,
+  vae: 8 * MB,
+  loras: 512 * 1024,
+  controlnet: 512 * 1024,
+  upscale_models: 1 * MB,
+  ultralytics: 1 * MB,
+  sams: 40 * MB,
+};
+const DEFAULT_FLOOR = 256 * 1024;
+const CEILING = 80 * GB;
+const CONCURRENCY = 8;
+const TIMEOUT_MS = 30_000;
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const packsRoot = join(repoRoot, "packs");
+
+function packDirs() {
+  const arg = process.argv[2];
+  if (arg) return [join(repoRoot, arg)];
+  return readdirSync(packsRoot)
+    .map((n) => join(packsRoot, n))
+    .filter((p) => statSync(p).isDirectory() && existsSync(join(p, "manifest.yaml")));
+}
+
+function category(m) {
+  if (m.local_path) return m.local_path.split(/[\\/]/)[0];
+  return m.model_type || "checkpoints";
+}
+
+function human(n) {
+  if (!Number.isFinite(n)) return "?";
+  if (n >= GB) return (n / GB).toFixed(2) + "GB";
+  if (n >= MB) return (n / MB).toFixed(1) + "MB";
+  return (n / 1024).toFixed(0) + "KB";
+}
+
+const RETRIES = 4;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Fetch with retries: transient network errors, timeouts, 429s and 5xx are
+// retried with linear backoff so one hiccup against a CDN doesn't fail CI.
+async function fetchRetry(url, opts) {
+  let lastErr;
+  for (let attempt = 0; attempt < RETRIES; attempt++) {
+    const ac = new AbortController();
+    const t = setTimeout(() => ac.abort(), TIMEOUT_MS);
+    try {
+      const r = await fetch(url, { ...opts, signal: ac.signal });
+      if (r.status === 429 || r.status >= 500) {
+        lastErr = new Error(`HTTP ${r.status}`);
+      } else {
+        return r;
+      }
+    } catch (e) {
+      lastErr = new Error(e?.name === "AbortError" ? "timeout" : e?.message ?? String(e));
+    } finally {
+      clearTimeout(t);
+    }
+    if (attempt < RETRIES - 1) await sleep(600 * (attempt + 1));
+  }
+  throw lastErr ?? new Error("request failed");
+}
+
+async function probe(url) {
+  try {
+    const r = await fetchRetry(url, { method: "HEAD", redirect: "follow" });
+    // Gated repos (HF 🔒) answer 401/403 without a token — the link is valid,
+    // it just needs auth. Treat as OK (size unverifiable without the token).
+    if (r.status === 401 || r.status === 403) return { ok: true, gated: true, status: r.status, size: NaN };
+    const len = r.headers.get("content-length");
+    if (r.ok && len) return { ok: true, status: r.status, size: Number(len) };
+    // Fallback: a 1-byte ranged GET yields the total via Content-Range, no download.
+    const g = await fetchRetry(url, { headers: { Range: "bytes=0-0" }, redirect: "follow" });
+    try { await g.body?.cancel(); } catch { /* ignore */ }
+    const cr = g.headers.get("content-range"); // "bytes 0-0/12345"
+    if (cr && cr.includes("/")) {
+      const total = Number(cr.split("/").pop());
+      if (Number.isFinite(total)) return { ok: g.status === 206 || g.ok, status: g.status, size: total };
+    }
+    const len2 = g.headers.get("content-length");
+    return { ok: r.ok || g.ok, status: g.ok ? g.status : r.status, size: len2 ? Number(len2) : NaN };
+  } catch (e) {
+    return { ok: false, status: 0, size: NaN, error: e?.message ?? String(e) };
+  }
+}
+
+async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length);
+  let i = 0;
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (i < items.length) {
+      const idx = i++;
+      out[idx] = await fn(items[idx], idx);
+    }
+  });
+  await Promise.all(workers);
+  return out;
+}
+
+const tasks = [];
+for (const dir of packDirs()) {
+  const manifest = parse(readFileSync(join(dir, "manifest.yaml"), "utf8")) || {};
+  for (const m of manifest.models || []) {
+    tasks.push({ pack: basename(dir), model: m, cat: category(m) });
+  }
+}
+
+console.log(`Checking ${tasks.length} model URLs across ${new Set(tasks.map((t) => t.pack)).size} packs...\n`);
+
+let bad = 0;
+const results = await mapLimit(tasks, CONCURRENCY, async (t) => {
+  const r = await probe(t.model.url);
+  const floor = FLOOR[t.cat] ?? DEFAULT_FLOOR;
+  let verdict = "OK";
+  if (!r.gated) {
+    if (!r.ok) verdict = `BAD LINK (${r.error || "HTTP " + r.status})`;
+    else if (!Number.isFinite(r.size)) verdict = "NO SIZE (server gave no length)";
+    else if (r.size < floor) verdict = `TOO SMALL (${human(r.size)} < floor ${human(floor)} for ${t.cat})`;
+    else if (r.size > CEILING) verdict = `TOO BIG (${human(r.size)})`;
+  }
+  if (verdict !== "OK") bad++;
+  return { ...t, ...r, verdict };
+});
+
+let curPack = "";
+for (const r of results) {
+  if (r.pack !== curPack) { curPack = r.pack; console.log(`# ${curPack}`); }
+  const name = r.model.local_path ? basename(r.model.local_path) : basename(new URL(r.model.url).pathname);
+  const mark = r.verdict === "OK" ? "ok " : "ERR";
+  console.log(`  [${mark}] ${name.padEnd(48)} ${human(r.size).padStart(8)}  ${r.verdict === "OK" ? "" : "<- " + r.verdict}`);
+}
+
+console.log(`\n${results.length - bad}/${results.length} OK`);
+if (bad) { console.error(`${bad} model URL(s) failed validation.`); process.exit(1); }

package/scripts/check-pack-models.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// Cross-check every pack's workflow.json against its manifest.yaml so a loader
+// node can't reference a model file the pack never downloads (and vice versa).
+//
+// This is the guard that was missing when two packs shipped a VAELoader pointing
+// at `ae.safetensors` while their installers only fetched a different VAE — the
+// node throws a missing-model error on load, but nothing caught it in review.
+//
+//   node scripts/check-pack-models.mjs              # all packs
+//   node scripts/check-pack-models.mjs packs/ernie  # one pack
+//
+// Exit non-zero if any workflow references a model the manifest doesn't provide.
+// Dead downloads (provided but never referenced) are reported as warnings only.
+
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "yaml";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const packsRoot = join(repoRoot, "packs");
+
+// File extensions that denote a model weight the pack must provide.
+const MODEL_EXT = /\.(safetensors|sft|gguf|ckpt|pt|pth|bin|onnx)$/i;
+
+// Loader widget values are sometimes a sentinel rather than a real file.
+const SENTINELS = new Set(["none", "undefined", "null", ""]);
+
+// Node types that fetch their own weights on first run (the model is NOT the
+// manifest's responsibility): controlnet-aux preprocessors, RIFE interpolation,
+// and the kijai DownloadAndLoad* nodes. A reference from one of these is never
+// a manifest gap.
+const SELF_MANAGING = /(^DownloadAndLoad)|Preprocessor$|RIFE|InsightFace/i;
+const isSelfManaging = (type) => SELF_MANAGING.test(String(type || ""));
+
+function packDirs() {
+  const arg = process.argv[2];
+  if (arg) return [join(repoRoot, arg)];
+  return readdirSync(packsRoot)
+    .map((n) => join(packsRoot, n))
+    .filter((p) => statSync(p).isDirectory() && existsSync(join(p, "manifest.yaml")));
+}
+
+// Compare by basename, lowercased — manifest local_paths and workflow widget
+// values disagree on subfolders (e.g. "loras\\style\\x.safetensors" vs
+// "loras/x.safetensors"), but the filename ComfyUI loads is the same.
+const norm = (p) => basename(String(p).replace(/\\/g, "/")).toLowerCase();
+
+// Files a manifest downloads (basename of local_path, else filename, else URL).
+function providedFiles(manifest) {
+  const out = new Map(); // norm -> display name
+  for (const m of manifest.models || []) {
+    let name;
+    if (m.local_path) name = basename(m.local_path);
+    else if (m.filename) name = m.filename;
+    else if (m.url) {
+      try {
+        name = basename(new URL(m.url).pathname);
+      } catch {
+        name = m.url;
+      }
+    }
+    if (name) out.set(norm(name), name);
+  }
+  return out;
+}
+
+// Model files referenced by a workflow's loader nodes. We scan widgets_values
+// (the value ComfyUI actually loads) for strings ending in a model extension —
+// NOT node.properties.models, which is a download hint that is often stale.
+function referencedFiles(workflow) {
+  const refs = new Map(); // norm -> { name, nodes: [{type,id,bypassed}] }
+  const record = (val, node) => {
+    if (typeof val !== "string") return;
+    if (SENTINELS.has(val.toLowerCase())) return;
+    if (!MODEL_EXT.test(val)) return;
+    const key = norm(val);
+    if (!refs.has(key)) refs.set(key, { name: val, nodes: [] });
+    refs.get(key).nodes.push({
+      type: node.type,
+      id: node.id,
+      bypassed: node.mode === 2 || node.mode === 4,
+    });
+  };
+  const walk = (v, node) => {
+    if (Array.isArray(v)) v.forEach((x) => walk(x, node));
+    else if (v && typeof v === "object") Object.values(v).forEach((x) => walk(x, node));
+    else record(v, node);
+  };
+  for (const node of workflow.nodes || []) walk(node.widgets_values, node);
+  return refs;
+}
+
+let errors = 0;
+let warnings = 0;
+
+for (const dir of packDirs()) {
+  const name = basename(dir);
+  const manifest = parse(readFileSync(join(dir, "manifest.yaml"), "utf8")) || {};
+  const packPath = join(dir, "pack.yaml");
+  const pack = existsSync(packPath) ? parse(readFileSync(packPath, "utf8")) || {} : {};
+  const wfFile = pack.workflow || "workflow.json";
+  const wfPath = join(dir, wfFile);
+  if (!existsSync(wfPath)) {
+    console.log(`SKIP ${name} — no ${wfFile}`);
+    continue;
+  }
+
+  const provided = providedFiles(manifest);
+  const referenced = referencedFiles(JSON.parse(readFileSync(wfPath, "utf8")));
+  // Files the workflow legitimately references but the pack intentionally does
+  // not download (user-supplied LoRAs, etc.). Declared in pack.yaml so the gap
+  // is explicit and reviewed, not silent. Compared by basename.
+  const allowed = new Set((pack.external_models || []).map(norm));
+
+  // An ACTIVE loader pointing at a file the manifest doesn't provide is a hard
+  // error (ComfyUI flags it missing on load). The same from a bypassed node, a
+  // self-managing node, or an allow-listed file is a warning at most.
+  const hardMissing = [];
+  const softMissing = [];
+  for (const [key, info] of referenced) {
+    if (provided.has(key)) continue;
+    if (allowed.has(key)) continue;
+    const liveLoaders = info.nodes.filter((n) => !n.bypassed && !isSelfManaging(n.type));
+    (liveLoaders.length ? hardMissing : softMissing).push(info);
+  }
+  // Dead downloads: provided but no loader references them. Often intentional
+  // (alt quants, optional upscalers), so this is a warning, not an error.
+  const unused = [];
+  for (const [key, disp] of provided) {
+    if (!referenced.has(key)) unused.push(disp);
+  }
+
+  if (hardMissing.length === 0) {
+    console.log(`OK   ${name} — ${referenced.size} model refs, no live gaps`);
+  }
+  for (const info of hardMissing) {
+    const where = info.nodes
+      .map((n) => `${n.type}#${n.id}${n.bypassed ? "(bypassed)" : ""}`)
+      .join(", ");
+    console.error(`FAIL ${name} — workflow references "${info.name}" not downloaded by manifest [${where}]`);
+    errors++;
+  }
+  for (const info of softMissing) {
+    console.warn(`warn ${name} — "${info.name}" referenced only by bypassed/self-managing nodes, not in manifest`);
+    warnings++;
+  }
+  for (const disp of unused) {
+    console.warn(`warn ${name} — manifest downloads "${disp}" but no loader references it`);
+    warnings++;
+  }
+}
+
+console.log(`\n${errors} error(s), ${warnings} warning(s)`);
+process.exit(errors ? 1 : 0);

package/scripts/gen-pack-installers.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// Generate one-click install-windows.bat + install-runpod.sh for each pack from
+// its pack.yaml + manifest.yaml. The manifest is the single source of truth
+// (also consumed by apply_manifest); never hand-edit the generated scripts.
+//
+//   node scripts/gen-pack-installers.mjs              # all packs/*
+//   node scripts/gen-pack-installers.mjs packs/anima  # one pack
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join, basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "yaml";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const packsRoot = join(repoRoot, "packs");
+
+function packDirsFromArgs() {
+  const arg = process.argv[2];
+  if (arg) return [join(repoRoot, arg)];
+  return readdirSync(packsRoot)
+    .map((n) => join(packsRoot, n))
+    .filter((p) => statSync(p).isDirectory() && existsSync(join(p, "manifest.yaml")));
+}
+
+// Folder a `git clone <url>` lands in (basename, minus .git / trailing ref).
+function repoFolder(url) {
+  const noRef = url.replace(/(?<!^)@[^@/]+$/, "").replace(/[?#].*$/, "").replace(/\/+$/, "");
+  return basename(noRef).replace(/\.git$/i, "");
+}
+
+// Target path of a model, relative to models/.
+function modelRel(m) {
+  if (m.local_path) return m.local_path;
+  const fn = m.filename || basename(new URL(m.url).pathname);
+  return `${m.model_type || "checkpoints"}/${fn}`;
+}
+
+function genBat(pack, manifest) {
+  const nodes = manifest.custom_nodes || [];
+  const models = manifest.models || [];
+  const pip = manifest.pip || [];
+  const workflow = pack.workflow || "workflow.json";
+  const L = [];
+  L.push("@echo off");
+  L.push("setlocal EnableExtensions EnableDelayedExpansion");
+  L.push("chcp 65001 >nul");
+  L.push(`rem ===== Auto-generated by scripts/gen-pack-installers.mjs — do not edit =====`);
+  L.push(`rem Pack: ${pack.display_name || pack.name}`);
+  L.push("rem Run from your ComfyUI root (the folder containing custom_nodes\\ and models\\).");
+  L.push('if not exist "custom_nodes" ( echo [ERROR] Run from your ComfyUI root ^(custom_nodes\\ not found^). & pause & exit /b 1 )');
+  L.push('where git >nul 2>&1 || ( echo [ERROR] git not found in PATH. & pause & exit /b 1 )');
+  L.push('where curl >nul 2>&1 || ( echo [ERROR] curl not found in PATH. & pause & exit /b 1 )');
+  L.push("rem Resolve the ComfyUI python: venv first, then portable embed, then PATH python.");
+  L.push('set "PY=%CD%\\.venv\\Scripts\\python.exe"');
+  L.push('if not exist "%PY%" set "PY=%CD%\\venv\\Scripts\\python.exe"');
+  L.push('if not exist "%PY%" set "PY=%CD%\\..\\python_embeded\\python.exe"');
+  L.push('if not exist "%PY%" set "PY=python"');
+  L.push('echo using python: %PY%');
+  L.push("");
+  L.push("echo -------- custom nodes --------");
+  for (const url of nodes) L.push(`call :clone "${repoFolder(url)}" "${url}"`);
+  if (pip.length) {
+    L.push("");
+    L.push("echo -------- pip (manifest extras) --------");
+    for (const p of pip) L.push(`"%PY%" -m pip install "${p}"`);
+  }
+  L.push("");
+  L.push("echo -------- models --------");
+  for (const m of models) L.push(`call :grab "models\\${modelRel(m).replace(/\//g, "\\")}" "${m.url}"`);
+  L.push("");
+  L.push(`echo DONE. Restart ComfyUI, then load ${workflow}.`);
+  L.push("pause");
+  L.push("exit /b");
+  L.push("");
+  L.push(":clone");
+  L.push('if not exist "custom_nodes\\%~1" (');
+  L.push("  echo   cloning %~1");
+  L.push('  git clone --depth 1 "%~2" "custom_nodes\\%~1"');
+  L.push('  if exist "custom_nodes\\%~1\\requirements.txt" ( echo   installing %~1 requirements.txt & "%PY%" -m pip install -r "custom_nodes\\%~1\\requirements.txt" )');
+  L.push(") else ( echo   %~1 present - skip )");
+  L.push("goto :eof");
+  L.push("");
+  L.push(":grab");
+  L.push('if not exist "%~dp1" mkdir "%~dp1"');
+  L.push('if not exist "%~1" ( echo   downloading %~nx1 & curl -L --ssl-no-revoke -o "%~1" "%~2" ) else ( echo   %~nx1 present - skip )');
+  L.push("goto :eof");
+  return L.join("\r\n") + "\r\n";
+}
+
+function genSh(pack, manifest) {
+  const nodes = manifest.custom_nodes || [];
+  const models = manifest.models || [];
+  const pip = manifest.pip || [];
+  const workflow = pack.workflow || "workflow.json";
+  const L = [];
+  L.push("#!/usr/bin/env bash");
+  L.push("set -euo pipefail");
+  L.push("# ===== Auto-generated by scripts/gen-pack-installers.mjs — do not edit =====");
+  L.push(`# Pack: ${pack.display_name || pack.name}  (Linux / RunPod)`);
+  L.push("# Run from your ComfyUI root (the folder containing custom_nodes/ and models/).");
+  L.push('[ -d custom_nodes ] || { echo "[ERROR] run from your ComfyUI root (custom_nodes/ not found)"; exit 1; }');
+  L.push("# Resolve the ComfyUI python: its venv first, then portable embed, then \\$PYTHON/python3.");
+  L.push('# Installing requirements into the wrong interpreter is why nodes silently fail to load.');
+  L.push('if [ -n "${PYTHON:-}" ]; then PY="$PYTHON";');
+  L.push('elif [ -x ".venv/bin/python" ]; then PY=".venv/bin/python";');
+  L.push('elif [ -x "venv/bin/python" ]; then PY="venv/bin/python";');
+  L.push('elif [ -x "../python_embeded/python" ]; then PY="../python_embeded/python";');
+  L.push('else PY="python3"; fi');
+  L.push('echo "using python: $PY"');
+  L.push("");
+  L.push("clone() { # folder url");
+  L.push('  if [ ! -d "custom_nodes/$1" ]; then');
+  L.push('    echo "  cloning $1"; git clone --depth 1 "$2" "custom_nodes/$1"');
+  L.push('    if [ -f "custom_nodes/$1/requirements.txt" ]; then echo "  installing $1 requirements.txt"; "$PY" -m pip install -r "custom_nodes/$1/requirements.txt"; fi');
+  L.push('  else echo "  $1 present - skip"; fi');
+  L.push("}");
+  L.push("grab() { # relpath url");
+  L.push('  mkdir -p "$(dirname "$1")"');
+  L.push('  if [ ! -f "$1" ]; then echo "  downloading $(basename "$1")"; curl -L -o "$1" "$2"; else echo "  $(basename "$1") present - skip"; fi');
+  L.push("}");
+  L.push("");
+  L.push('echo "-------- custom nodes --------"');
+  for (const url of nodes) L.push(`clone "${repoFolder(url)}" "${url}"`);
+  if (pip.length) {
+    L.push("");
+    L.push('echo "-------- pip (manifest extras) --------"');
+    for (const p of pip) L.push(`"$PY" -m pip install "${p}"`);
+  }
+  L.push("");
+  L.push('echo "-------- models --------"');
+  for (const m of models) L.push(`grab "models/${modelRel(m)}" "${m.url}"`);
+  L.push("");
+  L.push(`echo "DONE. Restart ComfyUI, then load ${workflow}."`);
+  return L.join("\n") + "\n";
+}
+
+const dirs = packDirsFromArgs();
+if (!dirs.length) {
+  console.error("No packs found under packs/.");
+  process.exit(1);
+}
+for (const dir of dirs) {
+  const manifest = parse(readFileSync(join(dir, "manifest.yaml"), "utf8")) || {};
+  const packPath = join(dir, "pack.yaml");
+  const pack = existsSync(packPath) ? parse(readFileSync(packPath, "utf8")) || {} : { name: basename(dir) };
+  writeFileSync(join(dir, "install-windows.bat"), genBat(pack, manifest));
+  writeFileSync(join(dir, "install-runpod.sh"), genSh(pack, manifest));
+  const n = (manifest.custom_nodes || []).length;
+  const m = (manifest.models || []).length;
+  console.log(`${basename(dir)}: wrote install-windows.bat + install-runpod.sh (${n} nodes, ${m} models)`);
+}