MCP Browser Debugger

# MCP Browser Debugger Servidor MCP avançado para debugging completo de frontend com análise de DOM, execução de JavaScript3. **🆕 Fluxo completo: Login e inspeção**: ``` "Primeiro, verifique se o browser está aberto. Se estiver fechado, abra o browser visível. Depois faça login em https://meusite.com/login usando: - Campo email: #email - Campo senha: #password - Botão: button.submit - Email: meu@email.com - Senha: minhasenha Depois me mostre o DOM da página logada" ``` 4. **Debugar uma página web**:o de rede e muito mais. **Desenvolvido em TypeScript** com padrões profissionais de código (ESLint + Prettier). ## 🚀 Funcionalidades ### 🌐 Controle do Browser - **open_browser**: Abre o browser em modo **VISÍVEL** (headful) para você ver as ações do agent em tempo real - **login**: Faz login automatizado e mantém a sessão ativa para inspeção ### Navegação e Carregamento - **navigate**: Navega para qualquer URL com controle de timeout e condições de espera - **get_page_info**: Obtém informações completas sobre a página atual ### Análise de DOM - **get_dom**: Extrai o HTML completo do DOM - **get_element**: Inspeciona elementos específicos com estilos computados - **query_selector_all**: Busca múltiplos elementos por seletor CSS - **evaluate_xpath**: Avalia expressões XPath ### Código Fonte - **get_page_source**: Extrai todo código fonte incluindo scripts e estilos - **execute_js**: Executa JavaScript arbitrário no contexto da página ### Debugging e Monitoramento - **get_console_logs**: Captura todos os logs do console - **get_network_activity**: Monitora todas as requisições HTTP - **screenshot**: Captura screenshots da página ou elementos específicos ### Interação - **click_element**: Clica em elementos - **type_text**: Digita texto em campos de input ### Inspeção de Dados - **get_local_storage**: Acessa localStorage - **get_cookies**: Lista todos os cookies ## 📦 Instalação ```bash npm install npm run build ``` ## 🛠️ Scripts Disponíveis ```bash npm run dev # Desenvolvimento com ts-node npm run start # Executa código compilado npm run build # Compila TypeScript para JavaScript npm run lint # Verifica código com ESLint npm run lint:fix # Corrige problemas do ESLint automaticamente npm run format # Formata código com Prettier npm run format:check # Verifica formatação sem modificar ``` ## ⚙️ Configuração no Claude Desktop Adicione ao seu arquivo de configuração do MCP client: **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "browser-debugger": { "command": "node", "args": ["c:\\Users\\Emmanuel\\Desktop\\mcp\\mcp-browser\\dist\\index.js"] } } } ``` **Nota**: Após qualquer alteração no código, execute `npm run build` antes de reiniciar o Claude Desktop. ## 🔧 Uso ### ⚠️ IMPORTANTE: Fluxo Correto para Evitar Perda de Sessão **SEMPRE siga esta ordem:** 1. **Primeiro: Verificar se browser está aberto** ``` "Verifique se o browser está aberto" ``` 2. **Se fechado: Abrir browser visível** ``` "Abra o browser em modo visível" ``` 3. **Fazer login (se necessário)** ``` "Faça login em https://site.com/login usando..." ``` 4. **Continuar usando SEM abrir browser novamente** ``` "Navegue para...", "Me mostre o DOM", etc. ``` ### Exemplos de Comandos para o Agent 1. **🆕 Verificar status do browser**: ``` "Verifique se o browser está aberto" ``` 2. **🆕 Abrir browser visível**: ``` "Abra o browser em modo visível e navegue para https://google.com" ``` 3. **🆕 Fluxo completo: Login e inspeção**: ``` "Abra o browser visível, faça login em https://meusite.com/login usando: - Campo email: #email - Campo senha: #password - Botão: button.submit - Email: meu@email.com - Senha: minhasenha Depois me mostre o DOM da página logada" ``` 3. **Debugar uma página web**: ``` "Navegue para https://example.com e me mostre o DOM completo" ``` 2. **Analisar erros de console**: ``` "Navegue para https://meusite.com e me mostre todos os erros do console" ``` 3. **Inspecionar elemento específico**: ``` "Encontre o elemento com classe 'header' e me mostre seus estilos computados" ``` 4. **Executar JavaScript customizado**: ``` "Execute este código: document.querySelectorAll('img').length" ``` 5. **Monitorar requisições de rede**: ``` "Mostre todas as requisições HTTP que falharam (status 4xx ou 5xx)" ``` 6. **Extrair código fonte**: ``` "Me mostre todos os scripts inline e externos da página" ``` 7. **Capturar screenshot**: ``` "Tire um screenshot da página inteira" ``` ## 🛠️ Ferramentas Disponíveis ### 1. get_browser_status ⭐ NOVO - USE PRIMEIRO! **Verifica se o browser está aberto ou fechado.** SEMPRE use esta ferramenta antes de abrir um novo browser! **Parâmetros**: Nenhum **Retorno**: - `isOpen`: Browser está aberto? - `headless`: Modo headless (invisível) ou headful (visível)? - `currentUrl`: URL atual da página - `pageTitle`: Título da página atual - `message`: Mensagem explicativa **Exemplo de uso**: ``` "Verifique se o browser está aberto" ``` **⚠️ Por que é importante:** - Se você abrir um browser que já está aberto, **perderá a sessão de login!** - Use esta ferramenta para evitar loops infinitos ### 2. close_browser ⭐ NOVO **Fecha o browser e encerra a sessão.** **Parâmetros**: Nenhum **⚠️ ATENÇÃO:** - Isso irá **perder todos os cookies, localStorage e sessões de login!** - Use apenas quando o usuário pedir explicitamente para fechar o browser - Após fechar, você precisará usar `open_browser` para abrir novamente **Exemplo de uso**: ``` "Feche o browser" ``` ### 3. open_browser ⭐ NOVO **Abre o browser em modo VISÍVEL** para você ver tudo que o agent está fazendo! **⚠️ ATENÇÃO:** Use `get_browser_status` ANTES! Se o browser já estiver aberto, NÃO use esta ferramenta. **Parâmetros**: - `url`: URL para abrir (opcional) - `headless`: Se false, browser fica visível (padrão: false) - `width`: Largura da janela (padrão: 1920) - `height`: Altura da janela (padrão: 1080) **Exemplo de uso**: ``` Passo 1: "Verifique se o browser está aberto" Passo 2: Se fechado -> "Abra o browser visível em https://github.com" ``` ### 4. login ⭐ NOVO **Faz login automatizado** e mantém a sessão aberta para inspeção. **Parâmetros**: - `url` (obrigatório): URL da página de login - `usernameSelector` (obrigatório): Seletor CSS do campo username/email - `passwordSelector` (obrigatório): Seletor CSS do campo senha - `submitSelector` (obrigatório): Seletor CSS do botão de submit - `username` (obrigatório): Username ou email - `password` (obrigatório): Senha - `waitForSelector`: Seletor para confirmar login bem-sucedido (opcional) - `timeout`: Timeout em ms (padrão: 30000) - `delayAfterType`: Delay após digitar, útil para SPAs (padrão: 500) **Exemplo de uso**: ``` "Faça login em https://exemplo.com/login usando: - Campo de email: input[name='email'] - Campo de senha: input[type='password'] - Botão: button[type='submit'] - Email: usuario@exemplo.com - Senha: minhasenha123" ``` ### 5. navigate Navega para uma URL específica. **Parâmetros**: - `url` (obrigatório): URL completa - `waitUntil`: "load" | "domcontentloaded" | "networkidle0" | "networkidle2" - `timeout`: Timeout em ms ### 6. get_dom Extrai o HTML completo do DOM. **Parâmetros**: - `prettify`: Formatar HTML (padrão: true) ### 7. get_element Inspeciona um elemento específico. **Parâmetros**: - `selector` (obrigatório): Seletor CSS - `includeStyles`: Incluir estilos computados - `includeAttributes`: Incluir atributos ### 8. execute_js Executa JavaScript no contexto da página. **Parâmetros**: - `code` (obrigatório): Código JavaScript - `returnValue`: Retornar valor da execução ### 9. screenshot Captura screenshot. **Parâmetros**: - `selector`: Elemento específico (opcional) - `fullPage`: Página inteira com scroll - `path`: Caminho para salvar ### 10. get_console_logs Recupera logs do console. **Parâmetros**: - `filterType`: "all" | "log" | "error" | "warning" | "info" - `clear`: Limpar logs após recuperação ### 11. get_network_activity Recupera atividade de rede. **Parâmetros**: - `filterType`: "all" | "request" | "response" - `clear`: Limpar histórico ### 12. get_page_source Extrai código fonte completo. **Parâmetros**: - `includeScripts`: Incluir scripts - `includeStyles`: Incluir estilos ### 13. query_selector_all Busca múltiplos elementos. **Parâmetros**: - `selector` (obrigatório): Seletor CSS - `limit`: Limitar resultados (padrão: 100) ### 14. get_page_info Informações gerais da página. ### 15. click_element Clica em um elemento. **Parâmetros**: - `selector` (obrigatório): Seletor CSS - `waitForNavigation`: Aguardar navegação ### 16. type_text Digita texto em input. **Parâmetros**: - `selector` (obrigatório): Seletor CSS - `text` (obrigatório): Texto a digitar - `clearFirst`: Limpar antes de digitar ### 17. get_local_storage Acessa localStorage. ### 18. get_cookies Lista cookies. ### 19. evaluate_xpath Avalia XPath. **Parâmetros**: - `xpath` (obrigatório): Expressão XPath ## 🎯 Casos de Uso ### Debugging de Aplicação React/Vue/Angular ``` 1. Navegar para a aplicação 2. Capturar console logs e erros 3. Inspecionar componentes específicos 4. Executar JavaScript para verificar estado da aplicação 5. Monitorar requisições API ``` ### Análise de Performance ``` 1. Navegar com networkidle0 2. Capturar todas as requisições de rede 3. Analisar tamanho de recursos 4. Verificar tempo de carregamento ``` ### Extração de Dados ``` 1. Navegar para a página 2. Executar query_selector_all para elementos desejados 3. Executar JavaScript customizado para processar dados 4. Extrair informações específicas ``` ### Testes de UI ``` 1. Navegar para a página 2. Interagir com elementos (click, type) 3. Verificar mudanças no DOM 4. Capturar screenshots de evidência ``` ## 🔒 Segurança - Browser executa em modo headless - Sandbox desabilitado apenas para compatibilidade local - Não armazena credenciais - Logs são mantidos em memória e podem ser limpos ## 📝 Notas - O browser é iniciado automaticamente na primeira ferramenta chamada - Uma única instância de página é mantida entre chamadas - Console logs e requisições de rede são acumulados entre navegações (use `clear: true` para limpar) - Screenshots podem ser salvos em disco ou retornados como base64