pilot-mcp

pilot — automatización de navegador MCP para agentes de IA

Sesiones de navegador nativas respaldadas por Playwright por defecto. No se requiere extensión de Chrome para automatización de QA.

Pilot tiene dos backends de navegador:

• Modo nativo (predeterminado): contextos de navegador Playwright aislados. Esta es la ruta compatible para automatización de QA en paralelo y capturas de pantalla confiables.
• Modo extensión (heredado/opt-in): se conecta a tu perfil real de Chrome cuando necesitas cookies existentes y sesiones iniciadas.

El modo nativo evita chrome.tabs.captureVisibleTab() por completo, por lo que las capturas de pantalla no dependen de que Chrome esté en primer plano, de que una pestaña esté visiblemente activa o de que el service worker de la extensión esté actualizado.

---

Cómo funciona

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

1. Pilot se ejecuta como servidor MCP — Claude Code, Cursor o cualquier cliente MCP se conecta vía stdio
2. El primer proceso de Pilot se convierte en el broker en localhost
3. Los procesos posteriores de Pilot se conectan como clientes del broker
4. Cada sesión obtiene un contexto/página de navegador nativo aislado
5. Las capturas de pantalla provienen de Playwright, no de la API de captura de la extensión de Chrome

---

Inicio rápido

1. Agrega el servidor MCP

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

Para una copia 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. Úsalo

"Abre https://example.com,, toma una captura de pantalla y resume la página."

Sin instalación de extensión. Sin requisito de Chrome en primer plano.

Para operaciones completas en modo nativo, comandos de estrés y verificaciones de limpieza, consulta docs/native-mode.md.

---

Instantáneas optimizadas

Otras herramientas vuelcan más de 50K caracteres por página en tu ventana de contexto. Pilot mantiene todo pequeño:

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

snapshot_diff muestra solo lo que cambió entre acciones — sin relecturas redundantes.

Menos contexto = respuestas más rápidas, llamadas API más económicas, menos alucinaciones.

---

Pilot vs @playwright/mcp

	Pilot	@playwright/mcp
Navegador	Contexto nativo de Playwright por defecto; Chrome real vía extensión heredada	Nueva instancia de Chromium
Estado de autenticación	Nativo aislado por defecto; el modo extensión puede usar cookies reales de Chrome	Anónimo — configuración manual
Detección de bots	Nativo para automatización; modo extensión para transferencia de perfil real	Bloqueado por Cloudflare
Tamaño de instantánea	~2K navegación, ~9K completo	~50-60K
Diff de instantánea	pilot_snapshot_diff	❌
Importación de cookies	Chrome, Arc, Brave, Edge, Comet	JSON manual
Iframes	✅	❌
Perfiles de herramientas	core (9) / standard (40) / full (69)	--caps grupos
Transporte	stdio	stdio, HTTP, SSE

---

69 herramientas en 3 perfiles

Los LLM se degradan a medida que crecen las listas de herramientas. Carga solo lo que necesitas:

Perfil	Herramientas	Qué incluye
core	9	navigate, snapshot, click, fill, type, press_key, wait, screenshot, snapshot_diff
standard	40	Core + pilot_act, pilot_guide, evidence, doctor/reset, tabs, scroll, hover, drag, iframes, auth, block, find
full	69	Standard + interceptación de red, aserciones, portapapeles, geolocalización, CDP, evaluate, PDF, responsive, inspección profunda

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

Predeterminado: standard. Referencia completa de herramientas →

---

Modo nativo

El modo nativo es el predeterminado:

PILOT_BROWSER_MODE=native

Úsalo para automatización de QA, sesiones MCP en paralelo y evidencia con capturas de pantalla.

Verifícalo antes de ejecutar QA:

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

Esperado: ambos reportan 6/6 passed.

Modo extensión

El modo extensión es heredado y opt-in:

PILOT_BROWSER_MODE=extension

Úsalo solo cuando necesites el perfil real de Chrome ya autenticado de un usuario.

Importa cookies desde tu navegador real: pilot_import_cookies({ browser: "chrome", domains: [".github.com"] })

Soporta Chrome, Arc, Brave, Edge, Comet vía macOS Keychain / Linux libsecret. Para CAPTCHAs: pilot_handoff → tú intervienes → pilot_resume.

---

Requisitos

• Node.js >= 18
• Playwright Chromium
• macOS o Linux
• Solo modo extensión: Chrome + extensión Pilot

Si falta Chromium:

npx playwright install chromium

Seguridad

• La extensión se comunica solo en localhost (127.0.0.1)
• El broker nativo se comunica solo en localhost (127.0.0.1)
• Las sesiones nativas usan contextos de navegador aislados por sesión MCP
• La validación de rutas de salida evita escrituras fuera de PILOT_OUTPUT_DIR
• Protección contra traversal de rutas en todas las operaciones de archivos
• PILOT_PROFILE controla qué herramientas se exponen (core / standard / full)

---

Créditos

Arquitectura central — selección de elementos basada en refs, diff de instantáneas, capturas de pantalla anotadas — portada de gstack por Garry Tan. Construido sobre Playwright y el MCP SDK.

---

Si Pilot te resulta útil, dale una estrella al repositorio — ayuda a que otros lo encuentren.