# 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