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),
570 lines • 23.7 kB
JavaScript
import { Client } from "@stable-canvas/comfyui-client";
import { config, getComfyUIApiHost, getComfyUIBasePath, getComfyUIBaseUrl, isCloudMode, isRemoteMode, } from "../config.js";
import { logger } from "../utils/logger.js";
import { ComfyUIError, ConnectionError } from "../utils/errors.js";
import { comfyuiFetch } from "./fetch.js";
import * as cloudClient from "./cloud-client.js";
// Functions that fundamentally require a local ComfyUI process (WebSocket-bound
// session, local `client.fetchApi` paths, etc.) throw via this guard when the
// server is configured for Comfy Cloud — there is no WebSocket to attach to
// and no local socket to call. Dispatcher pattern from @picoSols
// (picoSols/comfyui-cloud-mcp@7a812069).
function requireLocalMode(op) {
if (isCloudMode()) {
throw new ComfyUIError(`This tool needs a direct ComfyUI session (${op}) and is not available in Comfy Cloud mode. ` +
`Unset COMFYUI_API_KEY to target a local or remote ComfyUI instance.`, "CLOUD_UNSUPPORTED");
}
}
/**
* Assert that we are in pure local mode (not cloud, not remote) and that
* `config.comfyuiPath` is available. Unlike `requireLocalMode` which only
* blocks cloud mode, this also throws when `--comfyui-url` points at a
* non-loopback host (remote mode). Tools that spawn OS processes or read/write
* the local ComfyUI filesystem MUST call this guard.
*/
function requireLocalComfyUI(op) {
requireLocalMode(op);
if (isRemoteMode()) {
throw new ComfyUIError(`This operation (${op}) requires a local ComfyUI installation and is not available ` +
`when targeting a remote instance via --comfyui-url. Unset --comfyui-url or ` +
`point it at a local address to use this tool.`, "REMOTE_UNSUPPORTED");
}
if (!config.comfyuiPath) {
throw new ComfyUIError(`This operation (${op}) requires a local ComfyUI installation but COMFYUI_PATH ` +
`is not set. Set the COMFYUI_PATH environment variable to the ComfyUI root directory.`, "NO_LOCAL_PATH");
}
}
let clientInstance = null;
export function getClient() {
requireLocalMode("getClient");
if (!clientInstance) {
clientInstance = new Client({
api_host: getComfyUIApiHost(),
// Path prefix for reverse-proxied / gateway'd ComfyUI (e.g. "/comfyapi").
api_base: getComfyUIBasePath(),
ssl: config.comfyuiSsl,
clientId: "comfyui-mcp",
// Inject generic auth headers (COMFYUI_AUTH_*) on the library's own HTTP
// calls; a no-op when unset. Node 22+ provides global WebSocket.
fetch: comfyuiFetch,
});
logger.info("ComfyUI client created", {
host: getComfyUIApiHost(),
});
}
return clientInstance;
}
export async function connectClient() {
requireLocalMode("connectClient");
const client = getClient();
try {
await client.connect();
logger.info("Connected to ComfyUI via WebSocket");
return client;
}
catch (err) {
throw new ConnectionError(`Failed to connect to ComfyUI at ${getComfyUIApiHost()}: ${err instanceof Error ? err.message : err}`);
}
}
/**
* Ensures WebSocket is connected, auto-reconnecting if stale.
* Only needed before WebSocket-dependent operations (enqueue with progress tracking).
*/
export async function ensureConnected() {
requireLocalMode("ensureConnected");
const client = getClient();
// If the socket looks healthy, return immediately
if (!client.closed) {
return client;
}
// Socket is stale — reset and reconnect
logger.info("WebSocket stale (closed=true), reconnecting...");
resetClient();
try {
return await connectClient();
}
catch {
// First attempt failed — reset singleton completely and retry once
logger.warn("Reconnect failed, resetting client and retrying...");
resetClient();
try {
return await connectClient();
}
catch (err) {
throw new ConnectionError(`Failed to reconnect to ComfyUI after retry: ${err instanceof Error ? err.message : err}`);
}
}
}
export async function getSystemStats() {
if (isCloudMode())
return cloudClient.getSystemStats();
const client = getClient();
const stats = await client.getSystemStats();
return stats;
}
// /object_info is large (~MBs) and slow (300-800 ms) but only changes when
// ComfyUI restarts or a custom node is (un)installed. Memoize it for the
// life of the server process; restartComfyUI()/stopComfyUI() reset it.
// In-flight coalescing prevents a thundering herd on the first fetch.
// Perf gap flagged by josephoibrahim/comfy-cozy (re-validate ~7 s → ~0.5 s).
let objectInfoCache = null;
let objectInfoInflight = null;
// Invalidation epoch. resetObjectInfoCache() bumps it; a fetch that STARTED under
// an older epoch must not commit its result to the cache — otherwise a request
// in flight when a restart invalidates the cache can resolve afterward and
// repopulate it with the PRE-restart schema, and future callers would await that
// stale value (codex WS-3 finding #1).
let objectInfoEpoch = 0;
export async function getObjectInfo() {
if (isCloudMode())
return cloudClient.getObjectInfo();
if (objectInfoCache)
return objectInfoCache;
if (objectInfoInflight)
return objectInfoInflight;
const startEpoch = objectInfoEpoch;
// Commit to the shared cache ONLY if no invalidation happened while we were
// fetching. Awaiters of this promise still get the value (they asked before
// the reset), but the cache is not poisoned for callers that arrive after.
const commit = (info) => {
if (objectInfoEpoch === startEpoch)
objectInfoCache = info;
return info;
};
const inflight = (async () => {
// Capture the client this request runs on so the catch only resets THIS one.
const startClient = getClient();
try {
return commit((await startClient.getNodeDefs()));
}
catch (err) {
// A managed restart/reboot leaves the cached client bound to a socket that
// was torn down, so the first call after it surfaces a bare "fetch failed"
// (issue #376). Drop the stale client and retry once against a fresh one
// before giving up — this is exactly the reconnect the caller expects.
// Only reset if OUR client is still current: a concurrent reset may have
// already installed a newer client we must not close.
logger.warn("getObjectInfo failed; resetting client and retrying once", {
error: err instanceof Error ? err.message : String(err),
});
resetClientIfCurrent(startClient);
return commit((await getClient().getNodeDefs()));
}
})();
objectInfoInflight = inflight;
try {
return await inflight;
}
finally {
// Only clear the shared slot if it's still ours — a concurrent reset may have
// already abandoned it and a newer fetch may have taken the slot.
if (objectInfoInflight === inflight)
objectInfoInflight = null;
}
}
/**
* Drop the memoized /object_info so the next call refetches. Called after
* ComfyUI restarts (node packs may have changed) and available for tools
* that mutate the node set mid-session. Bumps the invalidation epoch and
* abandons any in-flight fetch so a fetch started before the reset can never
* commit a pre-restart result to the cache.
*/
export function resetObjectInfoCache() {
objectInfoCache = null;
objectInfoInflight = null;
objectInfoEpoch++;
logger.debug("object_info cache reset", { epoch: objectInfoEpoch });
}
/**
* Some custom nodes register individually (`/object_info/<Type>` returns a schema)
* but are absent from the bulk `/object_info` response — seen with controlnet_aux's
* `DWPreprocessor`. The converter would then skip the node and silently drop its
* connections. Backfill the schemas for the given node types missing from
* `objectInfo` by fetching each one individually, and return a merged copy.
*/
export async function backfillObjectInfo(objectInfo, nodeTypes) {
if (isCloudMode())
return objectInfo;
const oi = objectInfo;
const missing = [...new Set(nodeTypes)].filter((t) => t && !(t in oi));
if (missing.length === 0)
return objectInfo;
const base = `${getComfyUIBaseUrl()}/object_info`;
const merged = { ...oi };
await Promise.all(missing.map(async (t) => {
try {
const res = await comfyuiFetch(`${base}/${encodeURIComponent(t)}`);
if (!res.ok)
return;
const def = (await res.json());
if (!def || typeof def !== "object")
return;
// `/object_info/<Type>` returns the schema keyed by the node's LIVE
// registration name — which can differ from the string we asked for in
// case, namespace prefix, or display-vs-class name (#404,
// `DetectorForNSFW`). Honor whatever key(s) ComfyUI actually returns
// rather than narrowing to an exact `def[t]` match (which silently
// dropped the node and made get_node_info report "no match" for a node
// the server clearly registers). Prefer the exact key when present,
// otherwise merge every returned definition.
if (def[t]) {
merged[t] = def[t];
logger.info(`Backfilled object_info for '${t}' (missing from bulk /object_info)`);
}
else {
const keys = Object.keys(def);
if (keys.length === 0)
return;
for (const k of keys)
merged[k] = def[k];
logger.info(`Backfilled object_info for '${t}' under live registration key(s) [${keys.join(", ")}] (missing from bulk /object_info)`);
}
}
catch {
// Leave it missing — the converter skips + warns as before.
}
}));
return merged;
}
export async function getQueue() {
if (isCloudMode())
return cloudClient.getQueue();
const client = getClient();
const queue = await client.getQueue();
return {
queue_running: (queue.Running ?? queue.queue_running ?? []),
queue_pending: (queue.Pending ?? queue.queue_pending ?? []),
};
}
export async function interrupt(promptId) {
if (isCloudMode())
return cloudClient.interrupt(promptId);
const client = getClient();
await client.interrupt(promptId ?? null);
}
/**
* POST /free — unload resident models and/or free cached memory. Used by
* clear_vram and by the cancel escalation (a wedged sampler step can ignore an
* interrupt; freeing VRAM under it sometimes shakes it loose). No-op on cloud.
*/
export async function freeMemory(opts) {
if (isCloudMode())
return;
const client = getClient();
await client.fetchApi("/free", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
unload_models: !!opts.unload_models,
free_memory: !!opts.free_memory,
}),
});
}
/**
* Fire-and-forget: enqueue a prompt via HTTP POST (no WebSocket needed).
* Returns prompt_id and queue position immediately.
*/
export async function enqueuePrompt(workflow, extraData, opts) {
if (isCloudMode())
return cloudClient.enqueuePrompt(workflow, extraData);
const client = getClient();
// The SDK's _enqueue_prompt does not forward `extra_data`, which is how
// comfy.org API-node credentials (api_key_comfy_org / auth_token_comfy_org)
// must travel to the server. It also cannot enqueue at the front. When either
// is needed, POST /prompt directly.
if ((extraData && Object.keys(extraData).length > 0) || opts?.front) {
const url = `${getComfyUIBaseUrl()}/prompt`;
const res = await comfyuiFetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
prompt: workflow,
client_id: "comfyui-mcp",
...(extraData ? { extra_data: extraData } : {}),
...(opts?.front ? { front: true } : {}),
}),
});
if (!res.ok) {
const body = await res.text().catch(() => "");
throw new ConnectionError(`ComfyUI /prompt returned ${res.status} ${res.statusText}: ${body.slice(0, 500)}`);
}
const data = (await res.json());
return { prompt_id: data.prompt_id, queue_remaining: data.number };
}
const result = await client._enqueue_prompt(workflow);
return {
prompt_id: result.prompt_id,
queue_remaining: result.exec_info?.queue_remaining,
};
}
/**
* Remove a specific pending job from the queue by prompt_id.
*/
export async function deleteQueueItem(id) {
if (isCloudMode())
return cloudClient.deleteQueueItem(id);
const client = getClient();
await client.deleteItem("queue", id);
}
/**
* Clear all pending jobs from the queue (doesn't affect running job).
*/
export async function clearQueue() {
if (isCloudMode())
return cloudClient.clearQueue();
const client = getClient();
await client.clearItems("queue");
}
export async function getSamplers() {
if (isCloudMode())
return cloudClient.getSamplers();
const client = getClient();
return client.getSamplers();
}
export async function getSchedulers() {
if (isCloudMode())
return cloudClient.getSchedulers();
const client = getClient();
return client.getSchedulers();
}
export async function getCheckpoints() {
if (isCloudMode())
return cloudClient.getCheckpoints();
const client = getClient();
return client.getSDModels();
}
export async function getLoRAs() {
if (isCloudMode())
return cloudClient.getLoRAs();
const client = getClient();
return client.getLoRAs();
}
export async function getVAEs() {
if (isCloudMode())
return cloudClient.getVAEs();
const client = getClient();
return client.getVAEs();
}
export async function getUpscaleModels() {
if (isCloudMode())
return cloudClient.getUpscaleModels();
const client = getClient();
return client.getUpscaleModels();
}
export function resetClient() {
if (clientInstance) {
try {
clientInstance.close();
}
catch {
// Ignore close errors — process may already be dead
}
clientInstance = null;
logger.info("ComfyUI client reset");
}
}
/**
* Reset the singleton ONLY if it is still the client the caller was using. A
* failing request captures its client at start and passes it here in its catch;
* if a concurrent reset (resetObjectInfoCache abandons the in-flight slot) already
* spun up a NEW client in the meantime, we must not close that newer client + its
* fresh WebSocket out from under whoever created it (codex WS-3 round-2 finding).
* Returns true if it actually reset. A null argument never resets.
*/
export function resetClientIfCurrent(client) {
if (!client || clientInstance !== client)
return false;
resetClient();
return true;
}
export function getComfyUIPath() {
if (isCloudMode())
return cloudClient.getComfyUIPath();
return config.comfyuiPath;
}
export async function getLogs() {
if (isCloudMode())
return cloudClient.getLogs();
// A managed/panel restart or Manager reboot leaves the cached client bound to
// a socket that was torn down, so the first /internal/logs call after it
// surfaces a bare "fetch failed" (issue #399) — regardless of any keyword the
// caller passed, since filtering happens after this fetch. Mirror the
// getObjectInfo reset-and-retry: drop the stale client and retry once against
// a fresh one before giving up, and surface the underlying error if it still
// fails so callers see more than "fetch failed".
let text;
// Capture the client this request runs on so the catch only resets THIS one
// (not a newer client a concurrent reset may have installed).
const startClient = getClient();
try {
text = await startClient.fetchApi("/internal/logs").then((r) => r.text());
}
catch (err) {
logger.warn("getLogs failed; resetting client and retrying once", {
error: err instanceof Error ? err.message : String(err),
});
resetClientIfCurrent(startClient);
try {
text = await getClient().fetchApi("/internal/logs").then((r) => r.text());
}
catch (err2) {
const detail = err2 instanceof Error ? err2.message : String(err2);
throw new ConnectionError(`Failed to fetch ComfyUI logs after reconnect retry: ${detail}`);
}
}
// ComfyUI returns logs as a JSON-encoded string with \n separators,
// or as raw text depending on version. Handle both.
try {
const parsed = JSON.parse(text);
if (typeof parsed === "string") {
return parsed.split("\n").filter(Boolean);
}
}
catch {
// Not JSON — treat as raw text
}
return text.split("\n").filter(Boolean);
}
/**
* ComfyUI frontend per-user settings, served by the frontend user manager:
* GET /settings → every stored setting as one JSON object
* GET /settings/{id} → one setting's raw stored value
* POST /settings/{id} → persist one setting (JSON body is the raw value)
*
* These are the ComfyUI *frontend* UI settings (`Comfy.*` ids) and are entirely
* unrelated to our own get_defaults/set_defaults SQLite store. Local and remote
* (`--comfyui-url`) both work over plain REST and inherit `comfyuiFetch` auth
* headers. Comfy Cloud exposes no per-user settings store, so these throw
* CLOUD_UNSUPPORTED via `requireLocalMode`.
*
* Multi-user note: a `--multi-user` ComfyUI keys settings by a `comfy-user`
* header; set `COMFYUI_AUTH_COMFY_USER` (any COMFYUI_AUTH_* header is injected
* by `comfyuiFetch`) or requests may 404 or read/write another user's store.
*/
function settingsVersionDriftError() {
return new ComfyUIError("This ComfyUI version/config does not expose the user settings API " +
"(requires the standard frontend user manager). If this is a --multi-user " +
"server, set COMFYUI_AUTH_COMFY_USER so requests carry a comfy-user header.", "SETTINGS_UNSUPPORTED");
}
/** GET /settings — every stored frontend setting as a raw `id: value` object. */
export async function getSettings() {
requireLocalMode("settings");
const client = getClient();
const res = await client.fetchApi("/settings");
if (res.status === 404)
throw settingsVersionDriftError();
const text = await res.text();
try {
const parsed = JSON.parse(text);
if (parsed && typeof parsed === "object") {
return parsed;
}
}
catch {
// Non-JSON body — fall through to empty.
}
return {};
}
/**
* GET /settings/{id} — one setting's raw stored value. Returns `undefined` for
* an unset key: ComfyUI returns an empty body or `null` for unset ids on
* different versions, and some builds 404 the per-id route, so empty / `null` /
* 404 / parse-failure are all treated uniformly as "unset (frontend default
* applies)". Stored values are passed through verbatim — never coerced, so an
* older frontend's `"true"` string surfaces as a string.
*/
export async function getSetting(id) {
requireLocalMode("settings");
const client = getClient();
const res = await client.fetchApi(`/settings/${encodeURIComponent(id)}`);
if (res.status === 404)
return undefined;
const text = await res.text();
if (text.trim() === "")
return undefined;
try {
const parsed = JSON.parse(text);
return parsed === null ? undefined : parsed;
}
catch {
return undefined;
}
}
/**
* POST /settings/{id} — persist one setting. The value is sent as-is (raw JSON
* body); it is stored verbatim and never coerced. A 404 here means the settings
* route is absent (version drift), not an unknown id — unknown ids are stored
* verbatim and ignored by the UI.
*/
export async function setSetting(id, value) {
requireLocalMode("settings");
const client = getClient();
const res = await client.fetchApi(`/settings/${encodeURIComponent(id)}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(value),
});
if (res.status === 404)
throw settingsVersionDriftError();
if (!res.ok) {
const body = await res.text().catch(() => "");
throw new ConnectionError(`ComfyUI /settings/${id} returned ${res.status} ${res.statusText}: ${body.slice(0, 500)}`);
}
}
export async function getHistory(promptId) {
if (isCloudMode())
return cloudClient.getHistory(promptId);
const client = getClient();
const path = promptId ? `/history/${promptId}` : "/history";
const res = await client.fetchApi(path);
return res.json();
}
/**
* Fetch an image from ComfyUI's /view endpoint as a base64 string.
* Works over HTTP — no local filesystem access needed.
*/
export async function fetchImage(filename, type = "output", subfolder = "") {
if (isCloudMode())
return cloudClient.fetchImage(filename, type, subfolder);
const client = getClient();
const params = new URLSearchParams({ filename, type, subfolder });
const res = await client.fetchApi(`/view?${params.toString()}`);
if (!res.ok) {
const where = subfolder ? `${type}/${subfolder}` : type;
throw new ComfyUIError(`ComfyUI /view returned ${res.status} for "${filename}" (${where}). ` +
(res.status === 404
? `No such file in the ComfyUI ${type} directory` +
(subfolder ? ` under subfolder "${subfolder}"` : "") +
`. Check the filename/subfolder (e.g. via list_output_images or get_history).`
: `The ComfyUI server rejected the request.`), res.status === 404 ? "IMAGE_NOT_FOUND" : "VIEW_ERROR", { status: res.status, filename, type, subfolder });
}
const contentType = res.headers.get("content-type") ?? "image/png";
const mimeType = contentType.split(";")[0].trim();
const arrayBuffer = await res.arrayBuffer();
const base64 = Buffer.from(arrayBuffer).toString("base64");
return { base64, mimeType };
}
/**
* Upload an image to ComfyUI's input/ directory via HTTP multipart POST.
* Works over HTTP — no local filesystem access needed.
*/
export async function uploadImageHttp(filename, data, mimeType = "image/png") {
if (isCloudMode())
return cloudClient.uploadImageHttp(filename, data, mimeType);
const client = getClient();
const formData = new FormData();
const blob = new Blob([data], { type: mimeType });
formData.append("image", blob, filename);
formData.append("type", "input");
formData.append("overwrite", "true");
const res = await client.fetchApi("/upload/image", {
method: "POST",
body: formData,
});
if (!res.ok) {
const text = await res.text().catch(() => "");
throw new Error(`ComfyUI /upload/image returned ${res.status}: ${text}`);
}
return res.json();
}
//# sourceMappingURL=client.js.map