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),
535 lines • 28.4 kB
JavaScript
import { z } from "zod";
import { readFile } from "node:fs/promises";
import { getClient, getObjectInfo, backfillObjectInfo } from "../comfyui/client.js";
import { errorToToolResult, ValidationError } from "../utils/errors.js";
import { logger } from "../utils/logger.js";
import { isUiFormat, isApiFormat, convertUiToApi, convertApiToUi, collectNodeTypes, } from "../services/workflow-converter.js";
import { sliceWorkflow } from "../services/workflow-slicer.js";
import { queryApiGraph } from "../services/graph-query.js";
import { detectSections } from "../services/workflow-sections.js";
import { generateOverview, generateSectionDetail, listSections, generateSummary, } from "../services/hierarchical-mermaid.js";
import { convertToMermaid } from "../services/mermaid-converter.js";
import { analyzeGraphHealth } from "../services/workflow-health.js";
export function registerWorkflowLibraryTools(server) {
server.tool("list_workflows", "List the filenames of workflows saved in the connected ComfyUI server's user library (the same workflows visible in the ComfyUI web UI). Requires a running ComfyUI server. Takes no parameters. Returns a numbered list of .json filenames; pass a filename to get_workflow or analyze_workflow to load one. Returns \"No saved workflows found.\" when the library is empty.", {}, async () => {
try {
const client = getClient();
const res = await client.fetchApi("/api/userdata?dir=workflows");
const files = (await res.json());
if (files.length === 0) {
return {
content: [{ type: "text", text: "No saved workflows found." }],
};
}
const text = files
.map((f, i) => `${i + 1}. ${f}`)
.join("\n");
return {
content: [
{
type: "text",
text: `Found ${files.length} workflows:\n\n${text}`,
},
],
};
}
catch (err) {
return errorToToolResult(err);
}
});
server.tool("get_workflow", "Load a saved workflow and return its raw JSON. " +
"Use analyze_workflow instead if you just need to understand the workflow — it returns a structured summary without flooding context with JSON. " +
"Use get_workflow only when you need the actual JSON for enqueue_workflow, modify_workflow, or save_workflow.", {
filename: z
.string()
.describe("Workflow filename (e.g. 'my_workflow.json'). Use list_workflows to see available files."),
format: z
.enum(["ui", "api"])
.optional()
.default("api")
.describe("Output format: 'api' (default, recommended) converts to compact API format with " +
"named inputs, connection references, and _meta.mode flags for muted/bypassed nodes. " +
"'ui' returns the raw UI format with layout positions and links arrays."),
}, async ({ filename, format }) => {
try {
const client = getClient();
const encoded = encodeURIComponent(`workflows/${filename}`);
const res = await client.fetchApi(`/api/userdata/${encoded}`);
if (!res.ok) {
return {
content: [
{
type: "text",
text: `Workflow not found: ${filename} (${res.status})`,
},
],
};
}
const raw = await res.json();
// If API format requested and workflow is in UI format, convert
if (format === "api" && isUiFormat(raw)) {
const bulk = await getObjectInfo();
// Backfill node types missing from the bulk /object_info (e.g.
// controlnet_aux's DWPreprocessor) so the converter doesn't skip them.
const objectInfo = await backfillObjectInfo(bulk, collectNodeTypes(raw));
const { workflow, warnings } = convertUiToApi(raw, objectInfo);
const content = [];
if (warnings.length > 0) {
content.push({
type: "text",
text: `**Conversion warnings (${warnings.length}):**\n${warnings.map((w) => `- ${w}`).join("\n")}`,
});
}
content.push({
type: "text",
text: JSON.stringify(workflow, null, 2),
});
return { content };
}
return {
content: [
{
type: "text",
text: JSON.stringify(raw, null, 2),
},
],
};
}
catch (err) {
return errorToToolResult(err);
}
});
server.tool("strip_workflow", "Strip a workflow to a clean, flat API graph — resolving Get/Set buses, Reroutes, " +
"subgraph definitions, and bypassed/muted nodes into real connections (the 'de-getter-setter' pass). " +
"Unlike get_workflow, this reads from ANY server-side file path on disk (not just the cached " +
"workflow library), so it loads ad-hoc / expert workflow files that workflow_list and " +
"panel_open_workflow can't resolve. Provide exactly one of: path, filename, or graph. Returns " +
"conversion warnings, a node-type summary, and the stripped graph (much smaller than the raw UI JSON).", {
path: z
.string()
.optional()
.describe("Absolute server-side path to a workflow .json on disk (e.g. " +
"C:\\\\Users\\\\you\\\\ComfyUI\\\\user\\\\default\\\\workflows\\\\pusa_extend.json). Read directly from disk — no library lookup."),
filename: z
.string()
.optional()
.describe("Workflow filename in the ComfyUI userdata library, as an alternative to path."),
graph: z
.record(z.string(), z.any())
.optional()
.describe("Inline UI-format workflow JSON, as an alternative to path/filename."),
format: z
.enum(["api", "raw"])
.optional()
.default("api")
.describe("'api' (default) strips to the flat resolved graph; 'raw' returns the file/graph unchanged."),
}, async ({ path, filename, graph, format }) => {
try {
const provided = [path, filename, graph].filter((v) => v != null).length;
if (provided !== 1) {
throw new ValidationError("Provide exactly one of: path, filename, or graph.");
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
let raw;
if (graph) {
raw = graph;
}
else if (path) {
raw = JSON.parse(await readFile(path, "utf8"));
}
else {
const client = getClient();
const encoded = encodeURIComponent(`workflows/${filename}`);
const res = await client.fetchApi(`/api/userdata/${encoded}`);
if (!res.ok) {
throw new ValidationError(`Workflow not found in library: ${filename} (${res.status})`);
}
raw = await res.json();
}
if (format === "raw" || !isUiFormat(raw)) {
return { content: [{ type: "text", text: JSON.stringify(raw, null, 2) }] };
}
const bulk = await getObjectInfo();
const objectInfo = await backfillObjectInfo(bulk, collectNodeTypes(raw));
const { workflow, warnings } = convertUiToApi(raw, objectInfo);
const hist = {};
for (const node of Object.values(workflow)) {
const t = node.class_type ?? "?";
hist[t] = (hist[t] ?? 0) + 1;
}
const summary = Object.entries(hist)
.sort((a, b) => b[1] - a[1])
.map(([t, c]) => `${c}× ${t}`)
.join(", ");
return {
content: [
{
type: "text",
text: `Stripped to ${Object.keys(workflow).length} nodes` +
(warnings.length ? ` · ${warnings.length} warning(s)` : "") +
`\nNode types: ${summary}` +
(warnings.length
? `\nWarnings:\n${warnings.map((w) => `- ${w}`).join("\n")}`
: ""),
},
{ type: "text", text: JSON.stringify(workflow, null, 2) },
],
};
}
catch (err) {
return errorToToolResult(err);
}
});
server.tool("query_workflow", "QUERY a workflow file — filter, traverse, project, and aggregate over its nodes WITHOUT " +
"dumping the whole JSON (the missing middle between analyze_workflow's fixed summary and " +
"get_workflow's full dump; on 100+-node graphs this is the ONLY context-safe way to answer " +
"questions like 'which KSamplers run cfg>7', 'what feeds node 42', 'count nodes by type'). " +
"Provide exactly one of path/filename/graph, then combine: `types` (class_type contains any), " +
"`title` (contains), `where` widget predicates ANDed ('cfg>7', 'steps<=20', 'sampler_name=euler', " +
"'text~sunset' — ops = != >= <= > < ~contains), `ids` (exact nodes — the way to read ONE node's " +
"detail), `upstream_of`/`downstream_of` + `depth` (dependency traversal: upstream = what FEEDS " +
"that node, downstream = what CONSUMES it; seed included at depth 0), `fields` ('compact' one " +
"line per node [default], 'ids', or 'detail' JSON rows with widgets + wiring), `group_by:'type'` " +
"(counts only), `limit` (default 40). Output is TOKEN-BOUNDED with an explicit truncation marker. " +
"For the LIVE canvas use panel_query_graph instead. Read-only.", {
path: z.string().optional().describe("Absolute server-side path to a workflow .json on disk."),
filename: z
.string()
.optional()
.describe("Workflow filename in the ComfyUI userdata library, as an alternative to path."),
graph: z
.record(z.string(), z.any())
.optional()
.describe("Inline workflow JSON (UI or API format), as an alternative to path/filename."),
types: z
.array(z.string())
.optional()
.describe("Keep nodes whose class_type contains ANY of these (case-insensitive)."),
title: z.string().optional().describe("Keep nodes whose title contains this."),
where: z
.array(z.string())
.optional()
.describe("Widget predicates, ANDed: 'cfg>7', 'sampler_name=euler', 'text~sunset'."),
ids: z
.array(z.union([z.string(), z.number()]))
.optional()
.describe("Keep exactly these node ids."),
upstream_of: z
.union([z.string(), z.number()])
.optional()
.describe("Scope to the dependency closure FEEDING this node id."),
downstream_of: z
.union([z.string(), z.number()])
.optional()
.describe("Scope to the nodes CONSUMING this node id's outputs."),
depth: z
.number()
.int()
.min(0)
.optional()
.describe("Max hops from the traversal seed (seed=0). Absent = full closure."),
fields: z
.enum(["ids", "compact", "detail"])
.optional()
.describe("Projection: compact one-liners (default), bare ids, or detail JSON rows."),
group_by: z.enum(["type"]).optional().describe("Aggregate: counts per class_type instead of listing."),
limit: z.number().int().min(1).max(200).optional().describe("Max nodes listed (default 40)."),
max_chars: z
.number()
.int()
.min(500)
.max(60000)
.optional()
.describe("Output character bound (default 12000). Raise only for deliberate full reads."),
}, async ({ path, filename, graph, ...query }) => {
try {
const provided = [path, filename, graph].filter((v) => v != null).length;
if (provided !== 1) {
throw new ValidationError("Provide exactly one of: path, filename, or graph.");
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
let raw;
if (graph) {
raw = graph;
}
else if (path) {
raw = JSON.parse(await readFile(path, "utf8"));
}
else {
const client = getClient();
const encoded = encodeURIComponent(`workflows/${filename}`);
const res = await client.fetchApi(`/api/userdata/${encoded}`);
if (!res.ok) {
throw new ValidationError(`Workflow not found in library: ${filename} (${res.status})`);
}
raw = await res.json();
}
let api = raw;
const notes = [];
if (isUiFormat(raw)) {
const bulk = await getObjectInfo();
const objectInfo = await backfillObjectInfo(bulk, collectNodeTypes(raw));
const converted = convertUiToApi(raw, objectInfo);
api = converted.workflow;
if (converted.warnings.length)
notes.push(`${converted.warnings.length} conversion warning(s) — see strip_workflow for details`);
}
else if (!isApiFormat(raw)) {
throw new ValidationError("Not a recognizable workflow (neither UI nor API format).");
}
const result = queryApiGraph(api, query);
return {
content: [
{ type: "text", text: result.text + (notes.length ? `\n(${notes.join("; ")})` : "") },
],
};
}
catch (err) {
return errorToToolResult(err);
}
});
server.tool("slice_workflow", "Slice ONE pipeline out of a toggle-template workflow — the kind built with rgthree " +
"'Fast Groups Bypasser/Muter' where one graph holds many pipelines and only one is active at a time. " +
"Seeds from the output/SaveImage nodes in the named groups, takes their backward dependency closure " +
"(through real links AND virtual Set/Get buses), un-bypasses the kept nodes (and the internals of any " +
"subgraph defs they use), and returns a STANDALONE, activated UI graph carrying only the subgraph " +
"defs it uses. Reads from any server-side path, userdata filename, or inline graph. Pair with " +
"strip_workflow afterward to flatten the Set/Get buses into real connections.", {
path: z.string().optional().describe("Absolute server-side path to the workflow .json on disk."),
filename: z.string().optional().describe("Workflow filename in the ComfyUI userdata library."),
graph: z.record(z.string(), z.any()).optional().describe("Inline UI-format workflow JSON."),
groups: z
.union([z.string(), z.array(z.string())])
.describe("Group-title substrings (case-insensitive) whose output nodes seed the slice — CSV string or " +
"array, e.g. 'TEXT TO IMAGE,TXT' or ['extend','sampler']. Shared post-proc is pulled in via the closure."),
}, async ({ path, filename, graph, groups }) => {
try {
const provided = [path, filename, graph].filter((v) => v != null).length;
if (provided !== 1) {
throw new ValidationError("Provide exactly one of: path, filename, or graph.");
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
let raw;
if (graph) {
raw = graph;
}
else if (path) {
raw = JSON.parse(await readFile(path, "utf8"));
}
else {
const client = getClient();
const encoded = encodeURIComponent(`workflows/${filename}`);
const res = await client.fetchApi(`/api/userdata/${encoded}`);
if (!res.ok) {
throw new ValidationError(`Workflow not found in library: ${filename} (${res.status})`);
}
raw = await res.json();
}
const groupList = Array.isArray(groups) ? groups : String(groups).split(",");
const { workflow, stats } = sliceWorkflow(raw, groupList);
const flags = stats.badLinks || stats.orphanGets
? ` · ⚠ bad_links=${stats.badLinks} orphan_gets=${stats.orphanGets}`
: "";
return {
content: [
{
type: "text",
text: `Sliced ${stats.nodes} nodes (un-bypassed ${stats.unbypassed}), ${stats.links} links, ` +
`${stats.subgraphs} subgraph def(s) · seeds=${stats.seeds}${flags}`,
},
{ type: "text", text: JSON.stringify(workflow, null, 2) },
],
};
}
catch (err) {
return errorToToolResult(err);
}
});
server.tool("save_workflow", "Save a workflow JSON to the connected ComfyUI server's user library so it appears in the ComfyUI web UI. Requires a running ComfyUI server; this writes to that server's userdata and overwrites any existing file with the same filename without confirmation. Web-UI-format JSON ({ nodes: [], links: [] }) is saved as-is and is the preferred input — when re-saving an existing workflow, load it with get_workflow format='ui' and modify THAT. API-format graphs ({ '1': { class_type, inputs } }) are AUTO-CONVERTED to Web UI format with a generated layout so the saved file always opens in the ComfyUI canvas (the canvas cannot open raw API format). Returns a confirmation message (noting the conversion and any warnings), or the HTTP status and error text on failure.", {
filename: z
.string()
.describe("Filename to save as (e.g. 'my_workflow.json'). Will overwrite if it already exists."),
workflow: z
.record(z.string(), z.any())
.describe("Workflow JSON to save. Web UI format ({ nodes: [], links: [] }) is stored verbatim; API format ({ '1': { class_type, inputs } }) is auto-converted to Web UI format (generated layout) so it stays openable in ComfyUI's canvas. Not validated against the server before saving."),
}, async (args) => {
try {
const client = getClient();
const encoded = encodeURIComponent(`workflows/${args.filename}`);
// API-format graphs can't be opened by the canvas — the #1 way agents
// strand users with workflows that "exist" in the library yet load
// blank. Auto-convert them to UI format with a generated layout; fall
// back to a verbatim save (with the loud warning) only if conversion
// itself fails.
let toSave = args.workflow;
let note = "";
if (!isUiFormat(args.workflow) && isApiFormat(args.workflow)) {
try {
const apiGraph = args.workflow;
const bulk = await getObjectInfo();
const objectInfo = await backfillObjectInfo(bulk, Object.values(apiGraph).map((n) => n.class_type));
const { workflow: ui, warnings } = convertApiToUi(apiGraph, objectInfo);
toSave = ui;
note =
`\n\nℹ️ Input was API format — auto-converted to Web UI format (generated layout) ` +
`so it opens in the ComfyUI canvas.`;
if (warnings.length > 0) {
note += `\nConversion warnings (${warnings.length}):\n${warnings.map((w) => `- ${w}`).join("\n")}`;
}
}
catch (convErr) {
note =
`\n\n⚠️ Input was API format and auto-conversion to Web UI format failed ` +
`(${convErr instanceof Error ? convErr.message : String(convErr)}) — saved verbatim. ` +
`The ComfyUI canvas CANNOT open or edit this file. If it is meant to be reopened in ` +
`the UI, rebuild it in Web UI format ({ nodes: [], links: [] }) — e.g. load the ` +
`on-canvas graph or an existing file via get_workflow format="ui", apply your ` +
`changes to that, and save again.`;
}
}
else if (!isUiFormat(args.workflow)) {
note =
`\n\n⚠️ This JSON is neither Web UI format ({ nodes: [], links: [] }) nor API format ` +
`({ '1': { class_type, inputs } }) — saved verbatim, but the ComfyUI canvas likely ` +
`cannot open it.`;
}
const res = await client.fetchApi(`/api/userdata/${encoded}`, {
method: "POST",
body: JSON.stringify(toSave),
});
if (!res.ok) {
const errText = await res.text().catch(() => "");
return {
content: [
{
type: "text",
text: `Failed to save workflow: ${res.status} ${res.statusText}${errText ? `\n${errText}` : ""}`,
},
],
};
}
return {
content: [
{
type: "text",
text: `Workflow saved as "${args.filename}" in the ComfyUI user library.${note}`,
},
],
};
}
catch (err) {
return errorToToolResult(err);
}
});
// Helper: load and convert a workflow from the library
async function loadWorkflowApi(filename) {
const client = getClient();
const encoded = encodeURIComponent(`workflows/${filename}`);
const res = await client.fetchApi(`/api/userdata/${encoded}`);
if (!res.ok) {
throw new ValidationError(`Workflow not found: ${filename} (${res.status})`);
}
const raw = await res.json();
const objectInfo = await getObjectInfo();
if (isUiFormat(raw)) {
return convertUiToApi(raw, objectInfo);
}
// Already API format
return { workflow: raw, warnings: [] };
}
server.tool("analyze_workflow", "Load a saved workflow and return a structured analysis — sections, node settings, connections, " +
"and data flow. Use this to understand any workflow before modifying or executing it. " +
"Returns a concise text summary (not raw JSON) optimized for AI reasoning. " +
"Prefer this over get_workflow unless you need the raw JSON for enqueue_workflow or modify_workflow.", {
filename: z
.string()
.describe("Workflow filename (e.g. 'Scene Builder v3.json'). Use list_workflows to see available files."),
view: z
.enum(["summary", "overview", "detail", "list", "flat", "health"])
.optional()
.default("summary")
.describe("summary (default): structured text with sections, node IDs, key settings, virtual wires, " +
"and full connection graph — best for AI understanding. " +
"overview: mermaid diagram showing sections as summary nodes with cross-section data flow. " +
"detail: mermaid diagram for one section (requires section parameter). " +
"list: text listing of all sections with data flow summary. " +
"flat: single mermaid flowchart of the entire workflow (best for small workflows). " +
"health: graph-health heuristics (disconnected nodes, duplicate model loads, orphaned branches, muted/bypassed)."),
section: z
.string()
.optional()
.describe("Section name for detail view. Use view='list' first to see available section names."),
}, async ({ filename, view, section }) => {
try {
logger.info(`Analyzing workflow: ${filename} (view=${view})`);
const { workflow, warnings } = await loadWorkflowApi(filename);
const objectInfo = await getObjectInfo();
const nodeCount = Object.keys(workflow).length;
if (nodeCount === 0) {
throw new ValidationError("Workflow contains no nodes");
}
const content = [];
// Prepend warnings if any
if (warnings.length > 0) {
content.push({
type: "text",
text: `**Conversion warnings (${warnings.length}):**\n${warnings.map((w) => `- ${w}`).join("\n")}`,
});
}
if (view === "flat") {
// Simple mermaid flowchart — good for small workflows
const mermaid = convertToMermaid(workflow, { showValues: true, direction: "LR" });
content.push({ type: "text", text: `\`\`\`mermaid\n${mermaid}\n\`\`\`` });
return { content };
}
if (view === "health") {
const health = analyzeGraphHealth(workflow, objectInfo);
const lines = ["### Graph health", `- ${health.summary}`];
if (health.findings.length === 0) {
lines.push("- No health issues found.");
}
else {
for (const f of health.findings) {
const tag = f.heuristic ? `${f.severity}, heuristic` : f.severity;
lines.push(`- [${tag}] ${f.detail}`);
}
}
content.push({ type: "text", text: lines.join("\n") });
return { content };
}
// All other views need section detection
const detection = detectSections(workflow, objectInfo);
const { sections, virtualEdges, nodeToSection, getSetNodeIds } = detection;
if (view === "summary") {
const text = generateSummary(workflow, sections, objectInfo, virtualEdges, nodeToSection, getSetNodeIds);
content.push({ type: "text", text });
return { content };
}
if (view === "list") {
const text = listSections(workflow, sections);
content.push({ type: "text", text });
return { content };
}
if (view === "detail") {
if (!section) {
const available = [...sections.keys()].join(", ");
throw new ValidationError(`section parameter is required for detail view. Available sections: ${available}`);
}
const mermaid = generateSectionDetail(workflow, sections, section, {
showValues: true,
direction: "LR",
});
content.push({ type: "text", text: `\`\`\`mermaid\n${mermaid}\n\`\`\`` });
return { content };
}
// overview
const mermaid = generateOverview(workflow, sections, { direction: "TB" });
content.push({ type: "text", text: `\`\`\`mermaid\n${mermaid}\n\`\`\`` });
return { content };
}
catch (err) {
return errorToToolResult(err);
}
});
}
//# sourceMappingURL=workflow-library.js.map