Интеграция для агентов

QuokkaPix MCP Runner

Локальный MCP-адаптер для Claude Desktop, Cursor и других агентов: браузерный запуск QuokkaPix, локальные файлы и result manifest.

agents.html agent-test.html GitHub npm Glama mcpservers.org

Удалённый MCP с локальной обработкой

Claude web и другие облачные MCP-клиенты могут подключаться через OAuth, а существующий npm-адаптер выполняет все операции с изображениями на компьютере пользователя.

npx quokkapix-mcp bridge --input-root /path/to/input --output-root /path/to/output

Remote MCP: https://quokkapix.com/mcp

Scope mcp:tools разрешает инструменты чтения. Для обработки и сохранения unlock-токена также нужен bridge:execute. Параметр --reset отзывает предыдущее устройство перед подключением нового.

Control plane передаёт настройки, относительные имена файлов, статус и result manifest. У него нет endpoint для загрузки изображений, и байты исходных или готовых файлов через него не проходят.

Практический guide для Claude, Cursor и local MCP

Эта страница нужна, когда настольный AI-агент должен обработать локальные изображения через QuokkaPix. MCP Runner — это локальный stdio-адаптер: MCP-клиент запускает quokkapix-mcp, адаптер открывает QuokkaPix в локальном браузере, загружает файлы через браузерный выбор файла, применяет рецепт или прямые настройки, скачивает результат и записывает quokkapix-result.json.

Это не hosted API для обработки изображений. Исходные изображения остаются в локальном браузерном процессе и не загружаются на сервер обработки QuokkaPix.

Подключение Claude Desktop

Добавьте этот server entry в MCP settings Claude Desktop, затем перезапустите Claude Desktop. После перезапуска проверьте, что видны tools list_recipes, process_images и process_with_settings.

{
  "mcpServers": {
    "quokkapix": {
      "command": "npx",
      "args": [
        "-y",
        "quokkapix-mcp"
      ],
      "env": {
        "QUOKKAPIX_APP_URL": "https://quokkapix.com/#agent=1"
      }
    }
  }
}

Подключение Cursor

В Cursor используйте MCP settings и добавьте тот же server entry. Cursor запускает адаптер через stdio и получает те же tools, что и Claude Desktop.

{
  "mcpServers": {
    "quokkapix": {
      "command": "npx",
      "args": [
        "-y",
        "quokkapix-mcp"
      ],
      "env": {
        "QUOKKAPIX_APP_URL": "https://quokkapix.com/#agent=1"
      }
    }
  }
}

Fallback-команда для Windows

Если Windows MCP client не находит npx напрямую, запускайте его через cmd /c. Это нужно только когда простой command npx не определяется клиентом.

{
  "mcpServers": {
    "quokkapix": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "quokkapix-mcp"
      ],
      "env": {
        "QUOKKAPIX_APP_URL": "https://quokkapix.com/#agent=1"
      }
    }
  }
}

Local MCP clients и LLM wrappers

Любой локальный MCP-совместимый клиент, который умеет запускать stdio-сервер, может использовать этот пакет. Это относится к настольным клиентам, агентам редактора, оболочкам LM Studio/Ollama и другим средам, которые дают локальной модели MCP-инструменты.

Главное правило одинаковое везде: передавайте реальные локальные пути к изображениям в вызов MCP-инструмента, а не в URL публичного сайта. QuokkaPix получает файлы только через локальный браузерный выбор файла, открытый runner.

Первые полезные prompts

Фото товаров

Use QuokkaPix to prepare these local images for Shopify: white background, square product canvas, WebP output, max 300 KB, then save the ZIP and result manifest.

Сжатие для сайта

Use QuokkaPix to convert this folder of JPG and PNG images to WebP for the website, keep reasonable visual quality, and report files that fail QA.

Очистка метаданных

Use QuokkaPix to remove EXIF, GPS, camera and software metadata from these images and return the cleaned ZIP plus the manifest.

Запуск официального рецепта

Сначала используйте list_recipes, выберите recipe id, затем вызовите process_images. Официальные рецепты покрывают marketplace, social, compression, metadata, PDF, favicon и сценарии водяных знаков.

{
  "recipeId": "shopify_product_pack",
  "inputFiles": [
    "/Users/me/products/photo-01.jpg",
    "/Users/me/products/photo-02.jpg"
  ],
  "outputDir": "/Users/me/quokkapix-output/shopify"
}

Запуск прямых настроек

Используйте process_with_settings, когда агенту нужна та же поверхность настроек, что и window.QuokkaPixAgent.applySettings, а не именованный рецепт.

{
  "settings": {
    "mode": "batch",
    "tool": "compress",
    "settings": {
      "compress": {
        "format": "webp",
        "quality": 0.82
      }
    }
  },
  "inputFiles": [
    "/Users/me/site/hero.jpg",
    "/Users/me/site/card.jpg"
  ],
  "outputDir": "/Users/me/quokkapix-output/webp"
}

Что проверять после запуска

Проверка	Зачем это нужно
Выходной файл, ZIP или PDF есть в outputDir	Подтверждает, что скачивание в браузере завершилось и адаптер сохранил результат.
В quokkapix-result.json стоит status: done	Подтверждает, что QuokkaPix дошёл до успешного финального состояния, а не просто открыл редактор.
outputs[] содержит source/output metadata	Позволяет агенту отчитаться о размерах, форматах, весе файлов, warnings и именах.
qa.ok и qa.checks[] есть, если рецепт поддерживает QA	Показывает, прошёл ли marketplace/social recipe известные проверки и что надо исправить.

Бесплатные и платные agent runs

Запуски агента с одним изображением, одиночные сценарии и пакеты агента до 5 файлов бесплатны. Пакетные запуски или пакетные сценарии от 6 до 50 файлов используют x402-поток разблокировки. Клиенты должны получать актуальные условия из /api/agent-payment/options перед запросом платной разблокировки.

Когда нужна оплата, агент получает unlockToken, устанавливает его в QuokkaPix перед обработкой, и unlock списывается только при старте платного batch или batch scenario.

Troubleshooting

Tools не видны

Перезапустите MCP client и проверьте в терминале, что Node.js может выполнить npx -y quokkapix-mcp.

Браузер не открывается

Проверьте, что локальная среда разрешает запуск Playwright/Chromium. Адаптеру нужен браузер, потому что QuokkaPix browser-only.

Нет результата

Проверьте outputDir, память браузера, terminal status и errorCode в quokkapix-result.json.

Платный пакет заблокирован

Получите текущие условия оплаты, получите валидный x402-токен разблокировки и установите его перед пакетом выше бесплатного лимита.

Граница безопасности

Используйте официальный QuokkaPix URL или доверенный локальный development URL. Не направляйте runner на произвольный сторонний appUrl, потому что адаптер загружает локальные файлы в страницу, которую он открыл. Публичный сайт не получает локальные file paths, а адаптер не превращает QuokkaPix в server-side image API.

FAQ для агентов и разработчиков

QuokkaPix MCP загружает исходные изображения на сервер обработки?

Нет. Адаптер открывает QuokkaPix в локальном браузере и загружает файлы через браузерный выбор файла. Обычные сценарии обработки изображений выполняются в браузерном runtime.

Теперь есть hosted MCP endpoint?

Да, но только для координации. Remote MCP требует подключённый локальный bridge; обработка и байты изображений остаются на устройстве пользователя.

Когда агентам нужна оплата?

Single-image agent runs, single-image scenarios и agent batches до 5 файлов бесплатны. Более крупные batch или batch-scenario runs от 6 до 50 файлов используют x402 unlock flow.

Что могут делать агенты

Запускать официальные рецепты Shopify, Amazon, Google Merchant, WebP-сжатия, PDF-экспорта, очистки метаданных, социальных пакетов, аватаров и водяных знаков.
Запускать прямые custom settings через process_with_settings, тем же payload, что и window.QuokkaPixAgent.applySettings.
Проверять result manifest и получать QA-проверки формата, размеров, лимитов веса, типа результата, обязательных имён файлов и содержимого ZIP.
Читать условия оплаты x402 и проверять токены разблокировки для платных пакетных запусков агентов.
Загружать локальные asset-файлы для логотипа водяного знака и замены фона изображением.

Текущие возможности браузера

Опциональный объект capabilities.backends сообщает планируемые пути обработки, кодирования и фонового AI с явными fallback. Существующие поля запросов и ответов MCP не изменились.
Advanced export использует WASM-энкодеры для JPEG, оптимизации PNG, WebP, AVIF и экспериментального JPEG XL, когда они доступны в браузере.
ZIP-загрузка работает только в батче: браузер локально распаковывает поддерживаемые изображения перед обработкой.
PDF-инструменты используют прямые настройки: split и extract работают с одним PDF, merge работает с пакетом PDF, а images-to-PDF остаётся процессом для изображений. Extract сохраняет порядок pdf-pages; используйте pdf-extract-output=zip для отдельных PDF-страниц.

Когда использовать локальный MCP runner

Используйте runner, когда агенту нужно обработать локальные изображения без отправки исходников на сервер QuokkaPix. Адаптер запускает локальный браузер, загружает файлы через обычный file input, применяет официальный рецепт или прямые настройки, затем сохраняет результат и quokkapix-result.json в папку вывода.

Локальная граница безопасности

Runner должен открывать официальный URL QuokkaPix или доверенный локальный URL разработки. Он не превращает QuokkaPix в публичный серверный API обработки: файлы по-прежнему выбираются через браузер и обрабатываются на машине, где запущен браузер.

Что проверить после запуска

Проверьте, что в папке вывода есть изображение, ZIP или PDF и файл quokkapix-result.json.
Читайте qa.ok и qa.checks перед принятием batch для маркетплейса или соцсети.
Храните исходники отдельно, потому что QuokkaPix создает файлы для публикации, а не заменяет оригиналы.
Для платных пакетных запусков агентов сначала получайте актуальные условия оплаты, а потом запрашивайте x402-токен разблокировки.

Когда запуск можно считать успешным

MCP-клиент запустил локальный stdio-адаптер, а адаптер открыл ожидаемый URL QuokkaPix.
Файлы попали через браузерный выбор файла, а не через публичный URL-параметр.
В манифесте status равен done, qa.ok истинный для рецептов с QA, а warnings просмотрены до использования результата.
Для платных пакетов токен разблокировки проверен до старта и расходуется только платным запуском выше бесплатного лимита малого пакета.

MCP-инструменты

list_recipes
get_recipe
validate_recipe
list_rule_profiles
get_rule_profile
validate_result_manifest
process_images
process_with_settings
get_payment_options
explain_payment_flow
verify_unlock_token

один файл · zip

`watermark_product_batch`

пакет · zip

`favicon_app_icon_pack`

один файл · zip

Примеры

{
  "recipeId": "shopify_product_pack",
  "inputFiles": [
    "/Users/me/photo.jpg"
  ],
  "outputDir": "/Users/me/quokkapix-output"
}

Важные ограничения

Файлы всё равно передаются только через локальный input браузера. У QuokkaPix нет публичного серверного API обработки изображений.