Докер¶

Апублікаванае выява — гэта рэкамендаваны час працы для паўторнага выкарыстання 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¶

Апублікуйце наладжаны дыяпазон managed-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

Для пераадрасацыі портаў Docker патрабуецца --cdp-host 0.0.0.0, таму трэба дакладна таксама патрабуюцца яўная згода --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 і перасылае адзін да аднаго на слухача адкрытага тэксту. мост-да-Chromium перапрыгванне таксама застаецца адкрытым трафікам зваротнай петлі.

Супастаўленне GeoIP-праксі¶

Docker выкарыстоўвае тыя ж зменныя асяроддзя проксі і GeoIP, што і npm. Уключыце супадзенне проксі GeoIP, калі для рэгіянальных патрэб QA 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. Гл. ГеаIP-адпаведнасць праксі-сервераў для метаданых праксі-сервера ў часе выканання, выпадкаў шматрэгіянальнага выкарыстання і абмежаванняў.

Па змаўчанні¶

Канфігурацыя кліента 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.