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

296 lines • 16 kB
import { z } from "zod"; import { writeFile, mkdir } from "node:fs/promises"; import { join, basename } from "node:path"; import { extractWorkflowFromImage, listOutputImages, getOutputImage, uploadImageAuto, uploadVideoAuto, uploadAudioAuto, stageOutputAsInput, } from "../services/image-management.js"; import { errorToToolResult } from "../utils/errors.js"; export function registerImageManagementTools(server) { // ── get_image ──────────────────────────────────────────────────────────── // Fetches a generated image from ComfyUI via HTTP /view. // Works with remote ComfyUI — no COMFYUI_PATH required. server.tool("get_image", "Fetch a generated image from ComfyUI and return it as an inline image. " + "Works with remote ComfyUI instances — does not require COMFYUI_PATH. " + "Use get_history first to obtain the filename.", { filename: z .string() .describe("Output image filename, e.g. PulID_Klein_00001_.png"), type: z .enum(["output", "input", "temp"]) .optional() .default("output") .describe("Image directory: output (default), input, or temp"), subfolder: z .string() .optional() .default("") .describe("Subfolder within the directory, if any"), save_dir: z .string() .optional() .describe("Local directory to save the image file. Defaults to /tmp/comfyui-images/."), }, async (args) => { try { const { base64, mimeType } = await getOutputImage(args.filename, args.type ?? "output", args.subfolder ?? ""); // Save to local file const saveDir = args.save_dir ?? process.cwd(); await mkdir(saveDir, { recursive: true }); const localFilename = basename(args.filename); const savePath = join(saveDir, localFilename); await writeFile(savePath, Buffer.from(base64, "base64")); return { content: [ { type: "text", text: `Saved to: ${savePath}`, }, { type: "image", data: base64, mimeType, }, ], }; } catch (err) { return errorToToolResult(err); } }); // ── upload_image / upload_video / upload_audio ──────────────────────────── // HTTP-only (works for both local and remote ComfyUI via /upload/image). // Previous filesystem fallback was deceptive when COMFYUI_PATH auto-detected // an unrelated local install — files would land in the wrong tree and the // tool reported success while the remote ComfyUI never received them. // Originally diagnosed by João Lucas (github.com/joaolvivas) in // joaolvivas/comfyui-mcp-byjlucas@089180ad (2026-05-12). const registerMediaUpload = (name, description, autoFn, nodeHint) => { server.tool(name, description, { source_path: z .string() .describe("Absolute path to the local file to upload"), filename: z .string() .optional() .describe("Override the filename in ComfyUI's input/ directory. " + "Auto-detected from source path if omitted."), }, async (args) => { try { const result = await autoFn(args.source_path, args.filename); return { content: [ { type: "text", text: `Uploaded via HTTP.\n\nFilename: ${result.filename}\n\n` + `Use "${result.filename}" ${nodeHint}.`, }, ], }; } catch (err) { return errorToToolResult(err); } }); }; registerMediaUpload("upload_image", "Upload a local image file to the connected ComfyUI's input/ directory " + "via the HTTP /upload/image endpoint so it can be referenced in LoadImage " + "nodes. Works for both local and remote ComfyUI. Returns the stored " + "filename.", uploadImageAuto, "as the `image` input in LoadImage nodes"); registerMediaUpload("upload_video", "Upload a local video file (.mp4, .mov, .webm, .avi, .mkv, .m4v) to the " + "connected ComfyUI's input/ directory via the HTTP /upload/image endpoint " + "for use in video-loading nodes such as VHS_LoadVideo " + "(ComfyUI-VideoHelperSuite). Works for both local and remote ComfyUI. " + "Returns the stored filename. Use upload_image for images or " + "upload_audio for audio.", uploadVideoAuto, "as the video file input in VHS_LoadVideo (or similar) nodes"); registerMediaUpload("upload_audio", "Upload a local audio file (.wav, .mp3, .flac, .ogg, .m4a, .aac) to the " + "connected ComfyUI's input/ directory via the HTTP /upload/image endpoint " + "for use in audio-conditioned workflows (e.g. LoadAudio). Works for both " + "local and remote ComfyUI. Returns the stored filename. Use upload_image " + "for images or upload_video for video.", uploadAudioAuto, "as the audio file input in LoadAudio (or similar) nodes"); // ── stage_output_as_input ───────────────────────────────────────────────── // The correct, dir-agnostic way to pipe one pipeline stage's output into the // next stage's loader. Fetches the output via /view and re-registers it as an // input via /upload/image — never touches the filesystem, so it works with // custom --input-directory / --output-directory. server.tool("stage_output_as_input", "Stage an EXISTING ComfyUI output (or temp/preview) as an INPUT so the next " + "stage's loader (LoadImage / VHS_LoadVideo / LoadAudio) can read it. This " + "is the CORRECT way to chain a multi-stage pipeline (e.g. Krea2 image → " + "LTX video → WAN extend): it fetches the output's bytes from the server " + "via /view and re-registers them as an input via /upload/image — the same " + "endpoints get_image and upload_image use. Because it goes entirely " + "through the server API, it works even when ComfyUI was launched with a " + "CUSTOM input/output directory. Do NOT instead copy the output file or " + "guess a filesystem `input/` path — the server's input dir may be custom " + "and it will reject the file (\"Invalid image file\"), wasting the render. " + "Pass an existing output reference ({ filename, subfolder?, type? }); the " + "media kind (image/video/audio) is inferred from the extension unless you " + "set `kind`. Returns the registered input { filename, subfolder, type: " + "\"input\", kind } — drop the returned `filename` straight into the " + "loader's image/video/audio widget.", { filename: z .string() .describe("Filename of the existing output/temp asset (from get_history or list_output_images), e.g. LTX_video_00001.mp4"), subfolder: z .string() .optional() .describe("Subfolder the asset currently lives in, if any"), type: z .enum(["output", "temp"]) .optional() .default("output") .describe("Source directory the asset lives in: output (default) or temp (previews)"), kind: z .enum(["image", "video", "audio"]) .optional() .describe("Force the media kind instead of inferring it from the file extension"), as_filename: z .string() .optional() .describe("Override the filename it is registered under in the input/ directory (defaults to the source filename)"), }, async (args) => { try { const staged = await stageOutputAsInput({ filename: args.filename, subfolder: args.subfolder, type: args.type ?? "output", kind: args.kind, asFilename: args.as_filename, }); const loaderHint = staged.kind === "video" ? "the video file input in VHS_LoadVideo (or similar)" : staged.kind === "audio" ? "the audio input in LoadAudio (or similar)" : "the `image` input in LoadImage"; return { content: [ { type: "text", text: `Staged ${staged.kind} output as input via the server API.\n\n` + `Input filename: ${staged.filename}\n` + `subfolder: ${staged.subfolder || "(none)"}\n` + `type: ${staged.type}\n\n` + `Use "${staged.filename}" as ${loaderHint}.`, }, ], }; } catch (err) { return errorToToolResult(err); } }); // ── workflow_from_image ─────────────────────────────────────────────────── server.tool("workflow_from_image", "Extract embedded ComfyUI workflow metadata from a PNG file. " + "ComfyUI stores the full workflow (API format) and prompt data in PNG tEXt chunks. " + "Use this to reverse-engineer how any ComfyUI image was generated.", { image_path: z .string() .describe("Absolute path to a ComfyUI-generated PNG file"), }, async (args) => { try { const result = await extractWorkflowFromImage(args.image_path); const sections = []; if (result.prompt) { sections.push("## API Format (prompt)\n\nThis is the executable workflow format:\n```json\n" + JSON.stringify(result.prompt, null, 2) + "\n```"); } if (result.workflow) { sections.push("## UI Format (workflow)\n\nThis is the ComfyUI web UI format with layout data:\n```json\n" + JSON.stringify(result.workflow, null, 2) + "\n```"); } return { content: [ { type: "text", text: `# Workflow extracted from ${args.image_path}\n\n${sections.join("\n\n")}`, }, ], }; } catch (err) { return errorToToolResult(err); } }); // ── list_output_images ──────────────────────────────────────────────────── server.tool("list_output_images", "List recently generated image AND video files from ComfyUI's output/ directory, newest-first, with each file's kind ('image' | 'video'), subfolder, size, and modification time. Covers stills (.png/.jpg/.jpeg/.bmp) and video/animation outputs (.mp4/.webm/.mov/.mkv/.m4v/.avi/.gif/.webp). LOCAL ComfyUI (COMFYUI_PATH set): a RECURSIVE filesystem scan of output/ — includes subfolders like video/ that VHS/SaveVideo write to, and reports size + modification time. REMOTE ComfyUI: derives the list from /history over HTTP instead (size/modified are unavailable and omitted). It does NOT return the media bytes themselves — fetch those with get_image. USE THIS TO CONFIRM A VIDEO RENDER (e.g. VHS_VideoCombine / LTX / WAN output) when get_history shows the prompt done but lists no output: VHS-style video nodes write the file but often do NOT register in ComfyUI's /history, so the local filesystem scan is the reliable way to verify the .mp4 exists — then chain it with stage_output_as_input. Read-only.", { limit: z .number() .int() .min(1) .max(100) .optional() .describe("Max images to return (default: 20)"), pattern: z .string() .optional() .describe("Filter by filename pattern (case-insensitive substring match)"), format: z .enum(["markdown", "json"]) .optional() .describe("Response shape: markdown (default, human/agent-readable) or json ({images:[{filename,subfolder,kind,size,modified}]} — for app clients building pick grids)."), }, async (args) => { try { const images = await listOutputImages({ limit: args.limit, pattern: args.pattern, }); if (args.format === "json") { // Machine-readable form for app clients (the mobile dataset picker): // same entries, no prose. Thumbs render client-side via /view URLs. return { content: [ { type: "text", text: JSON.stringify({ images: images.map((img) => ({ filename: img.filename, subfolder: img.subfolder, kind: img.kind, ...(img.size > 0 ? { size: img.size } : {}), ...(img.modified ? { modified: img.modified } : {}), })), }), }, ], }; } if (images.length === 0) { return { content: [ { type: "text", text: args.pattern ? `No output media (images or videos) found matching "${args.pattern}".` : "No output media (images or videos) found.", }, ], }; } const lines = images.map((img, i) => { const loc = img.subfolder ? `${img.subfolder}/${img.filename}` : img.filename; const sub = img.subfolder ? ` _(subfolder: ${img.subfolder})_` : ""; // Size/modified are only available on the local filesystem scan; the // remote (history-derived) path leaves them as 0 / "" — omit them then. const sizePart = img.size > 0 ? ` (${(img.size / 1024 / 1024).toFixed(1)} MB)` : ""; const datePart = img.modified ? ` — ${new Date(img.modified).toLocaleString()}` : ""; return `${i + 1}. **${loc}** [${img.kind}]${sizePart}${datePart}${sub}`; }); const videoCount = images.filter((img) => img.kind === "video").length; const summary = videoCount > 0 ? `Found ${images.length} media file(s) (${videoCount} video):` : `Found ${images.length} media file(s):`; return { content: [ { type: "text", text: `${summary}\n\n${lines.join("\n")}`, }, ], }; } catch (err) { return errorToToolResult(err); } }); } //# sourceMappingURL=image-management.js.map