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

539 lines • 24.5 kB
import { readFile, copyFile, readdir, stat } from "node:fs/promises"; import { join, basename, extname, relative, sep } from "node:path"; import { config, isRemoteMode } from "../config.js"; import { getHistory } from "../comfyui/client.js"; import { ValidationError, ComfyUIError } from "../utils/errors.js"; import { logger } from "../utils/logger.js"; import { resolveOutputDir, resolveInputDir } from "./output-dir.js"; /** * Resolve ComfyUI's REAL input directory (honors a custom --input-directory / * --base-directory). Used only for genuine local filesystem copies; HTTP uploads * go through the server API and don't need a path. */ async function getInputDir() { return resolveInputDir(); } /** * Reject filenames that would escape the ComfyUI input/ directory. * The MCP client is untrusted input, so `filename` must be treated as such. */ function assertSafeInputFilename(filename) { // Strip any directory components — only allow a bare filename. const safe = basename(filename); if (!safe || safe === "." || safe === ".." || safe !== filename || safe.includes("/") || safe.includes("\\") || safe.includes("\0")) { throw new ValidationError(`Invalid filename "${filename}": must be a bare filename with no path components.`); } return safe; } /** * Copy a local image file into ComfyUI's input/ directory so it can be * referenced by LoadImage nodes in workflows. */ export async function uploadImage(sourcePath, filename) { const inputDir = await getInputDir(); const resolvedFilename = assertSafeInputFilename(filename ?? basename(sourcePath)); // Validate extension const ext = extname(resolvedFilename).toLowerCase(); const allowed = [".png", ".jpg", ".jpeg", ".webp", ".bmp", ".gif", ".tiff", ".tif"]; if (!allowed.includes(ext)) { throw new ValidationError(`Unsupported image format "${ext}". Supported: ${allowed.join(", ")}`); } const targetPath = join(inputDir, resolvedFilename); logger.info("Uploading image to ComfyUI input", { sourcePath, targetPath }); try { await copyFile(sourcePath, targetPath); } catch (err) { throw new ValidationError(`Failed to copy image: ${err instanceof Error ? err.message : err}`); } return { filename: resolvedFilename, path: targetPath }; } /** * Extract embedded workflow JSON from a ComfyUI-generated PNG file. * ComfyUI stores workflow data in PNG tEXt chunks under the keys * "prompt" (API format) and "workflow" (UI format). */ export async function extractWorkflowFromImage(imagePath) { const ext = extname(imagePath).toLowerCase(); if (ext !== ".png") { throw new ValidationError("Workflow extraction only works with PNG files. ComfyUI embeds metadata in PNG tEXt chunks."); } const buffer = await readFile(imagePath); const result = {}; // Parse PNG chunks to find tEXt/iTXt chunks with "prompt" or "workflow" keys const chunks = parsePngTextChunks(buffer); for (const { keyword, text } of chunks) { if (keyword === "prompt") { try { result.prompt = JSON.parse(text); } catch { logger.warn("Failed to parse 'prompt' PNG metadata as JSON"); } } else if (keyword === "workflow") { try { result.workflow = JSON.parse(text); } catch { logger.warn("Failed to parse 'workflow' PNG metadata as JSON"); } } } if (!result.prompt && !result.workflow) { throw new ValidationError("No ComfyUI workflow metadata found in this PNG. The image may not have been generated by ComfyUI, or metadata embedding may have been disabled."); } return result; } /** * Low-level PNG tEXt/iTXt chunk parser. * PNG format: 8-byte signature, then chunks of [4-byte length][4-byte type][data][4-byte CRC]. */ function parsePngTextChunks(buffer) { const results = []; // Verify PNG signature const PNG_SIG = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]); if (buffer.length < 8 || !buffer.subarray(0, 8).equals(PNG_SIG)) { throw new ValidationError("Not a valid PNG file"); } let offset = 8; // Skip signature while (offset + 8 <= buffer.length) { const chunkLength = buffer.readUInt32BE(offset); const chunkType = buffer.subarray(offset + 4, offset + 8).toString("ascii"); const dataStart = offset + 8; const dataEnd = dataStart + chunkLength; if (dataEnd > buffer.length) break; if (chunkType === "tEXt") { // tEXt: keyword\0text const data = buffer.subarray(dataStart, dataEnd); const nullIdx = data.indexOf(0); if (nullIdx >= 0) { const keyword = data.subarray(0, nullIdx).toString("latin1"); const text = data.subarray(nullIdx + 1).toString("latin1"); results.push({ keyword, text }); } } else if (chunkType === "iTXt") { // iTXt: keyword\0compressionFlag\0compressionMethod\0languageTag\0translatedKeyword\0text const data = buffer.subarray(dataStart, dataEnd); const nullIdx = data.indexOf(0); if (nullIdx >= 0) { const keyword = data.subarray(0, nullIdx).toString("utf-8"); const compressionFlag = data[nullIdx + 1]; // Skip compression method (1 byte), language tag, translated keyword let textStart = nullIdx + 3; // past null, compressionFlag, compressionMethod // Skip language tag (null-terminated) const langEnd = data.indexOf(0, textStart); if (langEnd >= 0) { textStart = langEnd + 1; // Skip translated keyword (null-terminated) const transEnd = data.indexOf(0, textStart); if (transEnd >= 0) { textStart = transEnd + 1; } } const textData = data.subarray(textStart); if (compressionFlag === 0) { results.push({ keyword, text: textData.toString("utf-8") }); } // We skip compressed iTXt chunks — ComfyUI typically uses uncompressed } } if (chunkType === "IEND") break; // Next chunk: length(4) + type(4) + data(chunkLength) + CRC(4) offset = dataEnd + 4; } return results; } // Still-image extensions. const IMAGE_EXTS = new Set([".png", ".jpg", ".jpeg", ".bmp"]); // Video / animation extensions written by VHS_VideoCombine, LTX, WAN, etc. // NOTE: .webp and .gif can be still OR animated; ComfyUI's video nodes emit // them as animations, so they're classified as "video" here. const VIDEO_EXTS = new Set([".mp4", ".webm", ".mov", ".mkv", ".m4v", ".avi", ".gif", ".webp"]); // Everything we list (images + videos/animations). const MEDIA_EXTS = new Set([...IMAGE_EXTS, ...VIDEO_EXTS]); function mediaKind(ext) { return VIDEO_EXTS.has(ext) ? "video" : "image"; } /** * List image AND video/animation files in the ComfyUI output directory. * * Covers VHS_VideoCombine / LTX / WAN video outputs (.mp4, .webm, …) in addition * to still images, because ComfyUI's /history often does NOT register VHS-style * video outputs — so a filesystem scan is the reliable way to confirm a finished * video render. */ export async function listOutputImages(options) { const limit = options?.limit ?? 20; const pattern = options?.pattern?.toLowerCase(); // REMOTE mode: no local filesystem to scan. Derive the output media from // ComfyUI's /history (HTTP, works against a remote instance) instead. Size and // modification time are unavailable over HTTP, so they come back as 0 / "". // Key off isRemoteMode() (not mere comfyuiPath absence): when a remote target // coexists with an unrelated local COMFYUI_PATH, scanning the local output dir // would report the wrong machine's outputs. Also fall back to /history when no // local path is configured at all. if (isRemoteMode() || !config.comfyuiPath) { return listOutputImagesFromHistory(limit, pattern); } // Resolve the real local output dir. Asking the running ComfyUI can fail // (unreachable, or a non-local --output-directory we can't read); treat any // failure as "nothing to list" rather than throwing, so the tool degrades to // an empty result instead of an opaque error. let outputDir; try { outputDir = await resolveOutputDir(); } catch { return []; } // RECURSIVE scan: ComfyUI writes to subfolders when a node's filename_prefix // contains a path (SaveVideo / VHS / "video/clip" → output/video/clip_00001.mp4). // A flat readdir of the top level silently misses those — so a finished video can // look "not found" even though the dir resolved correctly. Walk the whole tree. let dirents; try { dirents = await readdir(outputDir, { recursive: true, withFileTypes: true }); } catch { return []; } const images = []; for (const dirent of dirents) { if (!dirent.isFile()) continue; const ext = extname(dirent.name).toLowerCase(); if (!MEDIA_EXTS.has(ext)) continue; // Dirent.parentPath (Node ≥20.12) is the absolute dir holding the entry. const parent = dirent.parentPath ?? outputDir; const subfolder = relative(outputDir, parent).split(sep).join("/"); // "" at top level const relPath = subfolder ? `${subfolder}/${dirent.name}` : dirent.name; // Match the pattern against the subfolder-relative path so "video/clip" works. if (pattern && !relPath.toLowerCase().includes(pattern)) continue; const filePath = join(parent, dirent.name); try { const info = await stat(filePath); images.push({ filename: dirent.name, path: filePath, size: info.size, modified: info.mtime.toISOString(), subfolder, kind: mediaKind(ext), }); } catch { continue; } } // Sort newest first images.sort((a, b) => b.modified.localeCompare(a.modified)); return images.slice(0, limit); } /** * Remote-mode source for listOutputImages: derive output media from ComfyUI's * /history (HTTP) when there is no local filesystem to scan. Walks every history * entry's node outputs (images + videos/gifs), keeps only those that landed in * the "output" directory, dedupes by subfolder/filename, and returns them * newest-first (history is roughly insertion-ordered, so we iterate in reverse). * Size/modified are unavailable over HTTP and come back as 0 / "". */ async function listOutputImagesFromHistory(limit, pattern) { let history; try { history = await getHistory(); } catch (err) { logger.debug("getHistory failed while listing remote output media", { err }); return []; } const seen = new Set(); const images = []; const entries = Object.values(history); // Newest-first: history is keyed in roughly chronological (insertion) order, // so iterate from the end. for (let i = entries.length - 1; i >= 0; i--) { const outputs = entries[i]?.outputs; if (!outputs || typeof outputs !== "object") continue; for (const nodeOutput of Object.values(outputs)) { if (!nodeOutput || typeof nodeOutput !== "object") continue; const out = nodeOutput; // SaveImage emits under 'images'; SaveVideo/VHS/CreateVideo under // 'videos' | 'video' | 'gifs'. mediaKind() then classifies by extension. for (const key of ["images", "videos", "video", "gifs"]) { const arr = out[key]; if (!Array.isArray(arr)) continue; for (const m of arr) { if (!m || typeof m !== "object") continue; const media = m; if (typeof media.filename !== "string" || media.filename.length === 0) { continue; } // Only list assets in the output directory (skip temp previews). const type = typeof media.type === "string" ? media.type : "output"; if (type !== "output") continue; const ext = extname(media.filename).toLowerCase(); if (!MEDIA_EXTS.has(ext)) continue; const subfolder = typeof media.subfolder === "string" ? media.subfolder : ""; const relPath = subfolder ? `${subfolder}/${media.filename}` : media.filename; if (pattern && !relPath.toLowerCase().includes(pattern)) continue; const dedupeKey = relPath.toLowerCase(); if (seen.has(dedupeKey)) continue; seen.add(dedupeKey); images.push({ filename: media.filename, // ComfyUI-relative reference; the absolute path is unknown over HTTP. path: relPath, size: 0, modified: "", subfolder, kind: mediaKind(ext), }); } } } if (images.length >= limit) break; } return images.slice(0, limit); } import { fetchImage, uploadImageHttp } from "../comfyui/client.js"; import { readFile as nodeReadFile } from "node:fs/promises"; /** * Reject filename / subfolder values that could traverse out of ComfyUI's * output, input or temp directory when forwarded to the /view endpoint. * * ComfyUI's /view handler joins the requested `subfolder` and `filename` * onto the configured base directory; the server has historically been * permissive about ".." segments and absolute paths in those parameters * (see e.g. comfyanonymous/ComfyUI#785), so an attacker who can reach the * MCP tool surface could otherwise pivot through get_image / view_image / * stage_output_as_input to read arbitrary files from the ComfyUI host. * * Legitimate ComfyUI values are a single filename (no separators) and a * relative subfolder produced by listOutputImages (forward-slash joined, * no ".." segments). Anything outside that shape is refused here BEFORE * the request is forwarded. */ function assertSafeViewRef(filename, subfolder) { if (typeof filename !== "string" || filename.length === 0) { throw new ValidationError("filename is required"); } if (filename.includes("\0") || (subfolder && subfolder.includes("\0"))) { throw new ValidationError("filename / subfolder must not contain NUL bytes"); } // Filename must be a single path segment — no separators, no traversal. if (filename.includes("/") || filename.includes("\\") || filename === "." || filename === ".." || filename.split(/[\\/]/).some((s) => s === "..")) { throw new ValidationError(`Invalid filename "${filename}": must be a single filename without path separators or '..' segments`); } if (!subfolder) return; // Subfolder must be a forward-slash-joined relative path with no ".." // segments and no Windows-style drive / absolute prefix. if (subfolder.startsWith("/") || subfolder.startsWith("\\") || /^[A-Za-z]:[\\/]/.test(subfolder)) { throw new ValidationError(`Invalid subfolder "${subfolder}": must be relative to the ComfyUI media directory`); } const segments = subfolder.split(/[\\/]/); if (segments.some((s) => s === "..")) { throw new ValidationError(`Invalid subfolder "${subfolder}": '..' segments are not allowed`); } } /** * Fetch a generated image from ComfyUI via HTTP /view endpoint. * Does NOT require COMFYUI_PATH — works with remote ComfyUI instances. */ export async function getOutputImage(filename, type = "output", subfolder = "") { assertSafeViewRef(filename, subfolder); const result = await fetchImage(filename, type, subfolder); // Guard against non-image /view payloads. ComfyUI (or a reverse proxy in // front of it) can answer /view with a 200 whose body is actually a JSON or // HTML error page, or an empty body — this happens most often for `type=input` // refs, where the caller picked a filename/subfolder that doesn't resolve to a // real input file. The old code saved those bytes verbatim as a `.png` and // returned them as an inline image block, so the MCP client then choked trying // to decode them ("Unexpected end of JSON input"). Fail loudly and structured // instead, so get_image surfaces a clean not-found rather than a corrupt image. const mime = result.mimeType.toLowerCase(); const isImage = mime.startsWith("image/"); if (!isImage || result.base64.length === 0) { const where = subfolder ? `${type}/${subfolder}` : type; throw new ComfyUIError(`ComfyUI /view did not return an image for "${filename}" (${where}); ` + `got ${result.base64.length === 0 ? "an empty response" : `content-type "${result.mimeType}"`}. ` + `The file may not exist in the ComfyUI ${type} directory — ` + `check the filename/subfolder (e.g. via list_output_images or get_history).`, "IMAGE_NOT_FOUND", { filename, type, subfolder, mimeType: result.mimeType }); } return { ...result, filename }; } /** * Upload a local image to ComfyUI via HTTP multipart POST. * Falls back to HTTP when COMFYUI_PATH is not available (remote ComfyUI). */ export async function uploadImageAuto(sourcePath, filename) { const resolvedFilename = filename ?? basename(sourcePath); const ext = extname(resolvedFilename).toLowerCase(); if (!(ext in IMAGE_MIME)) { throw new ValidationError(`Unsupported image format "${ext}". Supported: ${Object.keys(IMAGE_MIME).join(", ")}`); } const data = await nodeReadFile(sourcePath); const mimeType = IMAGE_MIME[ext] ?? "application/octet-stream"; logger.info("Uploading image to ComfyUI via HTTP", { sourcePath, resolvedFilename }); const result = await uploadImageHttp(resolvedFilename, data, mimeType); return { filename: result.name }; } // --------------------------------------------------------------------------- // Video / audio upload — mirrors upload_image. ComfyUI's /upload/image endpoint // (and the input/ directory) accept arbitrary media, which video/audio loader // nodes (e.g. VHS_LoadVideo, LoadAudio) then read by filename. // --------------------------------------------------------------------------- const IMAGE_MIME = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".bmp": "image/bmp", ".gif": "image/gif", ".tiff": "image/tiff", ".tif": "image/tiff", }; const VIDEO_MIME = { ".mp4": "video/mp4", ".mov": "video/quicktime", ".webm": "video/webm", ".avi": "video/x-msvideo", ".mkv": "video/x-matroska", ".m4v": "video/x-m4v", }; const AUDIO_MIME = { ".wav": "audio/wav", ".mp3": "audio/mpeg", ".flac": "audio/flac", ".ogg": "audio/ogg", ".m4a": "audio/mp4", ".aac": "audio/aac", }; function resolveMediaMime(filename, mimeMap, kind) { const ext = extname(filename).toLowerCase(); const mime = mimeMap[ext]; if (!mime) { throw new ValidationError(`Unsupported ${kind} format "${ext}". Supported: ${Object.keys(mimeMap).join(", ")}`); } return mime; } /** HTTP multipart upload of a media file to ComfyUI's input/ (works remotely). */ async function uploadMediaHttp(sourcePath, filename, mimeMap, kind) { const resolvedFilename = filename ?? basename(sourcePath); const mimeType = resolveMediaMime(resolvedFilename, mimeMap, kind); const data = await nodeReadFile(sourcePath); logger.info(`Uploading ${kind} to ComfyUI via HTTP`, { sourcePath, resolvedFilename }); const result = await uploadImageHttp(resolvedFilename, data, mimeType); return { filename: result.name }; } /** Local filesystem copy of a media file into ComfyUI's input/ (needs COMFYUI_PATH). */ async function uploadMediaLocal(sourcePath, filename, mimeMap, kind) { const inputDir = await getInputDir(); const resolvedFilename = assertSafeInputFilename(filename ?? basename(sourcePath)); resolveMediaMime(resolvedFilename, mimeMap, kind); const targetPath = join(inputDir, resolvedFilename); logger.info(`Uploading ${kind} to ComfyUI input`, { sourcePath, targetPath }); try { await copyFile(sourcePath, targetPath); } catch (err) { throw new ValidationError(`Failed to copy ${kind}: ${err instanceof Error ? err.message : err}`); } return { filename: resolvedFilename, path: targetPath }; } export const uploadVideoAuto = (sourcePath, filename) => uploadMediaHttp(sourcePath, filename, VIDEO_MIME, "video"); export const uploadVideoLocal = (sourcePath, filename) => uploadMediaLocal(sourcePath, filename, VIDEO_MIME, "video"); export const uploadAudioAuto = (sourcePath, filename) => uploadMediaHttp(sourcePath, filename, AUDIO_MIME, "audio"); export const uploadAudioLocal = (sourcePath, filename) => uploadMediaLocal(sourcePath, filename, AUDIO_MIME, "audio"); const MIME_BY_KIND = { image: IMAGE_MIME, video: VIDEO_MIME, audio: AUDIO_MIME, }; /** Infer image/video/audio from a filename's extension. */ export function inferMediaKind(filename) { const ext = extname(filename).toLowerCase(); if (ext in IMAGE_MIME) return "image"; if (ext in VIDEO_MIME) return "video"; if (ext in AUDIO_MIME) return "audio"; throw new ValidationError(`Cannot infer media kind from extension "${ext}". ` + `Pass an explicit kind ("image" | "video" | "audio").`); } /** Resolve the upload MIME type for a filename within a given media kind. */ function mimeForKind(filename, kind) { const ext = extname(filename).toLowerCase(); const mime = MIME_BY_KIND[kind][ext]; if (!mime) { throw new ValidationError(`Extension "${ext}" is not a supported ${kind} format. ` + `Supported: ${Object.keys(MIME_BY_KIND[kind]).join(", ")}`); } return mime; } /** * Stage an EXISTING ComfyUI output (or temp preview) as an INPUT, ready to feed * into the next stage's LoadImage / VHS_LoadVideo / LoadAudio loader. * * Fetches the bytes from the server via /view (the same path get_image uses) and * re-registers them as an input via /upload/image (the same path upload_image / * upload_video / upload_audio use). Goes entirely through the server API, so it * is correct even when ComfyUI runs with a custom input/output directory. */ export async function stageOutputAsInput(args) { const sourceType = args.type ?? "output"; const kind = args.kind ?? inferMediaKind(args.filename); const targetName = args.asFilename ?? basename(args.filename); const mimeType = mimeForKind(targetName, kind); // Fetch the existing asset's bytes via the same /view mechanism the asset // tools use (fetchImage handles cloud vs local). Despite the name, /view // returns raw bytes for any media type, not just images. const sourceSubfolder = args.subfolder ?? ""; assertSafeViewRef(args.filename, sourceSubfolder); const { base64 } = await fetchImage(args.filename, sourceType, sourceSubfolder); const data = Buffer.from(base64, "base64"); logger.info("Staging ComfyUI output as input via server API", { source: args.filename, sourceType, kind, targetName, }); const result = await uploadImageHttp(targetName, data, mimeType); return { filename: result.name, subfolder: result.subfolder, type: result.type, kind, }; } //# sourceMappingURL=image-management.js.map