PsMCP
by w1zzyakik
README.md
<img src="assets/banner.svg" alt="PsMCP — MCP-сервер для Adobe Photoshop" width="100%">
# PsMCP — MCP-сервер для Adobe Photoshop
Управление Photoshop из любого MCP-клиента (opencode, Claude Desktop, Cursor, ...).
Ничего не устанавливается внутрь Photoshop: сервер говорит с ним по COM
(`Photoshop.Application.DoJavaScript`), а если Photoshop не запущен — COM запускает его сам.
## Что умеет
| Инструмент | Что делает |
|---|---|
| `ps_eval` | Выполняет **любой** ExtendScript в Photoshop и возвращает результат в JSON. Это вся объектная модель: документы, слои, текст, маски, выделения, фильтры, каналы, смарт-объекты, сохранение и экспорт. Не зависает: при модальном диалоге возвращает понятную ошибку. |
| `ps_dialogs` | Показывает модальные диалоги Photoshop и нажимает в них кнопку (`cancel` / `ok` / текст кнопки). Работает без COM — вытаскивает Photoshop из зависшего вызова. |
| `ps_screenshot` | Скриншот окна Photoshop — весь интерфейс: панели, слои, документ. |
| `ps_preview` | Предпросмотр: активный документ рендерится в PNG (с учётом слоёв и масок), сам документ не меняется. |
## Требования
* Windows, Adobe Photoshop 2022+ (проверено на 2024, 25.12).
* Python 3.10+ с пакетами `mcp`, `pywin32`, `pillow`.
* Photoshop должен быть зарегистрирован в COM с `/Automation` — обычная установка это делает
(ключ `HKLM\SOFTWARE\Classes\CLSID\{DD6CF2ED-4840-40A1-A393-B1F74F54D59A}\LocalServer32`).
## Установка
```powershell
cd F:\PsMCP
py -3.11 -m pip install -r requirements.txt
```
Проверка на живом Photoshop (запускает его, если закрыт):
```powershell
py -3.11 tests/smoke.py # eval, фильтры, сохранение, предпросмотр, скриншот
py -3.11 tests/dialogs.py # модальный диалог не вешает сервер
py -3.11 tests/stdio.py # протокол MCP: handshake, tools/list, tools/call
```
## Подключение к MCP-клиенту
opencode / любой клиент с форматом `mcp`:
```json
"photoshop": {
"type": "local",
"command": ["C:/Program Files/Python311/python.exe", "F:/PsMCP/server.py"],
"enabled": true
}
```
Claude Desktop (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"photoshop": {
"command": "C:/Program Files/Python311/python.exe",
"args": ["F:/PsMCP/server.py"]
}
}
}
```
## Примеры
```js
// что открыто
({docs: app.documents.length, active: app.activeDocument.name})
// новый документ
var d = app.documents.add(1920, 1080, 72, "Banner", NewDocumentMode.RGB, DocumentFill.WHITE);
d.layers.length
// текст
var t = app.activeDocument.artLayers.add();
t.kind = LayerKind.TEXT;
t.textItem.contents = "Привет";
t.textItem.size = 120;
// фильтр по тексту: сначала растеризовать, иначе Photoshop спросит разрешение
t.rasterize(RasterizeType.ENTIRELAYER);
t.applyGaussianBlur(2.5);
// сохранить
app.activeDocument.saveAs(new File("C:/work/banner.psd"), new PhotoshopSaveOptions(), false, Extension.LOWERCASE);
```
Особенности ExtendScript, которые полезно помнить:
* это ES3 — нет `JSON`, `let/const`, стрелок, `Array.prototype.map/forEach`;
* коллекции 0-based: `app.documents[0]`, `doc.layers[0]` (верхний слой), а `itemIndex` у слоя — 1-based;
* `UnitValue` печатается как `{}` — берите `.value` или `.as("px")`;
* операции над текстом, которые не умеет текстовый слой (фильтры, часть трансформаций),
вызывают диалог «растрировать или преобразовать в смарт-объект» — растеризуйте заранее
или отвечайте на диалог через `ps_dialogs`.
## Диалоги и зависания
Photoshop показывает модальные диалоги прямо посреди скрипта. Сервер устроен так, что это
не вешает MCP:
* скрипты идут через один COM-поток, поэтому занятый Photoshop возвращает ошибку, а не
бесконечное ожидание;
* если Photoshop отказал из-за модального окна, ошибка сразу называет диалог и его кнопки;
* `ps_dialogs` находит такие окна (в том числе собственный класс Photoshop `PSDialogBox`) и
жмёт кнопку: `ps_dialogs(close="cancel")`, `ps_dialogs(close="ok")`,
`ps_dialogs(close="Растрировать")`;
* у `ps_eval` / `ps_preview` есть параметр `timeout` (секунды, по умолчанию 120) — им
ограничивается ожидание ответа.
Если предыдущий скрипт всё ещё выполняется, новый вызов сразу вернёт «Photoshop занят»:
закройте диалог, и Photoshop доиграет прерванный скрипт.
## Поведение и ограничения
* Первый вызов при закрытом Photoshop стоит 10–20 с — COM запускает приложение.
* Скриншот окна сначала снимается через `PrintWindow`, а если Windows вернул пустой кадр
(холст рисуется через GPU) — через Grab экрана; во втором случае окно Photoshop выводится
на передний план.
* Готовые картинки складываются в `out/` рядом с `server.py`.
* Диалоги не закрываются автоматически: подтверждать растеризацию или сохранение должен
тот, кто вызвал инструмент.
## Файлы
```
server.py MCP-сервер: COM-мост с таймаутом, диалоги, скриншот окна, рендер документа
jsx/psmcp.jsx ExtendScript-обвязка: запуск кода + JSON-сериализатор
tests/smoke.py живой селф-чек инструментов
tests/dialogs.py модальный диалог не вешает сервер
tests/stdio.py MCP-протокол end-to-end
assets/banner.svg шапка README
```
## Лицензия
MIT
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues