Skip to main content
Glama
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