QuokkaPix MCP Runner

Image + Video local and remote MCP

Version 0.7.0 exposes one exact Image and Video quote/token flow through local stdio and the OAuth-protected remote MCP with a paired bridge. Use process_video with an official recipe or process_video_with_settings with direct settings. Video runs in local Chromium and never relays media bytes through the control plane.

{
  "recipeId": "tiktok_vertical",
  "inputFile": "/absolute/path/source.mp4",
  "outputDir": "/absolute/path/output"
}

Віддалений 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.

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

Що перевіряти після запуску

Безплатні та платні agent runs

Image: 1–5 фактичних файлів безплатно, 6–25 коштують 0,01 USDC, 26–50 — 0,02; PDF безплатний до 20 сторінок, далі 0,01 до 50 і 0,02 до 300. Багатокроковий сценарій Image коштує 0,02. Монтаж Video безплатний до 5 хвилин, далі 0,01 / 0,02 / 0,03; транскрибування — до 5 хвилин безплатно, далі 0,02 / 0,04 / 0,06 до 45 хвилин.

Спочатку завантажте файли й отримайте точну локальну котировку. Сплатіть зазначений продукт і повторіть незмінений запуск з unlockToken. Браузер витрачає токен лише безпосередньо перед обробкою; WebMCP і Bridge не додають комісії.

Troubleshooting

Межа безпеки

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

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

Що можуть робити агенти

• Запускати офіційні рецепти 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-сторінок.

Що перевірити після запуску

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

Коли запуск можна вважати успішним

• MCP-клієнт запустив локальний stdio-адаптер, а адаптер відкрив очікуваний URL QuokkaPix.
• Файли потрапили через браузерний вибір файла, а не через публічний URL-параметр.
• У маніфесті status дорівнює done, qa.ok істинний для рецептів із QA, а warnings переглянуті до використання результату.
• Спочатку завантажте файли й отримайте точну локальну котировку. Сплатіть зазначений продукт і повторіть незмінений запуск з unlockToken. Браузер витрачає токен лише безпосередньо перед обробкою; WebMCP і Bridge не додають комісії.

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

• list_recipes
• get_recipe
• validate_recipe
• list_rule_profiles
• get_rule_profile
• validate_result_manifest
• process_images
• process_with_settings
• list_video_recipes
• get_video_recipe
• validate_video_recipe
• list_video_rule_profiles
• get_video_rule_profile
• validate_video_result_manifest
• process_video
• process_video_with_settings
• get_payment_options
• explain_payment_flow
• verify_unlock_token

Офіційні рецепти

Приклади

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

Важливі обмеження

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