QuokkaPix MCP Runner

MCP distant avec traitement local

Claude web et d'autres clients MCP cloud peuvent se connecter via OAuth, tandis que l'adaptateur npm existant exécute chaque opération d'image sur l'ordinateur de l'utilisateur.

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

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

Le scope mcp:tools autorise les outils de lecture. Le traitement et le stockage d'un jeton de déverrouillage exigent aussi bridge:execute. --reset révoque l'ancien appareil avant d'en associer un nouveau.

Le control plane transmet les réglages, noms de fichiers relatifs, statuts et le result manifest. Il ne possède aucun endpoint d'upload d'image et ne transmet pas les octets source ou de sortie.

Guide pratique pour Claude, Cursor et MCP local

Utilisez cette page lorsqu'un agent desktop doit traiter des images locales avec QuokkaPix. Le MCP runner est un adaptateur stdio local : le client MCP lance quokkapix-mcp, l'adaptateur ouvre QuokkaPix dans un navigateur local, charge les fichiers via le sélecteur du navigateur, applique une recette ou des réglages directs, télécharge le résultat et écrit quokkapix-result.json.

Ce n'est pas une API hébergée de traitement d'images. Les images source restent dans le flux local du navigateur et ne sont pas envoyées à un serveur de traitement QuokkaPix.

Commande de secours pour Windows

Si un client MCP Windows ne trouve pas npx directement, lancez-le via cmd /c. Utilisez cette variante uniquement lorsque la commande npx simple n'est pas détectée.

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

Clients MCP locaux et wrappers LLM

Tout client local compatible MCP capable de démarrer un serveur stdio peut utiliser le même paquet. Cela inclut les clients desktop, les agents d'éditeur et les wrappers LM Studio ou Ollama exposant des outils MCP à un modèle local.

La règle importante est la même partout : passez de vrais chemins de fichiers locaux à l'appel MCP, pas à l'URL du site public. QuokkaPix reçoit les fichiers uniquement par le sélecteur local du navigateur ouvert par le runner.

Premiers prompts utiles

À vérifier après l'exécution

Exécutions agent gratuites et payantes

Les exécutions d'une seule image, les scénarios d'une seule image et les lots agent jusqu'à 5 fichiers sont gratuits. Les lots ou scénarios par lot de 6 à 50 fichiers utilisent le flux x402 unlock. Les clients doivent lire les conditions actuelles dans /api/agent-payment/options avant de demander un paid unlock.

Lorsqu'un paiement est nécessaire, l'agent obtient un unlockToken, le définit dans QuokkaPix avant le traitement, et l'unlock est consommé uniquement au démarrage d'un lot ou scénario par lot payant.

Dépannage

Limite de sécurité

Utilisez l'URL officielle de QuokkaPix ou une URL locale de développement fiable. Ne pointez pas le runner vers une appUrl tierce arbitraire, car l'adaptateur charge des fichiers locaux dans la page qu'il ouvre. Le site public ne reçoit pas les chemins de fichiers locaux et l'adaptateur ne transforme pas QuokkaPix en API serveur.

FAQ pour agents et développeurs

Ce que les agents peuvent faire

• Exécuter les recettes officielles Shopify, Amazon, Google Merchant, compression WebP, export PDF, nettoyage des métadonnées, packs sociaux, avatars et filigranes.
• Exécuter des custom settings directs avec process_with_settings, avec le même payload que window.QuokkaPixAgent.applySettings.
• Valider les result manifests et obtenir des contrôles QA sur format, dimensions, limites de taille, type de sortie, noms requis et contenu ZIP.
• Lire les conditions de paiement x402 et vérifier les jetons de déverrouillage pour les lots payants d’agents.
• Téléverser des fichiers asset locaux pour les filigranes logo et le remplacement d'arrière-plan.

Capacités actuelles du navigateur

• L’objet facultatif capabilities.backends indique les chemins prévus de traitement, d’encodage et d’IA de fond avec des fallbacks explicites. Les champs MCP existants restent inchangés.
• L’export avancé peut utiliser des encodeurs WASM pour JPEG, l’optimisation PNG, WebP, AVIF et JPEG XL expérimental quand ils sont disponibles.
• L’import ZIP fonctionne seulement en lot : le navigateur extrait localement les images prises en charge avant le traitement.
• Les outils PDF passent par les réglages directs : split et extract utilisent un seul PDF, merge utilise un lot de PDF et images-to-PDF reste un flux d’images. Extract conserve l’ordre de pdf-pages ; utilisez pdf-extract-output=zip pour obtenir des PDF séparés par page.

À vérifier après une exécution

• Confirmez que le dossier de sortie contient l'image, le ZIP ou le PDF généré ainsi que quokkapix-result.json.
• Lisez qa.ok et qa.checks avant d'accepter un lot pour marketplace ou réseau social.
• Gardez les fichiers source séparés, car QuokkaPix crée des sorties de livraison et ne remplace pas les originaux.
• Pour les lots payants d'agents, récupérez les options de paiement actuelles avant de demander un token x402.

Quand une exécution est acceptable

• Le client MCP a lancé l’adaptateur stdio local et l’adaptateur a ouvert une URL QuokkaPix attendue.
• Les fichiers sont passés par le sélecteur de fichiers du navigateur, pas par un paramètre d’URL publique.
• Le manifeste indique status done, qa.ok est vrai lorsqu’une recette a un QA, et les warnings sont relus avant d’utiliser la sortie.
• Pour les lots payants, l’unlock token est vérifié avant le démarrage et consommé seulement par une exécution payante au-dessus de la limite small-batch gratuite.

Outils 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

Recettes officielles

Exemples

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

Notes importantes

Les fichiers passent toujours par l'input local du navigateur. QuokkaPix n'expose pas d'API publique de traitement côté serveur.