# ComfyUI MCP Server - Production

A robust Model Context Protocol (MCP) server that provides Unity with reliable AI image generation through ComfyUI.

[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289DA?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/pVjjpBak)

## Features

🎨 **Reliable Image Generation**
- Queue-based completion detection (no timeouts)
- Multiple download fallback methods
- Production-grade error handling

🌸 **Specialized Workflows**
- General image generation with customizable parameters
- Flower texture generation optimized for Unity
- Support for seamless tileable textures

🔧 **Production Ready**
- Comprehensive logging and monitoring
- Configuration management with environment variables
- Robust error handling and recovery
- Performance statistics and health monitoring

🎮 **Unity Integration**
- Automatic Unity asset folder management
- PNG texture optimization
- Material-ready output format

## Quick Start

### Prerequisites

1. **ComfyUI** running on `http://127.0.0.1:8188`
2. **Python 3.8+** with required packages
3. **Unity project** with Assets folder structure

### Installation

1. Install dependencies:
   ```bash
   pip install mcp requests
   ```

2. Configure the MCP client to use this server:
   ```json
   {
     "mcpServers": {
       "comfy": {
         "command": "python",
         "args": ["path/to/comfyui-mcp/server.py"],
         "cwd": "path/to/comfyui-mcp"
       }
     }
   }
   ```

3. Start using through Unity/Coplay!

## Usage

### Generate General Images

```python
# Through MCP client
result = await mcp_client.call_tool("generate_image", {
    "client_id": "unity-client",
    "prompt": "beautiful landscape, sunset, high quality",
    "width": 1024,
    "height": 1024,
    "steps": 25,
    "cfg": 7.5
})
```

### Generate Flower Textures

```python
# Through MCP client
result = await mcp_client.call_tool("generate_flower_texture", {
    "client_id": "unity-client", 
    "flower_type": "rose",
    "seamless": True,
    "detail_level": "high"
})
```

### Check Server Status

```python
# Get server health and statistics
status = await mcp_client.call_tool("get_server_status", {
    "client_id": "unity-client"
})
```

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `COMFYUI_HOST` | `127.0.0.1` | ComfyUI server host |
| `COMFYUI_PORT` | `8188` | ComfyUI server port |
| `UNITY_TEXTURE_PATH` | `Assets/Textures/Generated` | Unity texture output path |
| `UNITY_MATERIAL_PATH` | `Assets/Materials` | Unity material path |
| `GENERATION_TIMEOUT` | `180` | Max wait time for generation (seconds) |
| `REQUEST_TIMEOUT` | `30` | HTTP request timeout (seconds) |
| `QUEUE_CHECK_INTERVAL` | `3` | Queue polling interval (seconds) |
| `DEFAULT_WIDTH` | `512` | Default image width |
| `DEFAULT_HEIGHT` | `512` | Default image height |
| `DEFAULT_STEPS` | `25` | Default sampling steps |
| `DEFAULT_CFG` | `7.5` | Default CFG scale |
| `DEFAULT_MODEL` | `v1-5-pruned-emaonly.ckpt` | Default ComfyUI model |
| `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
| `COMFYUI_MCP_MODE` | `production` | Mode (production, development) |

### Example Configuration

```bash
# Production settings
export COMFYUI_HOST="192.168.1.100"
export COMFYUI_PORT="8188"
export GENERATION_TIMEOUT="300"
export LOG_LEVEL="INFO"

# Development settings  
export COMFYUI_MCP_MODE="development"
export LOG_LEVEL="DEBUG"
export GENERATION_TIMEOUT="60"
```

## Architecture

### Core Components

1. **ComfyUIClient** - Handles all ComfyUI communication
2. **WorkflowGenerator** - Creates ComfyUI workflows for different use cases
3. **FileManager** - Manages Unity asset file operations
4. **ImageGenerationService** - High-level generation orchestration
5. **MCP Server** - Handles Model Context Protocol communication

### Queue-Based Completion Detection

The server uses ComfyUI's queue API to reliably detect completion:

1. Submit workflow to ComfyUI queue
2. Monitor queue status (pending → running → completed)
3. When prompt disappears from queue, fetch results from history
4. Download and save generated images

This approach eliminates timeout issues and provides reliable completion detection.

### Multiple Download Fallbacks

Images are downloaded using multiple fallback methods:

1. **Standard method**: `/view?filename=X&subfolder=Y&type=Z`
2. **Direct method**: `/view?filename=X`
3. **Type-only method**: `/view?filename=X&type=output`

This ensures compatibility with different ComfyUI configurations.

## Monitoring & Debugging

### Production Logs

The server provides comprehensive logging:

```
2025-01-24 14:21:35,123 - comfyui-mcp - INFO - Queued prompt abc123: beautiful landscape...
2025-01-24 14:21:45,456 - comfyui-mcp - INFO - Prompt abc123 completed
2025-01-24 14:21:46,789 - comfyui-mcp - INFO - Saved image: Assets/Textures/Generated/generated_1024x1024_2025-01-24_14-21-46.png (1234567 bytes)
```

### Server Statistics

The server tracks performance metrics:

- Total requests processed
- Successful vs failed generations
- Server uptime
- ComfyUI connection status

Access via `get_server_status` tool.

### Error Handling

The server provides detailed error information:

- ComfyUI connection issues
- Workflow submission failures
- Image download problems
- File system errors

All errors include context and suggested solutions.

## Performance Tips

### ComfyUI Optimization

1. **Use appropriate models** - Lighter models generate faster
2. **Optimize steps** - Fewer steps = faster generation
3. **Batch processing** - Queue multiple requests
4. **Model caching** - Keep models loaded in ComfyUI

### Unity Integration

1. **Texture compression** - Enable appropriate compression in Unity
2. **Mipmaps** - Enable for seamless textures
3. **Texture streaming** - For large textures
4. **Asset database refresh** - Happens automatically

## Troubleshooting

### Common Issues

**"ComfyUI is not running"**
- Check ComfyUI is started and accessible at configured URL
- Verify firewall/network settings
- Check ComfyUI console for errors

**"Generation timed out"**
- Increase `GENERATION_TIMEOUT` environment variable
- Check ComfyUI queue for stuck jobs
- Verify model is loaded in ComfyUI

**"No images found in outputs"**
- Check ComfyUI workflow compatibility
- Verify model exists and is loaded
- Check ComfyUI console for workflow errors

**"Cannot save to Unity folder"**
- Check Unity project is open
- Verify write permissions to Assets folder
- Check disk space availability

### Debug Mode

Enable debug logging:

```bash
export COMFYUI_MCP_MODE="development"
export LOG_LEVEL="DEBUG"
```

This provides detailed information about:
- Queue monitoring
- Image download attempts
- File operations
- Error details

## Version History

- **v1.0.0** - Production release with queue-based detection
- **v0.9.x** - Development versions with timeout fixes
- **v0.8.x** - Initial MCP server implementation

## Community & Collaboration

Join our Discord community to collaborate, get help, and share your projects:

[![Discord](https://img.shields.io/badge/Discord-Join%20Server-7289DA?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/pVjjpBak)

In our Discord server, you can:
- Get help with ComfyUI MCP integration
- Share your generated images and workflows
- Collaborate on new features and improvements
- Connect with other Unity AI developers
- Stay updated on the latest developments

## Support

For issues and questions:

1. Check the troubleshooting section above
2. Enable debug logging for detailed information
3. Check ComfyUI server logs
4. Verify Unity project setup
5. Join our [Discord community](https://discord.gg/pVjjpBak) for real-time help

## License

This ComfyUI MCP server is part of the Coplay AI development toolkit.