pilot-mcp

pilot — automação de navegador MCP para agentes de IA

Sessões de navegador nativas com suporte a Playwright por padrão. Nenhuma extensão do Chrome necessária para automação de QA.

Pilot tem dois backends de navegador:

• Modo nativo (padrão): contextos de navegador Playwright isolados. Este é o caminho suportado para automação de QA paralela e capturas de tela confiáveis.
• Modo de extensão (legado/opt-in): conecta-se ao seu perfil real do Chrome quando você precisa de cookies existentes e sessões logadas.

O modo nativo evita chrome.tabs.captureVisibleTab() completamente, então as capturas de tela não dependem do Chrome estar em primeiro plano, de uma aba estar visivelmente ativa ou do service worker da extensão estar atualizado.

---

Como funciona

AI Agent → MCP Server → Broker on 127.0.0.1:3131 → Native browser session
         (stdio)       (first process owns broker)  (Playwright context/page)

1. O Pilot roda como um servidor MCP — Claude Code, Cursor ou qualquer cliente MCP conecta via stdio
2. O primeiro processo do Pilot se torna o broker no localhost
3. Processos Pilot posteriores conectam-se como clientes do broker
4. Cada sessão obtém um contexto/página de navegador nativo isolado
5. As capturas de tela vêm do Playwright, não da API de captura da extensão do Chrome

---

Início Rápido

1. Adicione o servidor MCP

codex mcp add pilot \
  --env PILOT_BROWSER_MODE=native \
  --env PILOT_PROFILE=full \
  -- npx -y pilot-mcp

Para um checkout local:

npm install
npm run build
codex mcp add pilot \
  --env PILOT_BROWSER_MODE=native \
  --env PILOT_PROFILE=full \
  -- node /absolute/path/to/pilot/dist/index.js

2. Use-o

"Abra https://example.com,, tire uma captura de tela e resuma a página."

Sem instalação de extensão. Sem requisito de Chrome em primeiro plano.

Para operações completas do modo nativo, comandos de estresse e verificações de limpeza, veja docs/native-mode.md.

---

Snapshots enxutos

Outras ferramentas despejam 50K+ caracteres por página na sua janela de contexto. O Pilot mantém as coisas pequenas:

Other tools:   navigate(58K) → navigate(58K) → answer        = 116K chars
Pilot:         navigate(2K)  → navigate(2K)  → snapshot(9K)  =  13K chars

snapshot_diff mostra apenas o que mudou entre ações — sem re-leituras redundantes.

Menos contexto = respostas mais rápidas, chamadas de API mais baratas, menos alucinações.

---

Pilot vs @playwright/mcp

	Pilot	@playwright/mcp
Navegador	Contexto Playwright nativo por padrão; Chrome real via extensão legada	Nova instância do Chromium
Estado de autenticação	Nativo isolado por padrão; modo de extensão pode usar cookies reais do Chrome	Anônimo — configuração manual
Detecção de bot	Nativo para automação; modo de extensão para transferência de perfil real	Bloqueado pelo Cloudflare
Tamanho do snapshot	~2K navegação, ~9K completo	~50-60K
Diff de snapshot	pilot_snapshot_diff	❌
Importação de cookies	Chrome, Arc, Brave, Edge, Comet	JSON manual
Iframes	✅	❌
Perfis de ferramentas	core (9) / standard (40) / full (69)	--caps grupos
Transporte	stdio	stdio, HTTP, SSE

---

69 ferramentas em 3 perfis

LLMs degradam conforme as listas de ferramentas crescem. Carregue apenas o que você precisa:

Perfil	Ferramentas	O que está incluído
core	9	navigate, snapshot, click, fill, type, press_key, wait, screenshot, snapshot_diff
standard	40	Núcleo + pilot_act, pilot_guide, evidence, doctor/reset, tabs, scroll, hover, drag, iframes, auth, block, find
full	69	Padrão + interceptação de rede, asserções, área de transferência, geolocalização, CDP, evaluate, PDF, responsivo, inspeção profunda

{
  "mcpServers": {
    "pilot": {
      "command": "npx",
      "args": ["-y", "pilot-mcp"],
      "env": { "PILOT_PROFILE": "standard" }
    }
  }
}

Padrão: standard. Referência completa de ferramentas →

---

Modo nativo

O modo nativo é o padrão:

PILOT_BROWSER_MODE=native

Use-o para automação de QA, sessões MCP paralelas e evidências de captura de tela.

Verifique-o antes das execuções de QA:

PILOT_HEADLESS=1 npm run stress:screenshots
npm run stress:codex

Esperado: ambos relatam 6/6 passed.

Modo de extensão

O modo de extensão é legado e opt-in:

PILOT_BROWSER_MODE=extension

Use-o apenas quando precisar do perfil real do Chrome já autenticado de um usuário.

Importe cookies do seu navegador real: pilot_import_cookies({ browser: "chrome", domains: [".github.com"] })

Suporta Chrome, Arc, Brave, Edge, Comet via macOS Keychain / Linux libsecret. Para CAPTCHAs: pilot_handoff → você intervém → pilot_resume.

---

Requisitos

• Node.js >= 18
• Playwright Chromium
• macOS ou Linux
• Modo de extensão apenas: Chrome + extensão Pilot

Se o Chromium estiver ausente:

npx playwright install chromium

Segurança

• A extensão comunica-se apenas em localhost (127.0.0.1)
• O broker nativo comunica-se apenas em localhost (127.0.0.1)
• Sessões nativas usam contextos de navegador isolados por sessão MCP
• A validação do caminho de saída impede gravações fora de PILOT_OUTPUT_DIR
• Proteção contra travessia de caminho em todas as operações de arquivo
• PILOT_PROFILE controla quais ferramentas são expostas (core / standard / full)

---

Créditos

Arquitetura central — seleção de elementos baseada em ref, diff de snapshots, capturas de tela anotadas — portada de gstack por Garry Tan. Construído sobre Playwright e o MCP SDK.

---

Se o Pilot for útil, dê uma estrela no repositório — isso ajuda outros a encontrá-lo.