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),

485 lines • 24.2 kB
import { z } from "zod"; import { appendFileSync, existsSync, readdirSync, readFileSync, statSync } from "node:fs"; import { join } from "node:path"; import { fileURLToPath } from "node:url"; import { parse as parseYaml } from "yaml"; import { errorToToolResult } from "../utils/errors.js"; import { getComfyUIBaseUrl, getComfyUIAuthHeaders } from "../config.js"; import { checkWorkflowRuntime, extractWorkflowClassTypes } from "../services/api-nodes.js"; // Optional, opt-in observability hook for the knowledge-parity smoke test: when // COMFYUI_MCP_TOOL_TRACE points at a file, each of these tools appends a JSONL // record of its invocation. No-op in normal operation (env unset). This is the // only way an out-of-process harness can prove the agent actually CALLED // list_skills/read_skill/read_pack_workflow on the headless comfyui stdio MCP, // since those calls don't traverse the panel bridge. function traceToolCall(tool, args) { const path = process.env.COMFYUI_MCP_TOOL_TRACE; if (!path) return; try { appendFileSync(path, `${JSON.stringify({ tool, args, ts: Date.now() })}\n`); } catch { // tracing is best-effort and must never affect the tool's result } } // SKILL ACCESS — Codex↔Claude knowledge parity for the panel agent. // // Claude loads ALL plugin skills natively (the panel orchestrator passes // plugins:[{type:"local",path:pluginPath}], skills:"all"), so it knows the // per-family expertise (e.g. krea2-txt2img) and the installer-packs system out of // the box. Codex has NO skill mechanism. These tools expose the SAME bundled // knowledge through the comfyui MCP that BOTH backends (and any MCP client) share, // so Codex can discover and read a model family's skill on demand and prefer a // ready pack over hand-building a generic graph from scratch. // // Resolution mirrors the orchestrator's plugin lookup (src/orchestrator/index.ts // ~L246: "the bundled plugin (skills) ships alongside dist/ in the package root"). // This file compiles to dist/tools/skills-access.js, so the package root is two // levels up. /** Package root — dist/tools/skills-access.js → ../../ (the package root that * ships both plugin/skills and packs/). */ function packageRoot() { return fileURLToPath(new URL("../../", import.meta.url)); } function skillsDir() { return join(packageRoot(), "plugin", "skills"); } function packsDir() { return join(packageRoot(), "packs"); } /** A safe single path segment: a skill / pack directory name with no traversal, * separators, or oddities. Both tools validate the caller-supplied name against * this AND against an actually-existing directory before reading anything. */ const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/; /** Split a SKILL.md (or any frontmatter doc) into { frontmatter, body }. The * frontmatter is the YAML block between the leading `---` fences; the body is * everything after. Tolerant of a missing/garbled block (returns {} + full text). */ function splitFrontmatter(text) { // Normalize BOM + CRLF so the fence match is reliable cross-platform. const norm = text.replace(/^/, "").replace(/\r\n/g, "\n"); const m = /^---\n([\s\S]*?)\n---\n?/.exec(norm); if (!m) return { frontmatter: {}, body: norm }; let fm = {}; try { const parsed = parseYaml(m[1]); if (parsed && typeof parsed === "object") fm = parsed; } catch { // malformed frontmatter — fall back to no metadata, keep the body } return { frontmatter: fm, body: norm.slice(m[0].length) }; } /** Read a skill's SKILL.md, returning null when the dir/file is missing. */ function readSkillFile(name) { const file = join(skillsDir(), name, "SKILL.md"); if (!existsSync(file)) return null; try { return readFileSync(file, "utf8"); } catch { return null; } } /** Enumerate bundled skills as { name, description }. Tolerant of a missing * plugin dir (returns []) and of skills with no/garbled frontmatter. */ function enumerateSkills() { const dir = skillsDir(); if (!existsSync(dir)) return []; const out = []; for (const entry of readdirSync(dir)) { if (!SAFE_NAME.test(entry)) continue; let isDir = false; try { isDir = statSync(join(dir, entry)).isDirectory(); } catch { continue; } if (!isDir) continue; const text = readSkillFile(entry); if (text == null) continue; // no SKILL.md → not a skill const { frontmatter } = splitFrontmatter(text); const name = typeof frontmatter.name === "string" ? frontmatter.name : entry; const description = typeof frontmatter.description === "string" ? frontmatter.description : ""; out.push({ name, description }); } out.sort((a, b) => a.name.localeCompare(b.name)); return out; } /** Enumerate installer packs as { name, family, kind, description, workflow, * has_workflow, has_manifest }. Reads each packs/<name>/pack.yaml. */ export function enumeratePacks() { const dir = packsDir(); if (!existsSync(dir)) return []; const out = []; for (const entry of readdirSync(dir)) { if (!SAFE_NAME.test(entry)) continue; const packDir = join(dir, entry); let isDir = false; try { isDir = statSync(packDir).isDirectory(); } catch { continue; } if (!isDir) continue; const metaFile = join(packDir, "pack.yaml"); if (!existsSync(metaFile)) continue; // not a pack let meta = {}; try { const parsed = parseYaml(readFileSync(metaFile, "utf8")); if (parsed && typeof parsed === "object") meta = parsed; } catch { // malformed pack.yaml — still report the pack with just its dir name } const workflowName = typeof meta.workflow === "string" ? meta.workflow : "workflow.json"; out.push({ name: entry, family: meta.family ?? null, kind: meta.kind ?? null, display_name: meta.display_name ?? null, description: typeof meta.description === "string" ? meta.description.trim() : "", vram: meta.vram ?? null, skill: meta.skill ?? null, // Installer packs run on the user's OWN GPU (free) — none ship API-node // graphs. pack.yaml may override with an explicit `runtime`, but the // default is local/free. (Use check_workflow_runtime to verify a graph.) runtime: typeof meta.runtime === "string" ? meta.runtime : "local", has_workflow: existsSync(join(packDir, workflowName)), has_manifest: existsSync(join(packDir, "manifest.yaml")), manifest_path: existsSync(join(packDir, "manifest.yaml")) ? join(packDir, "manifest.yaml") : null, }); } out.sort((a, b) => String(a.name).localeCompare(String(b.name))); return out; } /** Locate a pack's workflow.json file path (name-guarded, must exist). Returns * null when the pack or its workflow is missing. Shared by read_pack_workflow * and check_workflow_runtime so they resolve the file identically. Also * exported for run_template, which resolves templates the same way. */ export function resolvePackWorkflowFile(packName) { const name = packName.trim(); if (!SAFE_NAME.test(name)) return null; const packDir = join(packsDir(), name); if (!packDir.startsWith(packsDir()) || !existsSync(packDir) || !statSync(packDir).isDirectory()) { return null; } let workflowName = "workflow.json"; const metaFile = join(packDir, "pack.yaml"); if (existsSync(metaFile)) { try { const meta = parseYaml(readFileSync(metaFile, "utf8")); if (meta && typeof meta.workflow === "string") workflowName = meta.workflow; } catch { // keep default } } if (!SAFE_NAME.test(workflowName) && workflowName !== "workflow.json") { workflowName = "workflow.json"; } const wfFile = join(packDir, workflowName); if (!wfFile.startsWith(packDir) || !existsSync(wfFile)) return null; return wfFile; } export function registerSkillsAccessTools(server) { server.tool("list_skills", "List the bundled ComfyUI model-family + workflow skills shipped with comfyui-mcp (name + description for each). These encode per-family expertise (e.g. krea2-txt2img: native krea2 CLIPLoader, Qwen3-VL encoder, 8-step turbo settings) and the installer-packs system. Call this BEFORE hand-building a <model-family> workflow from scratch — if a matching skill exists, read its full guidance with read_skill(name) and prefer a ready installer pack (see list_packs) over a generic graph. Claude loads these natively; this tool gives the SAME knowledge to any MCP client (e.g. the Codex backend).", {}, async () => { try { traceToolCall("list_skills", {}); const skills = enumerateSkills(); return { content: [ { type: "text", text: JSON.stringify({ count: skills.length, skills }, null, 2), }, ], }; } catch (err) { return errorToToolResult(err); } }); server.tool("read_skill", "Return the full body of a bundled skill's SKILL.md by name (discover names with list_skills). Gives you the family's complete expertise on demand — model slots, node graph, recommended settings, and gotchas — so you can build the right workflow instead of guessing. Names are validated (no path traversal) and must match an existing skill directory.", { name: z .string() .min(1) .describe("The skill name (a directory under plugin/skills/, e.g. 'krea2-txt2img'). Get valid names from list_skills."), }, async (args) => { try { traceToolCall("read_skill", { name: args.name }); const name = args.name.trim(); if (!SAFE_NAME.test(name)) { return { isError: true, content: [ { type: "text", text: `Invalid skill name "${args.name}". Use a plain skill directory name (letters, digits, dot, dash, underscore) from list_skills.`, }, ], }; } // Must resolve to an existing skill dir (defense in depth alongside the regex). const dir = join(skillsDir(), name); const resolvedRoot = skillsDir(); if (!dir.startsWith(resolvedRoot) || !existsSync(dir) || !statSync(dir).isDirectory()) { const known = enumerateSkills().map((s) => s.name); return { isError: true, content: [ { type: "text", text: `No skill named "${name}". Available skills: ${known.join(", ") || "(none bundled)"}.`, }, ], }; } const text = readSkillFile(name); if (text == null) { return { isError: true, content: [ { type: "text", text: `Skill "${name}" has no readable SKILL.md.` }, ], }; } return { content: [{ type: "text", text }] }; } catch (err) { return errorToToolResult(err); } }); server.tool("list_packs", "List the bundled installer packs under packs/ — one-command setups for a model family: custom nodes + model weights (manifest.yaml) PLUS a ready workflow.json graph. Each entry reports its family/kind, its runtime (these packs are LOCAL-GPU / FREE — they run on the user's own GPU and never spend paid API credits), whether it has a ready workflow + manifest, and the manifest path for apply_manifest. When asked to 'set up / build a <model-family> workflow', PREFER applying the matching pack (apply_manifest --path <manifest_path>) and loading its ready workflow (panel_load_workflow pack:<name>) over building a generic graph from scratch. Read the ready graph with read_pack_workflow(name). To check whether some OTHER (non-pack) workflow uses paid API nodes, use check_workflow_runtime.", {}, async () => { try { traceToolCall("list_packs", {}); const packs = enumeratePacks(); return { content: [ { type: "text", text: JSON.stringify({ count: packs.length, note: "All bundled installer packs are LOCAL-GPU / FREE (no API nodes, no paid credits). Loading or running a pack workflow runs entirely on the user's GPU.", packs, }, null, 2), }, ], }; } catch (err) { return errorToToolResult(err); } }); server.tool("list_workflow_templates", "List the OFFICIAL ComfyUI workflow templates available on the connected ComfyUI (the comfyui-workflow-templates package + any custom-node-provided templates), grouped by source. Hits the live server's /api/workflow_templates index. When asked to 'set up / build a <model-family> workflow', check here for a matching official starter template AFTER checking the bundled skills + installer packs (list_skills / list_packs). NOTE: this lists what's available; loading a template onto the canvas is done in the ComfyUI frontend's Templates browser (the panel agent cannot load a template graph headlessly yet) — surface the matching template name to the user.", {}, async () => { try { traceToolCall("list_workflow_templates", {}); // Canonical base URL + auth headers — same connected-ComfyUI path // get_template_schema uses, so a proxied/authed remote resolves // consistently between listing and schema lookup. const base = getComfyUIBaseUrl(); const res = await fetch(`${base}/api/workflow_templates`, { headers: getComfyUIAuthHeaders(), signal: AbortSignal.timeout(8000), }); if (!res.ok) { return { isError: true, content: [ { type: "text", text: `ComfyUI returned ${res.status} for /api/workflow_templates. Is the server running and recent enough to expose workflow templates?`, }, ], }; } const index = (await res.json()); const groups = Object.keys(index); const total = Object.values(index).reduce((n, v) => n + (Array.isArray(v) ? v.length : 0), 0); return { content: [ { type: "text", text: JSON.stringify({ source_count: groups.length, template_count: total, templates: index }, null, 2), }, ], }; } catch (err) { return errorToToolResult(err); } }); server.tool("read_pack_workflow", "Return a bundled pack's ready workflow.json graph by pack name (discover names + which packs have a workflow with list_packs). This is the EXPERT graph for that model family — use it as the source of truth when setting up the family on the user's canvas: recreate it node-by-node with the panel_* tools (panel_add_node / panel_connect / panel_set_widget) so it lands on their live canvas, or enqueue it headlessly. Prefer this over inventing a graph from scratch. Names are validated (no path traversal) and must match an existing pack directory.", { name: z .string() .min(1) .describe("The pack name (a directory under packs/, e.g. 'krea2-txt2img-manual'). Get valid names from list_packs."), }, async (args) => { try { traceToolCall("read_pack_workflow", { name: args.name }); const name = args.name.trim(); if (!SAFE_NAME.test(name)) { return { isError: true, content: [ { type: "text", text: `Invalid pack name "${args.name}". Use a plain pack directory name from list_packs.`, }, ], }; } const packDir = join(packsDir(), name); if (!packDir.startsWith(packsDir()) || !existsSync(packDir) || !statSync(packDir).isDirectory()) { const known = enumeratePacks().map((p) => p.name); return { isError: true, content: [ { type: "text", text: `No pack named "${name}". Available packs: ${known.join(", ") || "(none bundled)"}.`, }, ], }; } // Resolve the workflow filename from pack.yaml (default workflow.json). let workflowName = "workflow.json"; const metaFile = join(packDir, "pack.yaml"); if (existsSync(metaFile)) { try { const meta = parseYaml(readFileSync(metaFile, "utf8")); if (meta && typeof meta.workflow === "string") workflowName = meta.workflow; } catch { // keep default } } if (!SAFE_NAME.test(workflowName) && workflowName !== "workflow.json") { // pack.yaml controls this, but stay defensive against odd values. workflowName = "workflow.json"; } const wfFile = join(packDir, workflowName); if (!wfFile.startsWith(packDir) || !existsSync(wfFile)) { return { isError: true, content: [ { type: "text", text: `Pack "${name}" has no ready workflow (${workflowName} not found).`, }, ], }; } const text = readFileSync(wfFile, "utf8"); return { content: [{ type: "text", text }] }; } catch (err) { return errorToToolResult(err); } }); server.tool("check_workflow_runtime", "Determine whether a workflow runs on the user's OWN GPU (LOCAL — free) or uses hosted API NODES (PAID api credits). Pass `pack` (a bundled pack name — always local/free) OR `graph` (a UI or API/prompt workflow JSON, as object or string). It scans the workflow's node class_types against the connected ComfyUI's API-node set (the same signal list_api_nodes uses) and returns { runtime: 'local'|'api'|'mixed'|'unknown', usesApiNodes, apiNodes[], unknownNodes[] } — 'unknown' means some nodes couldn't be classified (could be paid), so treat it (and 'api'/'mixed') as POSSIBLY PAID; only 'local' is confirmed free. ALWAYS call this before building OR loading a non-pack/ad-hoc workflow so you can ASK the user before spending paid API credits — never silently use API nodes.", { pack: z .string() .optional() .describe("A bundled pack name (from list_packs). Packs are local/free; this confirms it from the actual graph."), graph: z .union([z.string(), z.record(z.string(), z.unknown())]) .optional() .describe("A workflow graph to classify (UI or API/prompt format), as an object or a JSON string. Use this for ad-hoc/generated workflows."), }, async (args) => { try { traceToolCall("check_workflow_runtime", { pack: args.pack }); let graph; if (args.pack) { const wfFile = resolvePackWorkflowFile(args.pack); if (!wfFile) { const known = enumeratePacks().map((p) => p.name); return { isError: true, content: [ { type: "text", text: `No pack named "${args.pack}" with a ready workflow. Available packs: ${known.join(", ") || "(none bundled)"}.`, }, ], }; } graph = JSON.parse(readFileSync(wfFile, "utf8")); } else if (args.graph != null) { graph = typeof args.graph === "string" ? JSON.parse(args.graph) : args.graph; } else { return { isError: true, content: [ { type: "text", text: "Provide either `pack` (a bundled pack name) or `graph` (a workflow JSON).", }, ], }; } // Cheap, server-independent class_type extraction first — so we always // return SOMETHING useful even if the live /object_info is unreachable. const classTypes = extractWorkflowClassTypes(graph); try { const runtime = await checkWorkflowRuntime(graph); const guidance = runtime.runtime === "local" ? "Local-GPU / free — every node runs on the user's own GPU, no paid credits." : runtime.runtime === "unknown" ? "UNKNOWN — some nodes aren't in this server's /object_info (uninstalled custom nodes, or possibly hosted API/partner nodes). Cannot confirm it's free. Treat as POSSIBLY PAID: ASK the user (free local GPU vs paid api credits) before building or loading it; prefer a local pack." : "This workflow uses hosted API nodes that consume PAID api credits. ASK the user (free local GPU vs paid api credits) BEFORE building or loading it; prefer a local pack unless they opt in."; return { content: [ { type: "text", text: JSON.stringify({ ...runtime, guidance }, null, 2), }, ], }; } catch (probeErr) { // No live server (or /object_info failed): we can't authoritatively // classify, but still surface the node list so the agent can reason. return { content: [ { type: "text", text: JSON.stringify({ runtime: "unknown", usesApiNodes: null, classTypes, note: `Could not reach the ComfyUI server to classify nodes (${probeErr.message}). API-node detection needs a running ComfyUI. If unsure, treat ad-hoc workflows as POSSIBLY paid and ask the user before spending credits.`, }, null, 2), }, ], }; } } catch (err) { return errorToToolResult(err); } }); } //# sourceMappingURL=skills-access.js.map