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¶

Licença do CloakBrowser e login com GitHub¶

A configuração da licença usa a CLI original do CloakBrowser; cloakbrowser-mcp não adiciona comandos de login ou logout:

npx -y cloakbrowser@latest login
npx -y cloakbrowser@latest info
npx -y cloakbrowser@latest logout

login aceita uma chave paga ou inicia o login com GitHub para obter uma chave do nível gratuito. A chave validada é armazenada em ~/.cloakbrowser/license.key; logout remove esse arquivo. info informa o nível de licença ativo e, para licenças Pro, a quantidade de sessões ativas.

Como alternativa, defina CLOAKBROWSER_LICENSE_KEY no ambiente do servidor MCP. A ponte encaminha essa variável ao processo filho upstream/do navegador sem registrá-la em logs. Quando CLOAKBROWSER_CACHE_DIR aponta para um cache personalizado que contém license.key, o CloakBrowser resolve a chave e a ponte encaminha apenas essa chave resolvida a partir do ambiente gerado do navegador. Outras entradas de ambiente geradas não são copiadas.

Se o CloakBrowser rejeitar a chave de licença fornecida, não puder validá-la ou não conseguir alcançar o servidor de licenças, a inicialização falhará com o erro explícito do CloakBrowser. A ponte preserva esse erro: não o mascara nem alterna silenciosamente para outro navegador ou nível de licença.

Gerenciado CDP¶

O acesso gerenciado ao Chrome DevTools Protocol (CDP) é uma opção explícita. Ele expõe o mesma geração de navegador Chromium controlada por MCP através de uma capacidade descoberta URL. Configurar apenas um conjunto de portas não habilita CDP.

Cada valor CLI substitui apenas sua variável de ambiente correspondente. Em particular, --no-cdp-enabled substitui CLOAK_PLAYWRIGHT_MCP_CDP_ENABLED=true, e --no-cdp-allow-remote substitui CLOAK_PLAYWRIGHT_MCP_CDP_ALLOW_REMOTE=true. Uma sessão habilitada sem um pool de portas é rejeitada antes que seu filho a montante comece. Um valor falso eficaz não cria nenhum ouvinte, aluguel de porta ou capacidade.

Para stdio, o valor do processo se aplica diretamente:

cloakbrowser-mcp \
  --cdp-enabled \
  --cdp-port-range 9222

Para Streamable HTTP, o booleano plano cdpEnabled no autenticado Os metadados initialize substituem o padrão do processo para essa sessão. Omitindo o o campo herda o valor do processo. Esses exemplos optam explicitamente por uma sessão e outro para fora:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "cdpEnabled": true
      }
    }
  }
}

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "cdpEnabled": false
      }
    }
  }
}

Uma sessão habilitada para CDP HTTP possui um aluguel de porta externa. Sessões desabilitadas não possuem consome a piscina. A alocação é local ao processo, seleciona o candidato não alugado mais baixo, e falha nessa sessão imediatamente se a porta externa selecionada já estiver ocupada. Feche sessões para liberar portas ou configure uma faixa maior quando o pool estiver esgotado.

Recupere o URL atual de cloakbrowser_bridge_info, então passe seu structuredContent.cdp.discoveryUrl para um cliente CDP como o de Playwright chromium.connectOverCDP(). Trate aquele URL como uma credencial: ele inclui um aleatório capacidade por geração e se torna obsoleta após a substituição do navegador. CDP gerenciado é não é um endpoint de servidor Playwright. chromium.connect() e o atual Open WebUI O fluxo PLAYWRIGHT_WS_URL não é suportado.

--cdp-advertised-scheme https publica https descoberta e wss WebSocket URLs somente. A ponte não fornece TLS para CDP gerenciado: seu ouvinte externo e Chromium hop permanece em texto simples HTTP/WebSocket. Um terminador TLS de propriedade do operador deve ouvir na mesma porta locada anunciada, preservar os Host e Origin anunciados autoridade, e encaminhar um a um para o ouvinte de texto simples daquela sessão.

A ativação do CDP começa Chromium durante a inicialização do MCP para que a propriedade e o externo a prontidão pode ser verificada. Configure o tempo limite de inicialização do cliente MCP para pelo menos 60 segundos. Quando o CDP gerenciado está ativado, fornecido pelo usuário CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS não deve conter --remote-debugging-port, --remote-debugging-address, ou --remote-debugging-pipe (incluindo as formas =). O próprio Playwright interno do --remote-debugging-pipe permanece ativado junto com o endpoint TCP de loopback gerenciado por bridge.

Veja Ferramentas, Docker, Segurança, e Arquitetura para estado de descoberta, implantação, limites e comportamento de reinício.

Canal de lançamento do CloakBrowser¶

CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL seleciona o canal de lançamento do binário do CloakBrowser. O padrão é stable. preview solicita uma versão de prévia do navegador Pro e está disponível apenas com uma licença Pro. Uma versão fixada explicitamente em CLOAKBROWSER_VERSION tem precedência. Se o Preview não estiver disponível para a plataforma, o CloakBrowser volta para Stable.

O canal de lançamento é selecionado quando o processo da ponte é iniciado. Ele se aplica a todas as sessões de Streamable HTTP e não pode ser definido nem substituído nos metadados de initialize. Reinicie a ponte para alterá-lo.

Binário personalizado do CloakBrowser¶

--binary-path <path> seleciona um executável personalizado do CloakBrowser para o processo atual da ponte. CLOAKBROWSER_BINARY_PATH fornece a mesma configuração para implantações baseadas em ambiente; a opção da CLI tem precedência. A ponte resolve o caminho, exige um arquivo regular legível e o escreve em browser.launchOptions.executablePath da configuração gerada do Playwright MCP.

npx -y cloakbrowser-mcp@latest --binary-path /opt/cloakbrowser/chrome

A ponte não baixa nem atualiza um executável personalizado. Sem um caminho personalizado, CLOAKBROWSER_VERSION pode fixar a versão do binário gerenciado pelo CloakBrowser.

No Streamable HTTP, o binário selecionado pertence ao processo da ponte e é usado por todas as sessões MCP que ele cria. Os metadados de initialize não podem selecionar nem substituir um caminho executável; execute processos separados para binários diferentes.

Quando o binário selecionado implementa document.modelContext, o Playwright MCP upstream pode adicionar ferramentas webmcp_<page-tool> após um snapshot da página. Ele envia tools/list_changed; a ponte encaminha a notificação e a lista de ferramentas atualizada. A página define o nome e o esquema de cada ferramenta dinâmica.

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 de saída do proxy. O CloakBrowser seleciona a autenticação nativa incorporada à URL para binários compatíveis e mantém o objeto de proxy do Playwright como fallback para binários antigos.

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.

A correspondência funciona em fail-closed: se o CloakBrowser não puder resolver o IP de saída do proxy, o banco de dados GeoIP, o fuso horário ou a localidade, o navegador não inicia com uma impressão digital parcialmente correspondente. A resolução de GeoIP tem no máximo 20 segundos; o primeiro download do banco de dados GeoIP offline é separado e pode levar mais tempo.

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.

Modo de conexão Playwright Extension¶

Esse modo se conecta pela extensão oficial do Playwright já instalada em um perfil do Chrome ou Edge e é diferente de carregar extensões descompactadas com CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS. Para stdio, configure PLAYWRIGHT_MCP_EXTENSION=true, PLAYWRIGHT_MCP_EXTENSION_TOKEN, PLAYWRIGHT_MCP_USER_DATA_DIR e, se necessário, um único segmento relativo em PLAYWRIGHT_MCP_PROFILE_DIR_NAME. No Streamable HTTP, os metadados extensionMode, profileDirName e userDataDir substituem os valores do processo, mas o token só é aceito pelo ambiente do processo. Sessões paralelas devem usar userDataDir diferentes; opções de launch, CDP, proxy, GeoIP, humanization, context e extensionPaths são incompatíveis.

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.

No Docker, headless: false inicia uma tela virtual privada sob demanda. Fora da imagem, uma sessão com interface gráfica ainda requer um ambiente de exibição utilizável.

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

Nos binários compatíveis do CloakBrowser, proxies HTTP autenticados usam autenticação nativa incorporada à URL, e a ponte remove o objeto de proxy duplicado do Playwright. Binários antigos mantêm o objeto de proxy do Playwright como fallback de compatibilidade.

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.

PLAYWRIGHT_MCP_CAPS=devtools é herdado pelo processo filho upstream e habilita as ferramentas controladas por essa capacidade sem uma opção --caps própria da ponte.

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.