Плагин GPT Image 2 для Claude Desktop Code

Создавайте и редактируйте изображения проектов с помощью OpenAI GPT Image 2 через встроенный локальный MCP-сервер. Плагин записывает одно проверенное изображение за платный вызов, сохраняет файлы в одобренной рабочей области проекта и никогда не перезаписывает существующий целевой файл.

English

Поддерживаемая поверхность Claude

Этот плагин предназначен для Claude Desktop Code — ориентированного на проекты режима Code в приложении Claude Desktop. Claude Desktop Chat не поддерживается. Это не пакет MCPB и не удаленный MCP-сервис.

Related MCP server: mcp-openai-images-audio

Установка через графический интерфейс Claude Desktop Code

Установка плагина через графический интерфейс является основным способом:

1. Откройте целевой проект в Claude Desktop Code.

2. Откройте графический интерфейс Настройки → Плагины. Названия могут незначительно отличаться в зависимости от версии Claude.

3. Добавьте корень этого репозитория как локальный маркетплейс или выберите его источник репозитория, затем установите gpt-image-2@kpk-plugins.

4. Включите установленный плагин для текущего проекта. Включение привязано к проекту; установка не предоставляет автоматический доступ ко всем проектам.

5. Откройте настройки плагина для конфигурации. Не копируйте .mcp.json в обычные настройки.

Корень плагина является корнем маркетплейса, а точка входа маркетплейса указывает на ./.

Требования к среде выполнения

Единственная зависимость среды выполнения — Node.js 20+, доступный в PATH, который видит Claude Desktop Code. Установленный плагин запускает предварительно собранный dist/server.mjs напрямую. Во время выполнения плагин не запускает npm, npx, скрипты жизненного цикла, компиляцию исходного кода и не загружает node_modules.

Зафиксированная копия маркетплейса включает автономный пакет. Тест установленной копии запускает только файлы, отслеживаемые Git, и проверяет, что get_status работает без наличия каталога node_modules и без API-ключа.

npm и зависимости для разработки нужны только участникам, собирающим или тестирующим исходный код.

Настройка в графическом интерфейсе

В настройках плагина введите API-ключ в защищенное поле OpenAI API key. Не помещайте его в командную строку, .env, .mcp.json, обычные настройки, README, подсказку или лог, и не просите Claude отображать или проверять его.

Базовый URL по умолчанию:

https://api.openai.com/v1

Пользовательский базовый URL получает API-ключ, подсказки и изображения для редактирования, отправляемые этим плагином. Настраивайте его только в том случае, если вы доверяете этой конечной точке и ее оператору. Пользовательская конечная точка обычно должна включать /v1; плагин не добавляет его автоматически. Единственный пример в пользовательской документации:

https://api.example.invalid/v1

URL должен быть абсолютным HTTP(S) URL без учетных данных, запроса, фрагмента, управляющих символов или окружающих пробелов. Совместимая конечная точка должна реализовывать API изображений, используемый клиентом OpenAI; совместимость не подразумевается только из-за принятия URL.

HTTP разрешен для доверенных локальных или частных сетевых совместимых конечных точек, но он отправляет API-ключ, подсказки и изображения для редактирования без шифрования передачи. Используйте базовый URL http:// только в сети и конечной точке, которым вы доверяете; в противном случае предпочитайте HTTPS.

Запустите /gpt-image-2:setup после установки. Команда вызывает только get_status и не отправляет запросы провайдеру.

Инструменты

get_status

Сообщает только безопасные данные о состоянии: логическое значение наличия API-ключа, настроен ли пользовательский базовый URL, base_url_valid: true для активного URL работающего сервера, одобренные корни рабочей области, модель, версия сервера и относительный каталог вывода по умолчанию. Неверный настроенный базовый URL предотвращает запуск сервера; исправьте его в настройках плагина и перезагрузите или перезапустите плагин. get_status не отправляет никаких запросов провайдеру или API изображений и никогда не возвращает значение ключа или базового URL.

generate_image

Генерирует одно изображение с моделью gpt-image-2, фиксированным n: 1, и сохраняет один новый файл. Основные входные данные:

• prompt

• quality: auto, low, medium или high

• size

• output_format: png, jpeg или webp

• необязательное сжатие JPEG/WebP output_compression от 0 до 100

• moderation: auto или low

• необязательный относительный output_path и одобренный workspace_root

edit_image

Редактирует от одного до восьми входных изображений в указанном порядке и сохраняет одно новое изображение. Входные данные могут быть в формате PNG, JPEG или WebP. Ограничение составляет 50 МиБ на входное изображение и 200 МиБ в сумме для всех изображений редактирования плюс необязательная маска.

Необязательная маска должна быть PNG с альфа-каналом, соответствовать размерам первого входного изображения и быть меньше 4 МиБ. Прозрачный фон вывода не поддерживается; альфа-канал маски определяет только область редактирования.

Форматы, размеры и вывод

• Форматы вывода: PNG, JPEG и WebP.

• Размер по умолчанию для инструмента — 1024x1024. Также принимается auto.

• Пользовательский WIDTHxHEIGHT должен быть кратен 16, каждая сторона должна быть не более 3840 пикселей, соотношение сторон должно быть от 1:3 до 3:1, а общее количество пикселей должно быть от 655 360 до 8 294 400.

• PNG не использует сжатие вывода. JPEG и WebP принимают значения сжатия от 0 до 100.

• Если output_path опущен, вывод сохраняется в .claude/generated-images/gpt-image-2 с уникальным именем файла без подсказки.

• Явные пути вывода сохраняются, должны быть относительными по отношению к одобренному корню рабочей области и должны использовать расширение, соответствующее запрошенному формату.

• Существующие целевые файлы отклоняются. Публикация без перезаписи также предотвращает одновременные вызовы от замены одного и того же целевого файла.

Фактические размеры сохраняются и сообщаются после декодирования и проверки сохраненного изображения. Если запрошенный явный размер отличается, файл сохраняется с его фактическими размерами, и результат включает SIZE_MISMATCH.

Изображения размером 2 МиБ или меньше включают встроенный предварительный просмотр. Для изображений большего размера встроенный предварительный просмотр опускается; сохраненный путь к файлу остается авторитетным. TEMP_CLEANUP_PENDING означает, что вывод был успешно сохранен, но очистка временного файла публикации все еще ожидается.

Стоимость, параллелизм и повторные попытки

Генерация и редактирование являются платными операциями провайдера. Плагин фиксирует один вывод на запрос и разрешает один платный вызов за раз в каждом процессе сервера. Повторные попытки SDK и приложения отсутствуют, поэтому неудачный платный вызов не повторяется автоматически. Подтвердите подсказки, входные данные редактирования, размер, формат и путь вывода перед вызовом инструмента изображения.

Рабочая область и границы безопасности

• Выводы остаются в корне рабочей области, одобренном Claude Desktop Code. Пути вывода не могут быть абсолютными или выходить за пределы корня.

• Содержащиеся абсолютные пути ввода принимаются только в том случае, если они уже разрешаются внутри одобренного корня; путь ввода никогда не предоставляет новый корень.

• Входные файлы копируются через стабильные дескрипторы в частные временные снимки перед загрузкой. Оригиналы не изменяются.

• Вывод провайдера строго декодируется, проверяется на изображение, сбрасывается и публикуется с семантикой без перезаписи.

• Логи принимают только ограниченные коды состояния и числовой контекст; подсказки, API-ключи, базовые URL, данные изображений, Base64 и полные пути ввода исключаются.

Граница Junction в Windows Node 20

В Windows под Node 20 существующие обходы reparse-point/Junction отклоняются, а родительские пути вывода повторно проверяются непосредственно перед эксклюзивной публикацией. Активная замена каталога другим процессом с теми же полномочиями между проверками остается за пределами границы угрозы. Для полного устранения гонки замены с теми же полномочиями потребуется собственный вспомогательный дескриптор Win32.

Устранение неполадок

• API-ключ не настроен: откройте настройки плагина Claude Desktop Code и заполните защищенное поле API-ключа. Не вставляйте ключ в чат или оболочку.

• Неверный или неиспользуемый пользовательский базовый URL: неверный настроенный базовый URL предотвращает запуск сервера. Исправьте его в настройках плагина, подтвердите сохранение настройки, затем перезагрузите или перезапустите плагин. Пользовательские конечные точки обычно должны заканчиваться на /v1; сегмент /v1 не добавляется автоматически.

• Нет одобренного корня рабочей области: откройте проект в Claude Desktop Code и включите плагин для этого проекта.

• OUTPUT_EXISTS: выберите новый относительный путь вывода. Плагин не будет перезаписывать.

• SIZE_MISMATCH: используйте возвращенные фактические ширину и высоту; сохраненное изображение допустимо.

• Предварительный просмотр опущен: откройте возвращенный относительный или абсолютный путь; встроенные предварительные просмотры ограничены 2 МиБ.

Сборка и тестирование из исходного кода

Команды разработки могут устанавливать и использовать зависимости для разработки; они не являются частью поведения установленного плагина во время выполнения. Команда проверки отключает неявные хуки жизненного цикла npm перед проверкой того, что одобренный набор скриптов точен.

npm ci --ignore-scripts
npm run typecheck
npm test
npm run build
npm run test:dist
npm --ignore-scripts run validate

Эти проверки используют локальные фикстуры, имитации и протокольные тесты. Платный запрос изображения не требуется. Никакая проверка с живым провайдером не выполнялась и не заявляется.

Лицензия

MIT © 2026 KPK. См. LICENSE и THIRD_PARTY_NOTICES.md.