feat: MCP Browser v3.0 - 42 tools with stealth mode, multi-tab, PDF, cookies, storage, network logs, device emulation

2026-03-27 11:58:52 -03:00
parent c1d716bb84
commit 13f7392555
48 changed files with 1269 additions and 714 deletions
@@ -1,254 +1,198 @@
-# MCP-Browser
+# MCP-Browser v3.0.0

-MCP server que permite a qualquer agente de IA controlar um navegador real usando [Playwright](https://playwright.dev/).
+MCP server para automação de navegador de alta qualidade usando [Playwright](https://playwright.dev/) com **42 tools** para automação avançada.

 ![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)
+![Tools](https://img.shields.io/badge/42%20tools-green)

-## Funcionalidades
+## Novidades v3.0

- 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+            |
+- **Stealth Mode** - Anti-detecção avançada
+- **25 novas tools** - Muito mais poder
+- **Multi-Tab real** - Gerenciamento completo
+- **PDF generation** - Geração de PDFs
+- **Network Monitoring** - Logs de rede
+- **Device Emulation** - iPhone, Pixel, etc
+- **Performance Metrics** - Métricas detalhadas

 ## 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
+## Configuração

 ```bash
-opencode mcp add
+node server.js
 ```

- **Nome:** `meu-navegador`
- **Tipo:** `Local`
- **Comando:** `node /caminho/MCP-Browser/server.js`
+## Tools Disponíveis (42)

-### Cursor
+### Navegação
+| Tool | Descrição |
+|------|-----------|
+| `open_url` | Abre URL |
+| `new_tab` | Nova aba |
+| `switch_tab` | Troca aba |
+| `list_tabs` | Lista abas |
+| `close_tab` | Fecha aba |
+| `go_back` | Voltar |
+| `go_forward` | Avançar |
+| `reload` | Recarregar |
+| `wait_for_url` | Espera URL |

-`~/.cursor/mcp.json` (global) ou `.cursor/mcp.json` (projeto):
+### Interação
+| Tool | Descrição |
+|------|-----------|
+| `click` | Clica (suporta duplo, right-click) |
+| `smart_click` | Clica por texto |
+| `type` | Digita (suporta lentamente) |
+| `smart_type` | Digita por label |
+| `hover` | Faz hover |
+| `select` | Seleciona opção |
+| `press_key` | Pressiona tecla |
+| `scroll_to` | Rola página |
+| `upload_file` | Upload de arquivo |

-```json
-{
-  "mcpServers": {
-    "browser": {
-      "command": "node",
-      "args": ["/caminho/MCP-Browser/server.js"]
-    }
-  }
-}
-```
+### Extração
+| Tool | Descrição |
+|------|-----------|
+| `get_text` | Extrai texto |
+| `get_html` | Extrai HTML |
+| `get_links` | Lista links |
+| `get_buttons` | Lista botões |
+| `get_forms` | Lista formulários |
+| `extract_elements` | Extrai elementos |
+| `get_url` | URL atual |
+| `get_title` | Título da página |
+| `evaluate_js` | Executa JavaScript |

-### Claude Desktop
+### Screens & PDF
+| Tool | Descrição |
+|------|-----------|
+| `screenshot` | Screenshot (full/elemento) |
+| `pdf` | Gera PDF |

-`%APPDATA%\Claude\claude_desktop_config.json` (Windows)
-`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+### Viewport & Device
+| Tool | Descrição |
+|------|-----------|
+| `set_viewport` | Define viewport |
+| `emulate_device` | Emula dispositivo |

-```json
-{
-  "mcpServers": {
-    "browser": {
-      "command": "node",
-      "args": ["/caminho/MCP-Browser/server.js"]
-    }
-  }
-}
-```
+### Cookies & Storage
+| Tool | Descrição |
+|------|-----------|
+| `get_cookies` | Obtém cookies |
+| `set_cookies` | Define cookies |
+| `clear_cookies` | Limpa cookies |
+| `get_storage` | Obtém storage |
+| `set_storage` | Define storage |
+| `clear_storage` | Limpa storage |

-### Windsurf
+### Network
+| Tool | Descrição |
+|------|-----------|
+| `get_network_logs` | Logs de rede |
+| `block_resources` | Bloqueia recursos |

-`~/.windsurf/mcp.json`:
+### Performance
+| Tool | Descrição |
+|------|-----------|
+| `get_performance_metrics` | Métricas |

-```json
-{
-  "mcpServers": {
-    "browser": {
-      "command": "node",
-      "args": ["/caminho/MCP-Browser/server.js"]
-    }
-  }
-}
-```
+### Wait
+| Tool | Descrição |
+|------|-----------|
+| `wait` | Aguarda ms |
+| `wait_for_selector` | Espera elemento |

-### Trae
+### Automação
+| Tool | Descrição |
+|------|-----------|
+| `fill_form_auto` | Preenche formulário |
+| `agent_flow` | Fluxo automático |
+| `agent_flow_v2` | Fluxo com retry |

-Settings → Extensions → MCP → Adicionar server:
+### Controle
+| Tool | Descrição |
+|------|-----------|
+| `close_browser` | Fecha navegador |

- **Name:** `browser`
- **Command:** `node`
- **Args:** `["/caminho/MCP-Browser/server.js"]`
+## Exemplo de Uso

-### 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
-
-```
+```javascript
+// Abrir site
 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"})
+// Login automático
+fill_form_auto({"email": "user@test.com", "password": "123"})
 smart_click("Entrar")
-smart_wait_navigation()
+wait_for_url("**dashboard**")
+
+// Extrair dados
+get_links()
+get_text(".product-title")
+
+// Screenshot
+screenshot({fullPage: true})
+
+// Emular mobile
+emulate_device("iphone-14")
 ```

-### Scraping com atributos
+## Dispositivos Disponíveis

-```
-open_url("https://site.com/produtos")
-extract_elements(".produto", ["href", "data-id"])
-```
+- iphone-se, iphone-14, iphone-14-pro-max
+- ipad, ipad-pro
+- pixel-5, galaxy-s20, galaxy-s23-ultra
+- desktop-1080p, desktop-4k

-## Estrutura do projeto
+## Estrutura

 ```
 MCP-Browser/
-├── server.js              # Servidor MCP (entry point)
-├── browser.js             # Engine Playwright (singleton)
+├── server.js           # Servidor MCP
+├── browser.js          # Engine Playwright
 ├── package.json
-├── docs.html              # Documentação detalhada
-└── tools/
+└── tools/              # 42 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
+    ├── getURL.js
+    ├── getTitle.js
+    ├── getHTML.js
+    ├── goBack.js
+    ├── goForward.js
+    ├── reload.js
+    ├── evaluateJS.js
+    ├── waitForURL.js
+    ├── newTab.js
+    ├── switchTab.js
+    ├── listTabs.js
+    ├── closeTab.js
+    ├── setViewport.js
+    ├── emulateDevice.js
+    ├── hover.js
+    ├── select.js
+    ├── pressKey.js
+    ├── scrollTo.js
+    ├── pdf.js
+    ├── getCookies.js
+    ├── setCookies.js
+    ├── clearCookies.js
+    ├── getStorage.js
+    ├── setStorage.js
+    ├── clearStorage.js
+    ├── getNetworkLogs.js
+    ├── blockResources.js
+    ├── uploadFile.js
+    ├── getPerformanceMetrics.js
+    └── wait.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