# opencode-mcp-browser

MCP server que permite a qualquer agente de IA controlar um navegador real via Playwright. 17 tools Windows / Linux / macOS

## Pré-requisitos

Dependência | Versão mínima | Verificar
--- | --- | ---
Node.js | 18+ | `node -v`
npm | 9+ | `npm -v`
Playwright | 1.50+ | `npx playwright --version`

## Instalação

### 1. Clonar ou copiar o projeto

    # Opção A — git clone
    git clone https://github.com/seu-usuario/opencode-mcp-browser.git
    cd opencode-mcp-browser

    # Opção B — copiar a pasta manualmente para qualquer diretório

### 2. Instalar dependências

    npm install

### 3. Instalar navegadores do Playwright

    npx playwright install chromium

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

### 4. Testar se funciona

    node server.js

O servidor inicia e aguarda conexão via stdin/stdout (MCP stdio transport). Não aparece nada no terminal — isso é normal.

## Estrutura do projeto

    opencode-mcp-browser/
    ├── server.js              ← servidor MCP (entry point)
    ├── browser.js             ← engine Playwright (singleton)
    ├── package.json
    ├── package-lock.json
    ├── docs.html              ← esta documentação
    ├── node_modules/
    └── tools/
        ├── openUrl.js         ← abre URL (reusa aba se mesmo domínio)
        ├── click.js           ← clica por seletor CSS
        ├── type.js            ← digita texto em campo
        ├── screenshot.js      ← captura screenshot
        ├── getText.js         ← extrai texto da página
        ├── getLinks.js        ← lista todos os links
        ├── getButtons.js      ← lista botões disponíveis
        ├── getForms.js        ← lista formulários e campos
        ├── extractElements.js ← extrai elementos com atributos
        ├── waitForSelector.js ← espera elemento aparecer
        ├── smartClick.js      ← clica por texto visível
        ├── smartType.js       ← digita por label/placeholder
        ├── fillFormAuto.js    ← preenche formulário automaticamente
        ├── smartWaitNavigation.js ← espera navegação
        ├── agentFlow.js       ← fluxo automático simples
        ├── agentFlowV2.js     ← fluxo com retry e fallback
        └── closeBrowser.js    ← fecha o navegador

## Configuração por plataforma

### OpenCode

1. Abra o terminal e execute:
   `opencode mcp add`
2. Preencha os campos:
   - Nome: `meu-navegador`
   - Tipo: `Local`
   - Comando: `node /caminho/absoluto/opencode-mcp-browser/server.js`
3. Reinicie o OpenCode.
4. Verifique: `opencode mcp list`

### Cursor

1. Abra Settings → MCP (ou `.cursor/mcp.json` no projeto).
2. Adicione ao arquivo `~/.cursor/mcp.json` (global) ou `.cursor/mcp.json` (projeto):

    {
      "mcpServers": {
        "browser": {
          "command": "node",
          "args": ["/caminho/absoluto/opencode-mcp-browser/server.js"]
        }
      }
    }

3. Reinicie o Cursor. As tools aparecerão no chat do Composer.

### Claude Desktop

1. Abra o arquivo de configuração:
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Linux: `~/.config/Claude/claude_desktop_config.json`
2. Adicione:

    {
      "mcpServers": {
        "browser": {
          "command": "node",
          "args": ["/caminho/absoluto/opencode-mcp-browser/server.js"]
        }
      }
    }

3. Reinicie o Claude Desktop.

### Windsurf (Codeium)

1. Abra Settings → Cascade → MCP Servers.
2. Ou edite `~/.windsurf/mcp.json`:

    {
      "mcpServers": {
        "browser": {
          "command": "node",
          "args": ["/caminho/absoluto/opencode-mcp-browser/server.js"]
        }
      }
    }

3. Reinicie o Windsurf.

### Trae

1. Abra Settings → Extensions → MCP.
2. Adicione server manualmente:
   - Name: `browser`
   - Command: `node`
   - Args: `["/caminho/absoluto/opencode-mcp-browser/server.js"]`
3. Ou edite o arquivo de configuração do Trae equivalente ao `mcp.json`.

### Antigravity

1. Abra a configuração de MCP do Antigravity.
2. Adicione um novo server com:
   - Name: `browser`
   - Type: `stdio`
   - Command: `node /caminho/absoluto/opencode-mcp-browser/server.js`
3. Salve e reinicie.

### VS Code (com extensão MCP)

1. Instale a extensão MCP no VS Code.
2. Abra `.vscode/mcp.json` no workspace ou `settings.json` global.
3. Adicione:

    {
      "mcpServers": {
        "browser": {
          "command": "node",
          "args": ["/caminho/absoluto/opencode-mcp-browser/server.js"]
        }
      }
    }

### Qualquer outra plataforma MCP

Se a plataforma suporta MCP stdio transport, use:

    Comando:   node
    Argumento: /caminho/absoluto/opencode-mcp-browser/server.js
    Transport: stdio

O servidor comunica via stdin/stdout — não precisa porta, não precisa daemon.

## Caminhos por sistema operacional

Sistema | Formato do caminho | Exemplo
--- | --- | ---
Windows | Use `/` ou `\\` | `C:/Users/seuuser/mcp-browser/server.js`
macOS | Unix path | `/Users/seuuser/mcp-browser/server.js`
Linux | Unix path | `/home/seuuser/mcp-browser/server.js`

Importante: Nunca use `\` simples nos caminhos. Sempre `/` ou `\\`.

## Lista de tools (17)

# | Tool | Descrição | Parâmetros
--- | --- | --- | ---
1 | `open_url` | Abre uma URL no navegador | `url` (string, obrigatório)
2 | `click` | Clica em elemento por seletor CSS | `selector` (string, obrigatório)
3 | `type` | Digita texto em um campo | `selector`, `text`
4 | `screenshot` | Captura screenshot da página | `fullPage` (bool, opcional)
5 | `get_text` | Extrai texto da página | `selector` (opcional, padrão: body)
6 | `get_links` | Lista todos os links | `selector` (opcional, padrão: a)
7 | `wait_for_selector` | Espera elemento aparecer no DOM | `selector`, `timeout`
8 | `extract_elements` | Extrai elementos com atributos | `selector`, `attributes` (array)
9 | `smart_click` | Clica pelo texto visível | `text` (string, obrigatório)
10 | `smart_type` | Digita buscando 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 seus campos | —
14 | `fill_form_auto` | Preenche formulário automaticamente | `data` (objeto, obrigatório)
15 | `agent_flow` | Fluxo automático simples | `goal`, `data` (opcional)
16 | `agent_flow_v2` | Fluxo com retry e 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()
    get_text()

### Scraping com atributos

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

### Preencher formulário complexo

    open_url("https://site.com/contato")
    smart_type("nome", "João Silva")
    type("#email", "joao@email.com")
    smart_type("mensagem", "Olá, quero mais informações")
    smart_click("Enviar")

## Comportamento do navegador

- Reuso de abas: Se o navegador já estiver aberto e você abrir uma URL do mesmo domínio, a aba atual é reutilizada. Domínios diferentes abrem em nova aba.
- Singleton: Apenas uma instância do navegador é mantida. Todas as tools compartilham a mesma página ativa.
- Headed mode: O navegador abre visível (não headless). Para headless, edite `browser.js` e mude `headless: true`.
- Auto-close: Use `close_browser` quando terminar. O navegador não fecha sozinho.

## Problemas comuns

Problema | Solução
--- | ---
Tools não aparecem na plataforma | Reiniciar a IDE/plataforma após configurar o MCP.
`node: command not found` | Instalar Node.js 18+ e garantir que está no PATH.
Playwright não encontra Chromium | `npx playwright install chromium`
Erro de permissão no Linux | `sudo npx playwright install-deps chromium`
Página não carrega (conteúdo vazio) | O servidor aguarda `domcontentloaded` + 1.5s. Se a página usa JS pesado, aumente o timeout em `browser.js`.
Erro `ECONNREFUSED` | O servidor MCP usa stdio (stdin/stdout), não HTTP. Verifique se o comando está correto.
Caminho com espaços no Windows | Use aspas: `"C:/Users/Meu Usuario/mcp/server.js"`

## Licença

MIT — uso livre.