Docker¶

Опубликованный образ представляет собой рекомендуемую среду выполнения для стабильного использования MCP.

Запустить¶

docker run --rm -i \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

Артефакты записываются в /data в контейнере. Подключите этот путь, чтобы сохранять скриншоты, моментальные снимки, загруженные файлы и сетевые выводы.

Образ уже запускает Tini как PID 1 и subreaper, поэтому обычным командам не требуется дополнительный init-процесс Docker.

Headed-сеансы, health check и ограниченный runtime¶

При headless: false контейнер по требованию запускает приватный Xvfb и использует его до завершения контейнера. Это не видимый рабочий стол и не сервис VNC, noVNC, RDP, host X11 или захвата экрана. Контексты, страницы, профили и артефакты Playwright изолированы, но нативные X11 focus, clipboard и захват экрана не являются границей изоляции арендаторов. Docker health check через приватный Unix socket проверяет event loop MCP CLI и, если Xvfb запущен, его доступность; это не запрос MCP stdio и не замена /healthz или /readyz. Для read-only root filesystem смонтируйте /data и предоставьте writable tmpfs для /tmp и /tmp/.X11-unix, если возможны headed-сеансы.

Те же самые теги версий публикуются на Docker Hub как swimmwatch/cloakbrowser-mcp, а на GHCR — как ghcr.io/swimmwatch/cloakbrowser-mcp.

Постоянные профили¶

Docker не включает постоянный профиль браузера по умолчанию. Используйте существующий том /data как корень хранения, если хотите, чтобы cookie, локальное хранилище, кэш или состояние расширений сохранялись после перезапуска контейнера:

docker run --rm -i \
  -e PLAYWRIGHT_MCP_USER_DATA_DIR=/data/profiles/default \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

Переменные среды внутри Docker должны использовать пути контейнера, такие как /data/profiles/default, а не пути хоста. Мост создает каталог профиля при отсутствии, проверяет доступность для записи, записывает путь контейнера в сгенерированную конфигурацию Playwright MCP и отклоняет дублирующиеся активные каталоги профиля внутри одного серверного процесса.

Кэш лицензии CloakBrowser¶

Образ хранит бинарные файлы CloakBrowser, состояние лицензии и кэш проверки в /home/node/.cloakbrowser. Смонтируйте в этот каталог именованный том, чтобы сохранять вход бесплатного уровня GitHub или Pro при замене контейнера:

docker volume create cloakbrowser-cache

docker run --rm -it \
  --entrypoint node \
  -v cloakbrowser-cache:/home/node/.cloakbrowser \
  swimmwatch/cloakbrowser-mcp:latest \
  /opt/cloakbrowser-mcp/node_modules/cloakbrowser/dist/cli.js login

docker run --rm -i \
  -v cloakbrowser-cache:/home/node/.cloakbrowser \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

Используйте тот же том с исходной командой info или logout, чтобы проверить или удалить сохраненный вход. Вместо этого можно передать CLOAKBROWSER_LICENSE_KEY через систему управления секретами контейнера. Не помещайте лицензионные ключи в слои образа, файлы Compose в системе контроля версий или вывод команд, сохраняемый как свидетельство сборки.

Пользовательский бинарный файл CloakBrowser¶

Смонтируйте совместимый исполняемый файл браузера в контейнер и передайте путь внутри контейнера через --binary-path (или CLOAKBROWSER_BINARY_PATH):

docker run --rm --init -i \
  -v "$PWD/artifacts:/data" \
  -v "$PWD/custom-chrome:/browser/chrome:ro" \
  swimmwatch/cloakbrowser-mcp:latest \
  --binary-path /browser/chrome

Файл должен быть доступным для чтения исполняемым файлом Linux, совместимым с архитектурой CPU образа; необходимые ему библиотеки должны быть доступны в контейнере. Этот путь действует для всех Streamable HTTP-сессий контейнера; для разных бинарных файлов браузера запускайте отдельные контейнеры.

Расширения Chrome¶

Расширения Chrome требуют постоянного профиля и должны монтироваться отдельно. Используйте пути контейнера в переменных среды, а не пути хоста. Монтирование расширения может быть доступно только для чтения:

docker run --rm -i \
  -e PLAYWRIGHT_MCP_USER_DATA_DIR=/data/profiles/default \
  -e CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS=/extensions/my-extension \
  -v "$PWD/artifacts:/data" \
  -v "$PWD/extensions/my-extension:/extensions/my-extension:ro" \
  swimmwatch/cloakbrowser-mcp:latest

Используйте JSON-массив для CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS, если путь содержит запятые или при передаче нескольких каталогов расширений. Перезапустите контейнер после изменения файлов расширений или путей расширений.

Режим подключения Playwright Extension отличается от монтирования распакованного расширения выше. Он требует официального расширения в persistent Chrome/Edge profile и PLAYWRIGHT_MCP_EXTENSION_TOKEN. Монтируйте каждую profile в отдельный writable path, передавайте token через secret manager и не сочетайте PLAYWRIGHT_MCP_EXTENSION=true с CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS.

HTTP с возможностью потоковой передачи¶

Для локального использования Streamable по протоколу HTTP необходимо открыть доступ к порту контейнера через loopback:

docker run --rm -p 127.0.0.1:3000:3000 \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest \
  --transport streamable-http --http-host 0.0.0.0 --http-port 3000

curl http://127.0.0.1:3000/healthz
curl http://127.0.0.1:3000/readyz

Для прямого подключения по HTTPS из контейнера смонтируйте файлы сертификатов и выберите HTTPS:

docker run --rm -p 127.0.0.1:3000:3000 \
  -v "$PWD/artifacts:/data" \
  -v "$PWD/certs:/certs:ro" \
  swimmwatch/cloakbrowser-mcp:latest \
  --transport streamable-http --http-host 0.0.0.0 --http-port 3000 \
  --http-protocol https --https-cert /certs/cert.pem --https-key /certs/key.pem

Привязка 127.0.0.1:3000 на стороне хоста обеспечивает локальность конечной точки. Если вы публикуете Streamable HTTP на интерфейсе, отличном от loopback, используйте HTTPS с аутентификацией или разместите сервер за доверенным обратным прокси-сервером с терминацией TLS, аутентификацией и средствами управления сетью. Streamable HTTP предоставляет фиксированные пробы GET /healthz и GET /readyz на одном и том же хосте и порту. Если настроены --http-auth-token или CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN, пробы должны использовать тот же заголовок Authorization: Bearer ..., что и запросы MCP. См. сгенерированное Руководство по CLI для ознакомления со всеми флагами HTTP-транспорта и переменными среды.

Управляемый CDP¶

Опубликуйте настроенный управляемый диапазон CDP один к одному. Этот пример stdio включает один сессия и удерживает каждый порт хоста привязанным к loopback:

docker run --rm -i \
  -p 127.0.0.1:9222-9231:9222-9231 \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest \
  --cdp-enabled \
  --cdp-port-range 9222-9231 \
  --cdp-host 0.0.0.0 \
  --cdp-allow-remote \
  --cdp-advertised-host 127.0.0.1

--cdp-host 0.0.0.0 требуется для переадресации портов Docker, поэтому явный Также требуется согласие на участие --cdp-allow-remote и конкретный --cdp-advertised-host. Не переназначайте диапазон на другие номера портов хоста: URL-адреса обнаружения содержат Арендованный порт и каждый опубликованный порт должны маршрутизироваться один к одному к принадлежащей им сессии.

Для многосессионного Streamable HTTP настройте и опубликуйте пул, не устанавливая процесс по умолчанию, если клиенты должны выбирать индивидуально:

docker run --rm \
  -p 127.0.0.1:3000:3000 \
  -p 127.0.0.1:9222-9231:9222-9231 \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest \
  --transport streamable-http \
  --http-host 0.0.0.0 \
  --http-port 3000 \
  --cdp-port-range 9222-9231 \
  --cdp-host 0.0.0.0 \
  --cdp-allow-remote \
  --cdp-advertised-host 127.0.0.1

Аутентифицированный запрос initialize с арендой cdpEnabled: true одного опубликованного порт. Пропущенное значение наследует значение процессa по умолчанию, в то время как cdpEnabled: false явно отказывается и не использует порт CDP. Истощение пула отклоняет только новый Сессия с включённым CDP; это не уменьшает ёмкость для отключённых сессий.

Прочитайте URL, несущий возможности, из cloakbrowser_bridge_info. Не помещайте его внутрь логи контейнера или проверки состояния. Подключитесь к CDP API, например chromium.connectOverCDP(); URL несовместим с Playwright chromium.connect() или текущий поток Open WebUI.

--cdp-advertised-scheme https изменяет опубликованные URL-адреса на https/wss, но мост не обеспечивает TLS для управляемого CDP. Используйте терминатор TLS, принадлежащий оператору, который занимает тот же заявленный порт во внешнем сетевом пространстве имен, сохраняет Host/Origin и пересылает один к одному слушателю моста открытого текста. The Мост к Chromium также оставляет трафик обратной петли в открытом виде.

Сопоставление прокси-серверов по GeoIP¶

Docker использует те же переменные среды прокси и GeoIP, что и npm. Включите сопоставление прокси по GeoIP, если региональному отделу контроля качества требуется, чтобы отпечатки часового пояса, языка и локали CloakBrowser соответствовали настроенному местоположению прокси:

docker run --rm -i \
  -e PLAYWRIGHT_MCP_PROXY_SERVER="http://user:pass@proxy.example:8080" \
  -e CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

Для прокси-серверов, требующих аутентификации, встройте учетные данные в URL-адрес прокси и закодируйте специальные символы в имени пользователя или пароле с помощью кодировки «процент» .

Поддерживаемые бинарные файлы CloakBrowser используют встроенную аутентификацию прокси в URL; старые бинарные файлы переходят на объект прокси Playwright.

Когда контейнер запускает Streamable HTTP, клиенты также могут выбирать различные прокси для каждого сеанса MCP с помощью метаданных initialize. См. Сопоставление прокси по GeoIP для получения информации о метаданных прокси во время выполнения, сценариях использования в нескольких регионах и ограничениях.

Значения по умолчанию¶

Настройки клиента MCP¶

{
  "mcpServers": {
    "cloakbrowser": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/tmp/cloakbrowser-artifacts:/data",
        "swimmwatch/cloakbrowser-mcp:latest"
      ]
    }
  }
}

Сборка локально¶

npm run docker:build
npm run docker:smoke

Файл Dockerfile использует зафиксированный официальный образ Playwright MCP в качестве базы для среды выполнения, применяет доступные обновления безопасности Debian во время сборки, удаляет неиспользуемые глобальные компоненты npm из образа среды выполнения и устанавливает мост под именем /opt/cloakbrowser-mcp.

В рамках рабочего процесса выпуска публикуются SBOM и сертификаты происхождения, добавляются метки OCI, содержащие информацию об источнике, ревизии, версии, лицензии, названии базового образа и хеше базового образа, а также перед публикацией выполняется сканирование скомпилированного образа с помощью Trivy.

Дополнительные практические сценарии¶

Для выбора между upstream Playwright MCP и этим пакетом используйте сравнение. Для быстрых задач используйте рецепты: постоянный профиль, расширения, reverse proxy, региональное QA, Claude Desktop, Codex CLI и smoke-тест CI.