Docker¶

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

Запустить¶

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

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

--init рекомендуется к использованию, поскольку при автоматизации работы браузера могут создаваться кратковременные дочерние процессы. Процесс инициализации Docker аккуратно завершает работу этих дочерних процессов.

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

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

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

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

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

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

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

docker run --rm --init -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, если путь содержит запятые или при передаче нескольких каталогов расширений. Перезапустите контейнер после изменения файлов расширений или путей расширений.

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

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

docker run --rm --init -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 --init -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-транспорта и переменными среды.

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

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

docker run --rm --init -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-адрес прокси и закодируйте специальные символы в имени пользователя или пароле с помощью кодировки «процент» .

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

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

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

{
  "mcpServers": {
    "cloakbrowser": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--init",
        "-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.