# ComfyUI MCP Server - AI Agent Behavioral Guide
**Purpose**: Hierarchical behavioral guide for AI coding assistants working on the ComfyUI MCP Server project.
---
## Agent Behavioral Protocols
### Thinking Process
1. **Explore Context First**: Search for existing patterns before creating new code
2. **Check Subfolder AGENTS.md**: When working in a layer (routes, orchestrators, tools), **ALWAYS** read its AGENTS.md for layer-specific patterns
3. **Verify DRY**: Check if similar functionality exists elsewhere
4. **Check Layer Boundaries**: Understand where code belongs (routes vs orchestration vs tools)
5. **Plan Before Execute**: Outline approach for multi-file changes
6. **Drift Check**: If this doc contradicts code, trust the codebase and flag the discrepancy
### Safety Constraints
- **Never run destructive commands** without explicit confirmation:
- `rm -rf` (especially on system directories or workspace files)
- `DROP TABLE` or database schema deletions
- `docker system prune -a` or volume deletions
- **No blind retries**: If fix fails, stop, analyze logs, propose new strategy
- **Always use route functions**: Never create direct HTTP calls outside `src/routes/`
- **Respect layer boundaries**: Routes = transport, Orchestration = logic, Tools = MCP interface
- **Environment awareness**: Distinguish dev/staging/prod ComfyUI instances. **WSL Alert**: If Cursor is Windows and Server is WSL, absolute paths in MCP config must be bridged via `wsl` command or use HTTP transport.
---
## Token Economy & Output
- Use `sed` or patch-style replacements for small edits
- Output changed code only (use `# ... existing code ...` for context)
- Do not repeat user's prompt verbatim
- Reference files by path: `src/routes/workflow.py`
- Keep responses concise and actionable
- **When working in a specific layer**: Check its AGENTS.md first (e.g., `src/routes/AGENTS.md`)
---
## 🏗️ Architecture Overview
### Three-Layer Architecture
```
┌─────────────────────────────────────────────────────────┐
│ MCP Tools Layer (src/tools/) ✅ REFACTORED │
│ - MCP tool registration and argument parsing │
│ - Thin wrappers calling orchestration layer │
│ - NO business logic, NO HTTP calls │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Orchestration Layer (src/orchestrators/) ✅ REFACTORED │
│ - Business logic, validation, polling, retries │
│ - Receives Auth, passes to routes │
│ - Coordinates multiple route calls │
│ - NO direct HTTP calls (uses routes only) │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Routes Layer (src/routes/) ✅ REFACTORED │
│ - HTTP transport ONLY │
│ - Minimal logic, standardized patterns │
│ - Uses httpx + auth injection │
│ - Returns ResponseGetData │
└─────────────────────────────────────────────────────────┘
```
### Refactoring Status
| Layer | Status | Location |
|-------|--------|----------|
| **Routes** | ✅ Complete | `src/routes/` |
| **Auth** | ✅ Complete | `src/auth/` |
| **Client** | ✅ Complete | `src/client/` |
| **Utils** | ✅ Complete | `src/utils/` |
| **Models** | ✅ Complete | `src/models/` |
| **Orchestration** | ✅ Complete | `src/orchestrators/` |
| **MCP Tools** | ✅ Complete | `src/tools/` |
**✅ Phase 3 Complete**: All three layers fully refactored with SOLID principles!
**✅ FastMCP v3 Integration**: Workflow orchestration upgraded with Context support, Resources, and Null Object pattern.
**Status**: Architecture refactoring complete. System uses:
- Routes for HTTP transport only
- Orchestrators for business logic with FastMCP v3 Context integration
- Tools for thin MCP wrappers with Resources support
- Null Object pattern for optional dependencies
---
## Universal Tech Stack
### Repository Type
- **Monorepo** with layered architecture
- **Language**: Python 3.10+
- **Package Manager**: uv (via pyproject.toml)
### Core Dependencies
```toml
httpx>=0.27.0 # Async HTTP client for routes
fastmcp>=3.0.0b1 # FastMCP v3 beta for MCP server
pillow>=10.0.0 # Image processing
```
### Core Commands
```bash
# Install dependencies
uv sync
# Run server (stdio for MCP clients)
python server.py --stdio
# Run server (HTTP for testing)
python server.py
```
### Code Style Standards
- **Python**:
- Formatter: `ruff format` (configured in pyproject.toml)
- Linter: `ruff check` (E, W, F, I, B, C4, UP rules enabled)
- Type hints: Required for function signatures
- Line length: 100 characters
- Import sorting: isort via ruff
- **Testing**:
- Framework: `pytest` with `pytest-asyncio` for async tests
- **Location**: All tests MUST be in `/tests` folder (unit, integration, E2E)
- Structure: Mirror `src/` structure (e.g., `tests/routes/`, `tests/orchestrators/`)
- Never create test files outside `/tests` directory
---
## Layer-Specific Rules
### 1. Routes Layer (`src/routes/`) ✅ REFACTORED
**Purpose**: HTTP transport ONLY. No business logic.
**⚠️ REQUIRED**: Read [src/routes/AGENTS.md](src/routes/AGENTS.md) before modifying routes - contains detailed patterns, error handling, and response types
### 2. Orchestration Layer (`src/orchestrators/`) ✅ REFACTORED
**Purpose**: Business logic, coordination, validation, polling.
**⚠️ REQUIRED**: Read [src/orchestrators/AGENTS.md](src/orchestrators/AGENTS.md) before modifying orchestrators - contains class patterns, DI rules, and integration guidelines
**Implemented Orchestrators**:
- `AssetOrchestrator`: Asset lifecycle management with TTL expiration
- `WorkflowOrchestrator`: Workflow execution with polling ✨ **FastMCP v3 Context support**
- `ParameterExtractor`: Extract parameters from workflow JSON
- `WorkflowLoader`: Load and cache workflow definitions
- `WorkflowRenderer`: Render workflow templates with parameters
- `WorkflowOrchestrator`: Main coordinator with progress reporting
- `DefaultsManager`: Parameter defaults with precedence chain (decoupled via DI)
- `NullDefaultsManager`: Null Object pattern for optional defaults ✨ **New**
- `PublishManager`: Safe asset publishing with path security
- `NodeOrchestrator`: Node definition discovery and caching for workflow construction
**Node Introspection Use Cases**: When users provide workflow JSON files or request workflow modifications, agents should use `NodeOrchestrator` to:
1. **Troubleshoot**: Validate node types exist (`get_node_by_class`), check parameter requirements (`get_node_inputs`)
2. **Extend**: Find compatible nodes for additions (`search_nodes`, `get_nodes_by_output_type`)
3. **Build**: Discover available nodes and capabilities (`get_all_nodes`, `get_categories`)
**FastMCP v3 Enhancements** ✨:
- **Context Integration**: Progress reporting via `ctx.report_progress()` and `ctx.info()`
- **Required Dependencies**: No `Optional` types, explicit dependency injection
- **Null Object Pattern**: `NullDefaultsManager` for optional features without Optional types
- **Resources**: Workflows exposed as MCP Resources (`workflows://catalog`, `workflows://{id}/definition`)
See [docs/FASTMCP_V3_REFACTORING.md](docs/FASTMCP_V3_REFACTORING.md) for details.
### 3. MCP Tools Layer (`src/tools/`) ✅ REFACTORED
**Purpose**: MCP tool registration, argument parsing, minimal glue.
**⚠️ REQUIRED**: See [.github/skills/fastmcp-v3/SKILL.md](.github/skills/fastmcp-v3/SKILL.md) for FastMCP v3 patterns before creating/modifying tools
**Rules**:
- ✅ Thin wrappers over orchestration layer
- ✅ MCP argument validation only
- ❌ NO business logic, NO HTTP calls
**Implemented Tools**:
- `asset.py`: Asset viewing and browsing tools
- `configuration.py`: Configuration management tools
- `generation.py`: Workflow generation and execution tools ✨ **Context passthrough**
- `job.py`: Job queue and execution monitoring tools
- `node.py`: Node introspection and schema discovery tools
- `publish.py`: Asset publishing and sharing tools
- `workflow.py`: Workflow catalog and management tools ✨ **Resources added**
**FastMCP v3 Features** ✨:
- **Resources**: `workflows://catalog`, `workflows://{id}/definition`, `workflows://{id}/parameters`
- **Context Passthrough**: Tools pass `ctx` to orchestrators for progress reporting
- **Thin Wrappers**: All tools follow FastMCP v3 patterns (no business logic)
---
## Anti-Patterns (What NOT to Do)
### ❌ Creating HTTP Requests Outside Routes
**Bad**:
```python
import httpx
async def queue_workflow(workflow):
async with httpx.AsyncClient() as client:
response = await client.post("http://localhost:8188/prompt", json={"prompt": workflow})
```
**Good**:
```python
from auth import NoAuth
from routes import queue_workflow
auth = NoAuth("http://localhost:8188")
res = await queue_workflow(auth=auth, workflow=workflow)
```
### ❌ Business Logic in Routes
Routes should only handle HTTP transport. Validation, transformation, and polling belong in orchestrators.
### ❌ Duplicating Route Functions
Always use existing route functions. Never reimplement HTTP calls.
---
## File Organization
### Root Directory Standards
**Do not create new root-level files or directories.** Use designated locations:
- **`.github/`** - GitHub-specific configs and skills
- **`docs/`** - Project documentation (ARCHITECTURE.md, REFERENCE.md)
- **`tests/`** - Test files (unit, integration, E2E)
- **`src/`** - Source code (see below)
- **`workflows/`** - ComfyUI workflow definitions (JSON)
- **`.venv/`** - Python virtual environment (created by uv)
### Source Code Organization (`src/`)
```
src/
├── auth/ ✅ Authentication abstractions
├── client/ ✅ HTTP client with httpx
├── routes/ ✅ HTTP transport layer
├── utils/ ✅ Correlation logging and cross-cutting concerns
├── models/ ✅ Data models (AssetRecord, WorkflowParameter, etc.)
├── orchestrators/ ✅ Business logic layer
│ ├── asset.py ✅ AssetOrchestrator (lifecycle management)
│ ├── workflow.py ✅ WorkflowOrchestrator + 3 focused classes
│ ├── defaults.py ✅ DefaultsManager (decoupled via DI)
│ └── publish.py ✅ PublishManager (path security)
└── tools/ ✅ MCP tool registrations
├── asset.py ✅ Asset viewing tools
├── configuration.py ✅ Configuration tools
├── generation.py ✅ Workflow generation tools
├── job.py ✅ Job and queue management
├── publish.py ✅ Asset publishing tools
├── workflow.py ✅ Workflow management tools
└── helpers.py ✅ Shared helper functions
```
---
## JIT Index (Component Map)
### Architecture Documentation
- **[Routes Layer](src/routes/AGENTS.md)** - HTTP transport patterns
- **[Orchestrators Layer](src/orchestrators/AGENTS.md)** - Business logic patterns
- **[REFACTORING_SUMMARY.md](docs/REFACTORING_SUMMARY.md)** - Phase 1 summary
- **[FASTMCP_V3_REFACTORING.md](docs/FASTMCP_V3_REFACTORING.md)** - FastMCP v3 workflow orchestration upgrade
### Skills Reference (Context-Specific Knowledge)
**🔧 When to Use Each Skill**:
- **[FastMCP v3](.github/skills/fastmcp-v3/SKILL.md)** - Creating/modifying MCP tools in `src/tools/`, Resources, Context integration
- **[MCP Logging](.github/skills/mcp-logging/SKILL.md)** - Adding correlation IDs, structured logging, debugging across layers
- **[Generate AGENTS.md](.github/skills/generate-agents-md/SKILL.md)** - Updating documentation, creating new AGENTS.md files
**💡 Note**: Skills provide deep domain knowledge. Read the relevant skill before implementing patterns.
---
## Error Handling Protocol
### Common Issues and Resolution
1. **Connection refused (localhost:8188)**
```bash
# Check if ComfyUI is running
curl http://localhost:8188/system_stats
# Start ComfyUI if needed
cd /path/to/ComfyUI && python main.py
```
2. **Module import errors**
```bash
# Reinstall dependencies
uv sync
# Verify Python environment
python --version # Should be 3.10+
```
3. **MCP server issues**
```bash
# Test server in HTTP mode
python server.py
# Test with MCP client
python server.py --stdio
```
4. **Asset not found errors**
- Check asset lifecycle: Assets expire after 24 hours
- Verify asset path: `browse_asset_directory()` to list files
- Check execution completion: `get_job_status()` before viewing
5. **Workflow execution failures**
- Validate workflow JSON structure
- Check node requirements: Models, LoRAs, VAE, etc.
- Review execution history: `get_queue()` for errors
---
## Search Hints
```bash
# Find route functions
rg -n "^async def (queue_|get_|cancel_)" src/routes/
# Find old HTTP patterns (needs refactoring)
rg -n "requests\.(get|post|head)" --type python
# Find auth usage
rg -n "ComfyAuth|NoAuth|TokenAuth" --type python
```
---
**Last Updated**: January 24, 2026
**Status**: Phase 3 Complete (Full Architecture Refactoring + FastMCP v3 Integration)
