QuokkaPix MCP Runner

MCP remoto con elaborazione locale

Claude web e altri client MCP cloud possono collegarsi tramite OAuth, mentre l'adattatore npm esistente esegue ogni operazione sulle immagini nel computer dell'utente.

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

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

Lo scope mcp:tools consente gli strumenti di lettura. L'elaborazione e il salvataggio di un unlock token richiedono anche bridge:execute. --reset revoca il dispositivo precedente prima di associarne uno nuovo.

Il control plane trasmette impostazioni, nomi file relativi, stato e result manifest. Non dispone di un endpoint per l'upload delle immagini e non trasmette i byte sorgente o di output.

Guida pratica per Claude, Cursor e MCP locale

Usa questa pagina quando un agente desktop deve elaborare immagini locali con QuokkaPix. Il MCP runner è un adattatore stdio locale: il client MCP avvia quokkapix-mcp, l'adattatore apre QuokkaPix in un browser locale, carica i file tramite il selettore del browser, applica una ricetta o impostazioni dirette, scarica il risultato e scrive quokkapix-result.json.

Non è una API hosted per l'elaborazione delle immagini. Le immagini sorgente restano nel flusso locale del browser e non vengono inviate a un server di elaborazione QuokkaPix.

Comando fallback per Windows

Se un client MCP Windows non trova npx direttamente, avvialo tramite cmd /c. Usa questa variante solo quando il comando npx semplice non viene rilevato dal client.

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

Client MCP locali e wrapper LLM

Qualsiasi client locale compatibile con MCP che possa avviare un server stdio può usare lo stesso pacchetto. Questo include client desktop, agenti negli editor e wrapper LM Studio o Ollama che espongono strumenti MCP a un modello locale.

La regola importante è la stessa ovunque: passa percorsi reali di file locali alla chiamata MCP, non all'URL del sito pubblico. QuokkaPix riceve i file solo tramite il selettore locale del browser aperto dal runner.

Primi prompt utili

Cosa verificare dopo l'esecuzione

Esecuzioni agente gratuite e a pagamento

Esecuzioni su una singola immagine, scenari su una singola immagine e lotti agente fino a 5 file sono gratuiti. Lotti o scenari in batch da 6 a 50 file usano il flusso x402 unlock. I client devono leggere i termini attuali da /api/agent-payment/options prima di richiedere uno sblocco a pagamento.

Quando serve pagamento, l'agente ottiene un unlockToken, lo imposta in QuokkaPix prima dell'elaborazione, e lo sblocco viene consumato solo all'avvio di un lotto o scenario in batch a pagamento.

Risoluzione problemi

Confine di sicurezza

Usa l'URL ufficiale di QuokkaPix o un URL locale di sviluppo fidato. Non puntare il runner a una appUrl arbitraria di terze parti, perché l'adattatore carica file locali nella pagina che apre. Il sito pubblico non riceve percorsi locali e l'adattatore non trasforma QuokkaPix in una API server-side.

FAQ per agenti e sviluppatori

Cosa possono fare gli agenti

• Eseguire ricette ufficiali per Shopify, Amazon, Google Merchant, compressione WebP, export PDF, pulizia dei metadati, pacchetti social, avatar e watermark.
• Eseguire custom settings diretti con process_with_settings, usando lo stesso payload di window.QuokkaPixAgent.applySettings.
• Validare result manifest e ottenere controlli QA su formato, dimensioni, limiti di peso, tipo di output, nomi richiesti e contenuto ZIP.
• Leggere le condizioni di pagamento x402 e verificare i token di sblocco per esecuzioni in batch degli agenti.
• Caricare asset locali per watermark con logo e sostituzione dello sfondo con immagine.

Capacità attuali del browser

• L’oggetto opzionale capabilities.backends indica i percorsi previsti di elaborazione, encoding e AI per lo sfondo con fallback espliciti. I campi MCP esistenti non cambiano.
• L’export avanzato può usare encoder WASM per JPEG, ottimizzazione PNG, WebP, AVIF e JPEG XL sperimentale quando disponibili.
• L’upload ZIP funziona solo in batch: il browser estrae localmente le immagini supportate prima dell’elaborazione.
• Gli strumenti PDF usano impostazioni dirette: split ed extract lavorano con un solo PDF, merge lavora con un lotto di PDF e images-to-PDF resta un flusso per immagini. Extract conserva l'ordine di pdf-pages; usa pdf-extract-output=zip per PDF separati per pagina.

Cosa controllare dopo l'esecuzione

• Conferma che la cartella di output contenga immagine, ZIP o PDF generato e quokkapix-result.json.
• Leggi qa.ok e qa.checks prima di accettare un batch per marketplace o social.
• Tieni separati i file sorgente, perché QuokkaPix crea output di consegna e non sostituisce gli originali.
• Per batch agent a pagamento, leggi le opzioni di pagamento correnti prima di richiedere un token x402.

Quando un’esecuzione è accettabile

• Il client MCP ha avviato l’adattatore stdio locale e l’adattatore ha aperto un URL QuokkaPix previsto.
• I file sono entrati tramite il selettore file del browser, non tramite un parametro URL pubblico.
• Il manifesto ha status done, qa.ok è true quando la ricetta ha QA e i warnings vengono controllati prima di usare l’output.
• Per lotti a pagamento, l’unlock token viene verificato prima dell’avvio e consumato solo da un paid run sopra il limite small-batch gratuito.

Strumenti 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

Ricette ufficiali

Esempi

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

Note importanti

I file passano comunque dalla selezione locale del browser. QuokkaPix non espone un'API pubblica di elaborazione lato server.