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:
- 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"
- 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
- 🆕 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"
- 🆕 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"
- 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"
- 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)"
- 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áginapageTitle: Título da página atualmessage: 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 completawaitUntil: "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 CSSincludeStyles: Incluir estilos computadosincludeAttributes: Incluir atributos
8. execute_js
Executa JavaScript no contexto da página.
Parâmetros:
code(obrigatório): Código JavaScriptreturnValue: Retornar valor da execução
9. screenshot
Captura screenshot.
Parâmetros:
selector: Elemento específico (opcional)fullPage: Página inteira com scrollpath: 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 scriptsincludeStyles: Incluir estilos
13. query_selector_all
Busca múltiplos elementos.
Parâmetros:
selector(obrigatório): Seletor CSSlimit: 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 CSSwaitForNavigation: Aguardar navegação
16. type_text
Digita texto em input.
Parâmetros:
selector(obrigatório): Seletor CSStext(obrigatório): Texto a digitarclearFirst: 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```
- Navegar para a aplicação
- Capturar console logs e erros
- Inspecionar componentes específicos
- Executar JavaScript para verificar estado da aplicação
- 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```
- Navegar para a página
- Executar query_selector_all para elementos desejados
- Executar JavaScript customizado para processar dados
- 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: truepara limpar) - Screenshots podem ser salvos em disco ou retornados como base64
