quokkapix-mcp

Adaptador/servidor MCP local para flujos de trabajo de imágenes solo en navegador de QuokkaPix. Permite a los agentes de IA redimensionar, comprimir, convertir, eliminar fondos, eliminar metadatos, añadir marcas de agua y exportar paquetes de imágenes localmente a través de un navegador sin cargar las imágenes de origen a un servidor de procesamiento.

GitHub
1
Prueba este MCPPatrocinado

Documentación

Ejecutor MCP de QuokkaPix

quokkapix-mcp MCP server

Adaptador MCP local primero y puente de nube a local para flujos de trabajo privados de Imagen y Video de QuokkaPix.

El Ejecutor MCP de QuokkaPix permite a los agentes de IA procesar imágenes y videos locales abriendo la superficie de navegador correspondiente de QuokkaPix, aplicando una receta oficial o configuraciones directas, seleccionando archivos locales a través de la entrada del navegador, guardando la salida y escribiendo un manifiesto de resultados legible por máquina. Las ejecuciones de Imagen escriben quokkapix-result.json; las ejecuciones de Video escriben quokkapix-video-result.json.

Soporta dos modos compatibles:

  • stdio local para Imagen y Video en Claude Desktop, Cursor, envoltorios de LM Studio/Ollama y otros clientes MCP locales;
  • bridge para clientes MCP remotos de Imagen y Video como Claude web, mientras que Chromium y todo el procesamiento de medios permanecen en la computadora del usuario.

Repositorio: https://github.com/quokkapix/quokkapix-mcp

Paquete npm: https://www.npmjs.com/package/quokkapix-mcp

Listado en Glama: https://glama.ai/mcp/servers/quokkapix/quokkapix-mcp

Listado en mcpservers.org: https://mcpservers.org/servers/quokkapix/quokkapix-mcp

Matriz de compatibilidad de navegadores: https://quokkapix.com/en/browser-compatibility/

Benchmark de navegadores: https://quokkapix.com/en/browser-image-processing-benchmark/

Matriz de compatibilidad de video: https://video.quokkapix.com/browser-compatibility/

Benchmark de video: https://video.quokkapix.com/browser-video-processing-benchmark/

Inicio rápido:

npx quokkapix-mcp

Puente de nube a local:

npx quokkapix-mcp bridge --input-root ./media --output-root ./quokkapix-output

Qué Es Esto

Este paquete es un adaptador de automatización local alrededor de dos superficies de navegador:

https://quokkapix.com/#agent=1
https://video.quokkapix.com/#agent=1

El adaptador utiliza Playwright para controlar Chromium local. Imagen usa window.QuokkaPixAgent; Video usa window.QuokkaPixVideoAgent.

Los archivos de imagen, video y audio se procesan en el entorno de ejecución del navegador del usuario. Los bytes de medios fuente no se cargan a un servidor de procesamiento de QuokkaPix. La transcripción local puede descargar y almacenar en caché archivos de modelo Whisper, pero no carga los medios seleccionados con esa solicitud de modelo.

El modo puente opcional se conecta hacia afuera al plano de control de QuokkaPix. El endpoint MCP remoto retransmite configuraciones de herramientas, nombres de archivos relativos, estado y metadatos de resultados. No tiene endpoint de carga de medios y no retransmite bytes de imagen, video, audio o salida fuente.

Qué No Es Esto

Este paquete no es:

  • una API pública de procesamiento de medios del lado del servidor;
  • un servicio de procesamiento de medios alojado (el plano de control MCP remoto solo coordina un puente local emparejado);
  • un backend de procesamiento de medios GPU/CPU operado por QuokkaPix;
  • una forma de pasar rutas de archivos locales a quokkapix.com por URL;
  • un reemplazo para los límites de memoria del navegador.

Las rutas de archivos locales están disponibles solo para el ejecutor MCP local en la máquina del usuario. El sitio web público de QuokkaPix aún recibe archivos solo a través de la entrada de archivos del navegador o la zona de arrastre.

Por Qué Usarlo

Use este adaptador cuando un agente de IA necesite flujos de trabajo de medios repetibles como:

  • preparar fotos de productos para Shopify, Amazon o Google Merchant;
  • validar salidas de imágenes de marketplaces y redes sociales contra perfiles de reglas con fuente;
  • comprimir imágenes a WebP para un sitio web;
  • eliminar metadatos EXIF/GPS;
  • generar paquetes de imágenes para redes sociales;
  • poner marca de agua a un lote de imágenes;
  • generar paquetes de favicon e íconos de aplicaciones;
  • ejecutar configuraciones personalizadas de QuokkaPix sin hacer clic manualmente en la interfaz.
  • cortar, recortar, redimensionar, convertir o comprimir un video local;
  • extraer, silenciar, mezclar o reemplazar audio de video con un archivo de música local;
  • generar transcripciones TXT, SRT o VTT localmente, o quemar subtítulos en MP4;
  • preparar perfiles de video con fuente de YouTube, TikTok Ads y Meta Reels.

El valor principal es la privacidad y el bajo costo de infraestructura: el agente obtiene herramientas prácticas de flujo de trabajo de Imagen y Video, mientras que el procesamiento de medios permanece local en el navegador del usuario.

Arquitectura

AI agent / MCP client
        |
        | stdio MCP
        v
quokkapix-mcp
        |
        | Playwright
        v
local Chromium browser
        |
        | window.QuokkaPixAgent or window.QuokkaPixVideoAgent
        v
quokkapix.com or video.quokkapix.com
        |
        | local browser processing
        v
downloaded output + surface-specific result manifest

Los clientes remotos usan el mismo paquete en modo puente:

Claude web / remote MCP client
        |
        | OAuth 2.1 + Streamable HTTP (commands and metadata only)
        v
QuokkaPix control plane
        |
        | outbound authenticated long poll
        v
quokkapix-mcp bridge on the user's computer
        |
        | Playwright
        v
local Chromium -> local output + quokkapix-result.json or quokkapix-video-result.json

Dependiendo de la superficie seleccionada, el adaptador guarda:

  • la salida generada de imagen, ZIP, PDF, video, audio o transcripción;
  • quokkapix-result.json o quokkapix-video-result.json;
  • un objeto qa devuelto al agente.

Requisitos

  • Node.js >=20
  • npm
  • Playwright Chromium
  • acceso a internet para cargar QuokkaPix y dependencias/modelos del lado del navegador cuando sea necesario
  • rutas de archivos locales que el proceso MCP pueda leer

El modo puente adicionalmente requiere raíces de entrada y salida explícitas. Las llamadas remotas no pueden leer o escribir fuera de esas raíces.

Instalar dependencias:

npm install
npx playwright install chromium

Configuración de MCP Remoto y Puente

  1. Inicie el paquete existente en modo puente:
npx -y quokkapix-mcp bridge \
  --input-root /absolute/path/to/input \
  --output-root /absolute/path/to/output
  1. Apruebe la URL de emparejamiento única impresa por el comando.
  2. Agregue https://quokkapix.com/mcp como conector MCP remoto personalizado.
  3. Complete la autorización OAuth en el navegador.

El puente almacena su credencial de dispositivo aleatoria en ~/.quokkapix/bridge.json con permisos solo de propietario donde el sistema operativo lo soporte. Use --pair para aprobar otra sesión de navegador o --reset para revocar la autorización de dispositivo anterior y crear una nueva credencial.

Las rutas de procesamiento remoto son relativas a --input-root y --output-root. El puente rechaza el traversal de rutas y no devuelve rutas locales absolutas al cliente en la nube.

Herramientas MCP

list_recipes

Lista las recetas oficiales de QuokkaPix.

Úsela primero cuando el agente no sepa qué flujo de trabajo ejecutar.

get_recipe

Devuelve una receta por id, incluyendo:

  • applySettings;
  • límites de archivos;
  • salida esperada;
  • contrato de QA;
  • requisito de pago.

Entrada:

{
  "id": "shopify_product_pack"
}

validate_recipe

Valida un objeto de receta personalizado antes del procesamiento.

Esto no carga archivos y no inicia el procesamiento.

list_rule_profiles

Lista perfiles de reglas de imagen de marketplaces y redes sociales con fuente.

Úsela cuando un agente necesite hechos para Amazon, Shopify, Google Merchant, Etsy, eBay, Walmart, TikTok Shop, Mercado Libre, Temu, Shopee, Instagram, YouTube, LinkedIn, X, Pinterest, Facebook o TikTok antes de elegir un flujo de trabajo o verificar una salida.

Cada perfil declara:

  • sourceType: official o secondary;
  • sourceUrl;
  • confidence;
  • requisitos y recomendaciones que se encontraron de la fuente nombrada.

El ejecutor no inventa requisitos de marketplace faltantes. Las entradas de Temu, Mercado Libre, Shopee y algunas de YouTube están marcadas como secundarias o específicas de categoría/país donde las especificaciones públicas oficiales eran limitadas.

get_rule_profile

Devuelve un perfil de reglas por id, por ejemplo:

{
  "id": "amazon.product.image"
}

Los agentes pueden pasar los hechos devueltos a su propia planificación, o llamar a validate_result_manifest con ruleProfileId.

validate_result_manifest

Valida un quokkapix-result.json existente contra una receta o contrato de QA personalizado.

Esto es útil cuando un agente quiere inspeccionar una ejecución anterior y decidir si la salida es aceptable.

Entrada opcional:

{
  "ruleProfileId": "amazon.product.image",
  "manifest": {}
}

Cuando se proporciona ruleProfileId, el informe de QA incluye verificaciones de marketplace con fuente como formatos soportados, dimensiones, tipo de fuente y URL. Si el manifiesto de resultados del navegador incluye outputs[].pixelQa, el validador también evalúa verificaciones visuales soportadas a nivel de píxel como fondo blanco, centrado del sujeto, márgenes seguros y fondo transparente.

Herramientas de video

  • list_video_recipes — lista recetas oficiales de Cortar, Recortar, Convertir, Comprimir, Audio y Transcribir.
  • get_video_recipe — devuelve una receta de Video y su QA esperado.
  • validate_video_recipe — valida una receta de Video personalizada sin procesar medios.
  • list_video_rule_profiles — lista perfiles con fuente de YouTube, TikTok Ads y Meta Reels.
  • get_video_rule_profile — devuelve un perfil de Video con su fuente oficial.
  • validate_video_result_manifest — valida un quokkapix-video-result.json existente.
  • process_video — procesa un video local con una receta oficial.
  • process_video_with_settings — procesa un video local con configuraciones directas de QuokkaPixVideoAgent.

Ejemplo:

{
  "recipeId": "tiktok_vertical",
  "inputFile": "/Users/me/video/source.mp4",
  "outputDir": "/Users/me/video/out"
}

Ejemplo de mezcla de audio:

{
  "settings": {
    "tool": "audio",
    "audio": { "mode": "mix", "volume": 100, "musicVolume": 35 }
  },
  "inputFile": "/Users/me/video/source.mp4",
  "musicFile": "/Users/me/audio/music.wav",
  "outputDir": "/Users/me/video/out"
}

La versión 0.7.0 expone el flujo unificado de cotización de pago y token de Imagen/Video a través del MCP remoto protegido por OAuth y el puente local emparejado. Los valores remotos de inputFile, musicFile opcional y outputDir son relativos a las raíces configuradas; sus bytes nunca pasan por el plano de control. Las llamadas de Video de pago a través del puente requieren 0.7.0 o más reciente.

process_images

Procesa archivos de imagen locales a través de QuokkaPix usando:

  • un recipeId oficial;
  • un objeto de receta personalizado completo.

Abre un navegador, aplica la receta, carga archivos, inicia el procesamiento, descarga la salida, escribe quokkapix-result.json y devuelve resultados de QA.

Archivos de activos locales opcionales:

  • watermarkLogoFile: archivo de logo/imagen local cargado en la entrada de logo de marca de agua de QuokkaPix.
  • backgroundImageFile: archivo de imagen local cargado en la entrada de imagen de reemplazo de fondo de QuokkaPix.

Estos activos aún se cargan solo en la página del navegador local. No se pasan como rutas URL al sitio web público de QuokkaPix.

process_with_settings

Procesa archivos de imagen locales usando un payload directo de applySettings de QuokkaPix.

Úsela cuando el agente ya conozca la configuración exacta del editor y no quiera envolverla en una receta.

Esta es la superficie de herramienta más amplia. Puede manejar la misma superficie de configuración que:

window.QuokkaPixAgent.applySettings(payload)

Las áreas de editor soportadas dependen del contrato de navegador de QuokkaPix e incluyen:

  • redimensionar;
  • recortar;
  • rotar;
  • convertir;
  • comprimir;
  • exportación avanzada a formatos soportados por el navegador y JPEG XL experimental cuando el codificador cargado en el navegador esté disponible;
  • eliminación/reporte de metadatos;
  • herramientas de fusión/división/extracción de PDF a través de tool=pdf y pdf.operation solo para archivos PDF cargados; los archivos ZIP se aceptan solo para fusión de PDF y solo se extraen entradas PDF;
  • configuración de eliminación/reemplazo de fondo;
  • marca de agua;
  • efectos;
  • renombrar;
  • flujos de trabajo de constructor/escenarios.

Para escenarios personalizados, prefiera la forma estructurada explícita:

{
  "mode": "batch",
  "tool": "constructor",
  "steps": [
    {
      "tool": "resize",
      "settings": { "mode": "fit", "width": 1200, "height": 1200 }
    },
    {
      "tool": "watermark",
      "settings": { "type": "text", "text": "Brand", "layout": "tiled", "angle": -20 }
    },
    {
      "tool": "compress",
      "settings": { "format": "webp", "quality": 0.82 }
    }
  ]
}

El paso settings usa las mismas claves de sección que window.QuokkaPixAgent.applySettings.

Las herramientas de PDF usan cargas de PDF en lugar de cargas de imagen:

{
  "tool": "pdf",
  "pdf": {
    "operation": "extract",
    "extractPages": "1,3-5",
    "extractOutput": "pdf"
  }
}

Use operation: "split" para exportar un PDF cargado como un ZIP de PDFs de una página. Use operation: "extract" con extractPages para crear un PDF que contenga solo las páginas seleccionadas de un PDF cargado; el orden de páginas se conserva, por lo que extractPages: "3,1" exporta la página 3 antes de la página 1. Establezca extractOutput: "zip" cuando las páginas seleccionadas deban devolverse como PDFs separados de una página dentro de un ZIP. tool: "pdf" tiene como valor predeterminado dividir. Dividir y extraer son flujos de trabajo de un solo PDF porque los números de página se refieren a un PDF fuente. Use operation: "merge" para combinar múltiples PDFs en un solo PDF en el orden de archivos actual del navegador; fusionar es un flujo de trabajo por lotes y cambia el editor del navegador a modo por lotes. Los usuarios humanos pueden reordenar archivos de fusión en la interfaz; los clientes MCP deben pasar los archivos en el orden de fusión deseado.

La carga ZIP es solo por lotes. Si un usuario o agente selecciona un .zip en modo por lotes, QuokkaPix lo descomprime localmente en el navegador y agrega imágenes soportadas del archivo a la cola por lotes. RAR y 7z no se aceptan.

get_payment_options

Obtiene la política de pago de agentes de QuokkaPix y los endpoints x402.

Esto no realiza un pago.

explain_payment_flow

Explica el flujo de pago x402 actual para agentes.

Importante: este adaptador MCP local no firma pagos x402 por sí mismo. Un cliente o billetera con capacidad x402 debe llamar al endpoint de desbloqueo de pago y devolver un unlockToken.

verify_unlock_token

Verifica de forma segura un token de desbloqueo de agente pagado antes del procesamiento sin consumirlo. El adaptador deliberadamente no tiene opción de pre-consumo: el desbloqueo de un solo uso se consume solo por la ruta de inicio del navegador después de que la validación tenga éxito.

Herramientas de puente solo remoto

El endpoint MCP remoto alojado también expone:

  • get_bridge_status para verificar el emparejamiento y la disponibilidad local;
  • get_billing_status para verificar si un desbloqueo de un solo uso verificado está preparado;
  • set_unlock_token para preparar un desbloqueo x402 para el próximo lote local pagado.

El verify_unlock_token remoto es solo de pre-vuelo y nunca consume el token. El consumo real permanece dentro de la ruta de inicio del navegador local.

El endpoint alojado también retransmite todas las herramientas de receta, regla, QA y procesamiento de Imagen y Video listadas anteriormente. Tanto process_video como process_video_with_settings requieren el alcance OAuth bridge:execute. Video usa productos de duración/transcripción en lugar de los productos de archivo/PDF de Imagen; ambas superficies usan el mismo protocolo x402.

Recetas Oficiales

El runner carga las recetas del proyecto local si están presentes. Si los archivos de recetas locales no existen, recurre a:

https://quokkapix.com/agent-recipes/

Recetas oficiales actuales:

ID de recetaPropósitoModoSalida
shopify_product_packFotos de productos para ShopifyloteZIP
amazon_white_background_packFotos de productos con fondo blanco estilo AmazonloteZIP
google_merchant_packImágenes de productos para Google MerchantloteZIP
etsy_product_batchLote de imágenes de productos para Etsy con QA verificadoloteZIP
ebay_listing_photo_batchLote de fotos para anuncios de eBayloteZIP
walmart_product_main_batchImágenes principales de productos para WalmartloteZIP
tiktok_shop_product_batchImágenes de productos para TikTok ShoploteZIP
temu_product_main_batchImágenes de productos estilo Temu con fuente secundarialoteZIP
shopee_product_batchImágenes de productos para ShopeeloteZIP
mercado_libre_accessories_batchFotos de accesorios para Mercado LibreloteZIP
allegro_listing_image_batchImágenes de anuncios para AllegroloteZIP
newegg_product_image_batchImágenes de productos para NeweggloteZIP
meta_catalog_product_batchImágenes de productos para Meta CatalogloteZIP
flipkart_product_image_batchFotos de productos para Flipkart según guía públicaloteZIP
shein_product_square_batchImágenes cuadradas de productos para SHEIN con fuente secundarialoteZIP
otto_product_image_batchImágenes de productos para OTTO con QA mínimo de 500 x 1000 px verificadoloteZIP
trendyol_product_image_batchImágenes de productos para Trendyol con tamaño de 1200 x 1800 px verificadoloteZIP
snapchat_ad_image_batchImágenes estáticas de anuncios para SnapchatloteZIP
website_webp_compressCompresión de imágenes de sitios web a WebPloteZIP
webp_compress_batchConversión y compresión general de lotes a WebPloteZIP
white_background_shadow_batchImágenes de productos con fondo blanco y sombra suaveloteZIP
metadata_clean_batchEliminar metadatos EXIF/GPS/cámara/softwareloteZIP
single_webp_compressComprimir una imagen a WebPindividualimagen
single_background_removeEliminar el fondo de una imagenindividualimagen
single_white_backgroundCrear una imagen de producto con fondo blancoindividualimagen
single_metadata_cleanEliminar metadatos de una imagenindividualimagen
single_watermarkAplicar una marca de agua de texto a una imagenindividualimagen
images_to_pdf_batchFusionar imágenes o escaneos seleccionados en un PDFlotePDF
social_pack_singleTamaños para redes sociales a partir de una imagenindividualZIP
profile_avatar_packTamaños de avatar de perfil a partir de una imagenindividualZIP
watermark_product_batchAplicar marca de agua a imágenes de productosloteZIP
favicon_app_icon_packGenerar tamaños de favicon e iconos de aplicaciónindividualZIP

Los agentes normalmente deben llamar a list_recipes, elegir la receta más cercana y luego llamar a process_images.

Use process_with_settings cuando el flujo de trabajo deseado no esté cubierto por una receta.

Instalación desde el código fuente

Desde la carpeta mcp-runner:

npm install
npx playwright install chromium
npm run check

Inicie el servidor MCP:

npx quokkapix-mcp

Ejecución directa por CLI sin un cliente MCP:

npx quokkapix-runner --recipe website_webp_compress --input ./photo.jpg --output ./out

Configuración del cliente MCP

Para la mayoría de los usuarios, configure el paquete npm publicado directamente:

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

Use rutas absolutas para cwd.

Claude Desktop desde el código fuente

Si clonó el repositorio de GitHub en lugar de usar npm, agregue esto a su configuración MCP de Claude Desktop:

{
  "mcpServers": {
    "quokkapix": {
      "command": "node",
      "args": ["src/server.mjs"],
      "cwd": "/absolute/path/to/quokkapix-mcp",
      "env": {
        "QUOKKAPIX_APP_URL": "https://quokkapix.com/#agent=1"
      }
    }
  }
}

Cursor desde el código fuente

Si clonó el repositorio de GitHub en lugar de usar npm, use la misma definición de servidor en la configuración MCP de Cursor:

{
  "mcpServers": {
    "quokkapix": {
      "command": "node",
      "args": ["src/server.mjs"],
      "cwd": "/absolute/path/to/quokkapix-mcp",
      "env": {
        "QUOKKAPIX_APP_URL": "https://quokkapix.com/#agent=1"
      }
    }
  }
}

Desarrollo local

Ejecute QuokkaPix localmente y apunte el runner hacia él:

QUOKKAPIX_APP_URL=http://127.0.0.1:4177/#agent=1 npx quokkapix-mcp

Anule la raíz del sitio local:

QUOKKAPIX_SITE_ROOT=/path/to/quokkapix-site npx quokkapix-mcp

Anule la fuente pública de recetas:

QUOKKAPIX_RECIPE_BASE_URL=https://quokkapix.com/agent-recipes npx quokkapix-mcp

Anule la URL base de pago:

QUOKKAPIX_PAYMENT_BASE_URL=https://quokkapix.com npx quokkapix-mcp

appUrl está restringido intencionalmente por seguridad de archivos locales. De forma predeterminada, el runner solo abre:

  • https://quokkapix.com/ y https://www.quokkapix.com/;
  • http://127.0.0.1, http://localhost y equivalentes HTTPS locales.

Esto evita que un prompt o receta maliciosa apunte el runner del navegador a una página no relacionada y cargue archivos locales allí. Solo para desarrollo confiable, las URL de aplicaciones personalizadas se pueden habilitar con:

QUOKKAPIX_ALLOW_CUSTOM_APP_URL=1 npx quokkapix-mcp

Ejemplo: Procesar fotos de productos para Shopify

Herramienta: process_images

{
  "recipeId": "shopify_product_pack",
  "inputFiles": [
    "/Users/me/products/photo-1.jpg",
    "/Users/me/products/photo-2.jpg",
    "/Users/me/products/photo-3.jpg",
    "/Users/me/products/photo-4.jpg",
    "/Users/me/products/photo-5.jpg",
    "/Users/me/products/photo-6.jpg"
  ],
  "outputDir": "/Users/me/products/out",
  "headless": true
}

Salida esperada:

  • un archivo ZIP en outputDir;
  • quokkapix-result.json;
  • un informe qa devuelto.

El resultado de la herramienta separa el éxito del procesamiento del éxito del QA:

  • processingOk: true significa que QuokkaPix completó y produjo un archivo de salida;
  • qaOk: true significa que la salida pasó las verificaciones de QA de la receta;
  • ok de nivel superior sigue a qaOk, por lo que los agentes no deben tratar una ejecución de QA fallida como completamente exitosa.

Ejemplo: Configuración personalizada directa

Herramienta: process_with_settings

{
  "settings": {
    "mode": "single",
    "tool": "compress",
    "settings": {
      "compress": {
        "format": "webp",
        "quality": 0.82,
        "targetEnabled": false
      }
    }
  },
  "settingsId": "custom-webp-compress",
  "expectedResultQa": {
    "profile": "custom-webp-compress",
    "expectedFormat": "webp"
  },
  "inputFiles": ["/Users/me/images/photo.jpg"],
  "outputDir": "/Users/me/images/out"
}

Use esto para flujos de trabajo personalizados que no sean recetas oficiales.

Ejemplo: Recurso de marca de agua de logotipo

Herramienta: process_with_settings

{
  "settings": {
    "mode": "single",
    "tool": "watermark",
    "settings": {
      "watermark": {
        "type": "image",
        "layout": "single",
        "position": "center",
        "scalePercent": 20,
        "opacity": 0.25
      }
    }
  },
  "watermarkLogoFile": "/Users/me/brand/logo.svg",
  "inputFiles": ["/Users/me/images/photo.jpg"],
  "outputDir": "/Users/me/images/out"
}

Ejemplo: Recurso de imagen de fondo

Herramienta: process_with_settings

{
  "settings": {
    "mode": "batch",
    "tool": "constructor",
    "steps": [
      {
        "tool": "background",
        "settings": {
          "mode": "replace",
          "replaceMode": "chroma",
          "fill": "image",
          "sourceColor": "#ffffff",
          "tolerance": 36,
          "exportFormat": "webp"
        }
      },
      {
        "tool": "compress",
        "settings": { "format": "webp", "quality": 0.82 }
      }
    ]
  },
  "backgroundImageFile": "/Users/me/backgrounds/studio.webp",
  "inputFiles": ["/Users/me/products/photo-1.jpg", "/Users/me/products/photo-2.jpg"],
  "outputDir": "/Users/me/products/out"
}

Este lote de dos archivos es gratuito. Para un nivel de pago, primero ejecute sin un token para obtener la cotización local exacta y luego reintente sin cambios con su producto unlockToken.

Ejemplo: Limpieza de metadatos

Herramienta: process_images

{
  "recipeId": "metadata_clean_batch",
  "inputFiles": [
    "/Users/me/private/photo-1.jpg",
    "/Users/me/private/photo-2.jpg"
  ],
  "outputDir": "/Users/me/private/clean"
}

Para ejecuciones por lotes, consulte la sección de pagos a continuación.

Ejemplo: Validación solo de QA

Herramienta: validate_result_manifest

{
  "recipeId": "shopify_product_pack",
  "manifest": {
    "status": "done",
    "source": {
      "count": 1,
      "totalBytes": 1000
    },
    "outputs": [
      {
        "sourceName": "photo.jpg",
        "outputName": "shopify_1.webp",
        "outputWidth": 2048,
        "outputHeight": 2048,
        "format": "webp",
        "sizeBytes": 250000,
        "warnings": []
      }
    ],
    "warnings": []
  }
}

El resultado contiene:

{
  "ok": true,
  "profile": "shopify-product",
  "summary": {
    "checks": 8,
    "failures": 0,
    "warnings": 0,
    "outputs": 1
  },
  "checks": []
}

Manifiesto de resultados

Después del procesamiento, el runner escribe:

quokkapix-result.json

El manifiesto es devuelto por:

window.QuokkaPixAgent.getResultManifest()

Contiene hechos de procesamiento local legibles por máquina:

  • schemaVersion;
  • status;
  • success;
  • tool;
  • mode;
  • source.count;
  • source.totalBytes;
  • outputs[];
  • dimensiones de origen/salida cuando estén disponibles;
  • nombres de archivos de salida;
  • formatos;
  • tamaños en bytes;
  • advertencias;
  • processingMs;
  • capacidades del navegador;
  • rutas de backend planificadas opcionales en capabilities.backends;
  • errorCode estable.

El manifiesto no contiene bytes de imagen.

capabilities.backends es aditivo y consultivo. El adaptador MCP actual ya pasa los campos de manifiesto del navegador desconocidos sin cambios, por lo que este campo no requiere una nueva versión del adaptador. Continúe usando el estado terminal, errorCode y los resultados de QA para decidir si una ejecución fue exitosa.

Validación de QA

El runner valida los manifiestos de resultados contra los contratos de QA de las recetas. Cada verificación incluye name, ok, severity, expected, actual, message y remediation, para que los agentes puedan informar tanto qué falló como qué configuración cambiar.

Las verificaciones de QA actuales incluyen:

  • el estado de ejecución es done;
  • el recuento de fuentes es positivo;
  • el recuento de fuentes está dentro del límite de la receta;
  • las salidas están presentes;
  • formato esperado;
  • ancho/alto esperado;
  • ancho/alto máximo;
  • salida cuadrada cuando se requiere;
  • tamaño máximo de salida en KB cuando el tamaño por archivo está disponible;
  • prefijo del nombre de salida;
  • ausencia de advertencias requeridas;
  • las entradas ZIP están representadas en el manifiesto;
  • recuento mínimo de salida esperado para paquetes.
  • verificaciones a nivel de píxel cuando el manifiesto del navegador contiene métricas outputs[].pixelQa:
    • fondo blanco;
    • sujeto centrado;
    • márgenes seguros;
    • fondo transparente.

Las verificaciones semánticas como presencia de marca de agua, texto promocional, restos de fondo antiguo o calidad subjetiva de recorte no se marcan como aprobadas sin una señal medible en el manifiesto. Si un contrato de QA personalizado solicita una verificación visual no compatible, el validador lo informa como una advertencia en lugar de tratarlo silenciosamente como aprobado.

Esas requieren un analizador semántico futuro u otra señal medible explícita. El runner actualmente no pretende verificarlas.

Pagos de agentes y x402

La interfaz humana de QuokkaPix y los flujos de recompensas no cambian.

El precio de los agentes se calcula a partir de los medios reales cargados en el navegador local.

Política actual:

Superficie/ejecuciónGratisSiguiente nivelNivel mayor
Herramientas normales de imagen1-5 archivos reales6-25: 0.0126-50: 0.02 USDC; >50 bloqueado
PDFHasta 20 páginas21-50: 0.0151-300: 0.02 USDC; >300 bloqueado
Escenario de imagen de múltiples pasos--0.02 USDC
Edición normal de videoHasta 5 min>5-15: 0.01; >15-30: 0.02>30: 0.03 USDC
Transcripción de videoHasta 5 min>5-15: 0.02; >15-30: 0.04>30-45: 0.06 USDC; >45 bloqueado

Los contenidos ZIP cuentan después de la extracción local. La transcripción más la grabación de subtítulos es una ejecución con precio de transcripción, no dos tarifas. Grabar segmentos de transcripción que ya existen usa el nivel normal de edición de video.

  • proveedor: Coinbase x402;
  • proveedor: Coinbase x402;
  • moneda/redes: USDC en Base (eip155:8453, predeterminado), Polygon (eip155:137), Arbitrum (eip155:42161) y World Chain (eip155:480) cuando lo expone /api/agent-payment/options;
  • endpoint de opciones de pago: /api/agent-payment/options;
  • endpoint de desbloqueo de producto: /api/agent-unlock/coinbase-x402/:productId;
  • endpoint de verificación: /api/agent-unlock/verify;
  • contrato formal de API: /x402-api.md.

El runner MCP puede:

  • obtener opciones de pago;
  • explicar el flujo de pago;
  • verificar un token de desbloqueo;
  • pasar un token de desbloqueo al procesamiento.

El runner MCP no firma pagos x402 por sí mismo. Un cliente o billetera compatible con x402 debe obtener el unlockToken.

El modo puente no agrega una segunda tarifa y WebMCP no tiene un cargo separado. Un cliente remoto puede pasar unlockToken en la llamada de procesamiento reintentada o llamar a set_unlock_token con el uso correspondiente. El plano de control mantiene un token escalonado solo en memoria y nunca lo consume. El navegador local sigue siendo autoritativo y consume el token inmediatamente antes de que comience el procesamiento.

Siempre llame a get_payment_options para conocer los productos actuales y la disponibilidad del proveedor. Para una cotización exacta, ejecute la herramienta de proceso adecuada sin un token. El navegador local primero expande los ZIP o lee las páginas PDF/duración de video y devuelve una cotización sin comenzar el trabajo de pago.

Flujo de pago:

  1. Aplique la configuración y proporcione las rutas locales a una herramienta de proceso sin un token.
  2. Lea la cotización local devuelta y su productId/paymentEndpoint.
  3. Use un cliente compatible con x402 para pagar ese endpoint de producto.
  4. Lea unlockToken; opcionalmente llame a verify_unlock_token con el uso correspondiente.
  5. Reintente la misma llamada de proceso de Imagen o Video sin cambios con unlockToken.
  6. El navegador vuelve a verificar el nivel y consume el token inmediatamente antes de que comience el trabajo.

Ejemplo:

{
  "recipeId": "shopify_product_pack",
  "inputFiles": [
    "/Users/me/products/photo-1.jpg",
    "/Users/me/products/photo-2.jpg"
  ],
  "outputDir": "/Users/me/products/out",
  "unlockToken": "eyJhbGciOiJIUzI1NiIs..."
}

Prompt recomendado para agentes

Use este prompt en su cliente de IA local:

Use QuokkaPix only through the MCP tools. First call list_recipes unless I give exact settings. For standard product, web, metadata, social, watermark or favicon workflows, prefer process_images with an official recipe. For custom image settings, use process_with_settings. After processing, inspect qa.ok and quokkapix-result.json. If qa.ok is false, report the failing checks and do not claim the output is ready. Do not say images were uploaded to a QuokkaPix processing server.

CLI

El paquete también expone un CLI directo:

quokkapix-runner --recipe website_webp_compress --input ./photo.jpg --output ./out

Opciones:

--recipe, --recipe-id   Official recipe id.
--input, --file         Input image path. Repeat for multiple files.
--output, --output-dir  Output directory.
--app-url               QuokkaPix URL, default https://quokkapix.com/#agent=1.
--unlock-token          Product-specific x402 unlock token for a paid Image run.
--headed                Show browser window.
--timeout-ms            Timeout in milliseconds.

El CLI actualmente ejecuta procesamiento basado en recetas. Para configuración directa, use la herramienta MCP process_with_settings.

Comando de puente:

npx quokkapix-mcp bridge --input-root ./media --output-root ./quokkapix-output

Use npx quokkapix-mcp bridge --help para emparejamiento, configuración, navegador con interfaz y opciones de diagnóstico. Ejecutar npx quokkapix-mcp sin bridge sigue siendo el servidor MCP stdio original.

Pruebas

Verificaciones rápidas:

npm run check

Esto verifica:

  • sintaxis de los archivos del servidor MCP;
  • carga y validación de recetas;
  • generación de flujos de trabajo de configuración directa;
  • validador de QA;
  • herramientas auxiliares de pago;
  • analizador de CLI.

GitHub Actions ejecuta las mismas verificaciones en Node 20 y Node 24 en Windows y Linux. El trabajo de Linux/Node 24 también sube el .tgz generado como un artefacto de flujo de trabajo de corta duración, por lo que una ejecución exitosa verifica el archivo del paquete real.

Prueba de procesamiento de navegador de extremo a extremo contra una aplicación QuokkaPix ya en ejecución:

QUOKKAPIX_E2E_APP_URL=http://127.0.0.1:4180/#agent=1 npm run test:e2e

Las pruebas e2e gratuitas procesan un fixture local, configuración personalizada directa y carga de recurso de marca de agua de logotipo. Las pruebas e2e de lote de pago se omiten a menos que se proporcionen tokens de desbloqueo reales.

Para pruebas e2e de pago:

QUOKKAPIX_E2E_APP_URL=http://127.0.0.1:4180/#agent=1 \
QUOKKAPIX_E2E_UNLOCK_TOKENS=token1,token2,token3,token4 \
npm run test:e2e

Las pruebas de pago usan tokens separados porque los desbloqueos son consumibles de un solo uso.

Verificación de publicación

Antes de publicar o etiquetar una versión:

npm run check
npm pack --dry-run

Al empujar una etiqueta vX.Y.Z auditada se ejecuta .github/workflows/release.yml, se compila el paquete nuevamente y se adjunta el .tgz a un lanzamiento de GitHub. La publicación en npm es un flujo de trabajo manual separado. Configure npm Trusted Publisher para este repositorio, el flujo de trabajo publish-npm.yml y el entorno de GitHub npm, luego ejecute Publicar paquete npm con la etiqueta de lanzamiento existente. El flujo de trabajo usa OIDC y no almacena un token de npm en el repositorio.

La lista blanca de paquetes incluye solo:

  • src/;
  • examples/;
  • CHANGELOG.md;
  • LICENSE;
  • README.md;
  • SECURITY.md;
  • package.json.

node_modules, los artefactos de prueba y el sitio web completo de QuokkaPix no se incluyen en el paquete npm.

Notas de seguridad y privacidad

  • Los archivos de imagen, video y música opcional se leen desde rutas locales por el ejecutor de MCP.
  • Los archivos se cargan solo en la página del navegador local a través de Playwright.
  • El procesamiento del navegador de QuokkaPix no carga medios fuente a un servidor de procesamiento de QuokkaPix.
  • El sitio web público aún no puede leer rutas locales arbitrarias.
  • Los tokens de pago deben tratarse como secretos de corta duración.
  • No confirme tokens de desbloqueo reales, archivos privados o carpetas de salida locales.
  • Los secretos del dispositivo puente permanecen en la configuración local y se almacenan como hashes por el plano de control.
  • OAuth usa código de autorización con PKCE, tokens de acceso vinculados a la audiencia y tokens de actualización rotativos. Las herramientas de procesamiento además requieren el alcance bridge:execute; mcp:tools solo es de solo lectura.
  • Los argumentos de archivos remotos están restringidos a raíces configuradas; se rechazan el recorrido .. y las rutas absolutas fuera de la raíz.
  • El plano de control no tiene una ruta de carga de medios. Recibe comandos, nombres relativos, estado y metadatos de resultados.
  • Una IA en la nube puede recibir bytes de medios solo si el usuario carga o comparte por separado una salida con esa IA; el modo puente no hace eso automáticamente.

Limitaciones

  • La RAM del navegador es el límite estricto para lotes grandes.
  • La eliminación de fondo puede descargar archivos de modelos de IA del lado del navegador y depende de la capacidad del navegador/dispositivo.
  • La disponibilidad de WebGPU/WebNN depende del navegador y hardware del usuario.
  • El soporte de HEIC/AVIF/WebP depende del navegador y de codificadores opcionales del lado del navegador.
  • La exportación JPEG XL es experimental y requiere el codificador avanzado cargado en el navegador; no tiene respaldo de Canvas.
  • La combinación/división/extracción de PDF espera archivos PDF. La receta existente de imágenes a PDF espera archivos de imagen.
  • La importación ZIP funciona solo en modo lote y solo extrae archivos de imagen compatibles.
  • La eliminación de fondo GIF no es compatible.
  • El control de calidad a nivel de píxeles es determinista y se limita a hechos de imagen medibles. No afirma reconocimiento semántico de texto, contenido de marcas de agua o calidad subjetiva de retoque.
  • El adaptador actualmente usa automatización del navegador Playwright, no una biblioteca nativa de procesamiento de imágenes.
  • En modo puente, el cliente remoto debe conocer rutas relativas bajo la raíz de entrada configurada; la navegación de directorios no se expone intencionalmente.
  • Los trabajos de puente activos son solo de memoria y fallan de forma segura durante un reinicio del plano de control.

Solución de problemas

Falta el navegador Playwright

Ejecute:

npx playwright install chromium

El agente no puede encontrar archivos

Use rutas de archivo locales absolutas. El proceso MCP debe tener permiso para leerlas.

Una ejecución indica que se requiere pago

Lea la cotización local devuelta, pague su endpoint específico del producto y reintente la llamada sin cambios con el unlockToken resultante. No reutilice un token para otro nivel de producto.

El navegador se queda sin memoria

Reduzca el tamaño del lote, redimensione primero, evite imágenes muy grandes o use flujos de trabajo más pequeños. El ejecutor no puede omitir los límites de RAM del navegador.

El control de calidad informa verificaciones visuales no compatibles

Eso es esperado para requisitos visuales semánticos que no se pueden probar desde el manifiesto del navegador. El validador usa outputs[].pixelQa para verificaciones medibles y deja las verificaciones semánticas no compatibles sin reclamar.

Archivos relacionados del agente QuokkaPix

Descubrimiento y documentación pública:

  • https://quokkapix.com/agents.md
  • https://quokkapix.com/agents.html
  • https://quokkapix.com/llms.txt
  • https://quokkapix.com/agent-manifest.json
  • https://quokkapix.com/.well-known/ai-catalog.json
  • https://quokkapix.com/agent-test.html
  • https://quokkapix.com/mcp-runner.html
  • https://quokkapix.com/x402-api.md

Licencia

MIT. Consulte LICENSE.