445 lines
15 KiB
HTML
445 lines
15 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="pt-BR">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>MCP-Browser — Documentação</title>
|
|
<style>
|
|
:root {
|
|
--bg: #0f172a;
|
|
--bg2: #1e293b;
|
|
--bg3: #334155;
|
|
--accent: #38bdf8;
|
|
--green: #22c55e;
|
|
--yellow: #eab308;
|
|
--red: #ef4444;
|
|
--text: #e2e8f0;
|
|
--text2: #94a3b8;
|
|
}
|
|
* { box-sizing: border-box; margin: 0; padding: 0; }
|
|
body {
|
|
font-family: 'Segoe UI', system-ui, -apple-system, sans-serif;
|
|
max-width: 960px;
|
|
margin: 0 auto;
|
|
padding: 40px 20px;
|
|
background: var(--bg);
|
|
color: var(--text);
|
|
line-height: 1.7;
|
|
}
|
|
h1 { color: var(--accent); font-size: 2em; margin-bottom: 8px; }
|
|
h2 { color: var(--accent); font-size: 1.4em; margin-bottom: 12px; border-bottom: 1px solid var(--bg3); padding-bottom: 8px; }
|
|
h3 { color: var(--green); font-size: 1.1em; margin: 16px 0 8px; }
|
|
a { color: var(--accent); text-decoration: none; }
|
|
a:hover { text-decoration: underline; }
|
|
pre {
|
|
background: var(--bg2);
|
|
padding: 16px;
|
|
border-radius: 8px;
|
|
overflow-x: auto;
|
|
margin: 10px 0 16px;
|
|
font-size: 0.9em;
|
|
border-left: 3px solid var(--accent);
|
|
}
|
|
code { color: var(--green); font-family: 'Cascadia Code', 'Fira Code', monospace; }
|
|
.box {
|
|
background: var(--bg2);
|
|
padding: 24px;
|
|
border-radius: 10px;
|
|
margin-bottom: 20px;
|
|
}
|
|
.warn {
|
|
background: #422006;
|
|
border-left: 3px solid var(--yellow);
|
|
padding: 14px 18px;
|
|
border-radius: 6px;
|
|
margin: 12px 0;
|
|
}
|
|
.ok {
|
|
background: #052e16;
|
|
border-left: 3px solid var(--green);
|
|
padding: 14px 18px;
|
|
border-radius: 6px;
|
|
margin: 12px 0;
|
|
}
|
|
table {
|
|
width: 100%;
|
|
border-collapse: collapse;
|
|
margin: 12px 0;
|
|
}
|
|
th, td {
|
|
text-align: left;
|
|
padding: 10px 14px;
|
|
border-bottom: 1px solid var(--bg3);
|
|
}
|
|
th { color: var(--accent); font-weight: 600; }
|
|
.badge {
|
|
display: inline-block;
|
|
padding: 2px 10px;
|
|
border-radius: 12px;
|
|
font-size: 0.8em;
|
|
font-weight: 600;
|
|
}
|
|
.badge-green { background: #166534; color: #86efac; }
|
|
.badge-blue { background: #1e3a5f; color: #7dd3fc; }
|
|
ol li, ul li { margin-bottom: 6px; }
|
|
.platform { margin-bottom: 24px; }
|
|
.tab-icon { margin-right: 6px; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<h1>MCP-Browser</h1>
|
|
<p style="color: var(--text2); margin-bottom: 30px;">
|
|
MCP server que permite a qualquer agente de IA controlar um navegador real via Playwright.
|
|
<span class="badge badge-green">17 tools</span>
|
|
<span class="badge badge-blue">Windows / Linux / macOS</span>
|
|
</p>
|
|
|
|
<!-- ============================================ -->
|
|
<div class="box">
|
|
<h2>Pré-requisitos</h2>
|
|
|
|
<table>
|
|
<tr><th>Dependência</th><th>Versão mínima</th><th>Verificar</th></tr>
|
|
<tr><td>Node.js</td><td>18+</td><td><code>node -v</code></td></tr>
|
|
<tr><td>npm</td><td>9+</td><td><code>npm -v</code></td></tr>
|
|
<tr><td>Playwright</td><td>1.50+</td><td><code>npx playwright --version</code></td></tr>
|
|
</table>
|
|
</div>
|
|
|
|
<!-- ============================================ -->
|
|
<div class="box">
|
|
<h2>Instalação</h2>
|
|
|
|
<h3>1. Clonar ou copiar o projeto</h3>
|
|
<pre><code># Opção A — git clone
|
|
git clone https://git.jf.eng.br/jfeng/MCP-Browser.git
|
|
cd MCP-Browser
|
|
|
|
# Opção B — copiar a pasta manualmente para qualquer diretório</code></pre>
|
|
|
|
<h3>2. Instalar dependências</h3>
|
|
<pre><code>npm install</code></pre>
|
|
|
|
<h3>3. Instalar navegadores do Playwright</h3>
|
|
<pre><code>npx playwright install chromium</code></pre>
|
|
|
|
<div class="warn">
|
|
<strong>Linux:</strong> Pode precisar instalar dependências do sistema:<br>
|
|
<code>sudo npx playwright install-deps chromium</code>
|
|
</div>
|
|
|
|
<h3>4. Testar se funciona</h3>
|
|
<pre><code>node server.js</code></pre>
|
|
<p>O servidor inicia e aguarda conexão via stdin/stdout (MCP stdio transport). Não aparece nada no terminal — isso é normal.</p>
|
|
</div>
|
|
|
|
<!-- ============================================ -->
|
|
<div class="box">
|
|
<h2>Estrutura do projeto</h2>
|
|
<pre><code>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</code></pre>
|
|
</div>
|
|
|
|
<!-- ============================================ -->
|
|
<div class="box">
|
|
<h2>Configuração por plataforma</h2>
|
|
|
|
<!-- OPENCODE -->
|
|
<div class="platform">
|
|
<h3>OpenCode</h3>
|
|
<ol>
|
|
<li>Abra o terminal e execute:<br>
|
|
<code>opencode mcp add</code>
|
|
</li>
|
|
<li>Preencha os campos:
|
|
<ul>
|
|
<li><strong>Nome:</strong> <code>meu-navegador</code></li>
|
|
<li><strong>Tipo:</strong> <code>Local</code></li>
|
|
<li><strong>Comando:</strong> <code>node /caminho/absoluto/MCP-Browser/server.js</code></li>
|
|
</ul>
|
|
</li>
|
|
<li>Reinicie o OpenCode.</li>
|
|
<li>Verifique: <code>opencode mcp list</code></li>
|
|
</ol>
|
|
</div>
|
|
|
|
<!-- CURSOR -->
|
|
<div class="platform">
|
|
<h3>Cursor</h3>
|
|
<ol>
|
|
<li>Abra <strong>Settings → MCP</strong> (ou <code>.cursor/mcp.json</code> no projeto).</li>
|
|
<li>Adicione ao arquivo <code>~/.cursor/mcp.json</code> (global) ou <code>.cursor/mcp.json</code> (projeto):</li>
|
|
</ol>
|
|
<pre><code>{
|
|
"mcpServers": {
|
|
"browser": {
|
|
"command": "node",
|
|
"args": ["/caminho/absoluto/MCP-Browser/server.js"]
|
|
}
|
|
}
|
|
}</code></pre>
|
|
<ol start="3">
|
|
<li>Reinicie o Cursor. As tools aparecerão no chat do Composer.</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<!-- CLAUDE DESKTOP -->
|
|
<div class="platform">
|
|
<h3>Claude Desktop</h3>
|
|
<ol>
|
|
<li>Abra o arquivo de configuração:
|
|
<ul>
|
|
<li><strong>Windows:</strong> <code>%APPDATA%\Claude\claude_desktop_config.json</code></li>
|
|
<li><strong>macOS:</strong> <code>~/Library/Application Support/Claude/claude_desktop_config.json</code></li>
|
|
<li><strong>Linux:</strong> <code>~/.config/Claude/claude_desktop_config.json</code></li>
|
|
</ul>
|
|
</li>
|
|
<li>Adicione:</li>
|
|
</ol>
|
|
<pre><code>{
|
|
"mcpServers": {
|
|
"browser": {
|
|
"command": "node",
|
|
"args": ["/caminho/absoluto/MCP-Browser/server.js"]
|
|
}
|
|
}
|
|
}</code></pre>
|
|
<ol start="3">
|
|
<li>Reinicie o Claude Desktop.</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<!-- WINDSURF -->
|
|
<div class="platform">
|
|
<h3>Windsurf (Codeium)</h3>
|
|
<ol>
|
|
<li>Abra <strong>Settings → Cascade → MCP Servers</strong>.</li>
|
|
<li>Ou edite <code>~/.windsurf/mcp.json</code>:</li>
|
|
</ol>
|
|
<pre><code>{
|
|
"mcpServers": {
|
|
"browser": {
|
|
"command": "node",
|
|
"args": ["/caminho/absoluto/MCP-Browser/server.js"]
|
|
}
|
|
}
|
|
}</code></pre>
|
|
<ol start="3">
|
|
<li>Reinicie o Windsurf.</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<!-- TRAE -->
|
|
<div class="platform">
|
|
<h3>Trae</h3>
|
|
<ol>
|
|
<li>Abra <strong>Settings → Extensions → MCP</strong>.</li>
|
|
<li>Adicione server manualmente:
|
|
<ul>
|
|
<li><strong>Name:</strong> <code>browser</code></li>
|
|
<li><strong>Command:</strong> <code>node</code></li>
|
|
<li><strong>Args:</strong> <code>["/caminho/absoluto/MCP-Browser/server.js"]</code></li>
|
|
</ul>
|
|
</li>
|
|
<li>Ou edite o arquivo de configuração do Trae equivalente ao <code>mcp.json</code>.</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<!-- ANTIGRAVITY -->
|
|
<div class="platform">
|
|
<h3>Antigravity</h3>
|
|
<ol>
|
|
<li>Abra a configuração de MCP do Antigravity.</li>
|
|
<li>Adicione um novo server com:
|
|
<ul>
|
|
<li><strong>Name:</strong> <code>browser</code></li>
|
|
<li><strong>Type:</strong> <code>stdio</code></li>
|
|
<li><strong>Command:</strong> <code>node /caminho/absoluto/MCP-Browser/server.js</code></li>
|
|
</ul>
|
|
</li>
|
|
<li>Salve e reinicie.</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<!-- VS CODE -->
|
|
<div class="platform">
|
|
<h3>VS Code (com extensão MCP)</h3>
|
|
<ol>
|
|
<li>Instale a extensão <strong>MCP</strong> no VS Code.</li>
|
|
<li>Abra <code>.vscode/mcp.json</code> no workspace ou <code>settings.json</code> global.</li>
|
|
<li>Adicione:</li>
|
|
</ol>
|
|
<pre><code>{
|
|
"mcpServers": {
|
|
"browser": {
|
|
"command": "node",
|
|
"args": ["/caminho/absoluto/MCP-Browser/server.js"]
|
|
}
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
|
|
<!-- GENERIC -->
|
|
<div class="platform">
|
|
<h3>Qualquer outra plataforma MCP</h3>
|
|
<p>Se a plataforma suporta <strong>MCP stdio transport</strong>, use:</p>
|
|
<pre><code>Comando: node
|
|
Argumento: /caminho/absoluto/MCP-Browser/server.js
|
|
Transport: stdio</code></pre>
|
|
<p>O servidor comunica via <strong>stdin/stdout</strong> — não precisa porta, não precisa daemon.</p>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<!-- ============================================ -->
|
|
<div class="box">
|
|
<h2>Caminhos por sistema operacional</h2>
|
|
|
|
<table>
|
|
<tr><th>Sistema</th><th>Formato do caminho</th><th>Exemplo</th></tr>
|
|
<tr><td>Windows</td><td>Use <code>/</code> ou <code>\\</code></td><td><code>C:/Users/seuuser/mcp-browser/server.js</code></td></tr>
|
|
<tr><td>macOS</td><td>Unix path</td><td><code>/Users/seuuser/mcp-browser/server.js</code></td></tr>
|
|
<tr><td>Linux</td><td>Unix path</td><td><code>/home/seuuser/mcp-browser/server.js</code></td></tr>
|
|
</table>
|
|
|
|
<div class="warn">
|
|
<strong>Importante:</strong> Nunca use <code>\</code> simples nos caminhos. Sempre <code>/</code> ou <code>\\</code>.
|
|
</div>
|
|
</div>
|
|
|
|
<!-- ============================================ -->
|
|
<div class="box">
|
|
<h2>Lista de tools (17)</h2>
|
|
|
|
<table>
|
|
<tr><th>#</th><th>Tool</th><th>Descrição</th><th>Parâmetros</th></tr>
|
|
<tr><td>1</td><td><code>open_url</code></td><td>Abre uma URL no navegador</td><td><code>url</code> (string, obrigatório)</td></tr>
|
|
<tr><td>2</td><td><code>click</code></td><td>Clica em elemento por seletor CSS</td><td><code>selector</code> (string, obrigatório)</td></tr>
|
|
<tr><td>3</td><td><code>type</code></td><td>Digita texto em um campo</td><td><code>selector</code>, <code>text</code></td></tr>
|
|
<tr><td>4</td><td><code>screenshot</code></td><td>Captura screenshot da página</td><td><code>fullPage</code> (bool, opcional)</td></tr>
|
|
<tr><td>5</td><td><code>get_text</code></td><td>Extrai texto da página</td><td><code>selector</code> (opcional, padrão: body)</td></tr>
|
|
<tr><td>6</td><td><code>get_links</code></td><td>Lista todos os links</td><td><code>selector</code> (opcional, padrão: a)</td></tr>
|
|
<tr><td>7</td><td><code>wait_for_selector</code></td><td>Espera elemento aparecer no DOM</td><td><code>selector</code>, <code>timeout</code></td></tr>
|
|
<tr><td>8</td><td><code>extract_elements</code></td><td>Extrai elementos com atributos</td><td><code>selector</code>, <code>attributes</code> (array)</td></tr>
|
|
<tr><td>9</td><td><code>smart_click</code></td><td>Clica pelo texto visível</td><td><code>text</code> (string, obrigatório)</td></tr>
|
|
<tr><td>10</td><td><code>smart_type</code></td><td>Digita buscando por label/placeholder</td><td><code>label</code>, <code>text</code></td></tr>
|
|
<tr><td>11</td><td><code>get_buttons</code></td><td>Lista botões disponíveis</td><td>—</td></tr>
|
|
<tr><td>12</td><td><code>smart_wait_navigation</code></td><td>Espera mudança de URL</td><td><code>timeout</code> (opcional)</td></tr>
|
|
<tr><td>13</td><td><code>get_forms</code></td><td>Lista formulários e seus campos</td><td>—</td></tr>
|
|
<tr><td>14</td><td><code>fill_form_auto</code></td><td>Preenche formulário automaticamente</td><td><code>data</code> (objeto, obrigatório)</td></tr>
|
|
<tr><td>15</td><td><code>agent_flow</code></td><td>Fluxo automático simples</td><td><code>goal</code>, <code>data</code> (opcional)</td></tr>
|
|
<tr><td>16</td><td><code>agent_flow_v2</code></td><td>Fluxo com retry e fallback</td><td><code>goal</code>, <code>data</code>, <code>retries</code></td></tr>
|
|
<tr><td>17</td><td><code>close_browser</code></td><td>Fecha o navegador</td><td>—</td></tr>
|
|
</table>
|
|
</div>
|
|
|
|
<!-- ============================================ -->
|
|
<div class="box">
|
|
<h2>Exemplos de uso</h2>
|
|
|
|
<h3>Abrir site e extrair conteúdo</h3>
|
|
<pre><code>open_url("https://example.com")
|
|
get_text()
|
|
get_links()
|
|
screenshot()</code></pre>
|
|
|
|
<h3>Login automático</h3>
|
|
<pre><code>open_url("https://site.com/login")
|
|
fill_form_auto({"email": "user@test.com", "password": "1234"})
|
|
smart_click("Entrar")
|
|
smart_wait_navigation()
|
|
get_text()</code></pre>
|
|
|
|
<h3>Scraping com atributos</h3>
|
|
<pre><code>open_url("https://site.com/produtos")
|
|
extract_elements(".produto", ["href", "data-id", "class"])</code></pre>
|
|
|
|
<h3>Preencher formulário complexo</h3>
|
|
<pre><code>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")</code></pre>
|
|
</div>
|
|
|
|
<!-- ============================================ -->
|
|
<div class="box">
|
|
<h2>Comportamento do navegador</h2>
|
|
<ul>
|
|
<li><strong>Reuso de abas:</strong> Se o navegador já estiver aberto e você abrir uma URL do <strong>mesmo domínio</strong>, a aba atual é reutilizada. Domínios diferentes abrem em <strong>nova aba</strong>.</li>
|
|
<li><strong>Singleton:</strong> Apenas uma instância do navegador é mantida. Todas as tools compartilham a mesma página ativa.</li>
|
|
<li><strong>Headed mode:</strong> O navegador abre visível (não headless). Para headless, edite <code>browser.js</code> e mude <code>headless: true</code>.</li>
|
|
<li><strong>Auto-close:</strong> Use <code>close_browser</code> quando terminar. O navegador não fecha sozinho.</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<!-- ============================================ -->
|
|
<div class="box">
|
|
<h2>Problemas comuns</h2>
|
|
|
|
<table>
|
|
<tr><th>Problema</th><th>Solução</th></tr>
|
|
<tr>
|
|
<td>Tools não aparecem na plataforma</td>
|
|
<td>Reiniciar a IDE/plataforma após configurar o MCP.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>node: command not found</code></td>
|
|
<td>Instalar Node.js 18+ e garantir que está no PATH.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Playwright não encontra Chromium</td>
|
|
<td><code>npx playwright install chromium</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Erro de permissão no Linux</td>
|
|
<td><code>sudo npx playwright install-deps chromium</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Página não carrega (conteúdo vazio)</td>
|
|
<td>O servidor aguarda <code>domcontentloaded</code> + 1.5s. Se a página usa JS pesado, aumente o timeout em <code>browser.js</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Erro <code>ECONNREFUSED</code></td>
|
|
<td>O servidor MCP usa stdio (stdin/stdout), não HTTP. Verifique se o comando está correto.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Caminho com espaços no Windows</td>
|
|
<td>Use aspas: <code>"C:/Users/Meu Usuario/mcp/server.js"</code></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
<!-- ============================================ -->
|
|
<div class="box">
|
|
<h2>Licença</h2>
|
|
<p>MIT — uso livre.</p>
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|