# browser-mcp

Servidor [MCP](https://modelcontextprotocol.io) local de automação de navegador para o [Claude Code](https://claude.com/claude-code): dá ao Claude ferramentas para navegar, clicar, digitar e inspecionar páginas web reais usando o Google Chrome já instalado na máquina.

## Por que existe

A maioria das libs de automação simula clique/digitação via eventos de mouse/teclado no nível do sistema operacional (CDP). Isso funciona bem em apps modernos, mas quebra silenciosamente em várias aplicações web legadas (ex: JSF/PrimeFaces), onde o listener de evento é delegado via jQuery e não recebe o evento simulado. Este servidor dispara os eventos DOM (`mousedown`/`mouseup`/`click`, `input`/`change`) diretamente no elemento via JavaScript, o que se mostrou mais confiável nesses casos.

Também inclui um `browser_snapshot`: uma árvore de texto compacta da página (em vez de screenshot), pensada pra gastar poucos tokens quando não é preciso conferir visualmente.

## Requisitos

- Node.js (testado com v16)
- Google Chrome instalado na máquina (usa o binário do sistema, não baixa um Chromium embutido)

## Instalação

```bash
git clone <url-do-repo>
cd browser-mcp
npm install
```

## Configuração

| Variável | Padrão | Descrição |
|---|---|---|
| `BROWSER_MCP_CHROME_PATH` | `/usr/bin/google-chrome-stable` | Caminho do binário do Chrome |
| `BROWSER_MCP_DOWNLOAD_DIR` | `./downloads` | Pasta onde downloads feitos pelo navegador são salvos |

## Registrar no Claude Code

```bash
claude mcp add browser -- node /caminho/completo/para/browser-mcp/server.js
```

## Ferramentas disponíveis

| Ferramenta | Descrição |
|---|---|
| `browser_navigate` | Abre uma URL (lança o Chrome na primeira chamada) |
| `browser_click` | Clica em um elemento via seletor CSS |
| `browser_type` | Preenche um campo de texto |
| `browser_select` | Seleciona uma opção em um `<select>` |
| `browser_wait_for_selector` | Espera um elemento aparecer (útil após AJAX) |
| `browser_get_text` | Lê o texto visível de um elemento ou da página |
| `browser_snapshot` | Árvore de texto compacta dos elementos relevantes da página |
| `browser_upload_file` | Faz upload de um arquivo em um `<input type="file">` |
| `browser_screenshot` | Tira um screenshot (viewport, página inteira ou de um elemento) |
| `browser_evaluate` | Executa JavaScript arbitrário na página |
| `browser_close` | Encerra a sessão do navegador |

## Arquitetura

Um único arquivo (`server.js`), sem dependências além de `puppeteer-core`. Fala o protocolo MCP via JSON-RPC 2.0 sobre stdio (uma mensagem por linha). As chamadas de ferramenta são serializadas em fila: automação de navegador é sequencial por natureza, então duas chamadas concorrentes contra a mesma aba/página são executadas uma após a outra, nunca em paralelo.

## Licença

MIT — veja [LICENSE](LICENSE).