PhotoFresco для AI-агентов

Позвольте AI-агентам редактировать изображения в окне PhotoFresco, подключение к которому вы подтвердили: работать со слоями и масками, просматривать результат и экспортировать файлы.

PhotoFresco — бесплатный графический редактор уровня Photoshop, который работает в браузере. В нём есть слои, маски, корректирующие слои, выделения, кисти, импорт и экспорт PSD, а также полная история действий с возможностью отмены. Этот репозиторий подключает к редактору AI-агентов. Агент (Claude, Cursor, VS Code, Codex, любой MCP-клиент или скрипт командной строки) управляет окном PhotoFresco на вашем компьютере. Вы видите все изменения, разрешаете подключение, выбираете доступные агенту действия и можете в любой момент приостановить или остановить его. Редактирование происходит непосредственно в редакторе, поэтому каждое изменение фиксируется в истории и может быть отменено так же, как ваше собственное.

Выше показана запись реального сеанса: MCP-клиент взаимодействует с этим сервером и редактором. Запись сделана в headless-режиме. Категория: дизайн и редактирование изображений.

Что входит в этот репозиторий:

MCP-сервер (photofresco mcp): отдельный инструмент для каждой операции редактора, предпросмотр в виде изображений, экспорт в файлы или ресурсы. Руководство: MCP.md.
Навык агента (skills/photofresco): объясняет агенту, когда и как эффективно использовать PhotoFresco.
Командная строка (photofresco ): открытие редактора, запуск сохранённых рабочих процессов, экспорт и остановка. Руководство: CLI.md.
Локальный коннектор (библиотека, которую используют остальные три компонента): CONNECTOR.md.

Самого редактора в этом репозитории нет: коннектор открывает его на photofresco.com.

Требования

Node.js версии 22 или новее.
Установленный браузер на базе Chromium: Google Chrome, Microsoft Edge или Chromium версии 120 и новее.

Ничего не скачивается. Если нужно использовать другой браузер, укажите его с помощью --browser (или PHOTOFRESCO_BROWSER).

Работа проверена на macOS; поддержка Windows и Linux реализована, но пока не проверена.

Настройка агента

В один клик (Cursor, VS Code, LM Studio):

Каждая кнопка предлагает приложению добавить сервер photofresco, который запускается через npx из архива исходного кода на GitHub версии 0.1.0 (коммит 328cfaf; из реестра npm ничего не загружается). Доступ к папкам не предоставляется: чтобы разрешить агенту открывать и сохранять файлы, добавьте аргументы --read и --write после mcp в настройках MCP приложения.

В противном случае добавьте сервер в конфигурацию MCP-клиента, как описано ниже. Укажите папки, из которых агенту разрешено открывать файлы (--read), и папки для сохранения экспортированных файлов (--write). Без этих параметров агент сможет редактировать изображения и просматривать результат, но не сможет работать с вашими файлами.

Публикация в npm ещё не состоялась. Пакет photofresco будет опубликован в npm в середине октября 2026 года, поэтому приведённые ниже команды npx -y photofresco@0.1.0 пока не работают. До публикации вместо photofresco@0.1.0 укажите --package=https://github.com/photofresco/photofresco-agent/archive/328cfaf3caf6483c5660381f19f2afdb2059a215.tar.gz photofresco (та же версия с GitHub), установите плагин или запустите сервер из клона этого репозитория, как описано ниже: вместо части npx -y photofresco@0.1.0 используйте node /path/to/photofresco-agent/src/bin/photofresco.js (команда npm install не требуется).

Из клона репозитория (работает уже сейчас; MCP SDK включён в комплект, устанавливать ничего не нужно):

git clone https://github.com/photofresco/photofresco-agent.git ~/photofresco-agent

Затем добавьте эту запись в любой клиент, который использует mcpServers (Claude Desktop, Cursor, Windsurf, Kiro и большинство других). Вместо /Users/you укажите путь к своей домашней папке:

{
  "mcpServers": {
    "photofresco": {
      "command": "node",
      "args": ["/Users/you/photofresco-agent/src/bin/photofresco.js", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
    }
  }
}

Claude Code:

claude mcp add photofresco -- npx -y photofresco@0.1.0 mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

Claude Desktop: claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "photofresco": {
      "command": "npx",
      "args": ["-y", "photofresco@0.1.0", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
    }
  }
}

Cursor: ~/.cursor/mcp.json (для всех проектов) или .cursor/mcp.json (для одного проекта). Используйте ту же запись mcpServers, что и для Claude Desktop.

VS Code: файл .vscode/mcp.json в рабочей области или команда MCP: Open User Configuration для настройки всех рабочих областей:

{
  "servers": {
    "photofresco": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "photofresco@0.1.0", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
    }
  }
}

Windsurf (Cascade): используйте ту же запись mcpServers, что и для Claude Desktop, в файле mcp_config.json (Cascade → MCPs → Open MCP config file).

Gemini CLI:

gemini mcp add -s user photofresco npx -y photofresco@0.1.0 mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

Codex:

codex mcp add photofresco -- npx -y photofresco@0.1.0 mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

OpenCode: файл opencode.json в проекте или ~/.config/opencode/opencode.json для всех проектов (используйте клон репозитория, как описано выше):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "photofresco": {
      "type": "local",
      "command": ["node", "/Users/you/photofresco-agent/src/bin/photofresco.js", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"],
      "enabled": true
    }
  }
}

Kiro: добавьте запись mcpServers из примера выше в файл ~/.kiro/settings/mcp.json (для всех рабочих областей) или .kiro/settings/mcp.json (для одной рабочей области).

Cline: передайте Cline этот репозиторий. В файле llms-install.md описаны установка, подключение и остановка сервера.

Сервер проверен с официальным MCP-клиентом для TypeScript через stdio; приведённые настройки соответствуют документированному формату stdio каждого приложения. Доступны следующие параметры:

Параметр	Значение
`--read`	Разрешает агенту открывать файлы изображений из указанной папки (параметр можно указывать несколько раз)
`--write`	Разрешает агенту сохранять экспортированные файлы в указанную папку и её новые подпапки (параметр можно указывать несколько раз)
`--overwrite`	Разрешает перезаписывать существующие файлы в папках `--write` (агент также должен запросить это разрешение)
`--tools`	Определяет, какие операции доступны в виде инструментов: `essentials` (по умолчанию, не более 40 инструментов), `all` или список групп, разделённых запятыми (MCP.md)
`--profile`	Папка профиля браузера или `ephemeral` для временного профиля
`--browser`	Браузер на базе Chromium (тот же параметр, что и `PHOTOFRESCO_BROWSER`)

Пакет MCP (для Claude Desktop и других приложений, устанавливающих файлы .mcpb): команда node scripts/build-mcpb.mjs создаёт dist/photofresco-mcp-0.1.0.mcpb и файл с его SHA-256. При одинаковой версии Node.js сборка воспроизводима. Пакет запускает тот же сервер и, как и плагин, не предоставляет доступ к папкам. Этот файл включается в каждый релиз на GitHub; его SHA-256 указан в поле fileSha256 файла server.json, записи в официальном MCP Registry.

Docker (для реестров MCP, которые проверяют серверы в контейнере): команда docker build -t photofresco-mcp . создаёт образ, а команда docker run -i --rm photofresco-mcp запускает сервер через stdio. В образе нет браузера, поэтому он предоставляет только список инструментов; вызов photofresco_connect завершится ошибкой browser_not_found. Для редактирования изображений установите сервер локально, как описано выше.

Как проходит сеанс

Агент вызывает photofresco_connect. PhotoFresco открывается в отдельном окне и показывает код подключения; агент сообщает вам тот же код. Проверьте его и нажмите Allow.
В начале сеанса нет разрешений. Агент запрашивает необходимые (Read, Edit, Export; Send и Spend — только для облачных сервисов и платного AI), а вы выбираете разрешения в диалоговом окне Permissions. По мере предоставления разрешений агенту становятся доступны инструменты редактирования.
Агент редактирует изображение с помощью отдельного инструмента для каждой операции редактора, просматривает результат и отменяет неудачные изменения. Когда вы редактируете изображение самостоятельно, работа агента приостанавливается до тех пор, пока вы не нажмёте Resume. Нажмите Stop, чтобы завершить сеанс; он также завершится, если закрыть окно.

Пока агент не вызовет photofresco_connect, ничего не открывается: запуск сервера и вывод списка инструментов не запускают браузер.

Установка в качестве плагина

Этот репозиторий также доступен как плагин для Claude Code, Codex, Cursor, Gemini CLI, Hermes Agent, OpenClaw, Antigravity, Devin и Kiro: при установке добавляются MCP-сервер и Agent Skill. Клиент копирует репозиторий и запускает сервер командой node /src/bin/photofresco.js mcp; ничего не скачивается из npm, поскольку MCP SDK включён в репозиторий в читаемом виде в vendor/. В PATH должна быть указана версия Node.js 22 или новее.

Установка плагина не предоставляет доступ ни к каким папкам: агент редактирует изображение, открытое в окне PhotoFresco, а файлы вы открываете и сохраняете самостоятельно. Чтобы предоставить агенту доступ к файлам, настройте сервер с параметрами --read и --write, как описано выше.

Claude Code (в рамках сеанса; третья команда выполняет оба шага сразу в Claude Code версии 2.1.275 или новее):

/plugin marketplace add photofresco/photofresco-agent
/plugin install photofresco@photofresco
/plugin install photofresco --marketplace photofresco/photofresco-agent

Codex:

codex plugin marketplace add photofresco/photofresco-agent
codex plugin add photofresco@photofresco

Gemini CLI:

gemini extensions install https://github.com/photofresco/photofresco-agent

Gemini CLI передаёт расширениям только несколько переменных окружения, поэтому PHOTOFRESCO_BROWSER этому расширению недоступна. Если браузер находится не в стандартном расположении, используйте приведённую выше конфигурацию MCP.

Cursor: установите PhotoFresco через раздел Customize, когда он появится в списке, или скопируйте этот репозиторий в ~/.cursor/plugins/local/photofresco и перезагрузите окно.

Hermes Agent (версия с поддержкой Agent Plugins, в которой доступна команда hermes plugins validate). Плагины устанавливаются отключёнными; после включения сервер и skill загрузятся в следующем сеансе:

hermes plugins install photofresco/photofresco-agent --no-enable
hermes plugins enable photofresco

OpenClaw (сначала предлагает проверить исходный код, затем подтвердить установку MCP-сервера и skill плагина):

openclaw plugins install photofresco --marketplace photofresco/photofresco-agent

Antigravity (CLI):

agy plugin install https://github.com/photofresco/photofresco-agent

Devin (CLI; также можно выбрать Customize → Plugins → Add plugin → From repository в приложении):

devin plugins install photofresco/photofresco-agent

Kiro: выберите Powers → Add Custom Power → Import power from GitHub, затем укажите

https://github.com/photofresco/photofresco-agent.

Манифесты находятся в .claude-plugin/ (Claude Code; также используется Devin), plugin.json вместе с mcp.json (стандарт Agent Plugins, используемый Codex, Hermes Agent и Kiro), .cursor-plugin/plugin.json (Cursor и OpenClaw; через него OpenClaw читает .mcp.json), gemini-extension.json (Gemini CLI), mcp_config.json (Antigravity) и openclaw.plugin.json (метаданные OpenClaw и ClawHub).

Agent skill

Agent Skill в skills/photofresco помогает агентам с поддержкой skills определять, когда использовать PhotoFresco, как подключаться и запрашивать разрешения, как выполнять цикл «ориентация → редактирование → предварительный просмотр → отмена», а также описывает рабочие процессы, экспорт, все коды ошибок и командную строку. Он не настраивает MCP-сервер — настройте его, как описано выше.

Установите его с помощью skills CLI в текущий проект (-g — для своей учётной записи):

npx skills add photofresco/photofresco-agent

Удалите его командой npx skills remove photofresco. Список операций приведён в перечне инструментов самого сервера (photofresco_list_tool_groups или photofresco ops в командной строке).

Командная строка

Этот же пакет устанавливает команду photofresco для скриптов и агентов, у которых есть оболочка, но нет MCP-клиента. Она управляет тем же типом окна с подтверждённым доступом через фоновый процесс-коннектор.

Пока пакет npm не опубликован (середина октября 2026 года), запускайте команду из клона репозитория вместо установки через npm install -g: alias photofresco="node /path/to/photofresco-agent/src/bin/photofresco.js".

npm install -g photofresco@0.1.0
photofresco connect --read ~/Pictures --write ~/Pictures/PhotoFresco
photofresco run warm.json --open ~/Pictures/beach.png --input amount=0.6 \
  --export ~/Pictures/PhotoFresco/beach-warm.png
photofresco stop

Команда connect открывает PhotoFresco и выводит код подключения. Убедитесь, что в окне отображается тот же код, нажмите Allow и выберите разрешения. Команда run открывает изображение в новой вкладке, запускает сохранённый рабочий процесс (переносимый файл, который можно экспортировать на панели Actions редактора) и сохраняет результат только после совпадения его SHA-256. Команда stop завершает сеанс, закрывает окно и останавливает процесс-коннектор.

Команда	Назначение
`connect`	При необходимости запускает коннектор, открывает PhotoFresco и устанавливает соединение (нажмите Allow)
`status`	Показывает состояние коннектора, окна и сеанса, разрешения и предоставленные папки
`request-access`	Запрашивает дополнительные разрешения (`read,edit,export,external-write,spend`)
`documents`, `attach`	Выводит список открытых документов; позволяет выбрать другой документ
`open`	Открывает изображение из папки с предоставленным доступом в новой вкладке
`run`	Запускает рабочий процесс (или `--action` ) с параметрами `--open`, `--input` и `--export`
`export`	Экспортирует документ (в формате PNG, PSD или `.pfd`) в папку с предоставленным доступом
`exec [params-json]`	Выполняет одну операцию редактора
`ops [prefix]`, `describe`	Показывает операции, доступные для выполнения в этом сеансе, и их параметры
`outcome`	Возвращает результат предыдущего запроса после потери соединения
`disconnect`, `stop`	Завершает сеанс; `stop` также закрывает окно и останавливает коннектор
`mcp`	Запускает описанный выше MCP-сервер

Для каждой команды можно указать --json: в stdout будет выведен один объект, в том числе при ошибке. Команда возвращает документированный код завершения: 0 — успешно, 2 — ошибка использования, 3 — нет подключения, 4 — путь запрещён, 5 — редактор отклонил запрос, 8 — отменено, 75 — ожидание ответа от вас. Полное описание: CLI.md.

Что запускается, отправляется и загружается

Наблюдения сделаны на macOS с Chrome for Testing 145 и локальной сборкой редактора. Все подробности записаны в

DISCLOSURE.md; всё, что не удалось проверить, отмечено в этом документе.

Запускается

Процесс Node.js: MCP-сервер, который запускает ваш клиент и который завершает работу после закрытия клиента, либо

каждая команда photofresco и один фоновый процесс-коннектор для каждой папки с данными. Он завершает работу после команды photofresco stop, при закрытии его окна или если в течение минуты нет ни окна, ни команды.

Дерево процессов браузера — только при подключении агента: установленный у вас Chrome, Edge или

Chromium запускается с отдельным профилем и каналом DevTools

(--user-data-dir= --remote-debugging-pipe --no-first-run --no-default-browser-check --disable-extensions). Браузер открывает обычное видимое окно (приведённая выше демонстрация записана в безголовом режиме).

Повседневные профили браузера никогда не открываются, не читаются и не используются для подключения.

Никакие другие программы, команды оболочки, установщики, службы, элементы входа в систему или расширения не запускаются.

Локальные файлы и каналы

Папка с данными: ~/Library/Application Support/PhotoFresco Connector (macOS),

%LOCALAPPDATA%\PhotoFresco Connector (Windows) или ~/.local/share/photofresco-connector

(Linux). В ней хранятся профиль браузера (файлы cookie и данные входа, если вы вошли в систему через этот профиль, кэш, локальное хранилище редактора и данные автосохранения), файл блокировки, а при работе из командной строки — папка cli/ с Unix-сокетом (0600 в папке с разрешениями 0700), случайный ключ для каждого запуска и connector.log с событиями без секретных данных: предоставленные пути к папкам, пути, размеры и SHA-256 прочитанных или записанных файлов; без ключей, содержимого файлов или пикселей; объём журнала — не более 4 MiB.

Ваши файлы: чтение разрешено только из папок, указанных в --read, и только когда агент открывает файл (не более 32 MiB); запись — только в папки, указанные в --write, при экспорте. Сначала данные записываются во временный файл, а затем он перемещается на место исходного после совпадения SHA-256.

Существующие файлы заменяются только при наличии --overwrite и запросе агента.

Порт для входящих сетевых подключений не открывается. Браузер управляется через закрытый канал, а командная строка использует локальный сокет. Наблюдение: в процессах сервера и коннектора не обнаружено TCP-сокетов.

Сеть

Коннектор, MCP-сервер и командная строка самостоятельно не отправляют сетевые запросы.

Сначала npx/npm install загружает пакет из реестра npm (до публикации релиза в npm кнопки установки в один клик вместо этого загружают архив исходного кода репозитория с GitHub); при установке плагина клиент агента копирует этот репозиторий с GitHub, а при запуске сервера ничего не загружается.

Браузер открывает https://photofresco.com/app/?pf_ref=mcp (или cli) — несекретную метку для определения источника перехода — и загружает редактор, как при обычном посещении сайта. Поскольку браузер работает в автоматизированном режиме, сторонняя реклама не показывается.
Окно коннектора запускается с выключенной записью сеанса. Редактор распознаёт окно, открытое коннектором (для этого используется закрытый канал, который не может создать ни ссылка, ни сайт), и при запуске отключает все разрешения в разделе Data & privacy. Это означает, что файлы не загружаются: не ведётся запись сеанса и диагностики, не отправляются копии файлов, открываемых агентом, и события об использовании. Наблюдение: от момента подключения до завершения сеанса не было запросов на запись или телеметрию, в том числе после импорта фотографии агентом. Если разрешить агенту работу, включается только External agents.
Запись остаётся выключенной, пока вы сами не включите её в разделе Data & privacy этого окна. После этого PhotoFresco получает события ввода, команды редактора, названия документов, введённый текст (содержимое полей пароля и электронной почты скрывается) и копию каждого изображения, открытого в окне, в том числе файлов, открытых агентом через коннектор (не более 16 MiB каждое, 6 изображений на одну загрузку страницы). Также отправляются диагностические данные (ошибки, события функций, показатели производительности, профиль устройства) и события использования, безопасные с точки зрения конфиденциальности (referral, open, edit, export, помеченные как automated; без имён файлов и пикселей).

При обычном посещении photofresco.com, не через окно коннектора, запись включена по умолчанию.

Собственный фоновый сетевой трафик браузера (обновления, безопасный просмотр) подчиняется настройкам браузера; он не измерялся. Запросы к сторонним ресурсам на рабочей версии сайта не проверялись.

Какие данные получает агент

Только те данные, доступ к которым разрешён выданными вами разрешениями: состояние сеанса, состояние документа, результаты операций, предварительные просмотры (пиксели) и экспортированные файлы. Все полученные агентом данные передаются провайдеру модели этого агента в соответствии с политикой провайдера.
Платные функции AI работают только при наличии разрешения Spend и установленного вами лимита расходов; для отправки данных службам PhotoFresco (облачные документы, AI) необходимо разрешение Send.
В окне отображается, кто подключается: имя, которое MCP-клиент передаёт при установлении соединения (" via MCP"), или значение --client в командной строке ("Terminal via CLI" по умолчанию).

Вы сохраняете контроль: для каждого подключения требуется ваше разрешение Allow, сеанс начинается без разрешений, а команда Stop, закрытие окна, перезагрузка страницы или выход из редактора завершают сеанс. При закрытии коннектора закрывается и его окно.

Удаление

Удалите запись MCP из конфигурации клиента (или выполните photofresco stop и

npm uninstall -g photofresco), либо удалите плагин (/plugin uninstall photofresco@photofresco в

Claude Code, codex plugin remove photofresco@photofresco, gemini extensions uninstall photofresco,

hermes plugins remove photofresco, openclaw plugins uninstall photofresco,

agy plugin uninstall photofresco, devin plugins remove photofresco или Customize в Cursor и

панели Powers в Kiro). Удалите skill командой npx skills remove photofresco и удалите указанную выше папку с данными. Никакие другие компоненты не устанавливаются.

Поддержка

Вопросы и сообщения об ошибках: обсуждения и ошибки на GitHub или

hello@photofresco.com.

Документация: Использование PhotoFresco с AI-агентами.
Политика конфиденциальности: photofresco.com/docs/privacy.
Условия использования: photofresco.com/docs/terms.
Сайт: photofresco.com.

Лицензия

Этот репозиторий (MCP-сервер, командная строка, коннектор и skill) распространяется по

лицензии MIT. Редактор PhotoFresco и сервис photofresco.com в него не входят.