ComfyMCP Studio

# 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