Налаштування¶

Використовуйте вхідні змінні PLAYWRIGHT_MCP_* для забезпечення роботи Playwright MCP. Використовуйте CLOAK_PLAYWRIGHT_MCP_* лише для поведінки мосту, характерної для Cloak.

Старі змінні CLOAKBROWSER_MCP_* не підтримуються. Створений Довідник CLI є авторитетним переліком прапорів CLI мосту та відповідних їм змінних середовища.

Варіанти мостів¶

Ліцензія CloakBrowser і вхід через GitHub¶

Для налаштування ліцензії використовується CLI вихідного проєкту CloakBrowser; cloakbrowser-mcp не додає команд входу або виходу:

npx -y cloakbrowser@latest login
npx -y cloakbrowser@latest info
npx -y cloakbrowser@latest logout

Команда login приймає платний ключ або запускає вхід через GitHub для отримання ключа безкоштовного рівня. Перевірений ключ зберігається у ~/.cloakbrowser/license.key; команда logout видаляє цей файл. Команда info повідомляє активний рівень ліцензії, а для ліцензій Pro — кількість активних сеансів.

Натомість можна задати CLOAKBROWSER_LICENSE_KEY у середовищі MCP-сервера. Міст передає цю змінну дочірньому процесу верхнього рівня/браузера, не записуючи її до журналу. Якщо CLOAKBROWSER_CACHE_DIR указує на користувацький кеш із файлом license.key, CloakBrowser визначає ключ, а міст передає зі згенерованого середовища браузера лише цей визначений ключ. Інші згенеровані записи середовища не копіюються.

Якщо CloakBrowser відхиляє переданий ліцензійний ключ, не може його перевірити або зв'язатися із сервером ліцензій, запуск завершується з явною помилкою CloakBrowser. Міст зберігає цю помилку: він не маскує її і не переходить мовчки на інший браузер або рівень ліцензії.

Керований CDP¶

Керований доступ до Chrome DevTools Protocol (CDP) здійснюється лише за явним вибором. Він відкриває такий самий браузер Chromium, що генерується і контролюється MCP через можливість виявлення URL. Налаштування лише пулу портів не активує CDP.

Кожне значення CLI перекриває лише відповідну змінну середовища. Зокрема, --no-cdp-enabled замінює CLOAK_PLAYWRIGHT_MCP_CDP_ENABLED=true, і --no-cdp-allow-remote перевизначає CLOAK_PLAYWRIGHT_MCP_CDP_ALLOW_REMOTE=true. Увімкнена сесія без пулу портів відхиляється до того, як її upstream-дитина почне працювати. Ефективне хибне значення не створює слухача, оренду порту або можливості.

Для stdio значення процесу застосовується безпосередньо:

cloakbrowser-mcp \
  --cdp-enabled \
  --cdp-port-range 9222

Для Streamable HTTP, плоский логічний cdpEnabled у автентифікованому Метадані initialize перевизначають стандартні налаштування процесу для цієї сесії. Пропуск поле успадковує значення процесу. Ці приклади явно вибирають одну сесію та ще один вихід:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "cdpEnabled": true
      }
    }
  }
}

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "cdpEnabled": false
      }
    }
  }
}

Одна сесія CDP з підтримкою HTTP має одну оренду зовнішнього порту. Вимкнені сесії не мають. споживати пул. Виділення є локальним для процесу, вибирає найнижчого незадіяного кандидата, і негайно скасовує ту сесію, якщо обраний зовнішній порт вже зайнятий. Закрийте сеанси, щоб звільнити порти, або налаштуйте більший діапазон, коли пул вичерпано.

Отримайте поточний URL з cloakbrowser_bridge_info, потім передайте його structuredContent.cdp.discoveryUrl клієнту CDP, наприклад, Playwright chromium.connectOverCDP(). Ставтеся до цього URL як до облікових даних: він включає випадковий здібність на одне покоління і стає застарілою після заміни браузера. Керований CDP є не кінцева точка сервера Playwright. chromium.connect() та поточний Open WebUI Потоки PLAYWRIGHT_WS_URL не підтримуються.

--cdp-advertised-scheme https публікує відкриття https та URL-адреси wss WebSocket тільки. Міст не забезпечує TLS для керованого CDP: його зовнішній слухач та Chromium hop залишатися у відкритому тексті HTTP/WebSocket. Закінчувач TLS, що належить оператору, повинен слухати на тому ж рекламованому орендованому порту, зберігати рекламовані Host і Origin повноваження і пересилати один на один тому прозорому слухачеві сесії.

Увімкнення CDP починається Chromium під час ініціалізації MCP, тому що власність і зовнішні готовність можна перевірити. Налаштуйте таймаут ініціалізації клієнта MCP не менше ніж на 60 секунди. Коли увімкнено керування CDP, надане користувачем CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS не повинно містити --remote-debugging-port, --remote-debugging-address або --remote-debugging-pipe (включаючи форми =). Власна внутрішня --remote-debugging-pipe Playwright залишається увімкненою разом із TCP-термінал з керованим мостом зворотного зв'язку.

Див. Інструменти, Docker, Безпека, та Архітектура для стану виявлення, розгортання, обмеження та поведінка при перезапуску.

Канал випуску CloakBrowser¶

CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL вибирає канал випуску двійкового файла CloakBrowser. Типове значення — stable. preview запитує попередню Pro-збірку браузера та доступний лише з ліцензією Pro. Явно задана версія CLOAKBROWSER_VERSION має пріоритет. Якщо Preview недоступний для платформи, CloakBrowser повертається до Stable.

Канал випуску вибирається під час запуску процесу моста. Він застосовується до всіх сеансів Streamable HTTP і не може задаватися чи перевизначатися в метаданих initialize. Щоб змінити його, перезапустіть міст.

Власний бінарний файл CloakBrowser¶

--binary-path <path> вибирає власний виконуваний файл CloakBrowser для поточного процесу моста. CLOAKBROWSER_BINARY_PATH надає те саме налаштування для розгортань через середовище; параметр CLI має пріоритет. Міст нормалізує шлях, вимагає доступний для читання звичайний файл і записує його в browser.launchOptions.executablePath створеної конфігурації Playwright MCP.

npx -y cloakbrowser-mcp@latest --binary-path /opt/cloakbrowser/chrome

Міст не завантажує та не оновлює власний виконуваний файл. Якщо шлях не задано, CLOAKBROWSER_VERSION може закріпити версію бінарного файла, яким керує CloakBrowser.

Для Streamable HTTP вибраний бінарний файл належить процесу моста та використовується всіма створеними ним сесіями MCP. Метадані initialize не можуть вибирати або перевизначати виконуваний шлях; для різних бінарних файлів запускайте окремі процеси моста.

Якщо вибраний бінарний файл реалізує document.modelContext, upstream Playwright MCP може після знімка сторінки додавати інструменти виду webmcp_<page-tool>. Він надсилає сповіщення tools/list_changed, а міст пересилає його разом з оновленим списком інструментів. Імена та схеми динамічних інструментів визначає сторінка.

Збіг проксі-серверів за GeoIP¶

Установіть CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true разом із PLAYWRIGHT_MCP_PROXY_SERVER, щоб визначити прапорці часового поясу, мови та локалі CloakBrowser за місцем виходу проксі. Для підтримуваних бінарних файлів CloakBrowser вибирає вбудовану автентифікацію в URL, а для старіших бінарних файлів зберігає об'єкт проксі Playwright як резервний варіант.

Див. Збіг проксі-серверів за GeoIP для ознайомлення з прикладами налаштування, метаданими HTTP-проксі-серверів, що підтримують потокову передачу даних під час виконання, сценаріями використання, правилами пріоритетності та обмеженнями.

Зіставлення працює fail-closed: якщо CloakBrowser не може визначити IP виходу проксі, базу GeoIP, часовий пояс або локаль, браузер не запускається з частково зіставленим відбитком. Розв'язання GeoIP обмежено 20 секундами; первинне завантаження автономної бази GeoIP виконується окремо й може тривати довше.

Гуманізована поведінка при введенні даних¶

Встановіть CLOAK_PLAYWRIGHT_MCP_HUMANIZE=true, щоб увімкнути в CloakBrowser імітацію миші, клавіатури та прокрутки для взаємодії зі сторінками. Міст застосовує це через хук ініціалізації сторінки Playwright MCP, тому схеми інструментів браузера вищого рівня залишаються незмінними.

Див. «Гуманізована поведінка введення даних» для ознайомлення з прикладами налаштування, метаданими Streamable HTTP під час виконання, сценаріями використання та обмеженнями.

Розширення Chrome¶

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

PLAYWRIGHT_MCP_USER_DATA_DIR="$PWD/.profiles/default" \
  CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS='["/absolute/path/to/my-extension"]' \
  npx -y cloakbrowser-mcp@latest

Для Streamable HTTP передайте каталоги профілю та розширення в метаданих initialize:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "userDataDir": "/absolute/path/to/profile",
        "extensionPaths": ["/absolute/path/to/my-extension"]
      }
    }
  }
}

Перезапустіть міст або створіть новий HTTP-сеанс після зміни файлів розширень або шляхів розширень. Використовуйте JSON-масив для CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS, коли шляхи містять коми, під час передавання кількох розширень або під час використання шляхів Windows із літерами дисків.

Режим підключення Playwright Extension¶

Цей режим підключається через офіційне розширення Playwright, уже встановлене у профілі Chrome або Edge, і відрізняється від завантаження розпакованих розширень через CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS. Для stdio задайте PLAYWRIGHT_MCP_EXTENSION=true, PLAYWRIGHT_MCP_EXTENSION_TOKEN, PLAYWRIGHT_MCP_USER_DATA_DIR і за потреби один відносний сегмент PLAYWRIGHT_MCP_PROFILE_DIR_NAME. У Streamable HTTP метадані extensionMode, profileDirName і userDataDir перевизначають налаштування процесу, але token приймається лише з оточення процесу. Паралельні сесії мають використовувати різні userDataDir; launch-, CDP-, proxy-, GeoIP-, humanization-, context- і extensionPaths-налаштування несумісні з цим режимом.

Метадані середовища виконання Streamable HTTP¶

HTTP-клієнти з підтримкою потокової передачі можуть вибирати певні параметри виконання для кожного сеансу MCP, додаючи метадані, специфічні для мосту, до запиту initialize:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "proxyServer": "http://user:pass@proxy.example:8080",
        "proxyBypass": ".internal,localhost",
        "geoipProxyMatch": true,
        "headless": false,
        "humanize": true,
        "humanPreset": "careful",
        "userDataDir": "/absolute/path/to/profile",
        "contextOptions": {
          "viewport": { "width": 1280, "height": 720 },
          "locale": "en-US",
          "timezoneId": "America/New_York"
        },
        "extensionPaths": ["/absolute/path/to/extension"]
      }
    }
  }
}

proxyServer замінює PLAYWRIGHT_MCP_PROXY_SERVER для цієї сесії HTTP. proxyBypass замінює PLAYWRIGHT_MCP_PROXY_BYPASS лише тоді, коли proxyServer присутній. geoipProxyMatch може ввімкнути або вимкнути зіставлення за GeoIP для цієї сесії без перезапуску сервера MCP. Існуючі сесії зберігають свій проксі-сервер запуску; для зміни місцезнаходження створіть нову HTTP-сесію.

humanize може ввімкнути або вимкнути гуманізовану поведінку введення даних для цієї сесії, не впливаючи на інші сесії. humanPreset дозволяє вибрати default або careful для цієї сесії, але сам по собі не вмикає гуманізовану поведінку. Існуючі сесії зберігають поведінку, зафіксовану під час initialize.

У Docker значення headless: false за потреби запускає приватний віртуальний дисплей. Поза образом headed-сеансу все ще потрібне робоче середовище відображення.

userDataDir вмикає постійний профіль Chromium для цієї сесії та перевизначає PLAYWRIGHT_MCP_USER_DATA_DIR. Міст перетворює каталог на абсолютний шлях у форматі поточної платформи, створює його за відсутності, перевіряє доступність для запису та записує у згенероване browser.userDataDir. Постійний профіль вимикає стандартний ізольований профіль Streamable HTTP для цієї сесії. Міст відхиляє дубльовані активні каталоги профілю в межах одного процесу; конфлікти профілів між процесами залишаються помилками Chromium/Playwright.

contextOptions перевіряються та поверхнево об'єднуються поверх CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS; вкладені об'єкти замінюються цілком. Підтримувані поля: userAgent, viewport, locale, timezoneId, colorScheme, permissions, geolocation, extraHTTPHeaders, httpCredentials, ignoreHTTPSErrors, offline, deviceScaleFactor, isMobile і hasTouch. Довільна передача BrowserContextOptions у цьому випуску не підтримується.

extensionPaths мають указувати на наявні каталоги та потребують постійного userDataDir. Міст перетворює шляхи розширень на абсолютні шляхи поточної платформи, передає їх у CloakBrowser і записує згенеровані Chromium-аргументи --load-extension і --disable-extensions-except у згенеровану конфігурацію Playwright MCP.

Повноваження проксі-сервера HTTP з автентифікацією можна вбудувати в proxyServer, наприклад, http://user:pass@proxy.example:8080. Символи облікових даних, які мають значення в URL-адресі, слід кодувати у форматі «процент», наприклад @, :, /, ?, #, та %.

У підтримуваних бінарних файлах CloakBrowser автентифіковані HTTP-проксі використовують вбудовану автентифікацію в URL, а міст видаляє дубльований об'єкт проксі Playwright. Старіші бінарні файли зберігають об'єкт проксі Playwright як резервний варіант сумісності.

Щодо моделей контролю якості для декількох локацій див. GeoIP Proxy Matching. Щодо шаблонів реалістичності взаємодії див. Humanized Input Behavior.

Варіанти вибору джерела¶

Міст передає налаштування PLAYWRIGHT_MCP_* до верхнього рівня Playwright MCP. Сюди входять такі параметри верхнього рівня, як:

• PLAYWRIGHT_MCP_ALLOWED_ORIGINS
• PLAYWRIGHT_MCP_BLOCKED_ORIGINS
• PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS
• PLAYWRIGHT_MCP_CAPS
• PLAYWRIGHT_MCP_CONSOLE_LEVEL
• PLAYWRIGHT_MCP_IMAGE_RESPONSES
• PLAYWRIGHT_MCP_SNAPSHOT_MODE
• PLAYWRIGHT_MCP_STORAGE_STATE

Повний перелік опцій, що надаються розробниками Playwright MCP, дивіться в їхній документації.

PLAYWRIGHT_MCP_CAPS=devtools успадковується дочірнім upstream-процесом і вмикає інструменти цієї можливості без окремого прапорця моста --caps.

Ведення журналу¶

У режимі Streamable HTTP журнали запуску та запитів, зрозумілі для людини, записуються у stdout. У режимі stdio рутинні операційні журнали не виводяться, тому stdout MCP JSON-RPC залишається «чистим» з точки зору протоколу. Помилки запуску CLI, що призводять до збою, як і раніше, записуються у stderr.

HTTPS¶

Streamable HTTP за замовчуванням використовує локальний HTTP. Виберіть прямий TLS із --http-protocol https або CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL=https, а потім надайте пару сертифікат/ключ або файл PFX:

cloakbrowser-mcp --transport streamable-http \
  --http-protocol https \
  --https-cert ./cert.pem \
  --https-key ./key.pem

Для зовнішнього доступу або доступу без використання функції loopback використовуйте протокол HTTPS разом із --http-auth-token або завершуйте з’єднання TLS на надійному зворотньому проксі-сервері, який також забезпечує аутентифікацію та контроль доступу до мережі.

Сесії HTTP, що підтримують потокову передачу даних¶

Кожен сеанс Streamable HTTP MCP має власне середовище виконання мосту та дочірній процес Playwright MCP, що працює вище за ланцюгом. Сеанси HTTP запускають Playwright MCP з ізольованим профілем браузера, щоб одночасні користувачі не змагалися за один і той самий постійний профіль Chromium. Вбудований бекенд сеансів memory зберігає лише метадані, такі як ідентифікатор сеансу, мітки часу, термін дії та статус. Стан браузера зберігається в активному дочірньому процесі, а артефакти як і раніше контролюються PLAYWRIGHT_MCP_OUTPUT_DIR.

Для горизонтального масштабування запустіть кілька реплік сервера за балансувальником навантаження з використанням «прив’язаних» сесій, що ідентифікуються за заголовком mcp-session-id. Майбутні бекенди Redis, Postgres або SQLite зможуть координувати метадані та блокування, але вони не зможуть відновити активну сесію браузера після завершення процесу, якому вона належить.

HTTP-зонди, що підтримують потокову передачу даних¶

Коли міст працює з --transport streamable-http, він надає доступ до фіксованих кінцевих точок зондування на тому самому хості та порту, що й кінцева точка MCP:

• GET /healthz повертає метадані про стан процесу: status, version, transport та uptimeMs.
• GET /readyz повертає метадані готовності та ємність сеансу: sessions.active, sessions.pending, sessions.max та sessions.available.

Функція готовності повертає HTTP 200, поки є вільні ресурси сеансу, та HTTP 503, коли active + pending >= max. Якщо налаштовано --http-auth-token або CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN, обидва зонди вимагають того самого заголовка Authorization: Bearer ..., що й запити MCP. Без токена автентифікації зонди відкриті на налаштованій адресі прив'язки HTTP.

Додаткові практичні сценарії¶

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