UNPKG

comfyui-mcp

Version:

Local-first, agent-native control plane for ComfyUI — MCP server + autonomous sidebar agent that drives your live graph in natural language on ANY LLM: Claude/ChatGPT/Gemini on your subscription (no API key), free local models via Ollama (fully offline),

249 lines • 14.8 kB
import { z } from "zod"; import { searchHuggingFaceModels, listLocalModels, MODEL_SUBDIRS, } from "../services/model-resolver.js"; import { startDownloadJob, getDownloadJob, listDownloadJobs, } from "../services/download-jobs.js"; import { readDownloadProgress } from "../services/download-progress.js"; import { errorToToolResult, ModelError } from "../utils/errors.js"; /** * How long download_model waits before handing back a handle instead of a path. * Long enough that ordinary files (LoRAs, VAEs, cache hits) still return a path * as they always did; short enough that a big checkpoint never pins the turn. */ function downloadGraceMs() { const raw = Number(process.env.COMFYUI_MCP_DOWNLOAD_GRACE_MS); return Number.isFinite(raw) && raw >= 0 ? raw : 20_000; } const modelTypeEnum = z.enum(MODEL_SUBDIRS); // Download target subfolder: accept ANY relative subfolder under models/ (not // just the standard MODEL_SUBDIRS), since custom nodes expect models in arbitrary // or nested dirs (e.g. 'loras/<subdir>', a brand-new model type). The service // (resolveModelSubfolder) guards against absolute paths and traversal escapes. const downloadTargetSchema = z .string() .min(1) .describe(`Target subfolder under ComfyUI models/. Standard names: ${MODEL_SUBDIRS.join(", ")}. ` + `Any other relative subfolder (incl. nested like 'loras/<subdir>') is allowed; ` + `absolute paths and '..' escapes are rejected.`); const downloadAuthSchema = z.discriminatedUnion("type", [ z.object({ type: z.literal("bearer"), token: z.string().min(1).describe("Bearer token value"), }), z.object({ type: z.literal("basic"), username: z.string().describe("Basic auth username"), password: z.string().describe("Basic auth password"), }), z.object({ type: z.literal("header"), header_name: z.string().min(1).describe("HTTP header name"), header_value: z.string().describe("HTTP header value"), }), z.object({ type: z.literal("query"), query_param: z.string().min(1).describe("Query parameter name"), query_value: z.string().describe("Query parameter value"), }), z.object({ type: z.literal("s3"), access_key_id: z.string().min(1).describe("AWS/S3-compatible access key id"), secret_access_key: z.string().min(1).describe("AWS/S3-compatible secret access key"), session_token: z.string().optional().describe("Optional temporary session token"), region: z.string().optional().describe("Optional AWS region override"), endpoint: z.string().url().optional().describe("Optional S3-compatible endpoint for R2-style storage"), }), ]); export function registerModelManagementTools(server) { server.tool("search_models", "Search HuggingFace Hub for models usable in ComfyUI (checkpoints, LoRAs, VAEs, ControlNets, etc.). Read-only and network-only: queries HuggingFace over HTTP, does NOT require a running ComfyUI or COMFYUI_PATH and does not download anything. Returns a ranked list with modelId, author, downloads, likes, and tags. Pick a result's download URL and pass it to download_model to install it locally. For CIVITAI searches ('find a Flux LoRA on Civitai') use search_civitai_models instead — it filters by type + base model and returns ids for download_civitai_model. For packs of custom nodes (not models) use search_custom_nodes.", { query: z.string().describe("Search query (e.g. 'SDXL', 'flux', 'controlnet')"), filter: z .string() .optional() .describe("Optional HuggingFace pipeline/library tag to narrow results, e.g. 'diffusers' or 'text-to-image'"), limit: z .number() .int() .min(1) .max(50) .optional() .describe("Max results to return (default 10)"), }, async (args) => { try { const results = await searchHuggingFaceModels(args.query, { filter: args.filter, limit: args.limit, }); const text = results.length === 0 ? `No models found for "${args.query}".` : results .map((m, i) => `${i + 1}. **${m.modelId}** by ${m.author || "unknown"}\n` + ` Downloads: ${m.downloads.toLocaleString()} | Likes: ${m.likes}\n` + ` Tags: ${m.tags.slice(0, 5).join(", ") || "none"}`) .join("\n\n"); return { content: [{ type: "text", text }] }; } catch (err) { return errorToToolResult(err); } }); server.tool("download_model", "Download a model file to the connected ComfyUI's models directory from a URL (HuggingFace, direct HTTP(S), s3://, or Azure Blob). PREFER this over a raw shell download (curl/wget) for model weights: it lands the file in the right models/ subfolder. LOCAL ComfyUI: streams to disk and surfaces live progress in the panel download tray. REMOTE ComfyUI: dispatches the fetch to the ComfyUI host via the ComfyUI-Manager install-model HTTP API (downloaded server-side; a per-request `auth` header can't be forwarded). This requires the host's Manager to run with network_mode=personal_cloud (or loopback) and a permissive security level — a stricter gate silently rejects the download, and Manager reports the queue task 'done' even on failure, so a remote dispatch does not guarantee the file landed. target_subfolder accepts any relative subfolder (incl. nested, e.g. 'loras/<subdir>').", { url: z.string().url().describe("Direct download URL for the model file"), target_subfolder: downloadTargetSchema, filename: z .string() .optional() .describe("Override filename (auto-detected from URL if omitted)"), auth: downloadAuthSchema .optional() .describe("Optional per-request authentication for private/gated model URLs. " + "When provided it overrides built-in HuggingFace/CivitAI token handling."), }, async (args) => { try { // Start it, then wait only a GRACE WINDOW rather than the whole // transfer. Small files (a VAE, a LoRA, a cache hit) still finish // inside the window and return a path exactly as before, so the common // case is unchanged. A multi-GB checkpoint hands back a handle instead // of pinning the turn for ten minutes — which is what made the agent // look stuck and then wrongly disclaim a download that was running. const { job, settled } = await startDownloadJob(args.url, args.target_subfolder, args.filename, args.auth); let timer; await Promise.race([ settled, new Promise((r) => { timer = setTimeout(r, downloadGraceMs()); }), ]); if (timer) clearTimeout(timer); if (job.status === "done") { return { content: [{ type: "text", text: `Model downloaded successfully to:\n${job.path}` }], }; } if (job.status === "error") { return errorToToolResult(new ModelError(job.error ?? "Download failed", { url: args.url })); } const p = readDownloadProgress(job.trayId); const pct = p && p.total > 0 ? ` (${Math.floor((p.downloaded / p.total) * 100)}%)` : ""; return { content: [ { type: "text", text: `Download STARTED and is still running${pct} — id \`${job.id}\`.\n\n` + `This is NOT a failure and you must not describe it as one. The file is ` + `streaming to disk in the background and will land on its own.\n\n` + `Tell the user it is downloading, then check \`download_status\` with this id ` + `when they ask. Do NOT call download_model again for this URL — a repeat ` + `request adopts the same job rather than starting a second copy, but saying ` + `"I'll leave it to you" or reporting it as incomplete would be wrong.`, }, ], }; } catch (err) { return errorToToolResult(err); } }); server.tool("download_status", "Check on model downloads started by download_model. Reports each download's state (downloading / done / error), its destination path once it lands, and byte progress when the panel progress channel is enabled. " + "Use this after download_model reports a download is still running — that means the transfer is in flight, NOT that it failed. Read-only.", { id: z .string() .optional() .describe("Download id from download_model. Omit to list every download this session."), }, async (args) => { try { const list = args.id ? [getDownloadJob(args.id)].filter((j) => !!j) : listDownloadJobs(); if (list.length === 0) { return { content: [ { type: "text", text: args.id ? `No download with id \`${args.id}\`. Downloads are tracked per server session, so an id from a previous session won't resolve — check the panel download tray instead.` : "No downloads have been started this session.", }, ], }; } const lines = list.map((j) => { const p = readDownloadProgress(j.trayId); const bytes = p && p.total > 0 ? ` ${(p.downloaded / 1024 ** 3).toFixed(2)}/${(p.total / 1024 ** 3).toFixed(2)} GB (${Math.floor((p.downloaded / p.total) * 100)}%)` : p && p.downloaded > 0 ? ` ${(p.downloaded / 1024 ** 3).toFixed(2)} GB so far` : ""; const head = `- \`${j.id}\` **${j.status}**${bytes}`; const detail = j.status === "done" ? `\n landed at: ${j.path}` : j.status === "error" ? `\n failed: ${j.error}` : `\n still streaming — started ${Math.round((Date.now() - j.started_at) / 1000)}s ago`; return `${head}${detail}\n from: ${j.url}`; }); return { content: [{ type: "text", text: `## Downloads\n\n${lines.join("\n")}` }] }; } catch (err) { return errorToToolResult(err); } }); server.tool("list_local_models", "List model files available to the connected ComfyUI, grouped by type. Read-only. Queries ComfyUI's /models REST endpoint first (works with remote ComfyUI and respects extra_model_paths.yaml — symlinked / mounted dirs the install-path filesystem scan would miss), then falls back to a filesystem scan of COMFYUI_PATH/models/ when the REST endpoint is unavailable. Size and modified time are only available on the filesystem fallback path. Use to see which models are already available before generating or downloading; use search_models to discover new models on HuggingFace, then download_model to fetch them. For models fetched via download_civitai_model, any CivitAI trigger/activation words and base model are shown inline (read from the `<file>.civitai.json` sidecar) — apply those trigger words in your prompt when generating with that model. A `civitai:` line under an entry is that model's CivitAI page URL (modelId + INSTALLED modelVersionId, from the same sidecar) — use it to reference the source or check for newer versions.", { model_type: modelTypeEnum .optional() .describe("Filter by model type (e.g. 'checkpoints', 'loras'). Lists all types if omitted."), }, async (args) => { try { const models = await listLocalModels(args.model_type); if (models.length === 0) { const scope = args.model_type ? `No ${args.model_type} models found.` : "No local models found."; return { content: [{ type: "text", text: scope }] }; } // Group by type const grouped = new Map(); for (const m of models) { const list = grouped.get(m.type) ?? []; list.push(m); grouped.set(m.type, list); } const lines = []; for (const [type, list] of grouped) { lines.push(`## ${type} (${list.length})`); for (const m of list) { // Size/modified are only populated on the filesystem-scan path. // The HTTP /models endpoint just returns filenames, so we render // a bare name in that case. if (m.size > 0) { const sizeMB = (m.size / 1024 / 1024).toFixed(1); lines.push(`- ${m.name} (${sizeMB} MB) — modified ${m.modified}`); } else { lines.push(`- ${m.name}`); } // Surface CivitAI sidecar hints so the agent applies the trigger // words (and picks the right base model) when it builds a workflow. if (m.triggerWords && m.triggerWords.length > 0) { lines.push(` trigger words: ${m.triggerWords.join(", ")}` + (m.baseModel ? ` · base: ${m.baseModel}` : "")); } else if (m.baseModel) { lines.push(` base: ${m.baseModel}`); } // Provenance: the sidecar's CivitAI page URL carries the modelId // and the INSTALLED modelVersionId — link back to the source, and // let clients check whether a newer version exists on CivitAI. if (m.civitaiUrl) { lines.push(` civitai: ${m.civitaiUrl}`); } } lines.push(""); } return { content: [{ type: "text", text: lines.join("\n") }] }; } catch (err) { return errorToToolResult(err); } }); } //# sourceMappingURL=model-management.js.map