pw-pool

Un navegador por sesión de agente para el Playwright MCP.

@playwright/mcp asume un servidor y un navegador. Si ejecutas dos sesiones de agente en una misma máquina y fallan por el bloqueo de perfil o, con un navegador compartido, trabajan en el mismo espacio de pestañas y navegan por las páginas del otro. pw-pool da a cada sesión su propio Chrome y recuerda de quién es cada uno.

Perfiles

Chrome guarda todo sobre una "persona" en un directorio de perfil (--user-data-dir): cookies, almacenamiento local, contraseñas guardadas, pestañas abiertas. Eso es lo que te mantiene con la sesión iniciada entre ejecuciones. Solo un Chrome puede usar un perfil a la vez. pw-pool crea un perfil por sesión, lo conserva entre ejecuciones y puede sembrar uno nuevo desde una plantilla — una copia de los archivos de inicio de sesión de un perfil con el que ya hayas iniciado sesión — para que una nueva sesión comience con la sesión iniciada sin compartir navegador con nadie.

Related MCP server: playwright-mcp-supercharged

Instalación

Requiere Node 22+ y macOS o Linux.

git clone https://github.com/ckarnell/pw-pool && cd pw-pool
npm install            # pins @playwright/mcp and patches it
node bin/pw-pool.js install    # checks the setup; offers to download Chrome for Testing if missing

O globalmente, lo que pone pw-mcp y pw-pool en tu PATH: npm install -g github:ckarnell/pw-pool.

Luego usa pw-mcp como comando MCP de Playwright. Claude Code (~/.claude.json o un .mcp.json de proyecto):

"playwright": { "type": "stdio", "command": "pw-mcp" }

(o "command": "node", "args": ["/path/to/pw-pool/bin/pw-mcp.js"] para un clon que no esté en el PATH).

Otras banderas de MCP (--caps, --output-dir, …) se pueden añadir a args; se pasan tal cual. --headless se aplica al lanzamiento del pool. --cdp-endpoint, --user-data-dir, --isolated y --browser se descartan con una advertencia, porque el pool elige el navegador.

Por defecto los navegadores son el Chrome para Testing de Playwright. Para usar el Chrome ya instalado en la máquina: pw-pool config set channel '"chrome"' (también chrome-beta, chrome-canary, msedge), o config.chrome para una ruta explícita.

Opcional, para iniciar cada sesión con la sesión iniciada:

pw-pool template save main --from ~/path/to/a/signed-in/user-data-dir
pw-pool config set defaultTemplate '"main"'

Cambiar con sesiones abiertas

Puedes cambiar la configuración de MCP en cualquier momento; nada de lo que se esté ejecutando se ve afectado. Un servidor MCP se inicia una vez por sesión, así que las sesiones ya abiertas conservan su servidor y navegador antiguos hasta que se reinicien. Las sesiones que se inicien (o reinicien, por ejemplo claude --resume) después del cambio usan pw-pool. Orden que funciona:

1. Guarda una plantilla desde el navegador que usas hoy y establécela como predeterminada (arriba), para que los nuevos navegadores tengan la sesión iniciada.

2. Cambia la entrada de MCP a pw-mcp.

3. Nada más. Las sesiones antiguas continúan; las nuevas reciben su propio navegador.

Para volver atrás, restaura la entrada de MCP anterior. Los navegadores que inició pw-pool se eliminan después del TTL de inactividad, o de inmediato con pw-pool stop all. Un navegador que ejecutaste antes (por ejemplo, uno compartido en un puerto CDP fijo) no lo toca pw-pool y puede seguir ejecutándose a su lado.

Cómo funciona

session A ─▶ pw-mcp ─▶ registry ─▶ Chrome :9300, profiles/A/ ◀─ @playwright/mcp --cdp-endpoint
session B ─▶ pw-mcp ─▶ registry ─▶ Chrome :9301, profiles/B/ ◀─ @playwright/mcp --cdp-endpoint

• pw-mcp reemplaza a npx @playwright/mcp como comando del servidor MCP. Averigua qué sesión está llamando, toma el navegador de esa sesión del pool (lanzándolo si es necesario) y ejecuta el @playwright/mcp incluido contra él a través de CDP. Stdio pasa directamente.

• Cuando el MCP sale, el navegador permanece activo. Una sesión reanudada obtiene el mismo navegador, pestañas y todo.

• Un navegador sin pestañas abiertas y sin sesión activa se detiene de inmediato; uno que aún tenga pestañas se detiene 1 hora después de que termine su sesión (pestañas guardadas). Un inicio posterior lo relanza en el mismo perfil y reabre las pestañas. Los perfiles no utilizados se eliminan después de 30 días. Una sesión activa mantiene un arrendamiento y nunca se elimina.

• Nada abre una ventana: los navegadores se inician sin ventana y las pestañas se abren en segundo plano. El MCP incluido lleva un parche de dos líneas por la misma razón (ver Enfoque).

Sin demonio. El estado es un registro JSON en ~/.pw-pool/, protegido por un bloqueo.

Qué sesión es cuál

pw-mcp necesita una clave estable por sesión. En orden:

1. --key / PW_POOL_KEY — explícito. Cualquier sistema puede configurarlo. PW_POOL_NAME etiqueta la ventana.

2. CLAUDE_CODE_SESSION_ID — Claude Code (2.1.239+) lo establece en el entorno del servidor MCP.

3. ~/.claude/sessions/<parent pid>.json — Claude Code escribe allí su id de sesión, nombre y cwd.

4. El pid padre — respaldo; el navegador se elimina cuando termina el arrendamiento.

Misma clave, mismo navegador. claude --resume conserva el id de sesión, por lo que recupera su navegador.

Plantillas

pw-pool template save <name> --from <dir> copia los archivos de inicio de sesión de un perfil (cookies, almacenamiento local, IndexedDB, contraseñas guardadas, preferencias — unos pocos MB; sin cachés). El perfil de una nueva sesión se siembra desde --template <name>, PW_POOL_TEMPLATE o config.defaultTemplate, una vez, cuando se crea. Después, cada perfil evoluciona por su cuenta. --fresh fuerza un perfil vacío.

Las plantillas y los perfiles contienen credenciales en vivo. Mantén ~/.pw-pool/ fuera de los repositorios. Una plantilla es una copia en un momento dado: guárdala de nuevo después de iniciar sesión en algo nuevo.

CLI

pw-pool install [--yes]            first-time setup; asks before downloading Chrome
pw-pool ls                         registered browsers: key, name, port, pid, status, tabs, leases
pw-pool cdp [key] [--ensure]       CDP endpoint of a session's browser (default: the calling session)
pw-pool tabs [key]
pw-pool gc [--force] [--dry-run]   reap stale leases, idle browsers, old profiles
pw-pool stop <key|all> [--rm]      stop a browser (tabs saved); --rm also deletes its profile
pw-pool template save <name> [--from <dir>] | ls | rm <name>
pw-pool config [get <key> | set <key> <json>]
pw-pool doctor

<key> es una clave completa, un prefijo único o un nombre de sesión. pw-pool cdp --ensure permite que los scripts manejen el mismo navegador que el MCP de su sesión. Cada inicio de pw-mcp ejecuta gc; para máquinas donde las sesiones son escasas, ejecuta pw-pool gc desde cron o launchd.

La configuración vive en ~/.pw-pool/config.json (pw-pool config): portRange [9300, 9399], idleTtlHours 1, profileTtlDays 30, defaultTemplate, sourceProfile, chrome, channel, headless, sandbox (desactivado, como el chromiumSandbox de Playwright), profileTheme, windowCascade, windowSize, extraChromeArgs, launchTimeoutMs. PW_POOL_HOME mueve todo el directorio de estado; PW_POOL_HEADLESS=1 ejecuta navegadores sin interfaz (servidores, contenedores).

profileTheme: true tiñe la barra de herramientas de cada navegador con un color estable derivado de su clave, para que varias ventanas del pool sean fáciles de distinguir en pantalla (el Cmd-Tab de macOS todavía muestra un icono por instancia; esto colorea la ventana en sí). Un "R,G,B" fijo aplica el mismo tema a todos los navegadores del pool.

Enfoque

En macOS, dos cosas activan una app de Chrome y le quitan el foco a la persona que usa la máquina: una ventana creada al inicio y una pestaña creada en primer plano. pw-pool lanza Chrome con --no-startup-window y abre pestañas con background: true de CDP. @playwright/mcp no tiene opción para esto, por lo que scripts/patch-focus.js cambia dos líneas en la copia incluida (browser_tabs new → pestaña en segundo plano, browser_tabs select → sin bringToFront). El parche se aplica en npm install; pw-pool doctor lo verifica; PW_MCP_FOREGROUND_TABS=1 restaura el comportamiento original.

Un caso está fuera del alcance del parche: cuando una página en sí abre una ventana emergente (window.open o un enlace target="_blank" en un clic), macOS activa el navegador para mostrarla, igual que cualquier Chrome. Los navegadores están con interfaz por defecto, coincidiendo con @playwright/mcp. Si ese robo de foco importa en una máquina compartida, ejecuta sin interfaz: pw-pool config set headless true, PW_POOL_HEADLESS=1, o por sesión pw-mcp --headless (y --headed para forzar interfaz cuando el valor predeterminado sea sin interfaz). Sin interfaz se renderiza de forma idéntica para instantáneas y capturas de pantalla.

Solución de problemas

• El MCP se desconecta ("Connection closed") justo después de un browser_evaluate. El resultado era mayor que el límite de mensajes del cliente (16 MB en Claude Code), por lo que el cliente cerró la conexión. Esto no es específico de pw-pool. El cliente reinicia el servidor en segundos y pw-mcp se vuelve a conectar al mismo navegador, pestañas incluidas; llama a la herramienta de nuevo y devuelve valores más pequeños. Claude Code mantiene el registro del servidor en ~/Library/Caches/claude-cli-nodejs/<project>/mcp-logs-playwright/.

• "Chrome exited during startup" o "did not answer": el error cita el final de ~/.pw-pool/logs/<key>.chrome.log. Causas comunes: sin pantalla en Linux (usa headless o Xvfb), un binario que no se puede ejecutar (pw-pool doctor).

• Un navegador parece no ser de nadie: pw-pool ls muestra los arrendamientos; ! marca un titular que ha salido. pw-pool gc los limpia; pw-pool stop <key> detiene un navegador del que estés seguro.

Desarrollo

npm test               # unit tests (no browser needed)
npm run test:e2e       # real browsers, throwaway pool home: isolation, reattach, concurrency, recovery, templates
npm run test:docker    # the same on Linux in a container

La versión de @playwright/mcp está fijada. Para subirla, cambia la versión, ejecuta npm install y arregla scripts/patch-focus.js si la instalación falla (el paquete cambió de forma).

Publicar

La publicación usa publicación de confianza de npm (OIDC desde GitHub Actions) — sin tokens. Configuración única en npmjs.com: Configuración del paquete → Trusted Publisher → flujo de trabajo publish.yml de este repositorio. Después, publica etiquetando: npm version patch && git push --follow-tags. El flujo de trabajo ejecuta las pruebas y npm publish --provenance. (La primera publicación, antes de que exista el paquete, se hace una vez localmente con npm publish --access public --auth-type=web).

Licencia

MIT