Інтеграція для агентів

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

Фото товарів

Використай QuokkaPix, щоб підготувати ці локальні зображення для Shopify: білий фон, квадратний product canvas, WebP output, максимум 300 KB, потім збережи ZIP і result manifest.

Стиснення для сайту

Використай QuokkaPix, щоб конвертувати цю папку JPG і PNG у WebP для сайту, зберегти нормальну якість і повідомити про файли, які не пройшли QA.

Очищення метаданих

Використай QuokkaPix, щоб прибрати EXIF, GPS, camera і software metadata з цих зображень та повернути очищений ZIP і 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 для обробки зображень.