pw-pool

Один браузер на сессию агента для Playwright MCP.

@playwright/mcp предполагает один сервер и один браузер. Если на одной машине запущены две сессии агента, они либо упираются в блокировку профиля, либо при общем браузере работают в одном пространстве вкладок и открывают страницы друг друга. pw-pool выдаёт каждой сессии собственный Chrome и помнит, какой браузер чей.

Профили

Chrome хранит всё о «человеке» в профиле (--user-data-dir): файлы cookie, локальное хранилище, настройки, сохранённые пароли, открытые вкладки. Именно это сохраняет вас авторизованным между запусками. Профиль одновременно может использовать только один Chrome. pw-pool создаёт один профиль на сессию, хранит его между запусками и может наполнить новый профиль из шаблона — копии файлов авторизации профиля, в который вы уже вошли, — поэтому новая сессия стартует авторизованной и не делит браузер ни с кем.

Related MCP server: playwright-mcp-supercharged

Установка

Требуется Node 22+ и macOS или 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

Или глобальная установка — которая помещает pw-mcp и pw-pool в PATH: npm install -g github:ckarnell/pw-pool.

Затем используйте pw-mcp как команду Playwright MCP. Claude Code (~/.claude.json или .mcp.json в проекте):

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

(или "command": "node", "args": ["/path/to/pw-pool/bin/pw-mcp.js"] для клона, который не в PATH).

Остальные флаги MCP (--caps, --output-dir, …) можно добавлять в args; они передаются насквозь. --headless применяется к запуску браузера пула. --cdp-endpoint, --user-data-dir, --isolated и --browser отбрасываются с предупреждением, потому что браузер выбирает пул.

По умолчанию браузеры — это Chrome for Testing от Playwright. Чтобы использовать уже установленный на машине Chrome: pw-pool config set channel '"chrome"' (также chrome-beta, chrome-canary, msedge) или config.check для явного пути.

Опционально, чтобы каждая сессия стартовала авторизованной:

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

Переключение при открытых сессиях

Конфигурацию MCP можно менять в любой момент; на работающие процессы это не влияет. MCP-сервер запускается один раз за сессию, поэтому уже открытые сессии сохраняют свой старый сервер и браузер до перезапуска. Сессии, которые запускаются (или перезапускаются, например claude --resume) после изменения, используют pw-pool. Рабочий порядок:

1. Сохраните шаблон из браузера, которым вы пользуетесь сегодня, и сделайте его шаблоном по умолчанию (см. выше), чтобы новые браузеры были авторизованы.

2. Измените запись MCP на pw-mcp.

3. Больше ничего. Старые сессии продолжают работать; новые получают собственный браузер.

Чтобы вернуться, восстановите прежнюю запись MCP. Браузеры, запущенные pw-pool, удаляются по истечении idle TTL или сразу командой pw-pool stop all. Браузер, который вы запускали раньше (например, общий на фиксированном CDP-порте), pw-pool не трогает, и он может продолжать работать рядом.

Как это работает

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 заменяет npx @playwright/mcp в роли команды MCP-сервера. Он определяет, какая сессия вызывает, берёт из пула браузер этой сессии (запуская его при необходимости) и запускает против поставляемого @playwright/mcp по CDP. Stdio проходит насквозь.

• Когда MCP завершает работу, браузер продолжает работать. Возобновлённая сессия получает тот же браузер, включая вкладки.

• Браузер без открытых вкладок и без активной сессии останавливается немедленно; браузер, в котором ещё есть вкладки, останавливается через 1 час после завершения сессии (вкладки сохраняются). Следующий запуск поднимает его на том же профиле и открывает вкладки заново. Неиспользуемые профили удаляются через 30 дней. Активная сессия удерживает аренду и никогда не"перезапускается".

• Ничто не разворачивает окно: браузеры стартуют без окна, а вкладки открываются в фоне. Встроенный MCP несёт в себе патч из двух строк по той же причине (см. Focus).

Никакого демона. Состояние — это JSON-реестр в ~/.pw-pool/, защищённый блокировкой.

Какая сессия какая

pw-mcp нужен стабильный ключ для каждой сессии. В таком порядке:

1. --key / PW_POOL_KEY — явный ключ. Любая обвязка может его задать. PW_POOL_NAME задаёт заголовок/подпись окна.

2. CLAUDE_CODE_SESSION_ID — Claude Code (2.1.239+) передаёт его в окружение MCP-сервера.

3. ~/.claude/sessions/<parent pid>.json — Claude Code записывает туда идентификатор сессии, имя и cwd.

4. Родительский pid — запасной вариант; браузер удаляется, когда заканчивается аренда.

Один ключ — один браузер. claude --resume сохраняет идентификатор сессии, поэтому сессия получает свой браузер обратно.

Шаблоны

pw-pool template save <name> --from <dir> копирует входные файлы профиля (cookies, локальное хранилище, IndexedDB, сохранённые пароли, настройки — несколько мегабайт; без кэшей). Профиль новой сессии наполняется из --template <name>, PW_POOL_TEMPLATE или config.defaultTemplate один раз, при создании. После этого каждый профиль развивается самостоятельно. --fresh принудительно создаёт пустой профиль.

Шаблоны и профили содержат живые учётные данные. Не храните ~/.pw-pool/ в репозиториях. Шаблон — это снимок на момент времени: сохраните его заново после входа во что-то новое.

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> — это полный ключ, уникальный префикс или имя сессии. pw-pool cdp --ensure позволяет скриптам управлять тем же браузером, что и MCP этой сессии. Каждый запуск pw-mcp выполняется gc; на машинах, где сессии бывают редко, запускайте pw-pool gc по cron или launchd.

Конфигурация живёт в ~/.pw-pool/config.json (pw-pool config): portRange [9300, 9399], idleTtlHours 1, profileTtlDays 30, defaultTemplate, sourceProfile, chrome, channel, headless, sandbox (выключено, как chromiumSandbox в Playwright), profileTheme, windowCascade, windowSize, extraChromeArgs, launchTimeoutMs. PW_POOL_HOME перемещает весь каталог состояния; PW_POOL_HEADLESS=1 запускает браузеры в headless-режиме (серверы, контейнеры).

profileTheme: true окрашивает панель инструментов каждого браузера в стабильный цвет, производный от его ключа, чтобы несколько окон пула было легко различить на экране (macOS Cmd-Tab по-прежнему показывает по одной иконке на инстанс; здесь окрашивается само окно). Фиксированная строка "R,G,B" применяет одинаковую тему для всех браузеров пула.

Фокус

On macOS, две вещи активируют Chrome и забирают фокус у сидящего за машиной: окно, создаваемое при запуске, и вкладка, создаваемая на переднем плане. pw-pool запускает Chrome с --no-startup-window, а вкладки открывает через CDP с background: true. У @playwright/mcp нет такой опции, поэтому scripts/patch-focus.js правит две строки во встроенной копии (browser_mcpus new → фоновая вкладка, browser_mcpus select → без bringToFront). Патч применяется при npm install; pw-pool doctor проверяет его; PW_MCP_FOREGROUND_TABS=1 возвращает исходное поведение.

Есть случай, который патч не охватывает: когда сама страница открывает всплывающее окно (window.open или target="_blank"-link при клике), macOS активирует браузер, чтобы показать окно, — так же, как это работает с любым Chrome. Браузеры по умолчанию работают как @playwright/mcp вheaded-режиме. Если это переживание фокуса значимо на общей машине, работайте в headless-режиме: pw-pool config set headless true, PW_POOL_HEADLESS=1 или для каждой сессии pw-mcp --headless (а --headed переопределяет в headed, когда по умолчанию headless). Headless рендерится полностью одинаково для snapshots и файлов.

Troubleshooting

• MCP отключается («Connection closed») прямо после browser_evaluate. Результат был больше клиентского лимита на сообщение (16 MB в Claude Code), поэтому клиент закрыл соединение. Это никаких ,ontkwmfoq pw-pool. Клиент перезапускает сервер через пару секунд, и pw-mcp подключается снова к тому же браузеру, включая вкладки; вызовите инструмент ещё раз и возвращайте меньшие значения. Логи сервера Claude Code хранит в ~/Library/Caches/claude-cli-nodejs/<project>/mcp-logs-playwright/.

• "Chrome exited during startup" or «did not answer»: в ошибке цитируется конец файла ~/.pw-pool/logs/<key>.chrome.log. Частые причины: нет дисплея в Linux (используйте headless или Xvfb) либо непригодный к запуску бинарный файл (pw-pool doctor).

• Браузер, похоже, не принадлежит никому: pw-pool ls показывает аренды; ! помечает владельца, который уже завершился. pw-pool gc очищает их; pw-pool stop <key> останавливает браузер, в котором вы уверены.

Разработка

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

Версия @playwright/mcp зафиксирована. Чтобы обновить её, измените версию, выполните npm install и поправьте scripts/patch-focus.js, если установщик сообщит об ошибке (сборка изменилась).

Публикация релиза

Публикация использует npm trusted publishing (OIDC from GitHub Actions) — без токенов. Одноразовая настройка на npmjs.com: Settings → Trusted Publisher в настройках пакета → workflow publish.yml этого репозитория. После этого выпуск делается тегом: npm version patch && git push --follow-tags. Workflow запускает тесты и npm publish --provenance. (Самая первая публикация, когда пакета ещё нет, делается один раз локально командой npm publish --access public --auth-type=web.)

Лицензия

MIT