README.md•10.7 kB
# 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