Настройка¶

Используйте переменные PLAYWRIGHT_MCP_* на входе для обеспечения поведения Playwright MCP. Используйте CLOAK_PLAYWRIGHT_MCP_* только для поведения моста, специфичного для Cloak.

Старые переменные CLOAKBROWSER_MCP_* не поддерживаются. Сгенерированный Справочник CLI является авторитетным списком флагов CLI моста и соответствующих им переменных среды.

Параметры моста¶

Управляемый CDP¶

Управляемый доступ к протоколу Chrome DevTools (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. Включённая сессия без пула портов отвергается до того, как начнёт работу её дочерний поток вверх по цепочке. Эффективное ложное значение не создаёт ни слушателя, ни аренды порта, ни возможности.

Для 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 открытие и wss WebSocket URL-адреса только. Мост не предоставляет TLS для управляемого CDP: его внешний слушатель и Chromium хоп остается в открытом виде 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 и вход через 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. Мост сохраняет эту ошибку: он не маскирует её и не переключается молча на другой браузер или тариф лицензии.

Канал выпуска 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 для ознакомления с примерами настройки, метаданными прокси-серверов Streamable 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. Шаблоны реалистичности взаимодействия см. в разделе 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

Ознакомьтесь с исходной документацией по MCP для Playwright, чтобы узнать о полном наборе доступных опций.

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, а при наличии 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.