# Midjourney Proxy MCP Server

MCP server for Midjourney image generation via ImagineAPI.

## Installation

```bash
# Via uvx (recommended)
uvx midjourney-proxy-mcp

# Via pip
pip install midjourney-proxy-mcp
```

## Project Structure

```text
src/midjourney_proxy_mcp/
├── server.py       # FastMCP main server
├── client.py       # ImagineAPI HTTP client
├── config.py       # Environment settings (pydantic-settings)
├── models.py       # Pydantic models for requests/responses
├── tools/          # MCP Tool implementations
├── resources/      # MCP Resource implementations
└── prompts/        # MCP Prompt templates
tests/              # pytest tests
.claude-plugin/     # Claude Code plugin manifest
.claude/skills/     # Prompt optimization skills
.github/workflows/  # CI/CD workflows
```

## Development Commands

```bash
# Install dependencies
uv sync

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=midjourney_proxy_mcp

# Type checking
uv run mypy src/

# Linting
uv run ruff check src/ tests/

# Format code
uv run ruff format src/ tests/

# Run server (for testing)
uv run midjourney-proxy-mcp
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `IMAGINEAPI_URL` | ImagineAPI base URL | `https://cl.imagineapi.dev` |
| `IMAGINEAPI_TOKEN` | API authentication token | (required) |

## Architecture

### Core Components

- `client.py` - ImagineAPI async HTTP client with httpx
- `models.py` - Pydantic v2 models (ImageRequest, ImageData, ImageStatus, etc.)
- `config.py` - Environment settings with pydantic-settings
- `server.py` - FastMCP server with Tools

### MCP Primitives

**Tools** (Actions):
- `midjourney_imagine` - Generate images from prompt
- `midjourney_get_status` - Get image status with upscaled_urls
- `midjourney_get_image` - Get image data for inline display (returns Image object)
- `midjourney_list_images` - List recent images

**Resources** (Read-only data):
- `midjourney://generations` - All generations list
- `midjourney://generations/{status}` - Filter by status
- `midjourney://generation/{id}` - Single image details
- `midjourney://stats` - Generation statistics

### ImagineAPI Endpoints

| Method | Endpoint | Usage |
|--------|----------|-------|
| POST | `/items/images` | Create new image |
| GET | `/items/images/{id}` | Get image status |
| GET | `/items/images` | List images |

## Plugin Structure

Claude Code plugin bundling MCP server + Skill:

```text
.claude-plugin/
├── plugin.json      # MCP server config + skill references
└── marketplace.json # Self-hosted marketplace config
```

## CI/CD

- `.github/workflows/test.yml` - Run tests on PR/push (Python 3.11/3.12)
- `.github/workflows/publish.yml` - Publish to PyPI on release (trusted publishing)

## Code Conventions

- Use Pydantic v2 with `model_config = ConfigDict(strict=True)` for request models
- Response models should NOT use strict=True for external API compatibility
- All HTTP operations are async (httpx)
- Type hints required for all functions
- Docstrings for all public functions and classes
- Tests in `tests/` directory following `test_*.py` pattern

## Testing

TDD approach - write tests first:
1. Unit tests for models and client
2. Integration tests with mock ImagineAPI (using pytest-httpx)
3. E2E tests with MCP inspector

### Test Patterns
- Use `pytest-httpx` for mocking HTTP calls
- Use `match_json` parameter to validate request bodies
- Use fixtures in `conftest.py` for sample data
- Unit tests use dummy token (set in conftest.py)
- MCP handlers in `server.py` are tested directly via handler function calls
- Coverage excludes `if __name__ == "__main__"` blocks (configured in pyproject.toml)

### Integration Tests
실제 ImagineAPI 호출 테스트를 위해:
- 로컬: `.env`에 `IMAGINEAPI_TOKEN` 설정 후 `uv run pytest -m integration`
- CI: Mock 테스트만 실행 (토큰 없이 자동 skip)

## Documentation

```bash
# Install docs dependencies
uv sync --group docs

# Build documentation
uv run mkdocs build

# Serve locally
uv run mkdocs serve
```

Documentation files:
- `docs/` - MkDocs documentation source
- `llms.txt` - AI-readable API documentation
- `mkdocs.yml` - MkDocs Material configuration

## Related Skills

`.claude/skills/midjourney-imagineapi/` - Midjourney V7 prompt optimization skill

### Skill Contents
```text
.claude/skills/midjourney-imagineapi/
├── SKILL.md                              # Main skill file with workflow
└── references/
    ├── midjourney-parameters.md          # V7 parameter complete guide
    ├── midjourney-style-guide.md         # 5-layer prompt structure
    ├── prompt-examples.md                # Before/after transformations
    └── imagineapi-integration.md         # MCP tool usage guide
```

### Skill Features
- 5-layer prompt structure (Subject, Style, Lighting, Technical, Artistic)
- Interactive workflow with AskUserQuestion for clarification
- V7-optimized parameters (--draft, --exp, --oref, --sref)
- ImagineAPI MCP integration (midjourney_imagine, midjourney_get_status, midjourney_get_image tools)
- 16 transformation examples across genres
