@metabrain-labs/comfyui-mcp-server 1.0.0

package/__tests__/utils/mcp-helpers.test.ts

@@ -0,0 +1,137 @@
+/**
+ * @file mcp-helpers.test.ts
+ * @description 测试 MCP 辅助函数
+ */
+
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import type { CallToolResult, TextContent } from '@modelcontextprotocol/sdk/types.js';
+import {
+  withMcpErrorHandling,
+  ResultToMcpResponse,
+  ResultToMcpStringResponse,
+  buildComfyViewUrls,
+} from '../../src/utils/mcp-helpers.js';
+import { ok, error } from '../../src/types/result.js';
+import { ExecutionResult } from '../../src/types/execute.js';
+
+const originalEnv = process.env;
+
+describe('mcp-helpers', () => {
+  beforeEach(() => {
+    // 使用实际环境变量或默认值
+      if (!process.env.COMFY_UI_SERVER_IP) {
+        process.env.COMFY_UI_SERVER_IP = 'http://localhost:8188';
+      }
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  describe('withMcpErrorHandling()', () => {
+    it('should return result when handler succeeds with content property', async () => {
+      const mockHandler = jest.fn().mockResolvedValue({
+        content: [{ type: 'text', text: 'success' }],
+      } as CallToolResult);
+
+      const wrapped = withMcpErrorHandling(mockHandler);
+      const result = await wrapped('arg1', 'arg2');
+
+      expect(mockHandler).toHaveBeenCalledWith('arg1', 'arg2');
+      expect(result).toEqual({ content: [{ type: 'text', text: 'success' }] });
+    });
+
+    it('should wrap result when handler succeeds without content property', async () => {
+      const mockHandler = jest.fn().mockResolvedValue({ data: 'test' });
+
+      const wrapped = withMcpErrorHandling(mockHandler);
+      const result = await wrapped();
+
+      expect(result).toEqual({
+        content: [{ type: 'text', text: JSON.stringify({ data: 'test' }, null, 2) }],
+      });
+    });
+
+    it('should re-throw McpError without wrapping', async () => {
+      const mcpError = new McpError(ErrorCode.InternalError, 'MCP Error');
+      const mockHandler = jest.fn().mockRejectedValue(mcpError);
+
+      const wrapped = withMcpErrorHandling(mockHandler);
+
+      await expect(wrapped()).rejects.toThrow(McpError);
+      await expect(wrapped()).rejects.toThrow('MCP Error');
+    });
+
+    it('should wrap plain Error in McpError', async () => {
+      const plainError = new Error('Plain error message');
+      const mockHandler = jest.fn().mockRejectedValue(plainError);
+
+      const wrapped = withMcpErrorHandling(mockHandler);
+
+      await expect(wrapped()).rejects.toThrow(McpError);
+      await expect(wrapped()).rejects.toThrow('Plain error message');
+    });
+  });
+
+  describe('ResultToMcpResponse()', () => {
+    it('should convert success result to MCP response without isError', () => {
+      const result = ok('Success', { data: 'test' });
+      const response = ResultToMcpResponse(result);
+
+      expect(response.isError).toBeUndefined();
+    });
+
+    it('should convert error result to MCP response with isError flag', () => {
+      const result = error('Error occurred');
+      const response = ResultToMcpResponse(result);
+
+      expect(response.isError).toBe(true);
+    });
+  });
+
+  describe('buildComfyViewUrls()', () => {
+    it('should return empty array when outputs is undefined', () => {
+      const result: ExecutionResult = { 
+        success: true, 
+        promptId: '123', 
+        outputs: undefined, 
+        executionTime: 100 
+      };
+      const urls = buildComfyViewUrls(result);
+
+      expect(urls).toEqual([]);
+    });
+
+    it('should return empty array when outputs is empty object', () => {
+      const result: ExecutionResult = { 
+        success: true, 
+        promptId: '123', 
+        outputs: {}, 
+        executionTime: 100 
+      };
+      const urls = buildComfyViewUrls(result);
+
+      expect(urls).toEqual([]);
+    });
+
+    it('should build URLs for images with all fields', () => {
+      const result: ExecutionResult = {
+        success: true,
+        promptId: '123',
+        outputs: {
+          node1: {
+            images: [{ filename: 'image1.png', type: 'output', subfolder: 'sub1' }],
+          },
+        },
+        executionTime: 100,
+      };
+
+      const urls = buildComfyViewUrls(result);
+
+      const baseUrl = process.env.COMFY_UI_SERVER_IP || 'http://127.0.0.1:8188';
+      expect(urls).toEqual([
+        `${baseUrl}/view?filename=image1.png&type=output&subfolder=sub1`,
+      ]);
+    });
+  });
+});

package/__tests__/utils/special-node-handler.test.ts

@@ -0,0 +1,186 @@
+/**
+ * @file special-node-handler.test.ts
+ * @description 测试特殊节点处理函数
+ * 
+ * 【分支覆盖分析】
+ * 1. isSupportedKey() 函数:
+ *    - 正常路径: key 在 supportedKeys 中 (如 "seed")
+ *    - 边界: key 不在 supportedKeys 中
+ *    - 边界: 大小写不敏感匹配 ("SEED", "Seed", "SeEd")
+ * 
+ * 2. handleKey() 函数:
+ *    - 分支: key === "seed" (小写)
+ *    - 分支: key !== "seed" (走 default 分支)
+ *    - 边界: 大小写混合 ("Seed", "SEED")
+ * 
+ * 3. generateSeed32() 函数:
+ *    - 正常路径: 返回 32 位随机数
+ *    - 验证: 返回值在有效范围内 (0 到 2^32-1)
+ * 
+ * 【Mock 策略】
+ * - crypto.getRandomValues: Mock 为返回固定值以确保可预测性
+ */
+
+import {
+  isSupportedKey,
+  handleKey,
+  generateSeed32,
+} from '../../src/utils/special-node-handler';
+
+describe('special-node-handler', () => {
+  describe('isSupportedKey()', () => {
+    it('should return true for "seed" (lowercase)', () => {
+      expect(isSupportedKey('seed')).toBe(true);
+    });
+
+    it('should return true for "SEED" (uppercase)', () => {
+      expect(isSupportedKey('SEED')).toBe(true);
+    });
+
+    it('should return true for "Seed" (mixed case)', () => {
+      expect(isSupportedKey('Seed')).toBe(true);
+    });
+
+    it('should return true for "SeEd" (random case)', () => {
+      expect(isSupportedKey('SeEd')).toBe(true);
+    });
+
+    it('should return false for unsupported key "random"', () => {
+      expect(isSupportedKey('random')).toBe(false);
+    });
+
+    it('should return false for empty string', () => {
+      expect(isSupportedKey('')).toBe(false);
+    });
+
+    it('should return false for similar but different key "seeds"', () => {
+      expect(isSupportedKey('seeds')).toBe(false);
+    });
+
+    it('should return false for key containing "seed" substring', () => {
+      expect(isSupportedKey('my_seed')).toBe(false);
+      expect(isSupportedKey('seed_value')).toBe(false);
+    });
+  });
+
+  describe('handleKey()', () => {
+    // 保存原始 crypto 对象
+    const originalCrypto = global.crypto;
+
+    beforeEach(() => {
+      // Mock crypto.getRandomValues
+      global.crypto = {
+        getRandomValues: jest.fn((array: Uint32Array) => {
+          array[0] = 12345;
+          return array;
+        }),
+      } as unknown as Crypto;
+    });
+
+    afterEach(() => {
+      global.crypto = originalCrypto;
+    });
+
+    it('should handle "seed" key and return 32-bit random number', () => {
+      const result = handleKey('seed');
+      
+      expect(global.crypto.getRandomValues).toHaveBeenCalledWith(expect.any(Uint32Array));
+      expect(result).toBe(12345);
+    });
+
+    it('should handle "SEED" key (uppercase) and return random number', () => {
+      const result = handleKey('SEED');
+      
+      expect(global.crypto.getRandomValues).toHaveBeenCalledWith(expect.any(Uint32Array));
+      expect(result).toBe(12345);
+    });
+
+    it('should handle "Seed" key (mixed case) and return random number', () => {
+      const result = handleKey('Seed');
+      
+      expect(global.crypto.getRandomValues).toHaveBeenCalledWith(expect.any(Uint32Array));
+      expect(result).toBe(12345);
+    });
+
+    it('should handle unsupported key and return random number (default case)', () => {
+      const result = handleKey('unsupported');
+      
+      expect(global.crypto.getRandomValues).toHaveBeenCalledWith(expect.any(Uint32Array));
+      expect(result).toBe(12345);
+    });
+
+    it('should handle empty string key and return random number (default case)', () => {
+      const result = handleKey('');
+      
+      expect(global.crypto.getRandomValues).toHaveBeenCalledWith(expect.any(Uint32Array));
+      expect(result).toBe(12345);
+    });
+  });
+
+  describe('generateSeed32()', () => {
+    const originalCrypto = global.crypto;
+
+    beforeEach(() => {
+      global.crypto = {
+        getRandomValues: jest.fn((array: Uint32Array) => {
+          array[0] = 987654321;
+          return array;
+        }),
+      } as unknown as Crypto;
+    });
+
+    afterEach(() => {
+      global.crypto = originalCrypto;
+    });
+
+    it('should return a 32-bit random number', () => {
+      const result = generateSeed32();
+
+      expect(global.crypto.getRandomValues).toHaveBeenCalledWith(expect.any(Uint32Array));
+      expect(typeof result).toBe('number');
+      expect(result).toBe(987654321);
+    });
+
+    it('should return value within 32-bit unsigned integer range', () => {
+      global.crypto = {
+        getRandomValues: jest.fn((array: Uint32Array) => {
+          array[0] = 4294967295; // Max 32-bit unsigned int
+          return array;
+        }),
+      } as unknown as Crypto;
+
+      const result = generateSeed32();
+      expect(result).toBe(4294967295);
+    });
+
+    it('should return 0 when crypto returns 0', () => {
+      global.crypto = {
+        getRandomValues: jest.fn((array: Uint32Array) => {
+          array[0] = 0;
+          return array;
+        }),
+      } as unknown as Crypto;
+
+      const result = generateSeed32();
+      expect(result).toBe(0);
+    });
+
+    it('should modify the provided array in place', () => {
+      const mockArray = new Uint32Array(1);
+      
+      global.crypto = {
+        getRandomValues: jest.fn((array: Uint32Array) => {
+          array[0] = 55555;
+          return array;
+        }),
+      } as unknown as Crypto;
+
+      generateSeed32();
+      
+      expect(global.crypto.getRandomValues).toHaveBeenCalled();
+      const calledArray = (global.crypto.getRandomValues as jest.Mock).mock.calls[0][0] as Uint32Array;
+      expect(calledArray).toBeInstanceOf(Uint32Array);
+      expect(calledArray.length).toBe(1);
+    });
+  });
+});

package/comfyui-mcp-server-skill/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: comfyui-mcp-server
+
+description: Enables AI agents to discover, inspect, and execute ComfyUI workflows for image and video generation through a structured MCP interface. Supports the full task lifecycle—from context loading and workflow discovery, to parameter mounting and task submission, and finally result retrieval and generated asset management.
+
+tags: ComfyUI, Image Generation, Video Generation, MCP, Workflow Automation
+---
+
+## Use Cases
+
+Activate this skill when users request generate image, video, or multimedia generation. Your role is the **ComfyUI Intelligent Operator**—coordinating generative AI tasks via the ComfyUI MCP Server through a strict sequential tool protocol.
+
+## Usage Method
+
+### Mandatory Initialization
+
+Before executing any workflow task:
+
+1. Read `rules/**.md`
+2. Follow the tool calling sequence described there.
+3. Do not skip this step.
+
+Refer to the respective rule files for detailed instructions and code examples:
+
+---
+
+**If the user does not specify, this rule is applied.**
+
+- [rules/catalog.md](rules/catalog.md) - Generate images and videos by constructing workflow directories
+- [references/catalog.md](references/catalog.md) - Reference examples for generating images and videos via the build workflow directory
+
+---
+
+- [rules/api-json.md](rules/api-json.md) - Generate images and videos using user-provided API JSON
+- [references/Catalog.md](references/api-json.md) - Reference examples for generating images and videos using user-provided API JSON
+
+---
+
+## Important Notes
+
+1. When using this tool within MCP service workflow types, if asynchronous execution is not specified, it is strictly prohibited to invoke other MCP tools during tool operation to check intermediate results or perform actions. Wait for the tool to complete execution.
+
+2. Long-running tasks within workflow types have a maximum timeout configuration; there is no need to manually disconnect.

package/comfyui-mcp-server-skill/references/api-json.md

@@ -0,0 +1,323 @@
+# ComfyUI MCP Server – Agent Reference (Custom Workflow)
+
+## Example User Request
+
+User instruction:
+
+> Use the provided API JSON workflow to generate an image of a **cat and a dog**.
+
+Requirements:
+
+- The **cat and dog are lying down**
+- The **cat is grooming (licking) the dog**
+- The background must contain a **grassy meadow**
+- The weather must be **sunny**
+- **No humans** should appear in the image
+
+---
+
+# Execution Flow
+
+The Agent must execute the following tool calls **in order**:
+
+```
+1. get_core_manual
+2. save_custom_workflow
+3. mount_workflow
+4. queue_prompt
+```
+
+Optional:
+
+```
+5. save_task_assets
+```
+
+---
+
+# Step 1 — Retrieve Core Manual
+
+### Tool
+
+```
+comfy-ui-advanced/get_core_manual
+```
+
+### Purpose
+
+Retrieve the **ComfyUI MCP core manual** when the Host does not support Skills or when no Skill matches the request.
+
+### Request
+
+```json
+{}
+```
+
+### Example Response
+
+```json
+{
+  "success": true,
+  "message": "Core manual loaded. Please strictly follow its protocols and parameter strategies for subsequent operations.",
+  "detail": {
+    "data": "...",
+    "code": 200,
+    "timestamp": 1773194304101
+  }
+}
+```
+
+---
+
+# Step 2 — Save Custom Workflow
+
+### Tool
+
+```
+comfy-ui-advanced/save_custom_workflow
+```
+
+### Purpose
+
+Convert the provided **ComfyUI API JSON** into a workflow file and validate its feasibility.
+
+If validation succeeds:
+
+- The workflow is saved in the **workflow directory**
+- A **promptId** is returned
+
+### Request
+
+```json
+{
+  "filename": "cat_dog_workflow.json",
+  "apiJson": { ... }
+}
+```
+
+(The `apiJson` is the ComfyUI workflow JSON provided by the user.)
+
+### Example Response
+
+```json
+{
+  "success": true,
+  "message": "Custom workflow saved",
+  "detail": {
+    "data": {
+      "filePath": "E:\\comfyui-mcp\\workflow\\cat_dog_workflow.json",
+      "promptId": "a068f812-db05-4255-b755-596799e3dc22"
+    }
+  }
+}
+```
+
+### Important Output
+
+The Agent must store:
+
+```
+promptId
+```
+
+Example:
+
+```
+a068f812-db05-4255-b755-596799e3dc22
+```
+
+This value will be used in the next step.
+
+---
+
+# Step 3 — Mount Workflow as a Dynamic Tool
+
+### Tool
+
+```
+comfy-ui-advanced/mount_workflow
+```
+
+### Purpose
+
+Mount the saved workflow as a **dynamic executable tool**.
+
+### Request
+
+```json
+{
+  "promptId": "a068f812-db05-4255-b755-596799e3dc22",
+  "toolName": "cat_dog_workflow"
+}
+```
+
+### Response (Key Data)
+
+The response returns the **configurable parameters**.
+
+Example:
+
+```json
+{
+  "name": "cat_dog_workflow",
+  "configurableParams": [
+    {
+      "key": "3_text",
+      "description": "Positive prompt"
+    },
+    {
+      "key": "4_text",
+      "description": "Negative prompt"
+    },
+    {
+      "key": "12_value",
+      "description": "Random seed"
+    }
+  ]
+}
+```
+
+### Configurable Parameters
+
+| Parameter  | Description     |
+| ---------- | --------------- |
+| `3_text`   | Positive prompt |
+| `4_text`   | Negative prompt |
+| `12_value` | Random seed     |
+
+### Agent Constraints
+
+Allowed:
+
+```
+Modify parameter values
+```
+
+Not allowed:
+
+```
+Modify workflow structure
+Add or remove nodes
+```
+
+---
+
+# Step 4 — Execute Workflow
+
+### Tool
+
+```
+comfy-ui-advanced/queue_prompt
+```
+
+### Purpose
+
+Execute the mounted workflow with customized parameters.
+
+### Request
+
+```json
+{
+  "workflowName": "cat_dog_workflow",
+  "isAsync": false,
+  "params": {
+    "3_text": "A cat and a dog lying down on a grassy meadow, the cat is grooming the dog, sunny weather, blue sky, no people, realistic style, high quality, detailed",
+    "4_text": "people, human, buildings, urban, rainy, cloudy, low quality, blurry, distorted",
+    "12_value": 42
+  }
+}
+```
+
+### Prompt Strategy
+
+Positive prompt should include:
+
+```
+cat and dog interaction
+lying posture
+grooming behavior
+grassy meadow background
+sunny weather
+realistic style
+```
+
+Negative prompt should exclude:
+
+```
+humans
+urban environments
+bad quality
+visual artifacts
+```
+
+---
+
+# Execution Result
+
+Example response:
+
+```json
+{
+  "success": true,
+  "detail": {
+    "data": {
+      "promptId": "bd47c07f-6dc6-4b7a-8ed1-38535314de79",
+      "img": [
+        "http://192.168.0.171:8188/view?filename=ComfyUI_temp_bldgb_00003_.png"
+      ]
+    }
+  }
+}
+```
+
+### Important Output
+
+```
+Generated image URL
+promptId
+```
+
+---
+
+# Optional Step — Save Generated Assets
+
+### Tool
+
+```
+comfy-ui-advanced/save_task_assets
+```
+
+### Purpose
+
+Save generated images to the local **assets directory**.
+
+### Request
+
+```json
+{
+  "promptId": "bd47c07f-6dc6-4b7a-8ed1-38535314de79"
+}
+```
+
+---
+
+# Agent Execution Summary
+
+Complete workflow:
+
+```
+1 Retrieve MCP manual
+get_core_manual
+
+2 Save user-provided workflow
+save_custom_workflow
+
+3 Mount workflow as dynamic tool
+mount_workflow
+
+4 Execute workflow
+queue_prompt
+
+5 (Optional) Save generated assets
+save_task_assets
+```