# comfyui-workflow-editor-mcp

A lightweight MCP (Model Context Protocol) server that bridges AI agents (like Cursor, Claude, etc.) with a local ComfyUI instance. It enables AI agents to generate and iteratively refine images, audio, and video through conversational tool calls — with a graph-based workflow editor for safe, validated modifications.

## Features

- **Workflow Graph Editor**: Safe, validated editing of ComfyUI workflows as directed graphs
  - Add, remove, replace, and insert nodes with automatic type-checking and cycle detection
  - Search available node types from the ComfyUI `/object_info` catalog
  - Validate workflows before execution (type mismatches, cycles, orphans, missing inputs)
  - Compare workflows, convert between API and frontend formats, generate workflows from templates

## Quick Start

### Option 1: Via npx (for MCP clients)

No local clone needed. Add to your MCP client configuration (Cursor, Claude, etc.):

```json
"comfyui": {
  "command": "npx",
  "args": ["-y", "comfyui-workflow-editor-mcp"],
  "env": {
    "COMFYUI_URL": "http://localhost:8188",
    "COMFY_MCP_WORKFLOW_DIR": "/path/to/workflows",
    "COMFY_MCP_ASSET_TTL_HOURS": "24"
  }
}
```

> **Note:** ComfyUI must be running at `COMFYUI_URL` before the MCP client connects.

### Option 2: Local development

```bash
git clone https://github.com/yar3333/comfyui-workflow-editor-mcp.git
cd comfyui-workflow-editor-mcp
npm install
npm run build
```

Then start:

| Command       | Mode                    |
| ------------- | ----------------------- |
| `npm start`   | stdio (for MCP clients) |
| `npm run dev` | stdio with ts-node      |

## Configuration

### Environment Variables

| Variable                    | Description                 | Default                 |
| --------------------------- | --------------------------- | ----------------------- |
| `COMFYUI_URL`               | ComfyUI base URL            | `http://localhost:8188` |
| `COMFY_MCP_WORKFLOW_DIR`    | Path to workflow directory  | `./workflows`           |
| `COMFY_MCP_ASSET_TTL_HOURS` | Asset time-to-live in hours | `24`                    |

## API Tools

### Generation Tools

| Tool          | Description                                          |
| ------------- | ---------------------------------------------------- |
| `<workflows>` | Available workflows automatically published as tools |
| `regenerate`  | Regenerate a previously generated asset              |

### Viewing Tools

| Tool         | Description                           |
| ------------ | ------------------------------------- |
| `view_image` | View a generated image inline in chat |

### Job Management Tools

| Tool                 | Description                                   |
| -------------------- | --------------------------------------------- |
| `get_queue_status`   | Get current queue status from ComfyUI         |
| `get_job`            | Get job status by prompt_id                   |
| `wait_for_job`       | Wait for a job to complete with timeout       |
| `list_assets`        | List generated assets with optional filtering |
| `get_asset_metadata` | Get full metadata for a specific asset        |
| `cancel_job`         | Cancel a running job by prompt_id             |

### Configuration Tools

| Tool                     | Description                                                 |
| ------------------------ | ----------------------------------------------------------- |
| `list_checkpoint_models` | List available checkpoint models from ComfyUI               |
| `list_unet_models`       | List available UNet models in standard (safetensors) format |
| `list_unet_gguf_models`  | List available UNet models in GGUF format                   |

### Workflow Tools

| Tool             | Description                                        |
| ---------------- | -------------------------------------------------- |
| `list_workflows` | List available workflows in the workflow directory |
| `run_workflow`   | Run a specific workflow with parameter overrides   |

### Workflow Graph Editor Tools

Graph-based tools for safe, validated editing of ComfyUI workflows. All mutations validate type compatibility, detect cycles, and report orphan nodes.

| Tool                      | Description                                                     |
| ------------------------- | --------------------------------------------------------------- |
| `get_workflow_graph`      | Get workflow structure as a graph with nodes, links, chains     |
| `search_node_types`       | Search available node types from the ComfyUI catalog            |
| `get_node_info`           | Get detailed schema for a node type (inputs, outputs, defaults) |
| `add_node`                | Add a node with validation (type-check, cycle detection)        |
| `remove_node`             | Remove a node, reporting affected connections and orphans       |
| `connect_nodes`           | Create a connection between node outputs and inputs             |
| `disconnect_node_input`   | Disconnect an input from a node                                 |
| `set_node_input`          | Change a primitive input value on a node                        |
| `insert_node`             | Insert a node into an existing link (break-and-reconnect)       |
| `replace_node`            | Replace a node type, preserving compatible connections          |
| `validate_workflow`       | Full validation: types, cycles, orphans, missing inputs         |
| `find_connection_path`    | Find the dependency path between two nodes                      |
| `build_basic_workflow`    | Generate a workflow from a template (txt2img, img2img, etc.)    |
| `convert_workflow_format` | Convert between ComfyUI API format and frontend JSON format     |
| `diff_workflows`          | Compare two workflows, showing added/removed/modified nodes     |

## Workflow Graph Editor

The workflow graph editor represents ComfyUI workflows as directed graphs, enabling safe modifications with automatic validation.

### How It Works

- **`WorkflowGraph`** — in-memory graph representation of a workflow (nodes, connections, execution order)
- **`NodeTypesCatalog`** — cached catalog of available node types loaded from ComfyUI's `/object_info` API
- **Validation rules** — every mutation is checked against the same rules ComfyUI uses internally:

| Check              | Description                                                                |
| ------------------ | -------------------------------------------------------------------------- |
| Required inputs    | All mandatory inputs must be provided                                      |
| Link targets       | Links reference existing nodes and valid slot indices                      |
| Type compatibility | Output types match input type expectations (supports unions and wildcards) |
| Cycle detection    | DFS-based cycle detection prevents invalid dependency graphs               |
| Orphan detection   | Nodes unreachable from any output node are flagged                         |
| Output node check  | At least one output node (SaveImage, SaveAudio, etc.) must exist           |

### Built-in Templates

`build_basic_workflow` supports the following templates:

| Template             | Description                | Nodes                                                                                    |
| -------------------- | -------------------------- | ---------------------------------------------------------------------------------------- |
| `txt2img_basic`      | Basic text-to-image        | CheckpointLoader, 2×CLIPTextEncode, EmptyLatent, KSampler, VAEDecode, SaveImage          |
| `img2img_basic`      | Image-to-image             | CheckpointLoader, LoadImage, VAEEncode, 2×CLIPTextEncode, KSampler, VAEDecode, SaveImage |
| `txt2img_controlnet` | Text-to-image + ControlNet | Basic + ControlNetLoader, LoadImage, ControlNetApply                                     |
| `txt2img_sdxl`       | SDXL text-to-image         | CheckpointLoader, CLIPTextEncode (4×), EmptyLatent, KSampler (2×), VAEDecode, SaveImage  |
| `upscale_basic`      | Upscale pipeline           | CheckpointLoader, ImageUpscaleWithModel, VAEEncode, KSampler, VAEDecode, SaveImage       |

### Format Conversion

ComfyUI uses two JSON formats:

- **API format** — flat `{node_id: NodeData}` map used by the backend (what the MCP server works with)
- **Frontend format** — structured `{nodes, links, groups}` format exported from the ComfyUI UI

Use `convert_workflow_format` to convert between them.

## Workflow System

Workflows are stored as JSON files in the `workflows/` directory. The system automatically discovers workflows and exposes them as MCP tools. Parameters are defined using the `PARAM_*` placeholder system:

- `PARAM_INT_SEED` - Integer parameter for seed
- `PARAM_FLOAT_CFG` - Float parameter for CFG scale
- `PARAM_STR_SAMPLER_NAME` - String parameter for sampler name
- `PARAM_PROMPT` - String parameter for prompt

## Test

Prerequisites: ComfyUI running at `http://localhost:8188`, server built and started.

```bash
# Run the test client
npx ts-node test_client.ts

# With custom prompt
npx ts-node test_client.ts -p "a beautiful sunset over mountains"
```

```bash
# Run unit tests
npm test
```

## Project Structure

```
comfyui-workflow-editor-mcp/
├── src/
│   ├── comfyui_client.ts        # HTTP client for ComfyUI API
│   ├── asset_processor.ts       # Image processing utilities
│   ├── server.ts                # Main entry point
│   ├── models/                  # Data models
│   │   ├── asset.ts
│   │   ├── workflow.ts
│   │   ├── workflow_graph.ts    # WorkflowGraph — in-memory graph representation
│   │   └── node_types.ts        # NodeTypeSchema and related interfaces
│   ├── managers/                # Manager classes
│   │   ├── workflow_manager.ts
│   │   ├── asset_registry.ts
│   │   └── node_types_catalog.ts # NodeTypesCatalog — cached /object_info catalog
│   └── tools/                   # MCP tool implementations
│       ├── helpers.ts
│       ├── generation.ts
│       ├── asset.ts
│       ├── job.ts
│       ├── configuration.ts
│       ├── workflow.ts          # list_workflows, run_workflow
│       └── workflow_edit.ts     # Graph editor tools (add, remove, connect, validate, etc.)
├── workflows/                   # Workflow JSON files
├── test_client.ts               # Test client
├── package.json
├── tsconfig.json
└── README.md
```

## License

MIT

## Author

[@yar3333](https://github.com/yar3333)