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),
307 lines • 15.8 kB
JavaScript
import { z } from "zod";
import { getLogs, getHistory, } from "../comfyui/client.js";
import { selectNewestHistoryEntry, extractWorkflowGraph } from "../services/history-select.js";
import { validateWorkflow } from "../services/workflow-validator.js";
import { errorToToolResult } from "../utils/errors.js";
function findExecutionError(entry) {
const msg = (entry.status?.messages ?? []).find((m) => m[0] === "execution_error");
return msg ? msg[1] : null;
}
function findExecutionInterrupted(entry) {
const msg = (entry.status?.messages ?? []).find((m) => m[0] === "execution_interrupted");
return msg ? (msg[1] ?? {}) : null;
}
/**
* The Status line + outcome section of a diagnosis. Exported for tests.
*
* ComfyUI records an INTERRUPTED run with status_str "error" (plus an
* execution_interrupted message and NO execution_error) — echoing that raw
* "error" made cancelled runs read as failures ("Render failed" on mobile,
* see comfyui-mcp-mobile#23). Report it as interrupted instead; a genuine
* execution_error always wins over the interrupted marker.
*/
export function formatRunOutcome(entry) {
const lines = [];
const execError = findExecutionError(entry);
const interrupted = execError ? null : findExecutionInterrupted(entry);
lines.push(`**Status**: ${interrupted ? "interrupted" : (entry.status?.status_str ?? "unknown")}`);
if (execError) {
lines.push("");
lines.push("### Runtime failure");
lines.push(`**Failed node**: ${execError.node_id ?? "?"} (${execError.node_type ?? "unknown type"})`);
if (execError.exception_type)
lines.push(`**Type**: ${execError.exception_type}`);
if (execError.exception_message) {
lines.push(`**Message**: ${execError.exception_message}`);
}
if (Array.isArray(execError.traceback) && execError.traceback.length > 0) {
// Tail only — the last frames carry the cause, and a full traceback can
// be hundreds of lines (this reply goes straight into an agent's context).
const tail = execError.traceback.slice(-12);
lines.push("");
lines.push("```");
lines.push(tail.join("").trimEnd());
lines.push("```");
}
}
else if (interrupted) {
lines.push("");
lines.push("### Interrupted");
const where = interrupted.node_id !== undefined
? ` at node ${interrupted.node_id}${interrupted.node_type ? ` (${interrupted.node_type})` : ""}`
: "";
lines.push(`**This run was interrupted/cancelled${where}** — it did not crash. Nothing is broken; re-queue it if the cancellation wasn't intended.`);
}
else {
lines.push("");
lines.push("_No runtime error recorded for this run_ — if the user still sees a problem, it was likely rejected BEFORE execution (see validation below) or the run simply produced an unwanted result.");
}
return lines;
}
/**
* Pick the run to diagnose. An explicit id wins; otherwise prefer the most recent
* FAILED run over a newer successful one — "why did it fail?" should land on the
* failure even when the user has since kicked off something that worked.
*/
function selectRunToDiagnose(history, promptId) {
if (promptId)
return selectNewestHistoryEntry(history, promptId);
const failed = Object.entries(history).filter(([, e]) => findExecutionError(e));
if (failed.length > 0)
return selectNewestHistoryEntry(Object.fromEntries(failed));
return selectNewestHistoryEntry(history);
}
function formatHistoryEntry(promptId, entry) {
const lines = [];
const status = entry.status;
lines.push(`## Execution: ${promptId}`);
lines.push(`**Status**: ${status.status_str} | Completed: ${status.completed}`);
// Timing from messages
const messages = status.messages || [];
const start = messages.find((m) => m[0] === "execution_start");
const end = messages.find((m) => m[0] === "execution_success" || m[0] === "execution_error");
if (start && end) {
const startTs = start[1].timestamp;
const endTs = end[1].timestamp;
const durationSec = ((endTs - startTs) / 1000).toFixed(2);
lines.push(`**Duration**: ${durationSec}s`);
}
// Cached nodes
const cached = messages.find((m) => m[0] === "execution_cached");
if (cached) {
const cachedNodes = cached[1].nodes;
if (cachedNodes.length > 0) {
lines.push(`**Cached nodes**: ${cachedNodes.join(", ")}`);
}
}
// Error details
const errorMsg = messages.find((m) => m[0] === "execution_error");
if (errorMsg) {
const errData = errorMsg[1];
lines.push("");
lines.push("### Error Details");
if (errData.node_id) {
lines.push(`**Failed node**: ${errData.node_id} (${errData.node_type || "unknown type"})`);
}
if (errData.exception_message) {
lines.push(`**Exception**: ${errData.exception_message}`);
}
if (errData.exception_type) {
lines.push(`**Type**: ${errData.exception_type}`);
}
if (Array.isArray(errData.traceback) && errData.traceback.length > 0) {
lines.push("");
lines.push("**Traceback**:");
lines.push("```");
lines.push(errData.traceback.join(""));
lines.push("```");
}
}
// Interrupted
const interrupted = messages.find((m) => m[0] === "execution_interrupted");
if (interrupted) {
lines.push("");
lines.push("**Execution was interrupted/cancelled**");
}
const outputKeys = Object.keys(entry.outputs || {});
if (outputKeys.length > 0) {
lines.push("");
lines.push(`### Outputs (${outputKeys.length} nodes)`);
for (const nodeId of outputKeys) {
const raw = entry.outputs[nodeId];
if (!raw || typeof raw !== "object") {
lines.push(`- Node ${nodeId}: (no output data)`);
continue;
}
const output = raw;
// Expand media filenames so callers can use get_image directly.
// Video keys ('videos', 'video', 'gifs') adapted from jcd315's fork
// (jcd315/comfyui-mcp-muse, commit e13342ec).
const mediaKeys = ["images", "videos", "video", "gifs"];
const expanded = [];
for (const key of mediaKeys) {
const items = output[key];
if (!Array.isArray(items))
continue;
const fileList = items
.map((m) => (m.subfolder ? `${m.subfolder}/${m.filename}` : m.filename))
.join(", ");
if (fileList)
expanded.push(`${key} → **${fileList}**`);
}
if (expanded.length > 0) {
lines.push(`- Node ${nodeId}: ${expanded.join("; ")}`);
}
else {
const outputTypes = Object.keys(output);
lines.push(`- Node ${nodeId}: ${outputTypes.join(", ")}`);
}
}
}
return lines.join("\n");
}
export function registerDiagnosticsTools(server) {
server.tool("get_logs", "Get ComfyUI server runtime logs. Useful for debugging execution errors, model loading issues, missing nodes, and Python tracebacks.", {
max_lines: z
.number()
.int()
.min(1)
.max(2000)
.optional()
.describe("Maximum number of log lines to return from the end (default: 100)"),
keyword: z
.string()
.optional()
.describe("Filter log lines containing this keyword (case-insensitive). Examples: 'error', 'warning', 'VRAM', a node name"),
}, async (args) => {
try {
let lines = await getLogs();
// Filter by keyword if provided
if (args.keyword) {
const kw = args.keyword.toLowerCase();
lines = lines.filter((line) => line.toLowerCase().includes(kw));
}
// Tail to max_lines
const maxLines = args.max_lines ?? 100;
if (lines.length > maxLines) {
lines = lines.slice(-maxLines);
}
// Strip ANSI escape codes for readability
const clean = lines.map((l) => l.replace(/\x1b\[[0-9;]*m/g, ""));
const text = clean.length === 0
? `No log lines found${args.keyword ? ` matching "${args.keyword}"` : ""}.`
: clean.join("\n");
return { content: [{ type: "text", text }] };
}
catch (err) {
return errorToToolResult(err);
}
});
server.tool("get_history", "Get execution history for a ComfyUI prompt: status, timing, cached nodes, and output details (media filenames for get_image). Also carries the raw error/traceback. To diagnose WHY a run FAILED or what's missing, prefer `diagnose_run` — it returns the same failure info PLUS missing models (with the file + widget) and missing node types, which this tool does not. Use get_history when you need the run's OUTPUTS or timing for a specific prompt_id.", {
prompt_id: z
.string()
.optional()
.describe("Specific prompt ID to look up (returned by enqueue_workflow). If omitted, returns the most recent COMMITTED execution (chosen by ComfyUI's queue number, not dict order). Note: immediately after a run finishes it can briefly lag by one until ComfyUI commits the new entry — pass the prompt_id from enqueue_workflow to get that exact run, and prefer the run-finished event for naming a just-produced output."),
}, async (args) => {
try {
const history = await getHistory(args.prompt_id);
const selected = selectNewestHistoryEntry(history, args.prompt_id);
if (!selected) {
return {
content: [
{
type: "text",
text: args.prompt_id
? `No history found for prompt ${args.prompt_id}.`
: "No execution history available.",
},
],
};
}
const [promptId, entry] = selected;
const text = formatHistoryEntry(promptId, entry);
return { content: [{ type: "text", text }] };
}
catch (err) {
return errorToToolResult(err);
}
});
server.tool("diagnose_run", "WHY DID MY RENDER FAIL / WHAT'S MISSING? Explains a failed run in ONE call, without needing a canvas — the headless counterpart to the panel's panel_view_errored_nodes (\"why is this red?\"), so mobile/remote sessions get the same answer. Returns: the failed node (id, type) with its `exception_type` + message and a trimmed traceback; **missing_models** (the exact model file that isn't installed and the widget holding it — feed the filename to search_civitai_models/download_model to fix it); **missing_node_types** (node classes this install lacks — feed to search_custom_nodes/install_custom_node); and any other per-input validation errors. Call this whenever a run fails, an enqueue is rejected, or the user asks what's missing — instead of guessing from raw logs. With no prompt_id it diagnoses the most recent FAILED run (falling back to the most recent run). Read-only.", {
prompt_id: z
.string()
.optional()
.describe("Specific run to diagnose (the prompt_id from enqueue_workflow). Omit to diagnose the most recent FAILED run — preferred over a newer successful one — falling back to the most recent run if nothing failed."),
}, async (args) => {
try {
const history = await getHistory(args.prompt_id);
const selected = selectRunToDiagnose(history, args.prompt_id);
if (!selected) {
return {
content: [
{
type: "text",
text: args.prompt_id
? `No history found for prompt ${args.prompt_id}.`
: "No execution history available — nothing has run yet on this ComfyUI.",
},
],
};
}
const [promptId, entry] = selected;
const lines = [];
lines.push(`## Diagnosis: ${promptId}`);
// 1. Status + outcome: runtime failure, interruption, or clean.
lines.push(...formatRunOutcome(entry));
// 2. Re-validate the exact graph that ran, so we can name what's missing.
// Reuses the same validator behind validate_workflow — the graph is the
// one ComfyUI recorded, so this reflects what actually executed.
const graph = extractWorkflowGraph(entry);
if (!graph) {
lines.push("");
lines.push("_This history entry has no recorded graph_, so missing models/nodes can't be checked for it.");
}
else {
const result = await validateWorkflow(graph, { health: false });
const errors = result.issues.filter((i) => i.severity === "error");
const missingModels = errors.filter((i) => i.kind === "missing_model");
const missingNodeTypes = errors.filter((i) => i.kind === "missing_node_type");
const otherErrors = errors.filter((i) => i.kind !== "missing_model" && i.kind !== "missing_node_type");
if (missingModels.length > 0) {
lines.push("");
lines.push("### Missing models");
for (const i of missingModels) {
lines.push(`- **${i.value ?? "(unknown file)"}** — node ${i.node_id} (${i.node_type}), widget \`${i.input ?? "?"}\``);
}
lines.push("_Fix_: search_civitai_models / search_models by that filename, then download_model (or download_civitai_model) into the loader's directory.");
}
if (missingNodeTypes.length > 0) {
lines.push("");
lines.push("### Missing node types (packs this install lacks)");
const uniq = [...new Set(missingNodeTypes.map((i) => i.node_type))];
for (const t of uniq)
lines.push(`- **${t}**`);
lines.push("_Fix_: search_custom_nodes for the owning pack, install_custom_node, then restart ComfyUI to load it.");
}
if (otherErrors.length > 0) {
lines.push("");
lines.push("### Validation errors");
for (const i of otherErrors.slice(0, 20)) {
lines.push(`- node ${i.node_id} (${i.node_type}): ${i.message}`);
}
if (otherErrors.length > 20) {
lines.push(`- …and ${otherErrors.length - 20} more`);
}
}
if (errors.length === 0) {
lines.push("");
lines.push("_The recorded graph validates clean_ — nothing is missing, so the failure was a runtime one (see above), not a setup problem.");
}
}
return { content: [{ type: "text", text: lines.join("\n") }] };
}
catch (err) {
return errorToToolResult(err);
}
});
}
//# sourceMappingURL=diagnostics.js.map