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

174 lines • 8.53 kB
import { z } from "zod"; import { errorToToolResult } from "../utils/errors.js"; /** First sentence of a tool description, hard-capped so the manifest stays token-light. */ export function summarize(description, maxLen = 160) { const firstSentence = description.split(/(?<=\.)\s+/, 1)[0] ?? description; const line = firstSentence.replace(/\s+/g, " ").trim(); return line.length <= maxLen ? line : `${line.slice(0, maxLen - 1).trimEnd()}…`; } function text(s) { return { content: [{ type: "text", text: s }] }; } function errorText(s) { return { isError: true, content: [{ type: "text", text: s }] }; } function inputJsonSchema(tool) { if (!tool.schema || Object.keys(tool.schema).length === 0) return undefined; const json = z.toJSONSchema(z.object(tool.schema), { io: "input", unrepresentable: "any", }); delete json.$schema; // noise for an LLM reader return json; } /** Searchable corpus for one tool: name, description, and the parameter * names + descriptions — so a search like "checkpoint" also finds tools * whose relevance only shows in their arguments (e.g. list_local_models). */ function searchCorpus(tool) { const params = Object.entries(tool.schema ?? {}) .map(([key, schema]) => `${key} ${schema.description ?? ""}`) .join(" "); return `${tool.name} ${tool.description} ${params}`.toLowerCase(); } export function buildManifest(catalog, opts = {}) { const search = opts.search?.toLowerCase(); const lines = []; let shown = 0; for (const [category, tools] of catalog.byCategory()) { if (opts.category && category !== opts.category) continue; const matching = search ? tools.filter((t) => searchCorpus(t).includes(search)) : tools; if (matching.length === 0) continue; lines.push("", `## ${category} (${matching.length})`); for (const t of matching) { lines.push(`- ${t.name}: ${summarize(t.description)}`); shown++; } } if (shown === 0) { const cats = [...catalog.byCategory().keys()].join(", "); return `No tools matched (category=${opts.category ?? "any"}, search=${opts.search ?? "none"}). Categories: ${cats}`; } const header = `comfyui-mcp tool catalog — ${shown} of ${catalog.tools.size} tools` + (opts.category || opts.search ? " (filtered)" : "") + ". Workflow: pick a tool → describe_tool {\"name\": ...} for its parameters → call_tool {\"name\": ..., \"args\": {...}}."; const footer = (opts.category || opts.search) && shown < catalog.tools.size ? `\n\nThis is a FILTERED view (${catalog.tools.size - shown} tools hidden). If nothing here fits the task, call list_tools again with a broader search or no filter.` : ""; return header + lines.join("\n") + footer; } /** * Compact tool mode (COMFYUI_MCP_TOOL_MODE=compact / --compact): registers * exactly three meta-tools backed by the captured catalog, instead of the full * ~200-tool surface. Built for small/local models (Hermes Agent, Ollama, any * MCP client on a non-frontier LLM) where 200 JSON schemas blow the context * budget — see issue #97. */ export function registerCompactTools(server, catalog) { server.tool("list_tools", "List every comfyui-mcp capability as a token-light catalog: tool names with one-line summaries, grouped by category. Start here. Then use describe_tool to get a tool's parameters and call_tool to run it.", { category: z .string() .optional() .describe("Only list this category (as shown in the catalog headings)."), search: z .string() .optional() .describe("Case-insensitive substring filter over tool names and descriptions."), }, async (args) => text(buildManifest(catalog, args))); server.tool("describe_tool", "Get the full description and JSON Schema of one tool from the catalog. Always call this before the first call_tool of a tool you haven't used in this session.", { name: z.string().optional().describe("Exact tool name from list_tools."), tool_name: z.string().optional().describe("Alias for name."), }, async (params) => { const name = params.name ?? params.tool_name; if (!name) return errorText('Missing tool name. Call as: describe_tool {"name": "<tool>"}'); const tool = catalog.get(name); if (!tool) return errorText(unknownToolMessage(catalog, name)); const schema = inputJsonSchema(tool); const sections = [ `# ${tool.name} (category: ${tool.category})`, "", tool.description, "", schema ? `Parameters (JSON Schema):\n${JSON.stringify(schema, null, 1)}` : "Parameters: none.", "", `Run it with: call_tool {"name": "${tool.name}", "args": ${schema ? "{...}" : "{}"}}`, ]; return text(sections.join("\n")); }); server.tool("call_tool", "Execute a tool from the catalog by name. Pass its parameters in `args` (object). The result is exactly what the underlying tool returns.", { // Everything is optional and loosely typed on purpose: small models // frequently alias field names or mis-type values, and an SDK-level // -32602 gives them nothing to correct from. We validate inside the // handler instead, where errors can carry the expected schema. name: z.string().optional().describe("Exact tool name from list_tools."), tool_name: z.string().optional().describe("Alias for name."), args: z .unknown() .optional() .describe("The tool's parameters as an object matching its describe_tool schema. A JSON-encoded string is also accepted. Omit for tools without parameters."), arguments: z.unknown().optional().describe("Alias for args."), }, async (params) => { const name = params.name ?? params.tool_name; if (!name) { return errorText('Missing tool name. Call as: call_tool {"name": "<tool>", "args": {...}}'); } const tool = catalog.get(name); if (!tool) return errorText(unknownToolMessage(catalog, name)); const args = params.args ?? params.arguments; let rawArgs = {}; if (typeof args === "string") { if (args.trim()) { try { const parsed = JSON.parse(args); if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) { return errorText(`args must be a JSON object, got: ${args.slice(0, 200)}`); } rawArgs = parsed; } catch { return errorText(`args is not valid JSON: ${args.slice(0, 200)}`); } } } else if (Array.isArray(args)) { return errorText(`args must be a JSON object keyed by parameter name, not an array. Use describe_tool {"name": "${name}"} to see the schema.`); } else if (args !== undefined && args !== null) { if (typeof args !== "object") { return errorText(`args must be a JSON object, got ${typeof args}. Use describe_tool {"name": "${name}"} to see the schema.`); } rawArgs = args; } const validated = z.object(tool.schema ?? {}).safeParse(rawArgs); if (!validated.success) { const issues = validated.error.issues .map((i) => `- ${i.path.join(".") || "(root)"}: ${i.message}`) .join("\n"); const schema = inputJsonSchema(tool); return errorText(`Invalid arguments for ${name}:\n${issues}\n\nExpected schema:\n${JSON.stringify(schema ?? {}, null, 1)}`); } try { return await tool.handler(validated.data); } catch (err) { return errorToToolResult(err); } }); } function unknownToolMessage(catalog, name) { const needle = name.toLowerCase(); const close = [...catalog.tools.keys()] .filter((n) => n.includes(needle) || needle.includes(n)) .slice(0, 5); return (`Unknown tool '${name}'.` + (close.length ? ` Did you mean: ${close.join(", ")}?` : "") + " Use list_tools to see the catalog."); } //# sourceMappingURL=compact.js.map