# mcp_photo — MCP Image Generation Server

An MCP server for generating and editing images via the OpenRouter API. Deployed in Docker, connects to Claude Desktop through stdio transport. Supports dynamic model discovery from OpenRouter and model metadata caching for optimized performance.

> **[Документация на русском](#документация-на-русском)**

## Features

- **generate_image** — generate an image from a text prompt with support for multiple models; `project` — organize output into `output/{project}/` subfolders (optional, defaults to `_default`); `save_dir` — directory for saving output (optional, takes priority over `project`)
- **edit_image** — image-to-image editing (replacing or transforming part of an image); `project` — organize output into `output/{project}/` subfolders (optional, defaults to `_default`); `save_dir` — directory for saving output (optional, takes priority over `project`)
- **list_models** — dynamic list of available models with pricing and parameter details

## Requirements

- Python 3.11+
- Docker Desktop
- OpenRouter API key (https://openrouter.ai)

## Quick Start

1. Clone the repository:
   ```bash
   git clone https://github.com/afr13nd77/mcp_photo.git
   cd mcp_photo
   ```

2. Copy `.env.example` to `.env` and add your OpenRouter API key:
   ```bash
   cp .env.example .env
   # Edit .env: OPENROUTER_API_KEY=sk_...
   ```

3. Build the container:
   ```bash
   docker compose build
   ```

4. Start the server:
   ```bash
   docker compose run --rm -i mcp-photo
   ```

## Claude Desktop Integration

Add the following block to your `~/.claude/claude_desktop_config.json` config:

```json
{
  "mcpServers": {
    "mcp-photo": {
      "command": "docker",
      "args": ["compose", "-f", "I:/ai_projects/mcp_photo/docker-compose.yml", "run", "--rm", "-i", "mcp-photo"]
    }
  }
}
```

## Supported Models

| Tier | Model | ID | Price/img | Note |
|------|-------|-----|-----------|------|
| **Tier 1** | Gemini 3.1 Flash | `google/gemini-3.1-flash-image` | $0.00006 | Default |
| **Tier 1** | Gemini 3.1 Flash Lite | `google/gemini-3.1-flash-lite-image` | $0.00003 | Lightweight version |
| **Tier 1** | GPT-4 Vision | `openai/gpt-image-2` | $0.00003 | OpenAI vision |
| **Tier 1** | DALL-E 3 | `openai/gpt-image-1` | $0.00004 | DALL-E generation |

**Note**: The full list of available models and their current pricing is discovered dynamically when the `list_models` tool is invoked. The table above lists the most commonly used Tier 1 models.

## Configuration

| Variable | Type | Description | Default |
|----------|------|-------------|---------|
| `OPENROUTER_API_KEY` | string | OpenRouter API key | _(required)_ |
| `OUTPUT_DIR` | string | Directory for saved images | `./output` |
| `DEFAULT_MODEL` | string | Default model for generate_image | `google/gemini-3.1-flash-image` |
| `MODEL_CACHE_TTL` | float | Model cache time-to-live (seconds) | `3600` |
| `REQUEST_TIMEOUT` | float | Timeout for OpenRouter requests (seconds) | `120` |
| `MAX_RETRIES` | int | Maximum number of retries on error | `2` |
| `MAX_PROMPT_LENGTH` | int | Maximum text prompt length | `10000` |
| `MAX_SOURCE_IMAGE_SIZE` | int | Maximum source image size (bytes) | `20971520` (20 MB) |
| `ALLOWED_DIRS` | string | Comma-separated list of allowed directories for image loading | _(empty — any)_ |
| `LOG_LEVEL` | string | Log level (DEBUG, INFO, WARNING, ERROR) | `INFO` |

## Development

Install development dependencies:
```bash
pip install -e ".[dev]"
```

Run tests:
```bash
pytest
```

Lint:
```bash
ruff check .
```

Format:
```bash
ruff format .
```

## Version

**0.1.0** — Initial release with full MCP server functionality.

---

# Документация на русском

# mcp_photo — MCP-сервер генерации изображений

MCP-сервер для генерации и редактирования изображений через OpenRouter API. Развёртывается в Docker, подключается к Claude Desktop через stdio-транспорт. Поддерживает динамическое обнаружение моделей из OpenRouter и кэширование метаданных моделей для оптимизации производительности.

## Возможности

- **generate_image** — генерация изображения по текстовому промпту с поддержкой различных моделей; `project` — организация в подпапки `output/{project}/` (опционально, по умолчанию `_default`); `save_dir` — директория для сохранения (опционально, имеет приоритет над `project`)
- **edit_image** — image-to-image редактирование (замена или трансформация части изображения); `project` — организация в подпапки `output/{project}/` (опционально, по умолчанию `_default`); `save_dir` — директория для сохранения (опционально, имеет приоритет над `project`)
- **list_models** — динамический список доступных моделей с информацией о ценах и параметрах

## Требования

- Python 3.11+
- Docker Desktop
- OpenRouter API key (https://openrouter.ai)

## Быстрый старт

1. Клонируйте репозиторий:
   ```bash
   git clone https://github.com/afr13nd77/mcp_photo.git
   cd mcp_photo
   ```

2. Скопируйте `.env.example` в `.env` и вставьте ваш OpenRouter API key:
   ```bash
   cp .env.example .env
   # Отредактируйте .env: OPENROUTER_API_KEY=sk_...
   ```

3. Соберите контейнер:
   ```bash
   docker compose build
   ```

4. Запустите сервер:
   ```bash
   docker compose run --rm -i mcp-photo
   ```

## Подключение к Claude Desktop

Добавьте следующий блок в конфиг `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mcp-photo": {
      "command": "docker",
      "args": ["compose", "-f", "I:/ai_projects/mcp_photo/docker-compose.yml", "run", "--rm", "-i", "mcp-photo"]
    }
  }
}
```

## Поддерживаемые модели

| Уровень | Модель | ID | Цена/img | Примечание |
|---------|--------|-----|----------|-----------|
| **Tier 1** | Gemini 3.1 Flash | `google/gemini-3.1-flash-image` | $0.00006 | По умолчанию |
| **Tier 1** | Gemini 3.1 Flash Lite | `google/gemini-3.1-flash-lite-image` | $0.00003 | Облегчённая версия |
| **Tier 1** | GPT-4 Vision | `openai/gpt-image-2` | $0.00003 | OpenAI vision |
| **Tier 1** | DALL-E 3 | `openai/gpt-image-1` | $0.00004 | DALL-E generation |

**Примечание**: полный список доступных моделей и их актуальные цены обнаруживаются динамически при запуске инструмента `list_models`. Таблица выше содержит Tier 1 модели, наиболее часто используемые.

## Конфигурация

| Переменная | Тип | Описание | По умолчанию |
|-------------|-----|---------|--------------|
| `OPENROUTER_API_KEY` | string | API ключ OpenRouter | _(требуется)_ |
| `OUTPUT_DIR` | string | Директория для сохранённых изображений | `./output` |
| `DEFAULT_MODEL` | string | Модель по умолчанию для generate_image | `google/gemini-3.1-flash-image` |
| `MODEL_CACHE_TTL` | float | Время жизни кэша моделей (секунды) | `3600` |
| `REQUEST_TIMEOUT` | float | Таймаут для запросов к OpenRouter (секунды) | `120` |
| `MAX_RETRIES` | int | Максимальное количество повторов при ошибке | `2` |
| `MAX_PROMPT_LENGTH` | int | Максимальная длина текстового промпта | `10000` |
| `MAX_SOURCE_IMAGE_SIZE` | int | Максимальный размер исходного изображения (байты) | `20971520` (20 МБ) |
| `ALLOWED_DIRS` | string | Comma-separated список допустимых директорий для загрузки изображений | _(пусто — любые)_ |
| `LOG_LEVEL` | string | Уровень логирования (DEBUG, INFO, WARNING, ERROR) | `INFO` |

## Разработка

Установка зависимостей для разработки:
```bash
pip install -e ".[dev]"
```

Запуск тестов:
```bash
pytest
```

Проверка кода:
```bash
ruff check .
```

Форматирование кода:
```bash
ruff format .
```

## Версия

**0.1.0** — Первый релиз с полной функциональностью MCP-сервера.