# MCP-Browser

MCP server que permite a qualquer agente de IA controlar um navegador real usando [Playwright](https://playwright.dev/).

![Node](https://img.shields.io/badge/Node.js-18+-339933?logo=node.js&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-stdio-blue)
![Platform](https://img.shields.io/badge/Windows%20|%20Linux%20|%20macOS-lightgrey)
![Tools](https://img.shields.io/badge/17%20tools-green)

## Funcionalidades

- Controle total de navegador via IA
- 17 tools prontas para uso
- Reuso automático de abas (mesmo domínio)
- Preenchimento automático de formulários
- Fluxos agentísticos com retry
- Compatível com qualquer plataforma MCP

## Pré-requisitos

| Dependência | Versão mínima |
|-------------|---------------|
| Node.js     | 18+           |
| npm         | 9+            |

## Instalação

```bash
# 1. Clonar o repositório
git clone https://git.jf.eng.br/jfeng/MCP-Browser.git
cd MCP-Browser

# 2. Instalar dependências
npm install

# 3. Instalar Chromium do Playwright
npx playwright install chromium

# Linux: instalar dependências do sistema
sudo npx playwright install-deps chromium
```

## Configuração por plataforma

Todas as plataformas usam o mesmo padrão:

```
Comando:   node
Argumento: /caminho/absoluto/MCP-Browser/server.js
Transport: stdio
```

### OpenCode

```bash
opencode mcp add
```

- **Nome:** `meu-navegador`
- **Tipo:** `Local`
- **Comando:** `node /caminho/MCP-Browser/server.js`

### Cursor

`~/.cursor/mcp.json` (global) ou `.cursor/mcp.json` (projeto):

```json
{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/caminho/MCP-Browser/server.js"]
    }
  }
}
```

### Claude Desktop

`%APPDATA%\Claude\claude_desktop_config.json` (Windows)
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)

```json
{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/caminho/MCP-Browser/server.js"]
    }
  }
}
```

### Windsurf

`~/.windsurf/mcp.json`:

```json
{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/caminho/MCP-Browser/server.js"]
    }
  }
}
```

### Trae

Settings → Extensions → MCP → Adicionar server:

- **Name:** `browser`
- **Command:** `node`
- **Args:** `["/caminho/MCP-Browser/server.js"]`

### Antigravity

Configuração de MCP → Novo server:

- **Name:** `browser`
- **Type:** `stdio`
- **Command:** `node /caminho/MCP-Browser/server.js`

### VS Code

`.vscode/mcp.json`:

```json
{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/caminho/MCP-Browser/server.js"]
    }
  }
}
```

### Qualquer plataforma MCP

Se suporta **MCP stdio transport**, use:

```
Comando:   node
Argumento: /caminho/absoluto/MCP-Browser/server.js
```

## Tools disponíveis (17)

| # | Tool | Descrição | Parâmetros |
|---|------|-----------|------------|
| 1 | `open_url` | Abre uma URL | `url` |
| 2 | `click` | Clica por seletor CSS | `selector` |
| 3 | `type` | Digita texto em campo | `selector`, `text` |
| 4 | `screenshot` | Captura screenshot | `fullPage` (opcional) |
| 5 | `get_text` | Extrai texto da página | `selector` (opcional) |
| 6 | `get_links` | Lista links | `selector` (opcional) |
| 7 | `wait_for_selector` | Espera elemento aparecer | `selector`, `timeout` |
| 8 | `extract_elements` | Extrai elementos com atributos | `selector`, `attributes` |
| 9 | `smart_click` | Clica por texto visível | `text` |
| 10 | `smart_type` | Digita por label/placeholder | `label`, `text` |
| 11 | `get_buttons` | Lista botões disponíveis | — |
| 12 | `smart_wait_navigation` | Espera mudança de URL | `timeout` (opcional) |
| 13 | `get_forms` | Lista formulários e campos | — |
| 14 | `fill_form_auto` | Preenche formulário auto | `data` |
| 15 | `agent_flow` | Fluxo automático simples | `goal`, `data` |
| 16 | `agent_flow_v2` | Fluxo com retry/fallback | `goal`, `data`, `retries` |
| 17 | `close_browser` | Fecha o navegador | — |

## Exemplos de uso

### Abrir site e extrair conteúdo

```
open_url("https://example.com")
get_text()
get_links()
screenshot()
```

### Login automático

```
open_url("https://site.com/login")
fill_form_auto({"email": "user@test.com", "password": "1234"})
smart_click("Entrar")
smart_wait_navigation()
```

### Scraping com atributos

```
open_url("https://site.com/produtos")
extract_elements(".produto", ["href", "data-id"])
```

## Estrutura do projeto

```
MCP-Browser/
├── server.js              # Servidor MCP (entry point)
├── browser.js             # Engine Playwright (singleton)
├── package.json
├── docs.html              # Documentação detalhada
└── tools/
    ├── openUrl.js
    ├── click.js
    ├── type.js
    ├── screenshot.js
    ├── getText.js
    ├── getLinks.js
    ├── getButtons.js
    ├── getForms.js
    ├── extractElements.js
    ├── waitForSelector.js
    ├── smartClick.js
    ├── smartType.js
    ├── fillFormAuto.js
    ├── smartWaitNavigation.js
    ├── agentFlow.js
    ├── agentFlowV2.js
    └── closeBrowser.js
```

## Comportamento

- **Reuso de abas:** mesmo domínio reutiliza aba, domínios diferentes abrem nova aba
- **Headed mode:** navegador abre visível. Para headless, edite `browser.js` e mude `headless: true`
- **Singleton:** uma única instância do navegador compartilhada entre todas as tools

## Solução de problemas

| Problema | Solução |
|----------|---------|
| Tools não aparecem | Reiniciar a IDE após configurar MCP |
| `node: not found` | Instalar Node.js 18+ e adicionar ao PATH |
| Chromium não encontrado | `npx playwright install chromium` |
| Erro de permissão (Linux) | `sudo npx playwright install-deps chromium` |
| Caminho com espaços | Usar aspas no caminho |

## Caminhos por SO

| Sistema | Exemplo |
|---------|---------|
| Windows | `C:/Users/seuuser/mcp-browser/server.js` |
| macOS | `/Users/seuuser/mcp-browser/server.js` |
| Linux | `/home/seuuser/mcp-browser/server.js` |

> **Importante:** Nunca usar `\` simples. Sempre `/` ou `\\`.

## Licença

MIT