@metabrain-labs/comfyui-mcp-server 1.0.0

package/src/types/ws.ts

@@ -0,0 +1,80 @@
+export interface ComfyStatusData {
+  status: {
+    exec_info: {
+      queue_remaining: number;
+    };
+  };
+  sid: string;
+}
+
+export interface ComfyFeatureFlagsData {
+  supports_preview_metadata: boolean;
+  max_upload_size: number;
+  extension: {
+    manager?: {
+      supports_v4: boolean;
+    };
+    [key: string]: any;
+  };
+}
+
+export interface ComfyExecutionStartData {
+  prompt_id: string;
+  timestamp: number;
+}
+
+export interface ComfyExecutionCachedData {
+  nodes: string[];
+  prompt_id: string;
+  timestamp: number;
+}
+
+export interface ComfyExecutionSuccessData {
+  prompt_id: string;
+  timestamp: number;
+}
+
+export interface ComfyProgressStateData {
+  prompt_id: string;
+  nodes: Record<string, ComfyNodeProgressState>;
+}
+
+export interface ComfyProgressData {
+  prompt_id: string;
+  value: number;
+  max: number;
+  node: string;
+}
+
+export interface ComfyExecutingData {
+  node: string | null;
+  display_node: string;
+  prompt_id: string;
+}
+
+export interface ComfyExecutedData {
+  node: string;
+  display_node: string;
+  output: ComfyNodeOutputData;
+  prompt_id: string;
+}
+
+/** 节点进度详情 */
+export interface ComfyNodeProgressState {
+  value: number; // 当前进度 (0.0 - 1.0 或具体步数)
+  max: number; // 最大进度/总步数
+  state: "running" | "finished" | "pending" | string; // 节点状态
+  node_id: string; // 当前节点 ID
+  prompt_id: string; // 关联的任务 ID
+  display_node_id: string; // UI 显示的节点 ID
+  parent_node_id: string | null;
+  real_node_id: string; // 实际执行的节点 ID
+}
+
+import { ComfyImage } from "./task";
+
+/** 节点执行结果输出 (通常包含 images, 但也可能有 tags, text 等) */
+export interface ComfyNodeOutputData {
+  images?: ComfyImage[];
+  [key: string]: any; // 允许其他类型的输出（如 text, gifs 等）
+}

package/src/utils/format.ts

@@ -0,0 +1,134 @@
+import { CollectFormatTaskResult, SourceType } from "../types/common";
+import { ComfyPromptConfig, ComfyTaskResponse } from "../types/task";
+import "dotenv/config";
+
+/**
+ * @METHOD
+ * @description 格式化工作流任务数据
+ */
+export const formatTask = (
+  data: ComfyTaskResponse,
+  sourceType: SourceType,
+  modifiedWorkflow?: Map<string, number>,
+  workflowNames?: Map<string, string>,
+): CollectFormatTaskResult => {
+  const workflowNameRegexString =
+    process.env.WORKFLOW_NAME_REGEX || "==(.+?)==";
+  const workflowParamRegexString = process.env.WORKFLOW_PARAM_REGEX || "^=>";
+
+  const workflowNameRegex = new RegExp(workflowNameRegexString);
+  const workflowParamRegex = new RegExp(workflowParamRegexString);
+
+  const result: CollectFormatTaskResult = {
+    last_updated: Date.now(),
+    workflows: [],
+  };
+
+  for (const [uuid, item] of Object.entries(data)) {
+    const promptConfig: ComfyPromptConfig = item.prompt[2];
+    const promptId: string = item.prompt[1];
+    const parameters: string[] = [];
+    let modified: number | undefined;
+    let workflowName: string | undefined;
+    let description: string | null = null;
+    let name: string | null = null;
+
+    for (const [nodeId, nodeConfig] of Object.entries(promptConfig)) {
+      const isDesc = nodeConfig._meta?.title?.match(workflowNameRegex);
+      if (isDesc) {
+        description =
+          (nodeConfig.inputs["value"] as string) || "无工作流描述内容";
+        name = isDesc[1] || "无工作流名称";
+      }
+      const isRequired = nodeConfig._meta?.title?.match(workflowParamRegex);
+      if (isRequired) {
+        parameters.push(nodeConfig.class_type + nodeConfig._meta?.title);
+      }
+    }
+
+    // 如果name为null或者description为null的时候则不纳入列表
+    if (!name || !description) {
+      continue;
+    }
+
+    const timestamp = item.status.messages.find(
+      ([type]) => type === "execution_start",
+    )?.[1].timestamp;
+
+    if (!timestamp) {
+      continue;
+    }
+
+    if (
+      sourceType === "InitialInspection" &&
+      modifiedWorkflow &&
+      workflowNames
+    ) {
+      modified = modifiedWorkflow.get(promptId);
+      workflowName = workflowNames.get(promptId);
+    }
+
+    result.workflows.push({
+      name: name,
+      id: uuid,
+      description: description,
+      parameters: parameters,
+      last_updated: timestamp,
+      inspection_status: sourceType,
+      userdata_modified: modified,
+      workflowPath: workflowName,
+    });
+  }
+
+  return result;
+};
+
+export const formatTaskFromApiJson = (
+  apiJson: Record<string, any>,
+  promptId: string,
+): CollectFormatTaskResult => {
+  const workflowNameRegexString =
+    process.env.WORKFLOW_NAME_REGEX || "==(.+?)==";
+  const workflowParamRegexString = process.env.WORKFLOW_PARAM_REGEX || "^=>";
+
+  const workflowNameRegex = new RegExp(workflowNameRegexString);
+  const workflowParamRegex = new RegExp(workflowParamRegexString);
+
+  const result: CollectFormatTaskResult = {
+    last_updated: Date.now(),
+    workflows: [],
+  };
+
+  const parameters: string[] = [];
+  let description: string | null = null;
+  let name: string | null = null;
+
+  for (const [nodeId, nodeConfig] of Object.entries(apiJson)) {
+    const isDesc = nodeConfig._meta?.title?.match(workflowNameRegex);
+    if (isDesc) {
+      description =
+        (nodeConfig.inputs["value"] as string) || "无工作流描述内容";
+      name = isDesc[1] || "无工作流名称";
+    }
+    const isRequired = workflowParamRegex.test(nodeConfig._meta?.title);
+    if (isRequired) {
+      parameters.push(nodeConfig.class_type + nodeConfig._meta?.title);
+    }
+  }
+
+  // 如果name为null或者description为null的时候则不纳入列表
+  if (!name || !description) {
+    throw new Error("Invalid workflow name or description");
+  }
+
+  result.workflows.push({
+    name: name,
+    id: promptId,
+    description: description,
+    parameters: parameters,
+    last_updated: Date.now(),
+    inspection_status: "External",
+  });
+
+  return result;
+};

package/src/utils/mcp-helpers.ts

@@ -0,0 +1,110 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { ExecutionResult } from "../types/execute";
+import { Result } from "../types/result";
+import "dotenv/config";
+
+const BASE_URL = process.env.COMFY_UI_SERVER_IP ?? "http://127.0.0.1:8188";
+
+/**
+ * @METHOD
+ * @description 包装 MCP 工具处理函数，自动处理错误
+ */
+export function withMcpErrorHandling<T extends any[], R>(
+  handler: (...args: T) => Promise<R>,
+) {
+  return async (...args: T): Promise<CallToolResult> => {
+    try {
+      const result = await handler(...args);
+
+      if (result && typeof result === "object" && "content" in result) {
+        return result as CallToolResult;
+      }
+
+      // 否则包装成 CallToolResult
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      if (error instanceof McpError) {
+        throw error;
+      }
+
+      throw new McpError(
+        ErrorCode.InternalError,
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+  };
+}
+
+/**
+ * @METHOD
+ * @description 将结构化结果转换为 MCP 响应格式
+ */
+export function ResultToMcpResponse(result: Result): CallToolResult {
+  if (result.success) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+    };
+  } else {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+      isError: true,
+    };
+  }
+}
+
+/**
+ * @METHOD
+ * @description 将文本结果转换为 MCP 响应格式
+ */
+export function ResultToMcpStringResponse(result: string): CallToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2),
+      },
+    ],
+  };
+}
+
+/**
+ * @METHOD
+ * @description 拼接生成资源路径
+ */
+export function buildComfyViewUrls(result: ExecutionResult): string[] {
+  if (!result.outputs) return [];
+
+  const urls: string[] = [];
+
+  for (const nodeOutput of Object.values(result.outputs)) {
+    for (const img of nodeOutput.images ?? []) {
+      const params = new URLSearchParams({
+        filename: img.filename,
+        type: img.type,
+        subfolder: img.subfolder ?? "",
+      });
+
+      urls.push(`${BASE_URL}/view?${params.toString()}`);
+    }
+  }
+
+  return urls;
+}

package/src/utils/special-node-handler.ts

@@ -0,0 +1,36 @@
+// 当前需要特殊处理的结点参数
+const supportedKeys = new Set<string>(["seed"]);
+
+/**
+ * @METHOD
+ * @description 是否是受控 key
+ */
+export function isSupportedKey(key: string): boolean {
+  return supportedKeys.has(key.toLowerCase());
+}
+
+/**
+ * @METHOD
+ * @description 处理 key 对应生成随机数逻辑
+ */
+export function handleKey(key: string): number | string {
+  const lowerKey = key.toLowerCase();
+
+  switch (lowerKey) {
+    case "seed":
+      return generateSeed32();
+
+    default:
+      return generateSeed32();
+  }
+}
+
+/**
+ * @METHOD
+ * @description 生成32位随机数
+ */
+export function generateSeed32(): number {
+  const array = new Uint32Array(1);
+  crypto.getRandomValues(array);
+  return array[0];
+}

package/src/utils/workflow-converter.ts

@@ -0,0 +1,140 @@
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { ObjectInfoResponse } from "../types/object-info";
+import { ComfyInputValue, ComfyPromptConfig } from "../types/task";
+import {
+  ComfyLink,
+  ComfyNode,
+  ComfyNodeMode,
+  ComfyUIWorkflow,
+} from "../types/workflow";
+import { api } from "../api/api";
+
+/**
+ * @METHOD
+ * @description 根据 ComfyUI 规则，将从原始工作流中获取的信息（ComfyUIWorkflow）格式化为执行工作流需要用到的信息（ComfyPromptConfig）
+ */
+export class WorkflowConverter {
+  private objectInfo: ObjectInfoResponse = {};
+
+  /**
+   * @METHOD
+   * @description 初始化，加载图的节点对象定义
+   */
+  async init(): Promise<void> {
+    this.objectInfo = await api.getNodeDefs();
+  }
+
+  /**
+   * @METHOD
+   * @description 格式化核心方法 —— 将 ComfyUIWorkflow 转换为 ComfyPromptConfig
+   * @param workflow ComfyUIWorkflow 数据
+   * @returns ComfyPromptConfig 对象，可直接用于 /prompt 接口
+   */
+  convert(workflow: ComfyUIWorkflow): ComfyPromptConfig {
+    const output: ComfyPromptConfig = {};
+    const workflowId = workflow?.id || "";
+
+    // 1. 创建所有节点的映射，过滤掉不需要的节点
+    const validNodes = workflow.nodes.filter((node: ComfyNode) => {
+      return (
+        !node.mode ||
+        (node.mode !== ComfyNodeMode.Bypass &&
+          node.mode !== ComfyNodeMode.Never)
+      );
+    });
+
+    // 2. 构建节点ID到节点的映射
+    const nodeMap = new Map<string, ComfyNode>();
+    validNodes.forEach((node: ComfyNode) => {
+      nodeMap.set(String(node.id), node);
+    });
+
+    // 3. 构建连接关系映射 links 结构: [link_id, origin_id, origin_slot, target_id, target_slot, link_type]
+    const linksMap = new Map<string, Array<string | number>>();
+    workflow.links.forEach((link: ComfyLink) => {
+      const linkId = link[0];
+      const originId = String(link[1]);
+      const originSlot = link[2];
+      const linkType = link[5];
+
+      const linkKey = `${linkId}:${linkType}`;
+      if (!linksMap.has(linkKey)) {
+        linksMap.set(linkKey, []);
+      }
+      linksMap.get(linkKey)!.push(originId, originSlot);
+    });
+
+    // 4. 处理每个节点
+    validNodes.forEach((node: ComfyNode) => {
+      const nodeId = node.id;
+      const inputs: Record<string, ComfyInputValue> = {};
+      const inputNames: string[] = [];
+      let noLink = 0;
+
+      const object = Object.entries(this.objectInfo).find(([key, value]) => {
+        return key === node.type;
+      });
+
+      if (!object) {
+        throw new McpError(
+          ErrorCode.InternalError,
+          "MCP_OBJECT_INFO_NOT_FOUND",
+        );
+      }
+
+      Object.entries(object[1].input.required).forEach(([inputName, input]) => {
+        inputNames.push(inputName);
+      });
+
+      if (object[1].input.optional) {
+        Object.entries(object[1].input.optional).forEach(
+          ([inputName, input]) => {
+            inputNames.push(inputName);
+          },
+        );
+      }
+
+      if (object[1].input.hidden) {
+        Object.entries(object[1].input.hidden).forEach(([inputName, input]) => {
+          inputNames.push(inputName);
+        });
+      }
+
+      inputNames.forEach((inputName: string) => {
+        for (let i = 0; i < node.inputs.length; i++) {
+          if (inputName === node.inputs[i].name) {
+            if (node.inputs[i].link !== null && !node.inputs[i].widget) {
+              inputs[inputName] =
+                linksMap.get(`${node.inputs[i].link}:${node.inputs[i].type}`) ||
+                [];
+            } else {
+              if (Array.isArray(node.widgets_values)) {
+                if (node.widgets_values[noLink] === "randomize") {
+                  noLink++;
+                }
+                inputs[inputName] = node.widgets_values[noLink++];
+              } else if (
+                typeof node.widgets_values === "object" &&
+                node.widgets_values !== null
+              ) {
+                inputs[inputName] = node.widgets_values[inputName];
+              }
+            }
+            break;
+          }
+        }
+      });
+
+      // 构建节点对象
+      output[nodeId] = {
+        inputs,
+        class_type: node.type,
+        _meta: {
+          title: node.title || node.type,
+        },
+      };
+    });
+
+    return output;
+  }
+}