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

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

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

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

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

Встановити CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true разом із PLAYWRIGHT_MCP_PROXY_SERVER для визначення прапорців часового поясу, мови та локалі CloakBrowser на основі розташування проксі-сервера. Міст залишає маршрутизацію проксі-сервера за делегованим вищестоящим Playwright MCP, і лише вводить вирішені прапори запуску --fingerprint-timezone, --lang та --fingerprint-locale.

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

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

Встановіть 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 із літерами дисків.

Метадані середовища виконання 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.

headless дозволяє ввімкнути або вимкнути режим браузера без графічного інтерфейсу для даного сеансу. Для зміни значення headless на false необхідне робоче середовище з дисплеєм, особливо при розгортаннях у Docker або на серверах під управлінням Linux.

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-адресі, слід кодувати у форматі «процент», наприклад @, :, /, ?, #, та %.

Щодо моделей контролю якості для декількох локацій див. 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, дивіться в їхній документації.

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

У режимі 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.