QuokkaPix MCP Runner

MCP remoto com processamento local

Claude web e outros clientes MCP na nuvem podem se conectar por OAuth, enquanto o adaptador npm existente executa cada operação de imagem no computador do usuário.

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

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

O scope mcp:tools permite ferramentas de leitura. O processamento e o armazenamento de um unlock token também exigem bridge:execute. --reset revoga o dispositivo anterior antes de parear um novo.

O control plane transmite configurações, nomes de arquivo relativos, status e o result manifest. Ele não possui endpoint de upload de imagens e não transmite bytes de origem ou saída.

Guia prático para Claude, Cursor e MCP local

Use esta página quando um agente desktop precisar processar imagens locais com o QuokkaPix. O MCP runner é um adaptador stdio local: o cliente MCP inicia quokkapix-mcp, o adaptador abre o QuokkaPix em um navegador local, envia arquivos pelo seletor do navegador, aplica uma receita ou ajustes diretos, baixa o resultado e grava quokkapix-result.json.

Isto não é uma API hospedada de processamento de imagens. As imagens de origem permanecem no fluxo local do navegador e não são enviadas para um servidor de processamento do QuokkaPix.

Comando alternativo para Windows

Se um cliente MCP no Windows não encontrar npx diretamente, inicie por cmd /c. Use isso apenas quando o comando npx simples não for detectado pelo cliente.

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

Clientes MCP locais e wrappers de LLM

Qualquer cliente MCP local que consiga iniciar um servidor stdio pode usar o mesmo pacote. Isso inclui clientes desktop, agentes de editores e wrappers de LM Studio ou Ollama que expõem ferramentas MCP para um modelo local.

A regra importante é a mesma em todos os casos: passe caminhos reais de arquivos locais para a chamada MCP, não para a URL do site público. O QuokkaPix recebe arquivos apenas pelo seletor local do navegador aberto pelo runner.

Primeiros prompts úteis

Tabela de verificação da execução

Execuções gratuitas e pagas de agentes

Execuções de uma imagem, cenários de uma imagem e batches de agente até 5 arquivos são gratuitos. Batches ou cenários em batch de 6 a 50 arquivos usam o fluxo x402 unlock. Clientes devem buscar os termos atuais em /api/agent-payment/options antes de pedir um paid unlock.

Quando o pagamento é necessário, o agente obtém um unlockToken, define-o no QuokkaPix antes do processamento e o unlock é consumido apenas quando um batch pago ou cenário em batch começa.

Solução de problemas

Limite de segurança

Use a URL oficial do QuokkaPix ou uma URL local de desenvolvimento confiável. Não aponte o runner para uma appUrl arbitrária de terceiros, porque o adaptador envia arquivos locais para a página que ele abre. O site público não recebe caminhos locais, e o adaptador não transforma o QuokkaPix em uma API server-side.

FAQ para agentes e desenvolvedores

O que os agentes podem fazer

• Executar receitas oficiais para Shopify, Amazon, Google Merchant, compressão WebP, exportação PDF, limpeza de metadados, pacotes sociais, avatares e marcas d'água.
• Executar custom settings diretos com process_with_settings, usando o mesmo payload de window.QuokkaPixAgent.applySettings.
• Validar result manifests e obter QA de formato, dimensões, limites de tamanho, tipo de saída, nomes obrigatórios e conteúdo ZIP.
• Ler condições de pagamento x402 e verificar tokens de desbloqueio para execuções em lote de agentes.
• Enviar arquivos asset locais para marcas d'água com logotipo e substituição de fundo por imagem.

Capacidades atuais do navegador

• O objeto opcional capabilities.backends informa as rotas planejadas de processamento, codificação e AI de fundo com fallbacks explícitos. Os campos MCP existentes não mudam.
• A exportação avançada pode usar encoders WASM para JPEG, otimização PNG, WebP, AVIF e JPEG XL experimental quando disponíveis.
• O upload ZIP funciona apenas em lote: o navegador extrai localmente as imagens compatíveis antes do processamento.
• As ferramentas PDF usam configurações diretas: split e extract trabalham com um único PDF, merge trabalha com um lote de PDFs e images-to-PDF continua sendo um fluxo de imagens. Extract preserva a ordem de pdf-pages; use pdf-extract-output=zip para PDFs separados por página.

O que verificar depois da execução

• Confirme que a pasta de saída contém a imagem, ZIP ou PDF gerado e quokkapix-result.json.
• Leia qa.ok e qa.checks antes de aceitar um lote para marketplace ou rede social.
• Mantenha os arquivos de origem separados, porque o QuokkaPix cria saídas de entrega e não substitui originais.
• Para lotes pagos de agentes, busque as opções de pagamento atuais antes de solicitar um token x402.

Quando uma execução é aceitável

• O cliente MCP iniciou o adaptador stdio local e o adaptador abriu uma URL esperada do QuokkaPix.
• Os arquivos entraram pelo seletor de arquivos do navegador, não por um parâmetro de URL pública.
• O manifesto tem status done, qa.ok é verdadeiro quando a receita tem QA e os warnings são revisados antes de usar a saída.
• Em lotes pagos, o unlock token é verificado antes do início e consumido apenas por uma execução paga acima do limite small-batch gratuito.

Ferramentas 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

Receitas oficiais

Exemplos

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

Notas importantes

Os arquivos continuam entrando apenas pelo input local do navegador. O QuokkaPix não oferece API pública de processamento no servidor.