QuokkaPix MCP Runner

Zdalny MCP z lokalnym przetwarzaniem

Claude web i inne chmurowe klienty MCP mogą łączyć się przez OAuth, a istniejący adapter npm wykonuje każdą operację na obrazach na komputerze użytkownika.

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

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

Zakres mcp:tools zezwala na narzędzia tylko do odczytu. Przetwarzanie i zapis tokenu odblokowującego wymagają także bridge:execute. --reset unieważnia poprzednie urządzenie przed sparowaniem nowego.

Control plane przekazuje ustawienia, względne nazwy plików, status i result manifest. Nie ma endpointu do przesyłania obrazów i nie przekazuje bajtów plików źródłowych ani wynikowych.

Praktyczny przewodnik dla Claude, Cursor i lokalnego MCP

Użyj tej strony, gdy desktop AI agent ma przetwarzać lokalne obrazy za pomocą QuokkaPix. MCP runner jest lokalnym adapterem stdio: klient MCP uruchamia quokkapix-mcp, adapter otwiera QuokkaPix w lokalnej przeglądarce, przesyła pliki przez browser file input, stosuje przepis albo bezpośrednie ustawienia, pobiera wynik i zapisuje quokkapix-result.json.

To nie jest hosted API do przetwarzania obrazów. Obrazy źródłowe pozostają w lokalnym procesie przeglądarki i nie są wysyłane na serwer przetwarzania QuokkaPix.

Komenda fallback dla Windows

Jeśli Windows MCP client nie znajduje npx bezpośrednio, uruchom go przez cmd /c. Używaj tego tylko wtedy, gdy prosty command npx nie jest wykrywany przez klienta.

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

Lokalne klienty MCP i wrappery LLM

Każdy lokalny klient zgodny z MCP, który potrafi uruchomić serwer stdio, może używać tego samego pakietu. Dotyczy to desktop clients, editor agents oraz wrapperów LM Studio lub Ollama, które udostępniają narzędzia MCP lokalnemu modelowi.

Najważniejsza zasada jest wszędzie taka sama: przekazuj prawdziwe lokalne ścieżki plików do MCP tool call, a nie do URL publicznej strony. QuokkaPix otrzymuje pliki tylko przez lokalny browser file input otwarty przez runner.

Pierwsze przydatne prompty

Tabela kontroli uruchomienia

Darmowe i płatne uruchomienia agentów

Uruchomienia jednej grafiki, scenariusze jednej grafiki i batche agentów do 5 plików są darmowe. Batche albo batch-scenario runs od 6 do 50 plików używają x402 unlock flow. Klienci powinni pobrać aktualne warunki z /api/agent-payment/options przed paid unlock.

Gdy potrzebna jest płatność, agent otrzymuje unlockToken, ustawia go w QuokkaPix przed przetwarzaniem, a unlock jest zużywany tylko przy starcie płatnego batcha albo batch scenario.

Rozwiązywanie problemów

Granica bezpieczeństwa

Używaj oficjalnego URL QuokkaPix albo zaufanego lokalnego development URL. Nie kieruj runnera na dowolny zewnętrzny appUrl, bo adapter przesyła lokalne pliki do strony, którą otwiera. Publiczna strona nie otrzymuje lokalnych ścieżek plików, a adapter nie zmienia QuokkaPix w server-side image API.

FAQ dla agentów i deweloperów

Co mogą robić agenci

• Uruchamiać oficjalne przepisy dla Shopify, Amazon, Google Merchant, kompresji WebP, eksportu PDF, czyszczenia metadanych, pakietów społecznościowych, avatarów i znaków wodnych.
• Uruchamiać bezpośrednie custom settings przez process_with_settings, używając tego samego payloadu co window.QuokkaPixAgent.applySettings.
• Walidować result manifest i otrzymywać kontrole QA formatu, wymiarów, limitów rozmiaru, typu wyniku, wymaganych nazw plików oraz zawartości ZIP.
• Odczytywać warunki płatności x402 i sprawdzać tokeny odblokowania dla płatnych uruchomień wsadowych agentów.
• Przesyłać lokalne assety dla logo znaku wodnego i zamiany tła na obraz.

Aktualne możliwości przeglądarki

• Opcjonalny obiekt capabilities.backends podaje planowane ścieżki przetwarzania, kodowania i AI tła wraz z jawnymi fallbackami. Istniejące pola MCP pozostają bez zmian.
• Advanced export może używać enkoderów WASM dla JPEG, optymalizacji PNG, WebP, AVIF i eksperymentalnego JPEG XL, gdy są dostępne.
• Upload ZIP działa tylko w batchu: przeglądarka lokalnie rozpakowuje obsługiwane obrazy przed przetwarzaniem.
• Narzędzia PDF działają przez ustawienia bezpośrednie: split i extract używają jednego PDF, merge używa partii PDF, a images-to-PDF pozostaje scenariuszem dla obrazów. Extract zachowuje kolejność z pdf-pages; użyj pdf-extract-output=zip dla osobnych stron PDF.

Co sprawdzić po uruchomieniu

• Sprawdź, czy folder wyjściowy zawiera wygenerowany obraz, ZIP albo PDF oraz quokkapix-result.json.
• Przeczytaj qa.ok i qa.checks przed zaakceptowaniem batcha dla marketplace lub social media.
• Trzymaj pliki źródłowe osobno, bo QuokkaPix tworzy pliki do publikacji i nie zastępuje oryginałów.
• Dla płatnych batchy agentów najpierw pobierz aktualne opcje płatności, a dopiero potem poproś o token x402.

Kiedy uruchomienie jest akceptowalne

• Klient MCP uruchomił lokalny adapter stdio, a adapter otworzył oczekiwany URL QuokkaPix.
• Pliki trafiły przez selektor plików przeglądarki, a nie przez publiczny parametr URL.
• Manifest ma status done, qa.ok jest true dla receptur z QA, a warnings są sprawdzone przed użyciem wyniku.
• Dla płatnych partii unlock token jest weryfikowany przed startem i zużywany tylko przez paid run powyżej darmowego limitu small-batch.

Narzędzia 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

Oficjalne przepisy

Przykłady

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

Ważne ograniczenia

Pliki nadal trafiają wyłącznie przez lokalny input przeglądarki. QuokkaPix nie udostępnia publicznego serwerowego API do przetwarzania obrazów.