BrowserLoop

Tire capturas de tela e leia logs do console de páginas da web usando Playwright.

Documentação

BrowserLoop

⚠️ ARQUIVADO: Este projeto está arquivado e não receberá mais atualizações. Com o lançamento do Chrome DevTools MCP, um servidor MCP dedicado para automação de navegador não é mais necessário, pois esse projeto oferece recursos mais abrangentes de interação com o navegador, incluindo capturas de tela, monitoramento de console e muito mais.

Um servidor Model Context Protocol (MCP) para capturar screenshots e ler logs de console de páginas da web usando Playwright. Esta ferramenta permite que agentes de IA capturem automaticamente screenshots e monitorem a saída do console do navegador para tarefas de depuração, teste e desenvolvimento.

NOTA: Quase todo o código neste repositório foi gerado automaticamente. Isso significa que você provavelmente não deve confiar demais nele. Dito isso, ele funciona e eu mesmo o utilizo.

NOTA: Se a documentação estiver incorreta, por favor me avise ou envie um PR. Se você também quiser usar uma ferramenta de geração de código para atualizar o código deste projeto, o PROJECT_CONTEXT.md foi usado como contexto para fornecer uma boa visão geral das várias partes do projeto. Pode estar um pouco bagunçado agora, mas é um bom ponto de partida e você é bem-vindo para atualizá-lo.

Recursos

📸 Captura de screenshots de alta qualidade usando Playwright
📝 Monitoramento e coleta de logs de console de páginas da web
🌐 Suporte para URLs locais (localhost) e remotas
🍪 Autenticação baseada em cookies para páginas protegidas
🐳 Containerização com Docker para ambientes consistentes
⚡ Suporte aos formatos PNG, JPEG e WebP com qualidade configurável
🛡️ Execução segura em container como usuário não-root
🤖 Integração completa com o protocolo MCP para ferramentas de desenvolvimento de IA
🔧 Tamanhos de viewport e opções de captura configuráveis
📱 Captura de screenshots de página inteira e de elementos específicos
⚠️ Captura de avisos e erros do navegador (Permissions-Policy, avisos de segurança)
⚡ TypeScript com Biome para desenvolvimento rápido
🧪 Testes abrangentes com o executor de testes integrado do Node.js

Início Rápido

📦 Uso com NPX (Recomendado)

A maneira mais fácil de começar - sem necessidade de instalação!

# Install Chromium browser (one-time setup)
npx playwright install chromium

# Test that BrowserLoop works
npx browserloop@latest --version

É isso! A versão mais recente do BrowserLoop será baixada e executada automaticamente. Perfeito para usuários de MCP que desejam screenshots sem manutenção.

Configuração do MCP

Adicione o BrowserLoop ao seu arquivo de configuração do MCP (ex.: ~/.cursor/mcp.json):

{
  "mcpServers": {
    "browserloop": {
      "command": "npx",
      "args": ["-y", "browserloop@latest"],
      "description": "Screenshot and console log capture server for web pages using Playwright"
    }
  }
}

💡 Usar @latest garante que você sempre obtenha os recursos mais recentes e correções de bugs automaticamente.

🚀 Instalação com Um Clique para Cursor

Adicione o BrowserLoop ao Cursor com um único clique usando este deeplink:

🔗 Adicionar BrowserLoop ao Cursor

Este deeplink configurará automaticamente o BrowserLoop nas configurações de MCP do seu Cursor com a configuração ideal usando npx e a versão mais recente.

Pré-requisitos: Certifique-se de ter o Chromium instalado primeiro:

npx playwright install chromium

Requisitos de Instalação do Navegador

🚨 Crítico: O BrowserLoop requer que o Chromium seja instalado via Playwright antes de poder capturar screenshots.

Configuração Inicial (Todos os Usuários)

Instale o navegador Chromium:

npx playwright install chromium

Verifique a instalação:

# Check Playwright installation
npx playwright --version

# Test BrowserLoop (if using NPX)
npx browserloop@latest --version

🐳 Alternativa com Docker

Para ambientes containerizados:

# Pull and run with Docker
docker run --rm --network host browserloop

# Or use docker-compose for development
git clone <repository-url>
cd browserloop
docker-compose -f docker/docker-compose.yml up

💻 Instalação para Desenvolvimento

Para contribuidores ou usuários avançados que desejam compilar a partir do código-fonte:

# Clone the repository
git clone <repository-url>
cd browserloop

# Install dependencies
npm install

# Install Playwright browsers (required for screenshots)
npx playwright install chromium
# OR use the convenient script:
npm run install-browsers

# Build the project
npm run build

Configuração do MCP para Desenvolvimento

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": [
        "/absolute/path/to/browserloop/dist/src/index.js"
      ],
      "description": "Screenshot and console log capture server for web pages using Playwright"
    }
  }
}

Substitua /absolute/path/to/browserloop/ pelo caminho real do seu projeto.

Uso Básico

Uma vez configurado, você pode usar comandos em linguagem natural na sua ferramenta de IA:

Screenshots

Take a screenshot of https://example.com
Take a screenshot of https://example.com with width 1920 and height 1080
Take a screenshot of https://example.com in JPEG format with 95% quality
Take a full page screenshot of https://example.com
Take a screenshot of http://localhost:3000 to verify the UI changes

Leitura de Logs do Console

Read console logs from https://example.com
Check for console errors on https://example.com
Monitor console warnings from http://localhost:3000
Read only error and warning logs from https://example.com
Capture console output from https://example.com for debugging

🔐 Autenticação por Cookies

O BrowserLoop suporta autenticação baseada em cookies para capturar screenshots de páginas protegidas por login durante o desenvolvimento:

Take a screenshot of http://localhost:3000/admin/dashboard using these cookies: [{"name":"connect.sid","value":"s:session-id.signature","domain":"localhost"}]

📖 Para métodos de extração de cookies e fluxos de trabalho de desenvolvimento, consulte:

📖 Guia de Autenticação por Cookies

Casos de uso comuns em desenvolvimento:

Servidores de desenvolvimento locais com autenticação
Testes em ambientes de staging
Ferramentas de documentação de API (Swagger, GraphQL Playground)
Aplicações web personalizadas durante o desenvolvimento
Painéis administrativos e rotas protegidas

Documentação

🔐 Guia de Autenticação por Cookies - Guia completo para screenshots autenticados
📚 Referência Completa da API - Documentação detalhada de parâmetros, exemplos e formatos de resposta

Principais Parâmetros da API

Parâmetro	Tipo	Descrição	Padrão
`url`	string	URL de destino para captura (obrigatório)	-
`width`	number	Largura do viewport (200-4000)	1280
`height`	number	Altura do viewport (200-4000)	720
`format`	string	Formato da imagem (webp, png, jpeg)	webp
`quality`	number	Qualidade da imagem (1-100)	80
`fullPage`	boolean	Capturar página inteira	false
`selector`	string	Seletor CSS para captura de elemento	-

📖 Consulte docs/API.md para detalhes completos dos parâmetros, exemplos de uso e opções de configuração.

Configuração

O BrowserLoop pode ser configurado usando variáveis de ambiente:

Configuração Básica

Variável	Padrão	Descrição
`BROWSERLOOP_DEFAULT_WIDTH`	`1280`	Largura padrão do viewport (200-4000)
`BROWSERLOOP_DEFAULT_HEIGHT`	`720`	Altura padrão do viewport (200-4000)
`BROWSERLOOP_DEFAULT_FORMAT`	`webp`	Formato padrão da imagem (`webp`, `png`, `jpeg`)
`BROWSERLOOP_DEFAULT_QUALITY`	`80`	Qualidade padrão da imagem (0-100)
`BROWSERLOOP_DEFAULT_TIMEOUT`	`30000`	Tempo limite padrão em milissegundos
`BROWSERLOOP_USER_AGENT`	-	String personalizada de user agent

Configuração de Autenticação

Variável	Padrão	Descrição
`BROWSERLOOP_DEFAULT_COOKIES`	-	Cookies padrão como caminho de arquivo ou string JSON (consulte Guia de Autenticação por Cookies)

Configuração de Logs do Console

Variável	Padrão	Descrição
`BROWSERLOOP_CONSOLE_LOG_LEVELS`	`log,info,warn,error,debug`	Lista separada por vírgulas dos níveis de log a serem capturados
`BROWSERLOOP_CONSOLE_TIMEOUT`	`30000`	Tempo limite de navegação da página em milissegundos (não o tempo de coleta de logs)
`BROWSERLOOP_SANITIZE_LOGS`	`true`	Ativar/desativar a sanitização de dados sensíveis nos logs
`BROWSERLOOP_CONSOLE_WAIT_NETWORK_IDLE`	`true`	Aguardar rede ociosa antes de concluir a coleta
`BROWSERLOOP_MAX_LOG_SIZE`	`1048576`	Tamanho máximo total do log em bytes (1MB)

Nota: A coleta de logs do console sempre aguarda exatamente 3 segundos após o carregamento da página para capturar as mensagens do console. A configuração de tempo limite afeta apenas o tempo que a página tem para carregar inicialmente.

Sanitização de Logs

A sanitização de logs do console está ativada por padrão (BROWSERLOOP_SANITIZE_LOGS=true) para proteger informações sensíveis. Quando ativada, os seguintes padrões são mascarados automaticamente:

Tipo de Padrão	Exemplo de Entrada	Saída Mascarada
Chaves de API	`sk_live_1234567890abcdef...`	`[API_KEY_MASKED]`
Endereços de E-mail	`user@example.com`	`[EMAIL_MASKED]`
Tokens JWT	`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`	`[JWT_TOKEN_MASKED]`
Cabeçalhos de Autenticação	`Bearer abc123token...`	`[AUTH_HEADER_MASKED]`
URLs com Autenticação	`https://api.com/data?token=secret123`	`[URL_WITH_AUTH_MASKED]`
Variáveis Secretas	`password: mySecretPass`	`password: [VALUE_MASKED]`

Para desativar a sanitização (para depuração):

BROWSERLOOP_SANITIZE_LOGS=false

Nota: A sanitização preserva a estrutura do log enquanto mascara conteúdo sensível, tornando os logs seguros para compartilhamento e análise.

Desempenho e Confiabilidade

Variável	Padrão	Descrição
`BROWSERLOOP_RETRY_COUNT`	`3`	Número de tentativas de repetição para operações com falha
`BROWSERLOOP_RETRY_DELAY`	`1000`	Atraso entre tentativas em milissegundos

Logging e Depuração

Variável	Padrão	Descrição
`BROWSERLOOP_DEBUG`	`false`	Ativar logging de depuração para `/tmp/browserloop.log`
`BROWSERLOOP_ENABLE_METRICS`	`true`	Ativar coleta de métricas de erros
`BROWSERLOOP_DISABLE_FILE_WATCHING`	`false`	Desativar monitoramento automático do arquivo de cookies

Logging de Depuração

Quando BROWSERLOOP_DEBUG=true, logs detalhados são gravados em /tmp/browserloop.log, incluindo:

Eventos de carregamento e atualização automática do arquivo de cookies
Status do monitoramento de arquivos e eventos de recriação
Detalhes das operações de screenshot
Mudanças de configuração e erros

Monitore os logs em tempo real:

tail -f /tmp/browserloop.log

Nota: Os logs são gravados em um arquivo (não no console) para manter a compatibilidade com o protocolo stdio do MCP.

Exemplo de Configuração do MCP com Cookies Padrão

Método 1: Arquivo JSON (Recomendado)

Crie um arquivo de cookies:

// ~/.config/browserloop/cookies.json
[
  {
    "name": "connect.sid",
    "value": "s:your-dev-session.signature",
    "domain": "localhost"
  }
]

Referencie na configuração do MCP:

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": ["dist/src/mcp-server.js"],
      "env": {
        "BROWSERLOOP_DEFAULT_COOKIES": "/home/username/.config/browserloop/cookies.json",
        "BROWSERLOOP_DEFAULT_FORMAT": "webp",
        "BROWSERLOOP_DEFAULT_QUALITY": "85"
      }
    }
  }
}

Método 2: String JSON (Legado)

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": ["dist/src/mcp-server.js"],
      "env": {
        "BROWSERLOOP_DEFAULT_COOKIES": "[{\"name\":\"session_id\",\"value\":\"your_session_value\",\"domain\":\"example.com\"},{\"name\":\"auth_token\",\"value\":\"your_auth_token\"}]",
        "BROWSERLOOP_DEFAULT_FORMAT": "webp",
        "BROWSERLOOP_DEFAULT_QUALITY": "85"
      }
    }
  }
}

Exemplos de Configuração de Logs do Console

# Only capture warnings and errors
BROWSERLOOP_CONSOLE_LOG_LEVELS="warn,error"

# Debug mode with all logs, no sanitization
BROWSERLOOP_DEBUG="true"
BROWSERLOOP_SANITIZE_LOGS="false"
BROWSERLOOP_CONSOLE_LOG_LEVELS="log,info,warn,error,debug"

Solução de Problemas

Problemas Comuns

Erro "Executable doesn't exist"

# Install Chromium browser (most common fix)
npx playwright install chromium

Servidor MCP Não Inicia

Teste manualmente: npx browserloop@latest --version
Verifique os requisitos:
- Node.js 20+: node --version
- npm: npm --version
- npx: npx --version
Verifique a sintaxe JSON da configuração do MCP

Screenshots Mostram Páginas de Login

Use autenticação por cookies (consulte Guia de Autenticação por Cookies)
Verifique a expiração dos cookies e as configurações de domínio

Logs do Console Estão Vazios

Alguns sites de produção não têm saída de console (isso é normal)
Teste com sites de desenvolvimento que tenham atividade no console
Ative o logging de depuração: BROWSERLOOP_DEBUG=true e verifique /tmp/browserloop.log
Verifique a filtragem por nível de log: BROWSERLOOP_CONSOLE_LOG_LEVELS=log,info,warn,error,debug

Tempo de Coleta de Logs do Console

A coleta sempre aguarda exatamente 3 segundos após o carregamento da página
BROWSERLOOP_CONSOLE_TIMEOUT controla o tempo limite de carregamento da página, não o tempo de coleta de logs
Sites rápidos ainda levarão cerca de 3-4 segundos no total (carregamento + 3s de coleta + processamento)

Problemas de Rede/Conexão

Teste primeiro com URLs externas: https://example.com
Para localhost: certifique-se de que seu servidor de desenvolvimento esteja em execução
Verifique as configurações do firewall

Atualizando o BrowserLoop

NPX: Usa automaticamente a versão mais recente com @latest - sem necessidade de atualizações manuais!
Verifique a versão atual: npx browserloop@latest --version

Diagnóstico Rápido

# Test complete setup
node --version && npm --version
npx playwright --version

# Test BrowserLoop
npx browserloop@latest --version

Ative o logging de depuração: Defina BROWSERLOOP_DEBUG=true na sua configuração do MCP e monitore /tmp/browserloop.log

📖 Consulte docs/API.md#error-handling para solução de problemas detalhada.

Licença

O BrowserLoop é licenciado sob a GNU Affero General Public License v3.0 ou posterior (AGPL-3.0-or-later).

O que isso significa:

✅ Livre para usar - Uso pessoal e comercial permitido
✅ Livre para modificar - Você pode adaptar o código às suas necessidades
✅ Livre para distribuir - Compartilhe cópias com outras pessoas
✅ Proteção de patentes - Contribuidores concedem licenças de patente
⚠️ Copyleft - Trabalhos derivados também devem ser de código aberto sob AGPL-3.0
⚠️ Cláusula de rede - Se você executar uma versão modificada em um servidor, deve fornecer o código-fonte aos usuários

Para Serviços de Rede

Importante: Se você modificar o BrowserLoop e executá-lo como um serviço de rede (ex.: aplicativo web, servidor de API ou serviço em nuvem), a AGPL exige que você:

Ofereça o código-fonte completo a todos os usuários do seu serviço
Inclua um aviso em destaque sobre como os usuários podem acessar o código-fonte
Use uma licença compatível para todo o serviço

Arquivos de Licença

LICENSE - Texto completo da licença

Uso Comercial

Organizações podem usar o BrowserLoop sob a AGPL para fins comerciais, mas devem cumprir os requisitos de copyleft. Se você precisar manter modificações privadas, considere:

Usar o BrowserLoop sem modificações
Contribuir com melhorias de volta para a comunidade
Entrar em contato com os mantenedores sobre possíveis acordos alternativos de licenciamento

Para perguntas sobre licenciamento, abra uma issue ou entre em contato com os mantenedores.