# ComfyUI MCP Server - Blueprint
## Architecture Overview
A Python MCP server using FastMCP that wraps ComfyUI's REST API to expose image generation as MCP tools for Claude Desktop. The server is a simple bridge layer -- ComfyUI handles all the heavy lifting (model loading, inference, image saving). The MCP server translates tool calls into ComfyUI API requests and returns results.
```
Claude Desktop → MCP Server (this project) → ComfyUI REST API (localhost:8188) → GPU
```
## Key Components
| Component | File | Purpose |
|-----------|------|---------|
| **Server** | `src/server.py` | FastMCP server with tool definitions |
| **ComfyUI Client** | `src/comfyui_client.py` | httpx async client wrapping ComfyUI REST API |
| **Workflow Templates** | `src/workflows.py` | Default workflow JSON templates (txt2img, img2img) |
| **Config** | `src/config.py` | pydantic-settings for ComfyUI URL, output paths, defaults |
| **Models** | `src/models.py` | Pydantic models for generation params and results |
## MCP Tools (MVP)
1. **generate_image** - Text-to-image generation with prompt, model, size, steps params
2. **list_models** - List available checkpoints/models on the ComfyUI instance
3. **get_queue_status** - Check ComfyUI queue (pending/running/completed)
4. **get_generation** - Retrieve a completed generation's image path and metadata
5. **list_saved_workflows** - List available saved workflow templates
## Tech Stack Rationale
- **FastMCP** - Standard Python MCP framework, minimal boilerplate
- **httpx** - Async HTTP client for ComfyUI API calls, connection pooling
- **pydantic / pydantic-settings** - Config and data validation
- **pytest + pytest-asyncio** - Async test support for testing tool handlers
- **respx** - Mock httpx requests in tests (no live ComfyUI needed for testing)
## Implementation Phases
### Phase 1: Core Generation (MVP) ~20 hours
- [ ] Project setup (pyproject.toml, config, CI)
- [ ] ComfyUI client (connect, submit workflow, poll status, get image)
- [ ] Default txt2img workflow template
- [ ] generate_image tool
- [ ] get_queue_status tool
- [ ] get_generation tool
- [ ] Tests with mocked ComfyUI responses
- [ ] README with setup instructions
### Phase 2: Model & Workflow Management ~12 hours
- [ ] list_models tool (query ComfyUI for available checkpoints)
- [ ] list_saved_workflows tool
- [ ] img2img workflow template
- [ ] Configurable default parameters (model, steps, size)
- [ ] Error handling for ComfyUI connection failures
- [ ] Claude Desktop config documentation
### Phase 3: Polish & Publish ~8 hours
- [ ] Output directory management (organize generated images)
- [ ] Generation history/metadata logging
- [ ] Integration testing with live ComfyUI (manual)
- [ ] GitHub repo setup and publish
