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),
142 lines • 8.72 kB
JavaScript
// Model Explorer metadata-curation tools, on the SHARED comfyui MCP surface so
// EVERY backend (Claude, Kimi, Codex, Gemini, Grok, Ollama…) can call them — not
// just the panel/Claude in-process path. They HTTP-proxy the ComfyUI
// `comfyui-model-explorer` node's routes (the node is the single source of truth
// for embedded safetensors metadata). "read" + "propose" only — the human Confirms
// the write in the diff-review window, so there is intentionally no write tool here.
import { z } from "zod";
import { errorToToolResult } from "../utils/errors.js";
function comfyBase() {
return (process.env.COMFYUI_URL ||
(process.env.COMFYUI_PORT ? `http://127.0.0.1:${process.env.COMFYUI_PORT}` : "http://127.0.0.1:8188")).replace(/\/$/, "");
}
const okText = (value) => ({
content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }],
});
// A 404 on a /model_explorer/* route has two possible causes: (1) the optional
// `comfyui-model-explorer` custom node isn't installed, so the route itself does
// not exist (the common case — the raw 404 that motivated #363); or (2) the node
// IS installed but reports the requested model file as not found. HTTP status
// alone can't distinguish them, so surface an actionable message covering BOTH
// rather than leaking the bare 404 or over-claiming that the node is absent. A
// `detail` string from the upstream body (when present) is appended as a hint.
// Other statuses (500, 503, …) are real upstream errors and pass through.
export function explorerHttpError(route, status, body) {
if (status === 404) {
const hint = body && body.trim() ? ` Upstream detail: ${body.trim().slice(0, 200)}.` : "";
return new Error(`GET /model_explorer/${route} returned HTTP 404. Most likely the optional ` +
`'comfyui-model-explorer' custom node is not installed on the connected ComfyUI ` +
`(install it via ComfyUI-Manager or install_custom_node, then restart). If that node ` +
`IS installed, the 404 instead means it could not find the requested model file — ` +
`check that 'category' (model folder) and 'name' (filename incl. .safetensors) are ` +
`correct and the file exists.${hint}`);
}
return new Error(`model_explorer ${route} HTTP ${status}`);
}
async function readBodyText(res) {
try {
return res.text ? await res.text() : undefined;
}
catch {
return undefined;
}
}
export function registerModelExplorerTools(server) {
server.tool("model_metadata_read", "Read a model file's CURRENT embedded metadata + evidence, for curating it (Model Explorer). " +
"Returns classify (asset_type/base/precision/rank), the current model_card and prompt_director namespaces, " +
"read-only modelspec, top training tags (ss_tag_frequency), the Civitai description, and example prompts. " +
"Call this FIRST when the user wants to improve/curate a model's embedded .safetensors metadata, so you " +
"propose from real data. NOTE: this is the embedded-in-the-tensor metadata (model_card/prompt_director/" +
"modelspec/ss_*) — NOT the separate lora_catalog. `category` = ComfyUI model folder ('loras','checkpoints'," +
"'vae',…); `name` = filename incl. .safetensors.", {
category: z.string().describe("ComfyUI model folder, e.g. 'loras'"),
name: z.string().describe("model filename incl. .safetensors"),
}, async (args) => {
try {
const COMFY = comfyBase();
const q = `category=${encodeURIComponent(args.category)}&name=${encodeURIComponent(args.name)}`;
const dr = await fetch(`${COMFY}/model_explorer/detail?${q}`);
if (!dr.ok)
return errorToToolResult(explorerHttpError("detail", dr.status, await readBodyText(dr)));
const detail = (await dr.json());
let tags = null;
try {
const tr = await fetch(`${COMFY}/model_explorer/suggest_triggers?${q}`);
if (tr.ok)
tags = (await tr.json()).candidates;
}
catch { /* optional */ }
return okText({
classify: detail.classify,
model_card: detail.namespaces?.model_card ?? {},
prompt_director: detail.namespaces?.prompt_director ?? {},
modelspec: detail.namespaces?.modelspec ?? {},
description: detail.namespaces?.model_card?.description ?? null,
example_prompts: detail.namespaces?.prompt_director?.example_prompts ?? [],
tag_frequency_top: tags,
compat_suggestions: detail.compat_suggestions ?? [],
});
}
catch (err) {
return errorToToolResult(err);
}
});
server.tool("model_metadata_propose", "PROPOSE cleaned embedded metadata into the user's diff-review window (Model Explorer). This does NOT write " +
"the file — the user sees your proposed fields vs current, edits/discusses, and their Confirm does the write. " +
"Call whenever you have a proposal OR the user asks you to revise one; each call REPLACES the live proposal, " +
"so send the FULL field set you're proposing. Include only fields you're confident about. Keys: display_name, " +
"description_clean, semantic_intent, prompt_guidance, preservation_guidance, trigger_tokens[] (EXACT tokens — " +
"never invent), activation_phrases[], negative_tokens[], tags[], compatible_families[], default_strength_model, " +
"default_strength_clip, strength_min, strength_max. NEVER write metadata directly.", {
category: z.string(),
name: z.string(),
fields: z.record(z.string(), z.any()).describe("Proposed field map (see description)."),
note: z.string().optional().describe("Optional one-line note about this revision."),
}, async (args) => {
try {
const COMFY = comfyBase();
const r = await fetch(`${COMFY}/model_explorer/proposal`, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ category: args.category, name: args.name, fields: args.fields, note: args.note }),
});
const d = (await r.json());
if (!r.ok || !d.ok)
return errorToToolResult(new Error(d.error || `proposal HTTP ${r.status}`));
return okText({
pushed: true,
seq: d.seq,
note: "Proposal is now in the user's review window. Wait for their feedback; revise by calling this again with the full field set.",
});
}
catch (err) {
return errorToToolResult(err);
}
});
server.tool("model_metadata_fetch_civitai", "READ-ONLY: pull this model's data from Civitai (civitai.com) — the rich description, " +
"trainedWords, example prompts (with the prompt text used in the sample images), tags, nsfw flag, " +
"and source_url — WITHOUT writing anything. Call this when the embedded metadata is thin (empty " +
"model_card/prompt_director, no ss_tag_frequency) or to flesh out details before proposing. Treat the " +
"result as RAW input: distill the (often marketing-heavy) description, and MINE THE EXAMPLE PROMPTS for " +
"the real trigger — the trigger is frequently ONLY in the sample prompts even when trainedWords is EMPTY " +
"(e.g. every prompt starting with 'photo in the style of X' means X is the trigger). Adult models (civitai.red) " +
"resolve through this same API. Then clean it up and call model_metadata_propose.", {
category: z.string().describe("ComfyUI model folder, e.g. 'loras'"),
name: z.string().describe("model filename incl. .safetensors"),
version_id: z.number().int().optional().describe("Force a specific Civitai modelVersionId if hash lookup misses."),
}, async (args) => {
try {
const COMFY = comfyBase();
const q = `category=${encodeURIComponent(args.category)}&name=${encodeURIComponent(args.name)}` +
(args.version_id ? `&version_id=${args.version_id}` : "");
const r = await fetch(`${COMFY}/model_explorer/civitai?${q}`);
if (!r.ok)
return errorToToolResult(explorerHttpError("civitai", r.status, await readBodyText(r)));
return okText(await r.json());
}
catch (err) {
return errorToToolResult(err);
}
});
}
//# sourceMappingURL=model-explorer.js.map