Comfy Nodes

1---
2name: comfy-nodes
3description: Use when the user wants to create a ComfyUI custom node, convert Python code to a node, make a node from a script, or needs help with ComfyUI node development, INPUT_TYPES, RETURN_TYPES, or node class structure.
4version: 1.0.0
5---
6 
7# ComfyUI Custom Node Development
8 
9This skill helps you create custom ComfyUI nodes from Python code.
10 
11## Quick Template
12 
13```python
14class MyNode:
15    @classmethod
16    def INPUT_TYPES(cls):
17        return {
18            "required": {
19                "image": ("IMAGE",),
20                "value": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 1.0}),
21            },
22            "optional": {
23                "mask": ("MASK",),
24            }
25        }
26 
27    RETURN_TYPES = ("IMAGE",)
28    RETURN_NAMES = ("output",)
29    FUNCTION = "execute"
30    CATEGORY = "Custom/MyNodes"
31 
32    def execute(self, image, value, mask=None):
33        result = image * value
34        return (result,)
35 
36NODE_CLASS_MAPPINGS = {"MyNode": MyNode}
37NODE_DISPLAY_NAME_MAPPINGS = {"MyNode": "My Node"}
38```
39 
40## Converting Python to Node
41 
42When you have Python code to wrap:
43 
44### Step 1: Identify inputs and outputs
45```python
46# Original function
47def apply_blur(image, radius=5):
48    from PIL import ImageFilter
49    return image.filter(ImageFilter.GaussianBlur(radius))
50```
51 
52### Step 2: Map types
53 
54| Python Type | ComfyUI Type | Conversion |
55|-------------|--------------|------------|
56| PIL Image | IMAGE | `torch.from_numpy(np.array(pil) / 255.0)` |
57| numpy array | IMAGE | `torch.from_numpy(arr.astype(np.float32))` |
58| cv2 BGR | IMAGE | `torch.from_numpy(cv2.cvtColor(img, cv2.COLOR_BGR2RGB) / 255.0)` |
59| float 0-255 | IMAGE | Divide by 255.0 |
60| Single image | Batch | `tensor.unsqueeze(0)` |
61 
62### Step 3: Handle batch dimension
63 
64ComfyUI images are `[B,H,W,C]` - always process all batch items:
65 
66```python
67def execute(self, image, radius):
68    batch_results = []
69    for i in range(image.shape[0]):
70        # Convert to PIL
71        img_np = (image[i].cpu().numpy() * 255).astype(np.uint8)
72        pil_img = Image.fromarray(img_np)
73 
74        # Your processing
75        result = pil_img.filter(ImageFilter.GaussianBlur(radius))
76 
77        # Convert back
78        result_np = np.array(result).astype(np.float32) / 255.0
79        batch_results.append(torch.from_numpy(result_np))
80 
81    return (torch.stack(batch_results),)
82```
83 
84## Common Input Types
85 
86| Type | Shape/Format | Widget Options |
87|------|--------------|----------------|
88| IMAGE | [B,H,W,C] float 0-1 | - |
89| MASK | [H,W] or [B,H,W] float 0-1 | - |
90| LATENT | {"samples": [B,C,H,W]} | - |
91| MODEL | ModelPatcher | - |
92| CLIP | CLIP encoder | - |
93| VAE | VAE model | - |
94| CONDITIONING | [(cond, pooled), ...] | - |
95| INT | integer | default, min, max, step |
96| FLOAT | float | default, min, max, step, display |
97| STRING | str | default, multiline |
98| BOOLEAN | bool | default |
99| COMBO | str | List of options as type |
100 
101## Checklist
102 
103- [ ] `INPUT_TYPES` is a `@classmethod`
104- [ ] Return value is a tuple: `return (result,)`
105- [ ] Handle batch dimension `[B,H,W,C]`
106- [ ] Add to `NODE_CLASS_MAPPINGS`
107- [ ] Category uses `/` for submenus
108 
109## References
110 
111- [NODE_TEMPLATE.md](references/NODE_TEMPLATE.md) - Full template with V3 schema
112- [OFFICIAL_DOCS.md](references/OFFICIAL_DOCS.md) - Official ComfyUI documentation
113- [PURZ_EXAMPLES.md](references/PURZ_EXAMPLES.md) - Example nodes and workflows
114 
115## Finding Similar Nodes
116 
117Use the MCP tools to find existing nodes for reference:
118 
119```
120comfy_search("blur")        → Find blur implementations
121comfy_spec("GaussianBlur")  → See how inputs are defined
122```
123