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

npm install
npm run build

🛠️ Scripts Disponíveis

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

{
  "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