Photoshop Full MCP v2

Photoshop Full MCP v2 — это локальный MCP-сервер для Photoshop с ограничением по возможностям. Он ориентирован на установленный Photoshop 2026 (27.9), избегая предположений о версии и пути установки.

Быстрый старт для Windows

Предварительные требования: Windows 10/11, Photoshop 24 или новее, Node.js 20 или новее, а также Codex Desktop или Codex CLI. Photoshop 2026 (27.9) является эталонным хостом.

1. Скачайте photoshop-full-mcp-v2.0.1-windows.zip из последнего релиза, затем распакуйте его. Прилегающий подписанный манифест и подпись аутентифицируют будущие обновления в приложении; файл .sha256 — необязательная проверка целостности.

2. Откройте PowerShell в распакованной папке photoshop-full-mcp-2.0.1 и выполните:

   powershell -NoProfile -ExecutionPolicy Bypass -File .\Install.ps1

   Установщик проверяет встроенную среду выполнения, устанавливает её в %LOCALAPPDATA%\PS_MCP и регистрирует отдельный сервер photoshop_full_mcp. Папка загрузки/проверки после этого больше не нужна.

3. Дважды щёлкните включённый photoshop-full-mcp-v2.0.1.ccx, чтобы установить плагин Photoshop. Если установка CCX недоступна, используйте Adobe UXP Developer Tools и выберите установленный манифест, показанный Doctor.

4. Перезапустите Codex, откройте Photoshop, затем выберите Plugins > Photoshop Full MCP Bridge.

5. В Codex вызовите photoshop_pairing_begin, введите полное значение port-code, показанное доверенным диалогом Windows в панели Photoshop, и вызовите photoshop_host_describe. Ответ с bridge.connected: true — это проверка первого успеха.

Запустите Doctor в любое время:

powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Doctor.ps1"

Режим одобрения по умолчанию — автоматический. Обычные команды редактирования не требуют одобрения по одному клику. См. иллюстрированное руководство по установке для Windows и руководство по устранению неполадок для шагов обновления, удаления и восстановления.

Он не утверждает, что каждая функция интерфейса Photoshop может быть автоматизирована. Каталог разделяет:

• supported: реализовано и подтверждено живым фикстуром Photoshop на целевом хосте

• experimental: зависит от прав, модели, сети или кредитов

• requires_user: создаёт неблокирующее задание с явными инструкциями из нативного меню, которые пользователь должен выполнить; он не автоматизирует клики ОС

• unverified: внесено в каталог, но заблокировано до прохождения локального фикстура

• unavailable: нет известного надёжного контракта UXP для настольного приложения

Related MCP server: Photoshop MCP Server

Архитектура

• MCP-сервер: Node.js/TypeScript через stdio

• Мост Photoshop: панель UXP Manifest v5 через аутентифицированный 127.0.0.1

• Обнаружение: порты 38452–38462

• Сопряжение: кратковременный 128-битный port-code capability, отображаемый только в доверенном локальном диалоге Windows, открываемом photoshop_pairing_begin

• Выполнение: проверка схемы, политика возможностей/рисков, очередь FIFO, executeAsModal, группировка в одну историю и проверка состояния до/после

• Одобрения: автоматические по умолчанию; одноразовые токены с ограничением области, защита от повторного воспроизведения, ограничения путей и расширенные списки разрешённых дескрипторов остаются в силе

• Файловый мост по умолчанию: экспорт и ограниченное повторное открытие используют папку %LOCALAPPDATA%\PS_MCP\exports, принадлежащую серверу, без выбора файла; пользовательская постоянная папка UXP остаётся необязательной

• Расширенный raw batchPlay: скрыт по умолчанию; установите PS_MCP_ADVANCED=confirm, чтобы открыть только дескрипторы deselect и invert без параметров. Другие raw-дескрипторы и весь raw JSX отклоняются до того, как достигнут Photoshop

• Телеметрия: отсутствует

Обширный перечень функций находится в catalog/features.json. Исполняемые контракты — в catalog/commands.json.

Текущее проверенное состояние: 101 контракт команд (87 supported, 1 experimental, 0 unverified, 11 requires_user, 2 unavailable) и 52 группы функций (21 supported, 1 experimental, 0 unverified, 10 requires_user, 20 unavailable). Команда или группа функций переводится в supported только после того, как её подписанный живой фикстур Photoshop 27.9 пройдёт проверку. Недействительные унаследованные дескрипторы Generative Fill и Neural Filter явно недоступны, а некорректные или не входящие в список разрешённых raw-дескрипторы отклоняются на стороне сервера, чтобы они не открывали диалог неизвестной команды Photoshop.

Установка из исходного кода

Рекомендуется установка из ZIP-релиза выше. Участники могут вместо этого клонировать репозиторий и выполнить:

npm ci --no-audit --no-fund
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\Install-Local.ps1

Обёртка совместимости собирается один раз, копирует автономную производственную среду выполнения в %LOCALAPPDATA%\PS_MCP и регистрирует эту установленную копию. Перемещение или удаление исходного кода после этого не нарушает работу MCP-сервера. Установщик регистрирует photoshop_full_mcp рядом с существующим photoshop_mcp; он не удаляет и не изменяет старый пакет.

Для плагина UXP выполните npm run uxp:package и установите сгенерированный CCX, либо загрузите установленный манифест, указанный Doctor, в Adobe UXP Developer Tools. При желании выберите папку экспорта на панели. Без неё document.export использует аутентифицированную папку экспорта по умолчанию, принадлежащую серверу.

Обновление и удаление

# Download, verify, and install the newest GitHub release
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Update.ps1"

# Remove the installed runtime and Codex registration; preserve pairing and exports
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Uninstall.ps1"

# Also remove pairing state and exports
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Uninstall.ps1" -RemoveUserData

Безопасная последовательность использования

1. photoshop_host_describe

2. photoshop_capability_list

3. photoshop_state_get

4. photoshop_command_search / photoshop_command_describe

5. photoshop_command_execute

6. photoshop_preview_get после визуальных изменений

Деструктивные, проверочные, расходующие кредиты и разрешённые расширенные команды автоматически одобряются локальным сервером, поэтому клик одобрения на панели Photoshop не требуется. photoshop_approval_request остаётся как API совместимости и немедленно возвращает завершённое задание с ограниченной областью. Установите PS_MCP_APPROVAL_MODE=panel только если вы намеренно хотите прежний рабочий процесс с кликом для одобрения. Песочница путей, шлюзы статуса возможностей, защита от повторного воспроизведения и списки разрешённых raw-дескрипторов не обходятся.

Для локальной проверки хоста запустите временный сервер с PS_MCP_VALIDATION=confirm. Это открывает photoshop_validation_request и photoshop_command_validate. Они принимают только каталогизированные непроверенные команды UXP DOM, автоматически одобряются по умолчанию и работают только с документами, названными PS_MCP_VALIDATION_*. Выполнение проверки никогда не повышает capability автоматически.

Инвентаризация и аудит живых доказательств

npm run check включает машинный аудит каждой записи команд и функций. Аудит сообщает о наличии обработчика, происхождении живого фикстура, расхождении дайджеста контракта каталога и согласованности статуса/движка/маршрута. Команда или функция supported не проходит проверку, если нет соответствующего фикстура с транзакционной привязкой в evidence/live, поэтому только реализация или строка документации не могут повысить поддержку.

Сгенерируйте полный отчёт только для чтения с помощью:

npm run audit:inventory:json

Проверка повышения дополнительно требует свежего результата photoshop_host_describe, мост которого в данный момент подключён. Сам живой фикстур также должен иметь действительную локальную подпись доказательства:

npm run audit:promotion -- --promotion-command selection.ellipse --host-report .\host-describe.json

Команда завершается с LIVE_HOST_DISCONNECTED, когда мост UXP не активен, даже если существует более старый фикстур. Доказательства больше не принимаются из JSON хоста, результата или утверждения, созданных вызывающей стороной. Рекордер сам запускает MCP-сессию с профилем проверки, проверяет подключённую личность Photoshop, получает автоматическое одобрение с ограниченной областью, выполняет команду в документе PS_MCP_VALIDATION_*, проверяет хэши состояния и пиксельного предпросмотра, выполняет цикл отмены при необходимости, закрывает временный документ и подписывает квитанцию транзакции:

Set-Content .\validation-args.json '{"left":0,"top":0,"right":64,"bottom":64}'
npm run evidence:record -- --command selection.ellipse --args .\validation-args.json

Приватный ключ подписи доказательств хранится в %LOCALAPPDATA%\PS_MCP с ACL только для пользователя; в репозитории хранится только публичный ключ проверки. Рекордер записывает только хэши и разрешённые метаданные хоста/проверки. Он не копирует пиксели, содержимое или имена документов, подсказки, токены моста, аргументы запросов или необработанные результаты Photoshop. Запись доказательств не редактирует catalog/commands.json; повышение статуса остаётся отдельным проверенным изменением.

Проверка

npm run check
npm test
npm --prefix apps\uxp-plugin run check
npm run build
npm run test:contract

Живые генеративные тесты намеренно исключены. Они должны быть явно одобрены, так как могут расходовать кредиты и зависеть от вошедшей учётной записи Adobe.

Если проверочный запуск прерван, осмотрите активный документ перед очисткой. Команда обслуживания по умолчанию выполняется в режиме сухого прогона и останавливается, как только активный заголовок не является принадлежащим проверочным заголовком PS_MCP_*:

npm run cleanup:owned-documents
npm run cleanup:owned-documents -- --apply

Добавление записанного ActionJSON

Захватите команду с помощью рекордера действий разработчика Photoshop, затем сгенерируйте непроверенную запись каталога:

node .\scripts\import-action-recording.mjs --id filters.example --category filter --en "Example Filter" --ko "예제 필터" --file .\recording.json

Импортёр выводит определение каталога и дайджест доказательства SHA-256. Он никогда не повышает команду до supported; повышение требует интеграционного фикстура с изолированным документом.

Расположение данных

• Секрет сопряжения и метаданные конечной точки: %LOCALAPPDATA%\PS_MCP

• Экспорт по умолчанию: %LOCALAPPDATA%\PS_MCP\exports

• Токен UXP: защищённое хранилище UXP Photoshop

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