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 опублікуйте порт контейнера на петлі зворотного зв’язку:

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 на інтерфейсі, що не є петлевим, використовуйте 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 дозволяє один сесія і тримає кожен порт хоста прив’язаним до зворотного інтерфейсу:

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 одного опублікованого порт. Пропущене значення успадковує значення за замовчуванням процесу, тоді як 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 hop також залишається відкритим текстовим тунелем зворотного трафіку.

Збіг проксі-серверів за 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.