Metadata-Version: 2.4
Name: gpt-image-2-polza-mcp-server
Version: 0.6.0
Summary: GPT Image 2 generation and editing through the Polza API
Project-URL: Homepage, https://github.com/ivankhokholkov/gpt-image-2-polza-mcp
Project-URL: Repository, https://github.com/ivankhokholkov/gpt-image-2-polza-mcp.git
Project-URL: Documentation, https://github.com/ivankhokholkov/gpt-image-2-polza-mcp#readme
Project-URL: Bug Tracker, https://github.com/ivankhokholkov/gpt-image-2-polza-mcp/issues
Author-email: Ivan Khokholkov <ivankhokholkov@gmail.com>
License: MIT
License-File: LICENSE
Keywords: 4k,fastmcp,gpt-image-2,image-generation,mcp,openai,polza,polza-ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.11.0
Requires-Dist: pillow>=10.4.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.1
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: fastmcp>=2.11.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
Requires-Dist: mkdocs>=1.4.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.20.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Requires-Dist: responses>=0.23.0; extra == 'test'
Description-Content-Type: text/markdown

# GPT Image 2 Polza MCP Server

MCP-сервер для генерации и редактирования изображений моделью **GPT Image 2**
через API-провайдера [Polza](https://polza.ai).

- Провайдер: `Polza`
- Model ID: `openai/gpt-5.4-image-2`
- Model tier: `gpt-image-2`
- Поддержка генерации, редактирования и референсных изображений
- Сохранение полноразмерных файлов на диск
- Возврат превью и структурированных метаданных через MCP

Для работы нужен только `POLZA_AI_API_KEY`. Отдельный ключ OpenAI не требуется.

## Инструменты MCP

- `generate_image` — создаёт или редактирует изображения с помощью GPT Image 2.
- `fetch_generation` — получает результат уже запущенной генерации по `gen_...` ID.
- `upload_file` — загружает референс в Polza Storage.
- `show_output_stats` — показывает статистику локальной папки с результатами.
- `maintenance` — обслуживает локальный кэш и базу метаданных.

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

- Python 3.11+
- [uv](https://docs.astral.sh/uv/)
- Аккаунт Polza и `POLZA_AI_API_KEY`
- Любой MCP-клиент: Claude Code, Claude Desktop, Cursor, VS Code или другой

## Быстрая установка

Клонируйте репозиторий:

```bash
git clone https://github.com/ivankhokholkov/gpt-image-2-polza-mcp.git
cd gpt-image-2-polza-mcp
uv sync
```

Создайте `.mcp.json`:

```json
{
  "mcpServers": {
    "gpt-image-2-polza": {
      "command": "uv",
      "args": [
        "run",
        "gpt-image-2-polza-mcp-server"
      ],
      "cwd": "/absolute/path/to/gpt-image-2-polza-mcp",
      "env": {
        "POLZA_AI_API_KEY": "your-polza-api-key",
        "POLZA_BASE_URL": "https://polza.ai/api",
        "IMAGE_OUTPUT_DIR": "/absolute/path/to/gpt-image-2-output"
      }
    }
  }
}
```

Перезапустите MCP-клиент после добавления конфигурации.

## Использование

Обычная генерация:

```text
Создай рекламный кадр флакона духов на чёрном камне,
кинематографический свет, формат 16:9, разрешение 4K.
Используй gpt-image-2.
```

Основные параметры `generate_image`:

| Параметр | Описание |
|---|---|
| `prompt` | Текстовое описание изображения или инструкция по редактированию |
| `mode` | `generate`, `edit` или автоматическое определение |
| `model_tier` | `gpt-image-2`; используется по умолчанию |
| `resolution` | `1k`, `2k`, `4k` или `high` |
| `aspect_ratio` | Например, `1:1`, `16:9`, `9:16`, `4:5` |
| `input_image_path_1` | Путь к основному референсу или редактируемому изображению |
| `input_image_path_2` | Второй референс |
| `input_image_path_3` | Третий референс |
| `output_path` | Конкретный файл или папка для результата |
| `force_new_generation` | Принудительно запустить новую генерацию вместо использования кэша |

## Восстановление после таймаута

Генерация может продолжаться на стороне Polza после таймаута MCP-клиента. Не
запускайте тот же запрос повторно сразу: это может создать и оплатить ещё одну
генерацию.

Получите `gen_...` ID в истории генераций Polza и вызовите:

```text
fetch_generation(
  media_id="gen_2158267363095220225",
  output_path="/absolute/path/to/result.png"
)
```

## Переменные окружения

| Переменная | Обязательно | Описание |
|---|---|---|
| `POLZA_AI_API_KEY` | Да | API-ключ аккаунта Polza |
| `POLZA_BASE_URL` | Нет | Базовый URL API; по умолчанию `https://polza.ai/api` |
| `IMAGE_OUTPUT_DIR` | Нет | Папка результатов; по умолчанию `~/gpt-image-2-images` |
| `GPT_IMAGE_MODEL` | Нет | Model tier; по умолчанию `gpt-image-2` |
| `POLZA_POLL_INTERVAL_SECONDS` | Нет | Интервал проверки статуса генерации |
| `POLZA_POLL_TIMEOUT_SECONDS` | Нет | Максимальное время ожидания результата |
| `POLZA_EXTERNAL_USER_ID` | Нет | Внешний ID пользователя для Polza |
| `RETURN_FULL_IMAGE` | Нет | Возвращать полное изображение вместо превью |

## Локальный запуск

```bash
cp .env.example .env
uv sync
uv run gpt-image-2-polza-mcp-server
```

Минимальный `.env`:

```env
POLZA_AI_API_KEY=your-polza-api-key
POLZA_BASE_URL=https://polza.ai/api
GPT_IMAGE_MODEL=gpt-image-2
IMAGE_OUTPUT_DIR=/absolute/path/to/gpt-image-2-output
```

## API Polza

Сервер использует:

- `POST /v1/media` — запуск генерации
- `GET /v1/media/{id}` — получение статуса и результата
- `POST /v1/storage/upload` — загрузка референсов
- `GET /v1/storage/files/{id}` — метаданные файла
- `DELETE /v1/storage/files/{id}` — удаление файла

## Лицензия

MIT. См. [LICENSE](LICENSE).
