Configuração¶

Utilize as variáveis PLAYWRIGHT_MCP_* do upstream para o comportamento do MCP do Playwright. Use CLOAK_PLAYWRIGHT_MCP_* apenas para o comportamento da ponte específico do Cloak.

As antigas variáveis CLOAKBROWSER_MCP_* não são mais suportadas. A Referência da CLI gerada é a lista oficial dos sinalizadores da CLI da ponte e suas variáveis de ambiente correspondentes.

Opções de ponte¶

Correspondência de proxy GeoIP¶

Defina CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true com PLAYWRIGHT_MCP_PROXY_SERVER para derivar os sinalizadores de fuso horário, idioma e localidade do CloakBrowser a partir da localização do proxy. A ponte mantém o roteamento do proxy delegado ao MCP do Playwright MCP e injeta apenas os sinalizadores de inicialização resolvidos --fingerprint-timezone, --lang e --fingerprint-locale resolvidos.

Consulte Correspondência de proxy GeoIP para exemplos de configuração, metadados de proxy HTTP transmissíveis em tempo de execução, casos de uso, regras de precedência e limitações.

Comportamento humanizado de entrada¶

Defina CLOAK_PLAYWRIGHT_MCP_HUMANIZE=true para ativar a camada de interação com o mouse, teclado e rolagem do CloakBrowser, que simula o comportamento humano, para interações com a página. A ponte aplica isso por meio do gancho de inicialização de página do Playwright MCP, de modo que os esquemas das ferramentas de navegador originais permanecem inalterados.

Consulte Comportamento de Entrada Humanizado para exemplos de configuração, metadados HTTP do Streamable em tempo de execução, casos de uso e limitações.

Extensões do Chrome¶

Extensões do Chrome são carregadas quando o navegador inicia, então configure-as antes de iniciar a ponte ou antes de criar uma sessão Streamable HTTP. As extensões devem ser diretórios descompactados e exigem um perfil persistente:

PLAYWRIGHT_MCP_USER_DATA_DIR="$PWD/.profiles/default" \
  CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS='["/absolute/path/to/my-extension"]' \
  npx -y cloakbrowser-mcp@latest

Para Streamable HTTP, passe os diretórios do perfil e da extensão nos metadados de initialize:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "userDataDir": "/absolute/path/to/profile",
        "extensionPaths": ["/absolute/path/to/my-extension"]
      }
    }
  }
}

Reinicie a ponte ou crie uma nova sessão HTTP depois de alterar arquivos ou caminhos de extensões. Use uma matriz JSON para CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS quando os caminhos contiverem vírgulas, ao passar várias extensões ou ao usar caminhos do Windows com letras de unidade.

Metadados de tempo de execução HTTP transmitíveis¶

Os clientes HTTP compatíveis com stream podem selecionar opções de tempo de execução específicas para cada sessão MCP, adicionando metadados específicos da ponte à solicitação initialize:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "proxyServer": "http://user:pass@proxy.example:8080",
        "proxyBypass": ".internal,localhost",
        "geoipProxyMatch": true,
        "headless": false,
        "humanize": true,
        "humanPreset": "careful",
        "userDataDir": "/absolute/path/to/profile",
        "contextOptions": {
          "viewport": { "width": 1280, "height": 720 },
          "locale": "en-US",
          "timezoneId": "America/New_York"
        },
        "extensionPaths": ["/absolute/path/to/extension"]
      }
    }
  }
}

proxyServer substitui PLAYWRIGHT_MCP_PROXY_SERVER para essa sessão HTTP. proxyBypass substitui PLAYWRIGHT_MCP_PROXY_BYPASS somente quando proxyServer estiver presente. geoipProxyMatch pode ativar ou desativar a correspondência por GeoIP para essa sessão sem reiniciar o servidor MCP. As sessões existentes mantêm seu proxy de inicialização; crie uma nova sessão HTTP para alterar a localização.

humanize pode ativar ou desativar o comportamento de entrada humanizado para essa sessão sem alterar outras sessões. humanPreset pode selecionar default ou careful para essa sessão, mas não habilita o comportamento humanizado por si só. As sessões existentes mantêm o comportamento capturado durante initialize.

headless pode ativar ou desativar o modo de navegador sem interface gráfica para essa sessão. Configurar headless para false requer um ambiente de exibição funcional, especialmente em implantações no Docker ou em servidores Linux.

userDataDir habilita um perfil persistente do Chromium para essa sessão e substitui PLAYWRIGHT_MCP_USER_DATA_DIR. A ponte resolve o diretório como um caminho absoluto nativo da plataforma, cria se estiver ausente, verifica se é gravável e grava no browser.userDataDir gerado. Um perfil persistente desabilita o perfil isolado padrão do Streamable HTTP para essa sessão. A ponte rejeita diretórios de perfil ativos duplicados dentro de um mesmo processo; conflitos de perfil entre processos continuam sendo erros do Chromium/Playwright.

contextOptions são validadas e mescladas superficialmente sobre CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS; objetos aninhados substituem valores inteiros. Os campos compatíveis são userAgent, viewport, locale, timezoneId, colorScheme, permissions, geolocation, extraHTTPHeaders, httpCredentials, ignoreHTTPSErrors, offline, deviceScaleFactor, isMobile e hasTouch. A passagem arbitrária de BrowserContextOptions não é compatível nesta versão.

extensionPaths devem apontar para diretórios existentes e exigem um userDataDir persistente. A ponte resolve os caminhos das extensões como caminhos absolutos nativos da plataforma, passa-os para o CloakBrowser e grava os argumentos Chromium gerados --load-extension e --disable-extensions-except na configuração gerada do Playwright MCP.

As credenciais autenticadas do proxy HTTP podem ser incorporadas em proxyServer, por exemplo http://user:pass@proxy.example:8080. Codifique em formato percentual os caracteres de credenciais que tenham significado em URLs, como @, :, /, ?, #, e %.

Para padrões de controle de qualidade (QA) em múltiplas localizações, consulte Correspondência de proxy GeoIP. Para padrões de realismo de interação, consulte Comportamento de Entrada Humanizado.

Opções de upstream¶

A ponte encaminha as configurações de PLAYWRIGHT_MCP_* para o Playwright MCP a montante. Isso inclui opções a montante, tais como:

• PLAYWRIGHT_MCP_ALLOWED_ORIGINS
• PLAYWRIGHT_MCP_BLOCKED_ORIGINS
• PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS
• PLAYWRIGHT_MCP_CAPS
• PLAYWRIGHT_MCP_CONSOLE_LEVEL
• PLAYWRIGHT_MCP_IMAGE_RESPONSES
• PLAYWRIGHT_MCP_SNAPSHOT_MODE
• PLAYWRIGHT_MCP_STORAGE_STATE

Consulte a documentação do Playwright MCP do projeto original para conhecer todas as opções disponíveis.

Registro¶

O modo HTTP streamable grava logs de inicialização e de solicitações legíveis por humanos no stdout. O modo stdio não emite logs operacionais de rotina, de modo que o stdout do MCP JSON-RPC permanece livre de detalhes do protocolo. Falhas fatais na inicialização da CLI continuam sendo gravadas no stderr.

HTTPS¶

O Streamable HTTP usa HTTP local por padrão. Selecione TLS direto com --http-protocol https ou CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL=https e, em seguida, forneça um par de certificado/chave ou um arquivo PFX:

cloakbrowser-mcp --transport streamable-http \
  --http-protocol https \
  --https-cert ./cert.pem \
  --https-key ./key.pem

Para exposição externa ou sem loopback, utilize HTTPS junto com --http-auth-token, ou termine a conexão TLS em um proxy reverso confiável que também imponha autenticação e controles de acesso à rede.

Sessões HTTP transmitíveis¶

Cada sessão do Streamable HTTP MCP possui seu próprio ambiente de execução de ponte e um processo filho do Playwright MCP a montante. As sessões HTTP executam o Playwright MCP a montante com um perfil de navegador isolado, de modo que usuários simultâneos não disputem o mesmo perfil persistente do Chromium. O backend de sessão integrado memory armazena apenas metadados, como ID da sessão, carimbos de data/hora, validade e status. O estado do navegador permanece no processo filho ativo a montante, e os artefatos continuam sendo controlados pelo PLAYWRIGHT_MCP_OUTPUT_DIR.

Para escalonamento horizontal, execute várias réplicas de servidor atrás de um balanceador de carga com sessões fixas identificadas pelo cabeçalho mcp-session-id. Futuros back-ends como Redis, Postgres ou SQLite poderão coordenar metadados e bloqueios, mas não poderão restaurar uma sessão ativa do navegador após o encerramento do processo responsável por ela.

Sondas HTTP com transmissão contínua¶

Quando a ponte opera com --transport streamable-http, ela expõe pontos de extremidade de sonda fixos no mesmo host e na mesma porta que o ponto de extremidade do MCP:

• GET /healthz retorna metadados sobre o estado do processo: status, version, transport e uptimeMs.
• GET /readyz retorna metadados de prontidão e capacidade de sessão: sessions.active, sessions.pending, sessions.max e sessions.available.

A disponibilidade retorna HTTP 200 enquanto houver capacidade de sessão disponível e HTTP 503 quando active + pending >= max. Se --http-auth-token ou CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN estiverem configurados, ambas as sondas exigem o mesmo cabeçalho Authorization: Bearer ... que as solicitações MCP. Sem um token de autenticação, as sondas ficam abertas no endereço de ligação HTTP configurado.

Mais caminhos práticos¶

Para escolher entre o Playwright MCP upstream e este pacote, consulte a comparação. Para tarefas rápidas, use as receitas: perfil persistente, extensões, reverse proxy, QA regional, Claude Desktop, Codex CLI e teste smoke de CI.