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"
}

Remote MCP mit lokaler Verarbeitung

Claude web und andere Cloud-MCP-Clients können sich per OAuth verbinden, während der bestehende npm-Adapter alle Bildoperationen auf dem Computer des Nutzers ausführt.

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

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

Der Scope mcp:tools erlaubt Lese-Tools. Verarbeitung und das Hinterlegen eines Unlock-Tokens erfordern zusätzlich bridge:execute. --reset widerruft das bisherige Gerät, bevor ein neues gekoppelt wird.

Die Control Plane überträgt Einstellungen, relative Dateinamen, Status und das Result Manifest. Sie besitzt keinen Bild-Upload-Endpunkt und überträgt keine Quell- oder Ausgabebytes.

Praxisleitfaden für Claude, Cursor und lokales MCP

Diese Seite ist für den Fall gedacht, dass ein Desktop-AI-Agent lokale Bilder mit QuokkaPix verarbeiten soll. Der MCP Runner ist ein lokaler stdio-Adapter: Der MCP-Client startet quokkapix-mcp, der Adapter öffnet QuokkaPix in einem lokalen Browser, lädt Dateien über das Browser-Dateifeld hoch, wendet ein Rezept oder direkte Einstellungen an, lädt das Ergebnis herunter und schreibt quokkapix-result.json.

Das ist keine gehostete Bildverarbeitungs-API. Die Quelldateien bleiben im lokalen Browser-Workflow und werden nicht an einen QuokkaPix-Verarbeitungsserver gesendet.

Fallback-Befehl für Windows

Wenn ein Windows-MCP-Client npx nicht direkt findet, starte es über cmd /c. Nutze das nur, wenn der einfache npx-Befehl vom Client nicht erkannt wird.

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

Lokale MCP-Clients und LLM-Wrapper

Jeder lokale MCP-kompatible Client, der einen stdio-Server starten kann, kann dasselbe Paket verwenden. Dazu gehören Desktop-Clients, Editor-Agenten und LM-Studio- oder Ollama-Wrapper mit MCP-Tools.

Die wichtigste Regel ist überall gleich: Übergib echte lokale Dateipfade an den MCP-Tool-Aufruf, nicht an die URL der öffentlichen Website. QuokkaPix erhält Dateien nur über das lokale Browser-Dateifeld, das der Runner öffnet.

Erste nützliche Prompts

Was nach dem Lauf geprüft werden sollte

Kostenlose und bezahlte Agent-Läufe

Image: 1–5 tatsächliche Dateien kostenlos, 6–25 kosten 0,01 USDC und 26–50 0,02; PDF ist bis 20 Seiten kostenlos, danach 0,01 bis 50 und 0,02 bis 300. Ein mehrstufiges Image-Szenario kostet 0,02. Video ist bis 5 Minuten kostenlos, danach 0,01 / 0,02 / 0,03; Transkription kostet danach 0,02 / 0,04 / 0,06 bis 45 Minuten.

Zuerst lokal laden und das exakte Angebot abrufen. Das angegebene Produkt bezahlen und denselben Lauf mit unlockToken wiederholen. Der Browser verbraucht ihn erst direkt vor der Verarbeitung; WebMCP und Bridge kosten nicht extra.

Fehlerbehebung

Sicherheitsgrenze

Nutze die offizielle QuokkaPix-URL oder eine vertrauenswürdige lokale Entwicklungs-URL. Richte den Runner nicht auf eine beliebige fremde appUrl, weil der Adapter lokale Dateien in die geöffnete Seite hochlädt. Die öffentliche Website erhält keine lokalen Dateipfade, und der Adapter macht QuokkaPix nicht zu einer serverseitigen Bild-API.

FAQ für Agenten und Entwickler

Was Agenten tun können

• Offizielle Rezepte für Shopify, Amazon, Google Merchant, WebP-Komprimierung, PDF-Export, Metadatenbereinigung, Social Packs, Avatare und Wasserzeichen ausführen.
• Direkte custom settings mit process_with_settings ausführen, mit demselben Payload wie window.QuokkaPixAgent.applySettings.
• Result manifests validieren und QA-Prüfungen für Format, Abmessungen, Größenlimits, Ausgabetyp, erforderliche Dateinamen und ZIP-Inhalte erhalten.
• x402-Zahlungsbedingungen lesen und Freischalt-Token für bezahlte Agenten-Stapelläufe prüfen.
• Lokale Asset-Dateien für Logo-Wasserzeichen und Hintergrundbild-Ersatz hochladen.

Aktuelle Browser-Funktionen

• Das optionale Objekt capabilities.backends meldet geplante Verarbeitungs-, Encoding- und Hintergrund-AI-Pfade mit expliziten Fallbacks. Bestehende MCP-Felder bleiben unverändert.
• Advanced Export kann WASM-Encoder für JPEG, PNG-Optimierung, WebP, AVIF und experimentelles JPEG XL nutzen, wenn sie verfügbar sind.
• ZIP-Upload funktioniert nur im Batch: der Browser entpackt unterstützte Bilder lokal vor der Verarbeitung.
• PDF-Werkzeuge laufen über direkte Einstellungen: split und extract verwenden eine einzelne PDF, merge verwendet einen PDF-Stapel und images-to-PDF bleibt ein Bild-Workflow. Extract behält die Reihenfolge aus pdf-pages; nutze pdf-extract-output=zip für einzelne Seiten-PDFs.

Was nach einem Lauf zu prüfen ist

• Prüfe, ob der Ausgabeordner das erzeugte Bild, ZIP oder PDF und quokkapix-result.json enthält.
• Lies qa.ok und qa.checks, bevor ein Batch für Marktplatz oder soziale Plattform akzeptiert wird.
• Bewahre Quelldateien getrennt auf, weil QuokkaPix Lieferdateien schreibt und Originale nicht ersetzt.
• Bei bezahlten Agent-Batches zuerst aktuelle Zahlungsoptionen abrufen und danach ein x402-Token anfordern.

Wann ein Lauf akzeptabel ist

• Der MCP-Client hat den lokalen stdio-Adapter gestartet und der Adapter hat eine erwartete QuokkaPix-URL geöffnet.
• Dateien kamen über das Browser-Dateifeld hinein, nicht über einen öffentlichen URL-Parameter.
• Im Manifest steht status done, qa.ok ist bei Rezepten mit QA true und warnings werden vor der Nutzung des Outputs geprüft.
• Zuerst lokal laden und das exakte Angebot abrufen. Das angegebene Produkt bezahlen und denselben Lauf mit unlockToken wiederholen. Der Browser verbraucht ihn erst direkt vor der Verarbeitung; WebMCP und Bridge kosten nicht extra.

MCP-Tools

• 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

Offizielle Rezepte

Beispiele

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

Wichtige Hinweise

Dateien werden weiterhin nur über das lokale Browser-Dateifeld übergeben. QuokkaPix bietet keine öffentliche serverseitige Bildverarbeitungs-API.