ComfyUI MCP Server

Instructions

Implementation Reference

• src/tools/status.ts:117-200 (handler)

  The core handler function for 'comfy_wait_for_completion'. Polls ComfyUI's history for the specified prompt_id until completion or timeout, then extracts and returns image output paths.

  export async function handleWaitForCompletion(input: WaitForCompletionInput) {
    try {
      const client = getComfyUIClient();
      const config = getConfig();
      const pollInterval = input.poll_interval || config.comfyui.poll_interval;
      const timeout = input.timeout || config.comfyui.timeout;
      const startTime = Date.now();
  
      // Poll for completion
      while (true) {
        const elapsed = (Date.now() - startTime) / 1000;
        if (elapsed > timeout) {
          return {
            content: [{
              type: "text",
              text: JSON.stringify({
                prompt_id: input.prompt_id,
                status: "timeout",
                execution_time: elapsed,
                message: `Timeout after ${timeout} seconds`
              }, null, 2)
            }]
          };
        }
  
        // Check history
        const history = await client.getHistory(input.prompt_id);
  
        if (history[input.prompt_id]) {
          // Completed
          const historyItem = history[input.prompt_id];
          const outputs: any[] = [];
  
          if (historyItem.outputs) {
            for (const [nodeId, output] of Object.entries(historyItem.outputs)) {
              if (output.images) {
                const imagePaths = output.images.map((img: any) =>
                  client.getOutputPath(img.filename)
                );
                outputs.push({
                  images: imagePaths,
                  node_id: nodeId,
                  filename: output.images.map((img: any) => img.filename).join(', ')
                });
              }
            }
          }
  
          return {
            content: [{
              type: "text",
              text: JSON.stringify({
                prompt_id: input.prompt_id,
                status: "completed",
                outputs,
                execution_time: elapsed
              }, null, 2)
            }]
          };
        }
  
        // Wait before next poll
        await new Promise(resolve => setTimeout(resolve, pollInterval * 1000));
      }
    } catch (error: any) {
      if (error.error) {
        return {
          content: [{
            type: "text",
            text: JSON.stringify(error, null, 2)
          }],
          isError: true
        };
      }
  
      return {
        content: [{
          type: "text",
          text: JSON.stringify(ComfyUIErrorBuilder.executionError(error.message), null, 2)
        }],
        isError: true
      };
    }
  }

• src/types/tools.ts:54-59 (schema)

  Zod schema defining the input parameters for the tool: prompt_id (required string), timeout (optional number, default 300s), poll_interval (optional number, default 2s).

  // Wait for Completion Tool
  export const WaitForCompletionSchema = z.object({
    prompt_id: z.string(),
    timeout: z.number().optional().default(300),
    poll_interval: z.number().optional().default(2)
  });

• src/server.ts:82-86 (registration)

  Tool registration in the MCP server's listTools handler, specifying name, description, and input schema.

  {
    name: 'comfy_wait_for_completion',
    description: 'Block until a generation completes or fails. Returns final outputs with image paths. Useful for synchronous workflows.',
    inputSchema: zodToJsonSchema(WaitForCompletionSchema) as any,
  },

• src/server.ts:158-159 (registration)

  Dispatch case in the CallToolRequest handler that routes calls to the implementation.

  case 'comfy_wait_for_completion':
    return await handleWaitForCompletion(args as any);