quokkapix-mcp

Adaptador/servidor MCP local para fluxos de trabalho de imagem exclusivos do navegador QuokkaPix. Ele permite que agentes de IA redimensionem, comprimam, convertam, removam fundos, removam metadados, adicionem marcas d'água e exportem pacotes de imagens localmente através de um navegador, sem fazer upload das imagens de origem para um servidor de processamento.

GitHub

Experimente este MCPPatrocinado

Documentação

Runner MCP do QuokkaPix

Adaptador MCP local-first e ponte nuvem-para-local para fluxos de trabalho privados de Imagem e Vídeo do QuokkaPix.

O Runner MCP do QuokkaPix permite que agentes de IA processem imagens e vídeos locais abrindo a superfície de navegador correspondente do QuokkaPix, aplicando uma receita oficial ou configurações diretas, selecionando arquivos locais por meio do input do navegador, salvando a saída e escrevendo um manifesto de resultado legível por máquina. Execuções de Imagem gravam quokkapix-result.json; execuções de Vídeo gravam quokkapix-video-result.json.

Ele suporta dois modos compatíveis:

stdio local para Imagem e Vídeo no Claude Desktop, Cursor, wrappers LM Studio/Ollama e outros clientes MCP locais;
bridge para clientes MCP remotos de Imagem e Vídeo, como o Claude web, enquanto o Chromium e todo o processamento de mídia permanecem no computador do usuário.

Repositório: https://github.com/quokkapix/quokkapix-mcp

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

Listagem no Glama: https://glama.ai/mcp/servers/quokkapix/quokkapix-mcp

Listagem no mcpservers.org: https://mcpservers.org/servers/quokkapix/quokkapix-mcp

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

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

Matriz de compatibilidade de vídeo: https://video.quokkapix.com/browser-compatibility/

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

Início rápido:

npx quokkapix-mcp

Ponte nuvem-para-local:

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

O Que É Isto

Este pacote é um adaptador de automação local em torno de duas superfícies de navegador:

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

O adaptador usa Playwright para controlar o Chromium local. Imagem usa window.QuokkaPixAgent; Vídeo usa window.QuokkaPixVideoAgent.

Arquivos de imagem, vídeo e áudio são processados no runtime do navegador do usuário. Os bytes de mídia de origem não são enviados para um servidor de processamento do QuokkaPix. A transcrição local pode baixar e armazenar em cache arquivos de modelo Whisper, mas não envia a mídia selecionada com essa solicitação de modelo.

O modo de ponte opcional conecta-se externamente ao plano de controle do QuokkaPix. O endpoint MCP remoto retransmite configurações de ferramentas, nomes de arquivos relativos, status e metadados de resultado. Ele não possui endpoint de upload de mídia e não retransmite bytes de imagem, vídeo, áudio ou saída de origem.

O Que Isto Não É

Este pacote não é:

uma API pública de processamento de mídia no servidor;
um serviço de processamento de mídia hospedado (o plano de controle MCP remoto apenas coordena uma ponte local pareada);
um backend de processamento de mídia GPU/CPU operado pelo QuokkaPix;
uma forma de passar caminhos de arquivos locais para quokkapix.com por URL;
um substituto para os limites de memória do navegador.

Caminhos de arquivos locais estão disponíveis apenas para o runner MCP local na máquina do usuário. O site público do QuokkaPix ainda recebe arquivos somente por meio do input de arquivo ou zona de arrastar e soltar do navegador.

Por Que Usar

Use este adaptador quando um agente de IA precisar de fluxos de trabalho de mídia repetíveis, como:

preparar fotos de produtos para Shopify, Amazon ou Google Merchant;
validar saídas de imagens de marketplaces e redes sociais contra perfis de regras com fonte;
comprimir imagens para WebP para um site;
remover metadados EXIF/GPS;
gerar pacotes de imagens para redes sociais;
aplicar marca d'água em um lote de imagens;
gerar pacotes de favicon e ícones de aplicativos;
executar configurações personalizadas do QuokkaPix sem clicar manualmente na interface.
cortar, recortar, redimensionar, converter ou comprimir um vídeo local;
extrair, silenciar, mixar ou substituir o áudio de vídeo com um arquivo de música local;
gerar transcrições TXT, SRT ou VTT localmente, ou queimar legendas em MP4;
preparar perfis de vídeo com fonte para YouTube, TikTok Ads e Meta Reels.

O principal valor é a privacidade e o baixo custo de infraestrutura: o agente obtém ferramentas práticas de fluxo de trabalho de Imagem e Vídeo, enquanto o processamento de mídia permanece local no navegador do usuário.

Arquitetura

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

Clientes remotos usam o mesmo pacote no modo de ponte:

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

Dependendo da superfície selecionada, o adaptador salva:

a imagem, ZIP, PDF, vídeo, áudio ou transcrição gerados;
quokkapix-result.json ou quokkapix-video-result.json;
um objeto qa retornado ao agente.

Requisitos

Node.js >=20
npm
Playwright Chromium
acesso à internet para carregar o QuokkaPix e dependências/modelos do lado do navegador quando necessário
caminhos de arquivos locais que o processo MCP possa ler

O modo de ponte adicionalmente exige raízes de entrada e saída explícitas. Chamadas remotas não podem ler ou gravar fora dessas raízes.

Instale as dependências:

npm install
npx playwright install chromium

Configuração do MCP Remoto e da Ponte

Inicie o pacote existente no modo de ponte:

npx -y quokkapix-mcp bridge \
  --input-root /absolute/path/to/input \
  --output-root /absolute/path/to/output

Aprove a URL de pareamento única impressa pelo comando.
Adicione https://quokkapix.com/mcp como um conector MCP remoto personalizado.
Conclua a autorização OAuth no navegador.

A ponte armazena sua credencial de dispositivo aleatória em ~/.quokkapix/bridge.json com permissões somente do proprietário onde o sistema operacional suportar. Use --pair para aprovar outra sessão de navegador ou --reset para revogar a autorização antiga do dispositivo e criar uma nova credencial.

Os caminhos de processamento remoto são relativos a --input-root e --output-root. A ponte rejeita path traversal e não retorna caminhos locais absolutos para o cliente na nuvem.

Ferramentas MCP

`list_recipes`

Lista receitas oficiais do QuokkaPix.

Use primeiro quando o agente não souber qual fluxo de trabalho executar.

`get_recipe`

Retorna uma receita por id, incluindo:

applySettings;
limites de arquivo;
saída esperada;
contrato de QA;
exigência de pagamento.

Entrada:

{
  "id": "shopify_product_pack"
}

`validate_recipe`

Valida um objeto de receita personalizado antes do processamento.

Isso não envia arquivos e não inicia o processamento.

`list_rule_profiles`

Lista perfis de regras de imagem de marketplaces e redes sociais com fonte.

Use isto quando um agente precisar de fatos para Amazon, Shopify, Google Merchant, Etsy, eBay, Walmart, TikTok Shop, Mercado Livre, Temu, Shopee, Instagram, YouTube, LinkedIn, X, Pinterest, Facebook ou TikTok antes de escolher um fluxo de trabalho ou verificar uma saída.

Cada perfil declara:

sourceType: official ou secondary;
sourceUrl;
confidence;
requisitos e recomendações encontrados na fonte nomeada.

O runner não inventa requisitos de marketplace ausentes. Entradas do Temu, Mercado Livre, Shopee e alguns itens do YouTube são marcadas como secundárias ou específicas de categoria/país onde as especificações públicas oficiais eram limitadas.

`get_rule_profile`

Retorna um perfil de regras por id, por exemplo:

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

Agentes podem passar os fatos retornados para seu próprio planejamento, ou chamar validate_result_manifest com ruleProfileId.

`validate_result_manifest`

Valida um quokkapix-result.json existente contra uma receita ou contrato de QA personalizado.

Isso é útil quando um agente quer inspecionar uma execução anterior e decidir se a saída é aceitável.

Entrada opcional:

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

Quando ruleProfileId é fornecido, o relatório de QA inclui verificações de marketplace com fonte, como formatos suportados, dimensões, tipo de origem e URL. Se o manifesto de resultado do navegador incluir outputs[].pixelQa, o validador também avalia verificações visuais suportadas em nível de pixel, como fundo branco, centralização do assunto, margens seguras e fundo transparente.

Ferramentas de vídeo

list_video_recipes — lista receitas oficiais de Cortar, Recortar, Converter, Comprimir, Áudio e Transcrever.
get_video_recipe — retorna uma receita de Vídeo e seu QA esperado.
validate_video_recipe — valida uma receita de Vídeo personalizada sem processar mídia.
list_video_rule_profiles — lista perfis com fonte para YouTube, TikTok Ads e Meta Reels.
get_video_rule_profile — retorna um perfil de Vídeo com sua fonte oficial.
validate_video_result_manifest — valida um quokkapix-video-result.json existente.
process_video — processa um vídeo local com uma receita oficial.
process_video_with_settings — processa um vídeo local com configurações diretas de QuokkaPixVideoAgent.

Exemplo:

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

Exemplo de mixagem de áudio:

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

A versão 0.7.0 expõe o fluxo unificado de cotação de pagamento e token de Imagem/Vídeo por meio do MCP remoto protegido por OAuth e da ponte local pareada. Os valores remotos de inputFile, musicFile opcional e outputDir são relativos às raízes configuradas; seus bytes nunca passam pelo plano de controle. Chamadas de ponte de Vídeo pagas exigem 0.7.0 ou mais recente.

`process_images`

Processa arquivos de imagem locais por meio do QuokkaPix usando:

um recipeId oficial;
um objeto de receita personalizado completo.

Ele abre um navegador, aplica a receita, envia os arquivos, inicia o processamento, baixa a saída, grava quokkapix-result.json e retorna resultados de QA.

Arquivos de ativos locais opcionais:

watermarkLogoFile: arquivo local de logotipo/imagem enviado no input de logotipo de marca d'água do QuokkaPix.
backgroundImageFile: arquivo de imagem local enviado no input de imagem de substituição de fundo do QuokkaPix.

Esses ativos ainda são enviados apenas para a página local do navegador. Eles não são passados como caminhos de URL para o site público do QuokkaPix.

`process_with_settings`

Processa arquivos de imagem locais usando um payload direto de applySettings do QuokkaPix.

Use isto quando o agente já souber as configurações exatas do editor e não quiser envolvê-las em uma receita.

Esta é a superfície de ferramenta mais ampla. Ela pode acionar a mesma superfície de configurações que:

window.QuokkaPixAgent.applySettings(payload)

As áreas de editor suportadas dependem do contrato de navegador do QuokkaPix e incluem:

redimensionar;
recortar;
girar;
converter;
comprimir;
exportação avançada para formatos suportados pelo navegador e JPEG XL experimental quando o codificador carregado no navegador estiver disponível;
remoção/relatório de metadados;
ferramentas de mesclar/separar/extrair PDF por meio de tool=pdf e pdf.operation apenas para arquivos PDF enviados; arquivos ZIP são aceitos apenas para mesclagem de PDF e apenas entradas PDF são extraídas;
configurações de remoção/substituição de fundo;
marca d'água;
efeitos;
renomear;
fluxos de trabalho de construtor/cenário.

Para cenários personalizados, prefira a forma estruturada 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 }
    }
  ]
}

A etapa settings usa as mesmas chaves de seção que window.QuokkaPixAgent.applySettings.

As ferramentas de PDF usam uploads de PDF em vez de uploads de imagem:

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

Use operation: "split" para exportar um PDF enviado como um ZIP de PDFs de uma página. Use operation: "extract" com extractPages para criar um PDF contendo apenas as páginas selecionadas de um PDF enviado; a ordem das páginas é preservada, então extractPages: "3,1" exporta a página 3 antes da página 1. Defina extractOutput: "zip" quando as páginas selecionadas devem ser retornadas como PDFs separados de uma página dentro de um ZIP. tool: "pdf" tem como padrão separar. Separar e extrair são fluxos de trabalho de PDF único porque os números de página se referem a um PDF de origem. Use operation: "merge" para combinar vários PDFs em um único PDF na ordem atual de arquivos do navegador; mesclar é um fluxo de trabalho em lote e alterna o editor do navegador para o modo de lote. Usuários humanos podem reordenar arquivos de mesclagem na interface; clientes MCP devem passar os arquivos na ordem de mesclagem desejada.

O upload de ZIP é somente em lote. Se um usuário ou agente selecionar um .zip no modo de lote, o QuokkaPix o descompacta localmente no navegador e adiciona imagens suportadas do arquivo à fila do lote. RAR e 7z não são aceitos.

`get_payment_options`

Busca a política de pagamento do agente QuokkaPix e endpoints x402.

Isso não realiza um pagamento.

`explain_payment_flow`

Explica o fluxo de pagamento x402 atual para agentes.

Importante: este adaptador MCP local não assina pagamentos x402 por conta própria. Um cliente ou carteira compatível com x402 deve chamar o endpoint de desbloqueio pago e retornar um unlockToken.

`verify_unlock_token`

Verifica com segurança um token de desbloqueio de agente pago antes do processamento sem consumi-lo. O adaptador deliberadamente não tem opção de pré-consumo: o desbloqueio único é consumido apenas pelo caminho de início do navegador após a validação ser bem-sucedida.

Ferramentas somente de ponte remota

O endpoint MCP remoto hospedado também expõe:

get_bridge_status para verificar o pareamento e a disponibilidade local;
get_billing_status para verificar se um desbloqueio único verificado está preparado;
set_unlock_token para preparar um desbloqueio x402 para o próximo lote local pago.

O verify_unlock_token remoto é somente de pré-verificação e nunca consome o token. O consumo real permanece dentro do caminho de início do navegador local.

O endpoint hospedado também retransmite todas as ferramentas de receita, regra, QA e processamento de Imagem e Vídeo listadas acima. Tanto process_video quanto process_video_with_settings exigem o escopo OAuth bridge:execute. Vídeo usa produtos de duração/transcrição em vez dos produtos de arquivo/PDF de Imagem; ambas as superfícies usam o mesmo protocolo x402.

Receitas Oficiais

O runner carrega receitas do projeto local, se presentes. Se os arquivos de receita locais estiverem ausentes, ele usa como fallback:

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

Receitas oficiais atuais:

ID da receita	Finalidade	Modo	Saída
`shopify_product_pack`	Fotos de produtos para Shopify	lote	ZIP
`amazon_white_background_pack`	Fotos de produtos com fundo branco estilo Amazon	lote	ZIP
`google_merchant_pack`	Imagens de produtos para Google Merchant	lote	ZIP
`etsy_product_batch`	Lote de imagens de produtos para Etsy com QA com fonte	lote	ZIP
`ebay_listing_photo_batch`	Lote de fotos para anúncios no eBay	lote	ZIP
`walmart_product_main_batch`	Imagens principais de produtos para Walmart	lote	ZIP
`tiktok_shop_product_batch`	Imagens de produtos para TikTok Shop	lote	ZIP
`temu_product_main_batch`	Imagens de produtos estilo Temu com fonte secundária	lote	ZIP
`shopee_product_batch`	Imagens de produtos para Shopee	lote	ZIP
`mercado_libre_accessories_batch`	Fotos de acessórios para Mercado Libre	lote	ZIP
`allegro_listing_image_batch`	Imagens de anúncios para Allegro	lote	ZIP
`newegg_product_image_batch`	Imagens de produtos para Newegg	lote	ZIP
`meta_catalog_product_batch`	Imagens de produtos para Meta Catalog	lote	ZIP
`flipkart_product_image_batch`	Fotos de produtos Flipkart com base em orientações públicas	lote	ZIP
`shein_product_square_batch`	Imagens quadradas de produtos SHEIN com fonte secundária	lote	ZIP
`otto_product_image_batch`	Imagens de produtos OTTO com QA mínimo de 500 x 1000 px com fonte	lote	ZIP
`trendyol_product_image_batch`	Imagens de produtos Trendyol no tamanho de 1200 x 1800 px com fonte	lote	ZIP
`snapchat_ad_image_batch`	Imagens estáticas de anúncios para Snapchat	lote	ZIP
`website_webp_compress`	Compressão de imagens de sites para WebP	lote	ZIP
`webp_compress_batch`	Conversão e compressão geral de lote para WebP	lote	ZIP
`white_background_shadow_batch`	Imagens de produtos com fundo branco e sombra suave	lote	ZIP
`metadata_clean_batch`	Remover metadados EXIF/GPS/câmera/software	lote	ZIP
`single_webp_compress`	Comprimir uma imagem para WebP	individual	imagem
`single_background_remove`	Remover fundo de uma imagem	individual	imagem
`single_white_background`	Criar uma imagem de produto com fundo branco	individual	imagem
`single_metadata_clean`	Remover metadados de uma imagem	individual	imagem
`single_watermark`	Aplicar marca d'água de texto a uma imagem	individual	imagem
`images_to_pdf_batch`	Mesclar imagens ou digitalizações selecionadas em um PDF	lote	PDF
`social_pack_single`	Tamanhos para redes sociais a partir de uma imagem	individual	ZIP
`profile_avatar_pack`	Tamanhos de avatar de perfil a partir de uma imagem	individual	ZIP
`watermark_product_batch`	Aplicar marca d'água a imagens de produtos	lote	ZIP
`favicon_app_icon_pack`	Gerar tamanhos de favicon e ícones de aplicativo	individual	ZIP

Os agentes normalmente devem chamar list_recipes, escolher a receita mais próxima e então chamar process_images.

Use process_with_settings quando o fluxo de trabalho desejado não for coberto por uma receita.

Instalar a partir do código-fonte

Na pasta mcp-runner:

npm install
npx playwright install chromium
npm run check

Inicie o servidor MCP:

npx quokkapix-mcp

Execução direta via CLI sem um cliente MCP:

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

Configuração do cliente MCP

Para a maioria dos usuários, configure o pacote npm publicado diretamente:

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

Use caminhos absolutos para cwd.

Claude Desktop a partir do código-fonte

Se você clonou o repositório do GitHub em vez de usar npm, adicione isto à configuração MCP do 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 a partir do código-fonte

Se você clonou o repositório do GitHub em vez de usar npm, use a mesma definição de servidor nas configurações MCP do Cursor:

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

Desenvolvimento local

Execute o QuokkaPix localmente e aponte o runner para ele:

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

Substitua a raiz do site local:

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

Substitua a fonte pública de receitas:

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

Substitua a URL base de pagamento:

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

appUrl é intencionalmente restrito para segurança de arquivos locais. Por padrão, o runner só abre:

https://quokkapix.com/ e https://www.quokkapix.com/;
http://127.0.0.1, http://localhost e equivalentes HTTPS locais.

Isso impede que um prompt ou receita malicioso aponte o runner do navegador para uma página não relacionada e envie arquivos locais para lá. Apenas para desenvolvimento confiável, URLs de aplicativos personalizados podem ser habilitadas com:

QUOKKAPIX_ALLOW_CUSTOM_APP_URL=1 npx quokkapix-mcp

Exemplo: Processar fotos de produtos para Shopify

Ferramenta: 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
}

Saída esperada:

um arquivo ZIP em outputDir;
quokkapix-result.json;
um relatório qa retornado.

O resultado da ferramenta separa o sucesso do processamento do sucesso do QA:

processingOk: true significa que o QuokkaPix concluiu e produziu um arquivo de saída;
qaOk: true significa que a saída passou nas verificações de QA da receita;
ok de nível superior segue qaOk, portanto os agentes não devem tratar uma execução de QA com falha como totalmente bem-sucedida.

Exemplo: Configurações personalizadas diretas

Ferramenta: 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 isto para fluxos de trabalho personalizados que não são receitas oficiais.

Exemplo: Ativo de marca d'água com logotipo

Ferramenta: 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"
}

Exemplo: Ativo de imagem de fundo

Ferramenta: 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 dois arquivos é gratuito. Para um nível pago, execute primeiro sem token para obter o orçamento local exato e depois repita inalterado com seu produto unlockToken.

Exemplo: Limpeza de metadados

Ferramenta: 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 execuções em lote, consulte a seção de pagamento abaixo.

Exemplo: Validação somente de QA

Ferramenta: 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": []
  }
}

O resultado contém:

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

Manifesto de resultado

Após o processamento, o runner grava:

quokkapix-result.json

O manifesto é retornado por:

window.QuokkaPixAgent.getResultManifest()

Ele contém fatos de processamento local legíveis por máquina:

schemaVersion;
status;
success;
tool;
mode;
source.count;
source.totalBytes;
outputs[];
dimensões de origem/saída quando disponíveis;
nomes de arquivos de saída;
formatos;
tamanhos em bytes;
avisos;
processingMs;
recursos do navegador;
rotas de backend planejadas opcionais em capabilities.backends;
errorCode estável.

O manifesto não contém bytes de imagem.

capabilities.backends é aditivo e informativo. O adaptador MCP atual já transmite campos de manifesto do navegador desconhecidos sem alterações, portanto este campo não exige um novo lançamento do adaptador. Continue usando o status do terminal, errorCode e os resultados de QA para decidir se uma execução foi bem-sucedida.

Validação de QA

O runner valida os manifestos de resultado contra os contratos de QA da receita. Cada verificação inclui name, ok, severity, expected, actual, message e remediation, para que os agentes possam relatar tanto o que falhou quanto qual configuração alterar.

As verificações de QA atuais incluem:

o status da execução é done;
a contagem de origens é positiva;
a contagem de origens está dentro do limite da receita;
as saídas estão presentes;
formato esperado;
largura/altura esperadas;
largura/altura máximas;
saída quadrada quando necessário;
tamanho máximo de saída em KB quando o tamanho por arquivo estiver disponível;
prefixo do nome da saída;
ausência de aviso obrigatório;
entradas ZIP representadas no manifesto;
contagem mínima esperada de saídas para pacotes.
verificações em nível de pixel quando o manifesto do navegador contém métricas outputs[].pixelQa:
- fundo branco;
- assunto centralizado;
- margens seguras;
- fundo transparente.

Verificações semânticas, como presença de marca d'água, texto promocional, resquícios de fundo antigo ou qualidade subjetiva de recorte, não são marcadas como aprovadas sem um sinal mensurável no manifesto. Se um contrato de QA personalizado solicitar uma verificação visual não suportada, o validador a reporta como um aviso em vez de tratá-la silenciosamente como aprovada.

Elas exigem um analisador semântico futuro ou outro sinal mensurável explícito. O runner atualmente não finge verificá-las.

Pagamentos de agentes e x402

A interface humana do QuokkaPix e os fluxos de recompensa não foram alterados.

O preço para agentes é calculado a partir da mídia real carregada no navegador local.

Política atual:

Superfície/execução	Grátis	Próximo nível	Nível maior
Ferramentas normais de imagem	1-5 arquivos reais	6-25: `0.01`	26-50: `0.02 USDC`; >50 bloqueado
PDF	Até 20 páginas	21-50: `0.01`	51-300: `0.02 USDC`; >300 bloqueado
Cenário de múltiplas etapas de imagem	-	-	`0.02 USDC`
Edição normal de vídeo	Até 5 min	>5-15: `0.01`; >15-30: `0.02`	>30: `0.03 USDC`
Transcrição de vídeo	Até 5 min	>5-15: `0.02`; >15-30: `0.04`	>30-45: `0.06 USDC`; >45 bloqueado

Os conteúdos ZIP contam após a extração local. Transcrição mais queima de legendas é uma execução com preço de transcrição, não duas taxas. Queimar segmentos de transcrição que já existem usa o nível normal de edição de vídeo.

provedor: Coinbase x402;
provedor: Coinbase x402;
moeda/redes: USDC na Base (eip155:8453, padrão), Polygon (eip155:137), Arbitrum (eip155:42161) e World Chain (eip155:480) quando expostas por /api/agent-payment/options;
endpoint de opções de pagamento: /api/agent-payment/options;
endpoint de desbloqueio de produto: /api/agent-unlock/coinbase-x402/:productId;
endpoint de verificação: /api/agent-unlock/verify;
contrato formal da API: /x402-api.md.

O runner MCP pode:

buscar opções de pagamento;
explicar o fluxo de pagamento;
verificar um token de desbloqueio;
passar um token de desbloqueio para o processamento.

O runner MCP não assina pagamentos x402 por conta própria. Um cliente ou carteira compatível com x402 deve obter o unlockToken.

O modo bridge não adiciona uma segunda taxa e o WebMCP não tem cobrança separada. Um cliente remoto pode passar unlockToken na chamada de processamento repetida ou chamar set_unlock_token com o uso correspondente. O plano de controle mantém um token em estágio apenas na memória e nunca o consome. O navegador local permanece autoritativo e consome o token imediatamente antes do início do processamento.

Sempre chame get_payment_options para produtos atuais e disponibilidade do provedor. Para um orçamento exato, execute a ferramenta de processo apropriada sem token. O navegador local primeiro expande ZIPs ou lê páginas de PDF/duração de vídeo e retorna um orçamento sem iniciar o trabalho pago.

Fluxo de trabalho pago:

Aplique as configurações e forneça os caminhos locais a uma ferramenta de processo sem token.
Leia o orçamento local retornado e seu productId/paymentEndpoint.
Use um cliente compatível com x402 para pagar esse endpoint de produto.
Leia unlockToken; opcionalmente chame verify_unlock_token com o uso correspondente.
Repita a mesma chamada de processo de Imagem ou Vídeo inalterada com unlockToken.
O navegador verifica novamente o nível e consome o token imediatamente antes do início do trabalho.

Exemplo:

{
  "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 no seu 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

O pacote também expõe uma CLI direta:

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

Opções:

--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.

A CLI atualmente executa processamento baseado em receitas. Para configurações diretas, use a ferramenta MCP process_with_settings.

Comando bridge:

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

Use npx quokkapix-mcp bridge --help para pareamento, configuração, navegador com interface e opções de diagnóstico. Executar npx quokkapix-mcp sem bridge permanece o servidor MCP stdio original.

Testes

Verificações rápidas:

npm run check

Isto verifica:

sintaxe dos arquivos do servidor MCP;
carregamento e validação de receitas;
geração de fluxo de trabalho com configurações diretas;
validador de QA;
ferramentas auxiliares de pagamento;
analisador de CLI.

O GitHub Actions executa as mesmas verificações no Node 20 e Node 24 no Windows e Linux. O trabalho Linux/Node 24 também envia o .tgz gerado como um artefato de fluxo de trabalho de curta duração, portanto uma execução verde verifica o arquivo do pacote real.

Teste de processamento de navegador de ponta a ponta contra um aplicativo QuokkaPix já em execução:

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

Os testes e2e gratuitos processam um fixture local, configurações personalizadas diretas e upload de ativo de marca d'água com logotipo. Os testes e2e pagos em lote são ignorados, a menos que tokens de desbloqueio reais sejam fornecidos.

Para testes e2e pagos:

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

Os testes pagos usam tokens separados porque os desbloqueios são consumíveis uma única vez.

Verificação de publicação

Antes de publicar ou marcar um lançamento:

npm run check
npm pack --dry-run

Enviar uma tag auditada vX.Y.Z executa .github/workflows/release.yml, compila o pacote novamente e anexa o .tgz a um GitHub Release. A publicação no npm é um workflow manual separado. Configure o npm Trusted Publisher para este repositório, workflow publish-npm.yml e ambiente GitHub npm, depois execute Publish npm package com a tag de release existente. O workflow usa OIDC e não armazena um token npm no repositório.

A whitelist de pacotes inclui apenas:

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

node_modules, artefatos de teste e o site completo do QuokkaPix não estão incluídos no pacote npm.

Notas de Segurança e Privacidade

Arquivos de imagem, vídeo e música opcional são lidos de caminhos locais pelo runner do MCP.
Os arquivos são enviados apenas para a página do navegador local via Playwright.
O processamento no navegador do QuokkaPix não envia mídia de origem para um servidor de processamento QuokkaPix.
O site público ainda não consegue ler caminhos locais arbitrários.
Tokens de pagamento devem ser tratados como segredos de curta duração.
Não faça commit de tokens de desbloqueio reais, arquivos privados ou pastas de saída locais.
Segredos do dispositivo bridge permanecem na configuração local e são armazenados como hashes pelo plano de controle.
OAuth usa código de autorização com PKCE, tokens de acesso vinculados à audiência e tokens de atualização rotativos. As ferramentas de processamento exigem adicionalmente o escopo bridge:execute; mcp:tools sozinho é somente leitura.
Argumentos de arquivos remotos são restritos às raízes configuradas; travessia .. e caminhos absolutos fora da raiz são rejeitados.
O plano de controle não possui rota de upload de mídia. Ele recebe comandos, nomes relativos, status e metadados de resultado.
Uma IA em nuvem pode receber bytes de mídia somente se o usuário enviar ou compartilhar separadamente uma saída com essa IA; o modo bridge não faz isso automaticamente.

Limitações

A RAM do navegador é o limite rígido para lotes grandes.
A remoção de fundo pode baixar arquivos de modelo de IA no lado do navegador e depende da capacidade do navegador/dispositivo.
A disponibilidade de WebGPU/WebNN depende do navegador e do hardware do usuário.
O suporte a HEIC/AVIF/WebP depende do navegador e de codificadores opcionais no lado do navegador.
A exportação JPEG XL é experimental e requer o codificador avançado carregado no navegador; não possui fallback de Canvas.
Merge/split/extract de PDF espera arquivos PDF. A receita existente de imagens para PDF espera arquivos de imagem.
A importação ZIP funciona apenas no modo batch e extrai apenas arquivos de imagem suportados.
A remoção de fundo de GIF não é suportada.
A garantia de qualidade em nível de pixel é determinística e limitada a fatos mensuráveis da imagem. Ela não afirma reconhecimento semântico de texto, conteúdo de marca d'água ou qualidade subjetiva de retoque.
O adaptador atualmente usa automação de navegador Playwright, não uma biblioteca nativa de processamento de imagem.
No modo bridge, o cliente remoto deve conhecer caminhos relativos sob a raiz de entrada configurada; a navegação de diretórios não é exposta intencionalmente.
Jobs bridge ativos são apenas em memória e falham de forma segura durante uma reinicialização do plano de controle.

Solução de Problemas

O navegador Playwright está ausente

Execute:

npx playwright install chromium

O agente não consegue encontrar arquivos

Use caminhos de arquivo locais absolutos. O processo MCP deve ter permissão para lê-los.

Uma execução diz que o pagamento é necessário

Leia a cotação local retornada, pague seu endpoint específico do produto e repita a chamada inalterada com o unlockToken resultante. Não reutilize um token para outro nível de produto.

O navegador fica sem memória

Reduza o tamanho do lote, redimensione primeiro, evite imagens muito grandes ou use workflows menores. O runner não pode contornar os limites de RAM do navegador.

QA relata verificações visuais não suportadas

Isso é esperado para requisitos visuais semânticos que não podem ser comprovados a partir do manifesto do navegador. O validador usa outputs[].pixelQa para verificações mensuráveis e deixa verificações semânticas não suportadas sem reivindicação.

Arquivos Relacionados do Agente QuokkaPix

Descoberta e documentação públicas:

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

Licença

MIT. Consulte LICENSE.