feat: MCP Browser - servidor MCP para automação de navegador com Playwright
This commit is contained in:
@@ -0,0 +1,254 @@
|
||||
# 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
|
||||
|
||||
```
|
||||
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
|
||||
Reference in New Issue
Block a user