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