255 lines
6.0 KiB
Markdown
255 lines
6.0 KiB
Markdown
# opencode-mcp-browser
|
|
|
|
MCP server que permite a qualquer agente de IA controlar um navegador real usando [Playwright](https://playwright.dev/).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 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
|
|
|
|
```
|
|
opencode-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
|