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
JavaScript
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