@fre4x/comfyui 1.0.57 → 1.0.58

package/README.md

@@ -11,6 +11,12 @@ An MCP server to interact with ComfyUI remotely. Probe server state, inspect nod
 - `comfyui_get_queue`: Check current server queue.
 - `comfyui_get_view_url`: Get a direct URL for a generated file.
 
+**Do not assume `structuredContent` is what the model actually sees.** Many MCP clients
+surface `content.text` to the model first and treat `structuredContent` as secondary
+machine-readable metadata. Every actionable detail that an agent needs for its next step
+must therefore appear in `content.text` as well: node options, filenames, URLs, prompt
+IDs, and recovery hints.
+
 ## Setup
 
 ### Environment Variables

package/dist/index.js

@@ -30585,6 +30585,7 @@ var zNamespace = zod_exports;
 var z3 = zNamespace.z ?? zNamespace.default ?? zNamespace;
 var COMFYUI_SERVER_URL = process.env.COMFYUI_SERVER_URL || "http://localhost:8188";
 var PACKAGE_VERSION = getPackageVersion(import.meta.url);
+var BYTES_PER_GIB = 1024 ** 3;
 var PaginationMetadataSchema = z3.object({
   total_count: z3.number(),
   limit: z3.number(),
@@ -30716,6 +30717,161 @@ function normalizeSystemInfo(source) {
     })
   };
 }
+function formatGiB(bytes) {
+  return `${(bytes / BYTES_PER_GIB).toFixed(1)} GiB`;
+}
+function getEnumLikeOptions(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    return [];
+  }
+  const firstEntry = value[0];
+  if (!Array.isArray(firstEntry)) {
+    return [];
+  }
+  return firstEntry.filter(
+    (entry) => typeof entry === "string" || typeof entry === "number" || typeof entry === "boolean"
+  );
+}
+function summarizeOptionLines(inputSection) {
+  if (!inputSection) {
+    return [];
+  }
+  return Object.entries(inputSection).flatMap(([inputName, definition]) => {
+    const options = getEnumLikeOptions(definition);
+    if (options.length === 0) {
+      return [];
+    }
+    const preview = options.slice(0, 5).map(String).join(", ");
+    const suffix = options.length > 5 ? `, ... (${options.length} total)` : "";
+    return [`${inputName}: ${preview}${suffix}`];
+  });
+}
+function summarizeSystemInfoText(structuredContent) {
+  const deviceSummary = structuredContent.devices.length === 0 ? "_No devices reported._" : structuredContent.devices.map(
+    (device) => `- [${device.index}] ${device.name} (${device.type}, ${formatGiB(device.vram_free)} free / ${formatGiB(device.vram_total)} total VRAM)`
+  ).join("\n");
+  return [
+    `ComfyUI server is running on ${structuredContent.system.os} with ${structuredContent.devices.length} device(s).`,
+    formatFields([
+      ["Python", structuredContent.system.python_version],
+      [
+        "Embedded Python",
+        structuredContent.system.embedded_python ? "yes" : "no"
+      ]
+    ]),
+    `**Devices:**
+${deviceSummary}`
+  ].join("\n");
+}
+function summarizeNodeDefinitionText(nodeClass, nodeDefinition) {
+  if (!isRecord(nodeDefinition)) {
+    return `Schema retrieved for node: ${nodeClass}`;
+  }
+  const inputRecord = isRecord(nodeDefinition.input) ? nodeDefinition.input : void 0;
+  const requiredInputs = isRecord(inputRecord?.required) ? inputRecord.required : void 0;
+  const optionalInputs = isRecord(inputRecord?.optional) ? inputRecord.optional : void 0;
+  const outputNames = Array.isArray(nodeDefinition.output) ? nodeDefinition.output.filter(
+    (output) => typeof output === "string"
+  ) : [];
+  const optionLines = [
+    ...summarizeOptionLines(requiredInputs),
+    ...summarizeOptionLines(optionalInputs)
+  ];
+  return [
+    `Schema retrieved for node: ${nodeClass}`,
+    formatFields([
+      [
+        "Display Name",
+        typeof nodeDefinition.display_name === "string" ? nodeDefinition.display_name : typeof nodeDefinition.name === "string" ? nodeDefinition.name : nodeClass
+      ],
+      [
+        "Category",
+        typeof nodeDefinition.category === "string" ? nodeDefinition.category : null
+      ],
+      [
+        "Required Inputs",
+        requiredInputs ? Object.keys(requiredInputs).join(", ") || "none" : "none"
+      ],
+      [
+        "Optional Inputs",
+        optionalInputs ? Object.keys(optionalInputs).join(", ") || null : null
+      ],
+      ["Outputs", outputNames.join(", ") || null]
+    ]),
+    optionLines.length > 0 ? `**Enumerated options:**
+${optionLines.map((line) => `- ${line}`).join("\n")}` : ""
+  ].filter(Boolean).join("\n");
+}
+function summarizeHistoryEntryText(promptId, entry) {
+  if (!isRecord(entry)) {
+    return `History retrieved for job: ${promptId}`;
+  }
+  const statusRecord = isRecord(entry.status) ? entry.status : void 0;
+  const outputsRecord = isRecord(entry.outputs) ? entry.outputs : void 0;
+  const imageRefs = [];
+  if (outputsRecord) {
+    for (const output of Object.values(outputsRecord)) {
+      if (!isRecord(output) || !Array.isArray(output.images)) {
+        continue;
+      }
+      for (const image of output.images) {
+        if (!isRecord(image) || typeof image.filename !== "string") {
+          continue;
+        }
+        const subfolder = typeof image.subfolder === "string" && image.subfolder ? `${image.subfolder}/` : "";
+        imageRefs.push(`${subfolder}${image.filename}`);
+      }
+    }
+  }
+  return [
+    `History retrieved for job: ${promptId}`,
+    formatFields([
+      [
+        "Status",
+        typeof statusRecord?.status_str === "string" ? statusRecord.status_str : "unknown"
+      ],
+      [
+        "Completed",
+        statusRecord?.completed === true ? "yes" : statusRecord?.completed === false ? "no" : "unknown"
+      ],
+      [
+        "Images",
+        imageRefs.length > 0 ? imageRefs.slice(0, 5).join(", ") : "none reported"
+      ]
+    ])
+  ].join("\n");
+}
+function summarizeWorkflowResponseText(result) {
+  const hasErrors = Object.keys(result.node_errors).length > 0;
+  return [
+    formatFields([
+      [
+        "Status",
+        hasErrors ? "Submitted with node errors" : "Successfully queued"
+      ],
+      ["Prompt ID", result.prompt_id],
+      ["Queue Number", result.number]
+    ]),
+    hasErrors ? "Fix the reported node_errors before retrying this workflow." : `Next step: call comfyui_get_history with prompt_id="${result.prompt_id}" to monitor outputs.`
+  ].join("\n");
+}
+function createAgentFacingResult(text, structuredContent) {
+  const normalizedText = text.trim();
+  if (normalizedText.length === 0) {
+    throw new Error(
+      "Tool response text must be non-empty. Do not rely on structuredContent alone because many MCP clients expose content.text to the model first."
+    );
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: normalizedText
+      }
+    ],
+    structuredContent
+  };
+}
 async function fetchComfyJson(apiPath, options) {
   const url2 = new URL(apiPath, COMFYUI_SERVER_URL).toString();
   let response;
@@ -30775,15 +30931,10 @@ async function handleGetSystemInfo() {
   try {
     const rawStats = IS_MOCK ? MOCK_FIXTURES.system_stats : await fetchComfyJson("/system_stats");
     const structuredContent = normalizeSystemInfo(rawStats);
-    return {
-      content: [
-        {
-          type: "text",
-          text: `ComfyUI server is running on ${structuredContent.system.os} with ${structuredContent.devices.length} device(s).`
-        }
-      ],
+    return createAgentFacingResult(
+      summarizeSystemInfoText(structuredContent),
       structuredContent
-    };
+    );
   } catch (error48) {
     return handleComfyError(error48);
   }
@@ -30798,17 +30949,12 @@ async function handleListObjectInfo(args) {
         return createNotFoundError(`Node class ${args.node_class}`);
       }
       const nodeDefinition = unwrapNamedNode(args.node_class, rawInfo);
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Schema retrieved for node: ${args.node_class}`
-          }
-        ],
-        structuredContent: {
+      return createAgentFacingResult(
+        summarizeNodeDefinitionText(args.node_class, nodeDefinition),
+        {
           nodes: { [args.node_class]: nodeDefinition }
         }
-      };
+      );
     }
     const nodes = ensureRecord(rawInfo, "object_info");
     const entries = Object.entries(nodes);
@@ -30822,15 +30968,17 @@ async function handleListObjectInfo(args) {
         has_more: paginated.hasMore
       }
     };
-    return {
-      content: [
-        {
-          type: "text",
-          text: `Retrieved ${paginated.items.length} of ${paginated.total} node definitions.${paginated.hasMore ? " Use offset for more." : ""}`
-        }
-      ],
+    return createAgentFacingResult(
+      [
+        `Retrieved ${paginated.items.length} of ${paginated.total} node definitions.`,
+        paginated.items.length > 0 ? `Node classes: ${paginated.items.slice(0, 10).map(([nodeClass]) => nodeClass).join(
+          ", "
+        )}${paginated.items.length > 10 ? ", ..." : ""}` : "",
+        paginated.hasMore ? `Use offset=${paginated.offset + paginated.limit} for more.` : "",
+        "If you need a usable workflow field list, call comfyui_list_object_info again with node_class set to the exact node name."
+      ].filter(Boolean).join("\n"),
       structuredContent
-    };
+    );
   } catch (error48) {
     return handleComfyError(error48);
   }
@@ -30852,23 +31000,10 @@ async function handleExecuteWorkflow(args) {
       number: result.number,
       node_errors: result.node_errors
     };
-    const hasErrors = Object.keys(result.node_errors).length > 0;
-    return {
-      content: [
-        {
-          type: "text",
-          text: formatFields([
-            [
-              "Status",
-              hasErrors ? "Submitted with node errors" : "Successfully queued"
-            ],
-            ["Prompt ID", result.prompt_id],
-            ["Queue Number", result.number]
-          ])
-        }
-      ],
+    return createAgentFacingResult(
+      summarizeWorkflowResponseText(result),
       structuredContent
-    };
+    );
   } catch (error48) {
     return handleComfyError(error48);
   }
@@ -30882,17 +31017,12 @@ async function handleGetHistory(args) {
       if (rawHistory === void 0) {
         return createNotFoundError(`Prompt history ${args.prompt_id}`);
       }
-      return {
-        content: [
-          {
-            type: "text",
-            text: `History retrieved for job: ${args.prompt_id}`
-          }
-        ],
-        structuredContent: {
+      return createAgentFacingResult(
+        summarizeHistoryEntryText(args.prompt_id, rawHistory),
+        {
           history: { [args.prompt_id]: rawHistory }
         }
-      };
+      );
     }
     const history = ensureRecord(rawHistory, "history");
     const entries = Object.entries(history);
@@ -30906,15 +31036,16 @@ async function handleGetHistory(args) {
         has_more: paginated.hasMore
       }
     };
-    return {
-      content: [
-        {
-          type: "text",
-          text: `Retrieved ${paginated.items.length} of ${paginated.total} job(s) from history.${paginated.hasMore ? " Use offset for more." : ""}`
-        }
-      ],
+    return createAgentFacingResult(
+      [
+        `Retrieved ${paginated.items.length} of ${paginated.total} job(s) from history.`,
+        paginated.items.length > 0 ? `Prompt IDs: ${paginated.items.slice(0, 10).map(([promptId]) => promptId).join(
+          ", "
+        )}${paginated.items.length > 10 ? ", ..." : ""}` : "",
+        paginated.hasMore ? `Use offset=${paginated.offset + paginated.limit} for more.` : ""
+      ].filter(Boolean).join("\n"),
       structuredContent
-    };
+    );
   } catch (error48) {
     return handleComfyError(error48);
   }
@@ -30927,15 +31058,10 @@ async function handleGetQueue() {
       queue_running: Array.isArray(queueRecord.queue_running) ? queueRecord.queue_running : [],
       queue_pending: Array.isArray(queueRecord.queue_pending) ? queueRecord.queue_pending : []
     };
-    return {
-      content: [
-        {
-          type: "text",
-          text: `Queue status: ${structuredContent.queue_running.length} running, ${structuredContent.queue_pending.length} pending.`
-        }
-      ],
+    return createAgentFacingResult(
+      `Queue status: ${structuredContent.queue_running.length} running, ${structuredContent.queue_pending.length} pending.`,
       structuredContent
-    };
+    );
   } catch (error48) {
     return handleComfyError(error48);
   }
@@ -30952,15 +31078,11 @@ async function handleGetViewUrl(args) {
     `/view?${params.toString()}`,
     COMFYUI_SERVER_URL
   ).toString();
-  return {
-    content: [
-      {
-        type: "text",
-        text: `View URL generated for ${args.filename}`
-      }
-    ],
-    structuredContent: { url: url2 }
-  };
+  return createAgentFacingResult(
+    `View URL generated for ${args.filename}
+${url2}`,
+    { url: url2 }
+  );
 }
 function createServer() {
   const server = new McpServer({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fre4x/comfyui",
-  "version": "1.0.57",
+  "version": "1.0.58",
   "description": "MCP server for ComfyUI. Execute workflows and probe server state remotely.",
   "type": "module",
   "main": "dist/index.js",