Agenten-Integration

QuokkaPix MCP Runner

Lokaler MCP-Adapter für Claude Desktop, Cursor und andere Agenten: QuokkaPix im Browser starten, lokale Dateien verarbeiten und Manifest schreiben.

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

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.

Claude Desktop einrichten

Füge diesen Server-Eintrag in den MCP-Einstellungen von Claude Desktop hinzu und starte Claude Desktop neu. Prüfe danach, ob Tools wie list_recipes, process_images und process_with_settings sichtbar sind.

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

Cursor einrichten

Nutze die MCP-Einstellungen in Cursor und füge denselben Server-Eintrag hinzu. Cursor startet den Adapter über stdio und kann dieselben Tools wie Claude Desktop aufrufen.

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

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

Produktbilder

Nutze QuokkaPix, um diese lokalen Bilder für Shopify vorzubereiten: weißer Hintergrund, quadratische Produktfläche, WebP-Ausgabe, maximal 300 KB, danach ZIP und Result Manifest speichern.

Website-Komprimierung

Nutze QuokkaPix, um diesen Ordner mit JPG- und PNG-Dateien für die Website in WebP umzuwandeln, gute sichtbare Qualität zu behalten und QA-Fehler zu melden.

Metadaten bereinigen

Nutze QuokkaPix, um EXIF, GPS, Kamera- und Software-Metadaten aus diesen Bildern zu entfernen und ein bereinigtes ZIP mit Manifest zurückzugeben.

Offizielles Rezept ausführen

Nutze zuerst list_recipes, wähle eine recipe id und rufe dann process_images auf. Offizielle Rezepte decken Marketplace, Social, Komprimierung, Metadaten, PDF, Favicon und Wasserzeichen ab.

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

Direkte Einstellungen ausführen

Nutze process_with_settings, wenn der Agent dieselbe Einstellungsfläche wie window.QuokkaPixAgent.applySettings braucht, statt ein benanntes Rezept zu verwenden.

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

Was nach dem Lauf geprüft werden sollte

Prüfung	Warum es wichtig ist
Ausgabedatei, ZIP oder PDF liegt in outputDir	Bestätigt, dass der Browser-Download abgeschlossen und die Ausgabe gespeichert wurde.
quokkapix-result.json enthält status: done	Bestätigt, dass QuokkaPix erfolgreich beendet wurde und nicht nur den Editor geöffnet hat.
outputs[] enthält Quell- und Ausgabemetadaten	Erlaubt dem Agenten, Abmessungen, Formate, Dateigrößen, Warnungen und Namen zu melden.
qa.ok und qa.checks[] falls vorhanden	Zeigt, ob ein Marketplace- oder Social-Rezept bekannte Regeln erfüllt hat und was korrigiert werden muss.

Kostenlose und bezahlte Agent-Läufe

Einzelbild-Läufe, Einzelbild-Szenarien und Agent-Batches bis 5 Dateien sind kostenlos. Agent-Batches oder Batch-Szenarien von 6 bis 50 Dateien nutzen den x402 unlock flow. Clients sollten aktuelle Bedingungen aus /api/agent-payment/options lesen, bevor sie einen paid unlock anfordern.

Wenn Zahlung nötig ist, erhält der Agent ein unlockToken, setzt es vor der Verarbeitung in QuokkaPix, und der Unlock wird erst beim Start eines bezahlten Batch- oder Batch-Szenario-Laufs verbraucht.

Fehlerbehebung

Tools sind nicht sichtbar

Starte den MCP-Client neu und prüfe im Terminal, ob Node.js npx -y quokkapix-mcp ausführen kann.

Browser öffnet sich nicht

Prüfe, ob die lokale Umgebung Playwright/Chromium starten darf. Der Adapter braucht einen Browser, weil QuokkaPix browser-only ist.

Keine Ausgabe erscheint

Prüfe outputDir, Browserspeicher, Terminalstatus und errorCode in quokkapix-result.json.

Bezahlter Batch ist blockiert

Hole aktuelle payment options, erhalte ein gültiges x402 unlock token und setze es vor einem Batch oberhalb des kostenlosen Limits.

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

Lädt QuokkaPix MCP Quelldateien auf einen Verarbeitungsserver hoch?

Nein. Der Adapter öffnet QuokkaPix in einem lokalen Browser und lädt Dateien über das Browser-Dateifeld. Die normalen Bild-Workflows laufen im Browser.

Gibt es jetzt einen gehosteten MCP-Endpunkt?

Ja, aber nur zur Koordination. Remote MCP benötigt eine gekoppelte lokale Bridge; Verarbeitung und Bildbytes bleiben auf dem Gerät des Nutzers.

Wann ist Zahlung für Agenten nötig?

Einzelbild-Läufe, Einzelbild-Szenarien und Batches bis 5 Dateien sind kostenlos. Größere Batch- oder Batch-Szenario-Läufe von 6 bis 50 Dateien nutzen x402 unlock.

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.

Wann der lokale MCP Runner sinnvoll ist

Nutze den Runner, wenn ein Agent lokale Bilddateien verarbeiten soll, ohne die Quelldateien an einen QuokkaPix-Server zu senden. Der Adapter startet einen lokalen Browser, lädt Dateien über das normale Dateifeld, wendet ein offizielles Rezept oder direkte Einstellungen an und speichert Ausgabe sowie quokkapix-result.json im Ausgabeordner.

Lokale Sicherheitsgrenze

Der Runner sollte die offizielle QuokkaPix-URL oder eine vertrauenswürdige lokale Entwicklungs-URL öffnen. Er macht QuokkaPix nicht zu einer öffentlichen serverseitigen Verarbeitungs-API; Dateien werden weiter im Browser ausgewählt und auf dem Rechner verarbeitet, auf dem der Browser läuft.

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.
Bei bezahlten Stapeln wird das Unlock-Token vor dem Start geprüft und nur von einem paid run oberhalb des kostenlosen small-batch-Limits verbraucht.

MCP-Tools

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

Einzeldatei · zip

`watermark_product_batch`

Batch · zip

`favicon_app_icon_pack`

Einzeldatei · zip

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.