QuokkaPix MCP Runner

MCP remoto con procesamiento local

Claude web y otros clientes MCP en la nube pueden conectarse mediante OAuth, mientras el adaptador npm existente ejecuta cada operación de imagen en el equipo del usuario.

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

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

El scope mcp:tools permite herramientas de lectura. El procesamiento y el almacenamiento de un unlock token también requieren bridge:execute. --reset revoca el dispositivo anterior antes de emparejar uno nuevo.

El control plane transmite ajustes, nombres de archivo relativos, estado y el result manifest. No tiene un endpoint de carga de imágenes ni transmite los bytes de origen o salida.

Guía práctica para Claude, Cursor y MCP local

Usa esta página cuando un agente de escritorio tenga que procesar imágenes locales con QuokkaPix. El MCP runner es un adaptador stdio local: el cliente MCP inicia quokkapix-mcp, el adaptador abre QuokkaPix en un navegador local, carga archivos mediante el selector del navegador, aplica una receta o ajustes directos, descarga el resultado y escribe quokkapix-result.json.

No es una API alojada de procesamiento de imágenes. Las imágenes originales permanecen en el flujo local del navegador y no se suben a un servidor de procesamiento de QuokkaPix.

Comando alternativo para Windows

Si un cliente MCP en Windows no resuelve npx directamente, ejecútalo mediante cmd /c. Úsalo solo cuando el comando npx simple no sea detectado por el cliente.

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

Clientes MCP locales y wrappers de LLM

Cualquier cliente MCP local que pueda iniciar un servidor stdio puede usar el mismo paquete. Esto incluye clientes de escritorio, agentes de editores y wrappers de LM Studio u Ollama que exponen herramientas MCP a un modelo local.

La regla importante es la misma en todos los casos: pasa rutas reales de archivos locales a la llamada MCP, no a la URL del sitio público. QuokkaPix recibe los archivos solo por el selector local del navegador que abre el runner.

Primeros prompts útiles

Qué verificar después de la ejecución

Ejecuciones gratuitas y de pago

Las ejecuciones de una sola imagen, escenarios de una sola imagen y lotes de agente de hasta 5 archivos son gratuitos. Los lotes o escenarios por lotes de 6 a 50 archivos usan el flujo x402 unlock. Los clientes deben leer los términos actuales en /api/agent-payment/options antes de pedir un unlock de pago.

Cuándo se necesita pago, el agente obtiene un unlockToken, lo establece en QuokkaPix antes de procesar, y el unlock se consume solo cuando empieza un lote de pago o un escenario por lotes.

Solución de problemas

Límite de seguridad

Usa la URL oficial de QuokkaPix o una URL local de desarrollo confiable. No apuntes el runner a un appUrl arbitrario de terceros, porque el adaptador carga archivos locales en la página que abre. El sitio público no recibe rutas locales y el adaptador no convierte QuokkaPix en una API de procesamiento en servidor.

FAQ para agentes y desarrolladores

Qué pueden hacer los agentes

• Ejecutar recetas oficiales para Shopify, Amazon, Google Merchant, compresión WebP, exportación PDF, limpieza de metadatos, paquetes sociales, avatares y marcas de agua.
• Ejecutar custom settings directos con process_with_settings, usando el mismo payload que window.QuokkaPixAgent.applySettings.
• Validar result manifests y obtener QA de formato, dimensiones, límites de peso, tipo de salida, nombres requeridos y contenido ZIP.
• Leer condiciones de pago x402 y verificar tokens de desbloqueo para ejecuciones por lote de agentes.
• Subir archivos asset locales para marcas de agua con logotipo y fondos de reemplazo.

Capacidades actuales del navegador

• El objeto opcional capabilities.backends informa las rutas previstas de procesamiento, codificación e IA de fondo con fallbacks explícitos. Los campos MCP existentes no cambian.
• La exportación avanzada puede usar codificadores WASM para JPEG, optimización PNG, WebP, AVIF y JPEG XL experimental cuando están disponibles.
• La subida ZIP funciona solo en lote: el navegador descomprime localmente las imágenes compatibles antes de procesarlas.
• Las herramientas PDF se controlan con ajustes directos: split y extract usan un solo PDF, merge usa un lote de PDF e images-to-PDF sigue siendo un flujo para imágenes. Extract conserva el orden de pdf-pages; usa pdf-extract-output=zip para PDF separados por página.

Qué revisar después de una ejecución

• Confirma que la carpeta de salida contiene la imagen, ZIP o PDF generado y quokkapix-result.json.
• Lee qa.ok y qa.checks antes de aceptar un lote para marketplace o red social.
• Mantén los archivos fuente separados porque QuokkaPix crea copias de entrega, no reemplaza originales.
• Para lotes de agente de pago, consulta las opciones de pago actuales antes de pedir un token x402.

Cuándo una ejecución es aceptable

• El cliente MCP inició el adaptador stdio local y el adaptador abrió una URL esperada de QuokkaPix.
• Los archivos entraron por el selector de archivos del navegador, no por un parámetro de URL pública.
• El manifiesto tiene status done, qa.ok es verdadero cuando la receta tiene QA y las warnings se revisan antes de usar la salida.
• En lotes pagados, el unlock token se verifica antes de iniciar y se consume solo en una ejecución pagada por encima del límite small-batch gratuito.

Herramientas 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

Recetas oficiales

Ejemplos

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

Notas importantes

Los archivos siguen entrando solo por el selector de archivos local del navegador. QuokkaPix no ofrece una API pública de procesamiento en servidor.