# ComfyMCP Studio

 ComfyMCP Studio is an MCP (Model Context Protocol) server for generating 2D game assets using AI workflows powered by ComfyUI.

 ## What you get

 - **ComfyUI-backed generation**
   - Production-quality SDXL/SD1.5 workflows
 - **High-quality outputs by default**
   - Render at preset resolution (SDXL-native) then downscale for cleaner details
 - **Consistent character animations (img2img)**
   - Generate multiple poses from a single reference image
 - **Viewpoint control with ControlNet (top-down / side / front / 3/4)**
   - Generate top-down assets with stronger camera-angle consistency
 - **Presets for common game styles**
   - Icon, character, tileset, top-down presets, pixel presets
 - **Post-processing**
   - Resize, remove background, add outline
 - **Unity export + batch generation**

 ## Requirements

 - **Python**: 3.10+
 - **ComfyUI**: running locally (default `127.0.0.1:8188`)
 - **Stable Diffusion checkpoint**
   - SDXL recommended (default configured: `sd_xl_base_1.0.safetensors`)
 - **(Optional) ControlNet models**
   - Required only for `generate_with_viewpoint` / `generate_topdown_asset`

 ## Installation

 ```bash
 # Navigate to the project
 cd path/ComfyAI-MCP-GameAssets

 # Create virtual environment
 python -m venv venv
 venv\Scripts\activate

 # Install dependencies
 pip install -r requirements.txt
 ```

 ## Configuration

 Copy `.env.example` to `.env` and configure:

 ```env
 BACKEND_TYPE=comfyui
 COMFYUI_HOST=127.0.0.1
 COMFYUI_PORT=8188
 COMFYUI_CHECKPOINT=sd_xl_base_1.0.safetensors

 OUTPUT_DIR=./output
 UNITY_ASSETS_DIR=C:/Projects/MyGame/Assets
 ```

 ## ComfyUI setup

 - **Start ComfyUI** (example):

 ```bash
 python main.py --listen 0.0.0.0 --port 8188
 ```

 - **Checkpoint**
   - Make sure your checkpoint exists in ComfyUI (example: `ComfyUI/models/checkpoints/`).
   - This server reads `COMFYUI_CHECKPOINT` from `.env`.

 ## ControlNet setup (for viewpoint locking)

 If you use viewpoint tools, you must install a ControlNet model in:
 `ComfyUI/models/controlnet/`

 - **SDXL depth model (example)**
   - `diffusers_xl_depth_full.safetensors`

 Restart ComfyUI after adding models.

 If you see `HTTP 400 Bad Request` when calling `/prompt`, it usually means:
 - The `controlnet_model` name is wrong, or
 - The ControlNet nodes/models are not installed/available.

 ## Run as MCP server (Windsurf)

 Add this to your MCP settings (or copy from `mcp_config.json`):

 ```json
 {
   "mcpServers": {
     "comfymcp-studio": {
       "command": "python",
       "args": ["-m", "server.main"],
       "cwd": "path/ComfyAI-MCP-GameAssets",
       "env": {
         "BACKEND_TYPE": "comfyui",
         "COMFYUI_HOST": "127.0.0.1",
         "COMFYUI_PORT": "8188"
       }
     }
   }
 }
```

## Tools

- **`ping`** - Backend health check
- **`list_available_presets`** - Lists preset names + configs
- **`generate_sprite`** - Single image generation from prompt
- **`generate_icons`** - Batch icons + optional atlas
- **`generate_tileset`** - Tileable tiles by theme
- **`generate_character`** - Character generation (prompt-driven)
- **`generate_character_animations`** - Img2img multi-pose animations from a reference image
- **`generate_with_viewpoint`** - ControlNet depth-guided generation for stable camera angle
- **`generate_topdown_asset`** - Convenience wrapper for top-down assets (prop, character, creature, tile, effect)
- **`process_image`** - Resize / remove background / add outline
- **`create_sprite_atlas`** - Combine images to spritesheet
- **`export_to_unity`** - Export output PNGs into a Unity project folder
- **`batch_generate`** - Batch generation with prompts

## Presets

You can list presets via `list_available_presets`.

### General
- **`default`** - General purpose game asset
- **`icon`** / **`icon_item`** - Game icons
- **`character`** / **`character_portrait`** - Character sprites
- **`tileset`** - Seamless tileable textures
- **`environment`** - Background/environment art
- **`prop`** - Game props (3/4 view)

### Top-down (ControlNet)
- **`topdown_prop`** - Top-down props
- **`topdown_character`** - Top-down characters
- **`topdown_creature`** - Top-down creatures/enemies
- **`topdown_tile`** - Top-down tiles

### Effects & UI
- **`effect`** / **`magic_effect`** - VFX and spell effects
- **`ui_button`** / **`ui_frame`** - UI elements

### Creatures
- **`creature`** - Fantasy creatures/monsters

### Style-specific
- **`handpainted`** - Hand-painted art style
- **`flat_ui`** - Flat design UI
- **`isometric`** - Isometric game assets
- **`pixel_art`** / **`pixel_character`** - Pixel art style
- **`pixel_16`** / **`pixel_32`** / **`pixel_64`** - Specific pixel sizes

## Testing

### Quick smoke test

```bash
python test_generate.py --list-presets
python test_generate.py --preset icon --size 256 --steps 20 --seed 42 --save
```

### ControlNet viewpoint tests

```bash
# Top-down prop (depth ControlNet)
python test_controlnet.py --tests prop --size 512 --strength 0.95 --save

# Top-down character (wrapper tool)
python test_controlnet.py --tests character --size 512 --strength 1.0 --save

# Multi-view for the same object
python test_controlnet.py --tests multi --views topdown,side,front,3/4 --size 512 --strength 0.90 --save
```

### Character animation tests (img2img)

```bash
# Requires a local reference image
python test_character_animation.py --ref path\\to\\reference.png --poses idle,walking,attacking --denoise 0.35 --seed 42 --save
```

## Output

 Generated images are saved under `OUTPUT_DIR` when you call tools with `save_to_file=true`.
 Typical folders:

 - **`output/controlnet/`**
 - **`output/icons/`**
 - **`output/characters/`**
 - **`output/tilesets/`**

 ## Troubleshooting

 - **`HTTP 400 Bad Request` from ComfyUI `/prompt`**
   - Check ControlNet model file exists in `ComfyUI/models/controlnet/`
   - Verify the exact filename passed as `controlnet_model`
   - Restart ComfyUI after installing models
 - **Results still not top-down**
   - Increase `control_strength` (try `0.90` to `1.0`)
   - Use `preset=topdown_character/topdown_prop`
 - **Duplicated/fragmented weapons/armor**
   - Add explicit constraints to prompt: `single character`, `one sword`, `one shield`

 ## License

 MIT