Сопоставление прокси-серверов по GeoIP¶
Сопоставление прокси по GeoIP обеспечивает согласованность настроек «отпечатка» браузера с местоположением прокси, используемого вышестоящим Playwright MCP. Это полезно, когда региональное тестирование качества зависит от постоянного прокси, часового пояса, языка и профиля локали.
Пошаговые инструкции: Региональный QA через прокси.
Мост сам не создает и не маршрутизирует прокси-трафик. Он передает PLAYWRIGHT_MCP_PROXY_SERVER в подготовку запуска CloakBrowser. Когда сопоставление включено, CloakBrowser определяет местоположение выхода настроенного прокси и добавляет соответствующие флаги запуска для часового пояса, языка браузера, локали отпечатка и IP-адреса WebRTC.
Что изменится¶
Когда CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true, мост может добавить следующие параметры запуска для CloakBrowser:
--fingerprint-timezone--lang--fingerprint-locale--fingerprint-webrtc-ip
Это позволяет обеспечить внутреннюю согласованность профиля браузера с регионом прокси-сервера. Схемы инструментов Playwright MCP и инструментов браузера, расположенных выше по цепочке, по-прежнему передаются без изменений.
Глобальные настройки¶
Используйте переменные среды на уровне процесса для клиентов stdio и в качестве значений по умолчанию для сеансов Streamable HTTP:
PLAYWRIGHT_MCP_PROXY_SERVER="http://user:pass@proxy.example:8080" \
CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true \
npx -y cloakbrowser-mcp@latest
Добавьте список обхода, если некоторым хостам следует обойти прокси:
PLAYWRIGHT_MCP_PROXY_SERVER="http://user:pass@proxy.example:8080" \
PLAYWRIGHT_MCP_PROXY_BYPASS=".internal,localhost" \
CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true \
npx -y cloakbrowser-mcp@latest
Поддерживаются HTTP-прокси с аутентификацией за счёт встраивания учетных данных в PLAYWRIGHT_MCP_PROXY_SERVER. Специальные символы в учетных данных следует кодировать в формате «процент-кодировки», например, используйте p%40ssword вместо p@ssword.
Поддерживаемые бинарные файлы CloakBrowser используют встроенную аутентификацию в URL и сообщают реальный IP-адрес выхода прокси, даже если прокси требует строгого аутентифицированного запроса CONNECT. Старые бинарные файлы сохраняют объект прокси Playwright как резервный вариант совместимости.
Настройка Docker¶
Передайте те же переменные в контейнер. По возможности храните учетные данные прокси в вашем менеджере секретов или в среде клиента MCP.
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
Для Streamable HTTP в Docker опубликуйте HTTP-порт как обычно и оставьте переменные прокси в значениях по умолчанию для среды контейнера:
docker run --rm -p 127.0.0.1:3000:3000 \
-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 \
--transport streamable-http --http-host 0.0.0.0 --http-port 3000
HTTP-прокси с поддержкой потоковой передачи данных на уровне сеанса¶
HTTP-клиенты с поддержкой потоковой передачи данных могут выбирать прокси-сервер при инициализации сеанса MCP. Это позволяет одному долго работающему серверу MCP обрабатывать запросы из разных регионов без необходимости его перезапуска.
Отправьте метаданные моста в запросе initialize:
{
"params": {
"_meta": {
"io.github.swimmwatch/cloakbrowser-mcp": {
"proxyServer": "http://user:pass@proxy.example:8080",
"proxyBypass": ".internal,localhost",
"geoipProxyMatch": true
}
}
}
}
proxyServer переопределяет PLAYWRIGHT_MCP_PROXY_SERVER для данного HTTP-сеанса. proxyBypass переопределяет PLAYWRIGHT_MCP_PROXY_BYPASS только в том случае, если proxyServer присутствует. Если proxyServer присутствует, а proxyBypass опущен, наследуемая конфигурация обхода прокси для данного сеанса сбрасывается.
geoipProxyMatch переопределяет настройку GeoIP на уровне процесса для данного HTTP- сеанса. Используйте true, чтобы включить сопоставление для сеанса, или false, чтобы отключить его, даже если сервер был запущен с включенным сопоставлением.
Существующие HTTP-сессии являются неизменяемыми. Создайте ещё одну HTTP-сессию Streamable, чтобы переключиться на другой прокси-сервер или другое местоположение.
Если proxyServer содержит учетные данные, следует сохранять их в виде URL-кодированного значения и передавать его через секретные данные или конфигурацию среды выполнения клиента, а не фиксировать в файлах проекта.
Варианты использования¶
- QA локализованной коммерции
Проверяйте оформление заказа, налоги, сообщения о доставке, валюту и региональные правила каталога с часовым поясом и локалью браузера, согласованными с местоположением прокси.
- Региональные лендинги
Проверяйте язык, согласия, кампании и варианты контента, которые зависят от региона посетителя.
- Воспроизведение обращений поддержки
Воспроизводите отчет из региона клиента без перезапуска всего MCP-сервера для каждого местоположения прокси.
- Сценарии, чувствительные к часовому поясу
Проверяйте выбор дат, окна бронирования, напоминания и страницы планирования, где часовой пояс и локаль должны соответствовать сетевому региону.
- Параллельные региональные сеансы
Запускайте отдельные сеансы Streamable HTTP с разными прокси, чтобы агент мог сравнивать несколько регионов в одном серверном процессе.
Приоритет и ограничения¶
| Область | Поведение |
|---|---|
| Stdio | Использует только переменные среды и флаги CLI уровня процесса. |
| Значение по умолчанию Streamable HTTP | Использует переменные среды и флаги CLI уровня процесса, если метаданные времени выполнения не переданы. |
| Метаданные Streamable HTTP | initialize.params._meta["io.github.swimmwatch/cloakbrowser-mcp"] может переопределить прокси и сопоставление GeoIP для одного сеанса. |
| Существующие сеансы | Сохраняют прокси и настройку GeoIP, зафиксированные во время initialize. |
| Аутентифицированный HTTP-прокси | Использует встроенную аутентификацию CloakBrowser в URL на поддерживаемых бинарных файлах и объект прокси Playwright на старых бинарных файлах. |
| Необработанные флаги часового пояса/локали | Явные значения --fingerprint-timezone, --lang и --fingerprint-locale в CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS имеют приоритет над значениями GeoIP и не дублируются. |
| API геолокации браузера | Эта функция его не настраивает; она только согласует флаги отпечатка часового пояса, языка и локали CloakBrowser. |
Данные о местоположении по GeoIP являются приблизительными и зависят от IP-адреса прокси-сервера и базы данных GeoIP CloakBrowser. CloakBrowser загружает и кэширует эту автономную базу данных при первом использовании, когда в ней возникает необходимость.
Например, следующая конфигурация сохраняет явные часовой пояс и локаль, но продолжает использовать сопоставление GeoIP для определения IP-адреса выхода прокси:
PLAYWRIGHT_MCP_PROXY_SERVER="http://user:pass@proxy.example:8080" \
CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true \
CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS='["--fingerprint-timezone=America/New_York","--lang=en-US","--fingerprint-locale=en-US"]' \
npx -y cloakbrowser-mcp@latest
Используйте эту функцию для проведения надлежащего контроля качества, локализации и тестирования согласованности сред. Её не следует рассматривать как способ обойти средства контроля доступа или проверки региональных политик.
Сопоставление GeoIP останавливает запуск, если CloakBrowser не может определить IP выхода прокси, загрузить или прочитать базу GeoIP либо получить часовой пояс. Начиная с CloakBrowser 0.6.3, отсутствие страны в таблице локалей вызывает предупреждение и выбор en-US; для Сейшельских Островов используется en-SC. Разрешение GeoIP ограничено 20 секундами; первичная загрузка автономной базы не входит в этот лимит и может занять больше времени.
Связанные настройки¶
- Конфигурация содержит список всех переменных среды для моста и вышестоящих компонентов.
- Docker объясняет настройки по умолчанию среды выполнения контейнеров и публикацию Streamable HTTP.
- Инструменты объясняет, почему браузерные инструменты Playwright MCP, расположенные выше по потоку, перенаправляются без изменений.
Дополнительные практические сценарии¶
Для выбора между upstream Playwright MCP и этим пакетом используйте сравнение. Для быстрых задач используйте рецепты: постоянный профиль, расширения, reverse proxy, региональное QA, Claude Desktop, Codex CLI и smoke-тест CI.
CloakBrowser 0.6.0¶
Когда SOCKS5 или HTTP-прокси с аутентификацией задан флагом браузера --proxy-server, context.request, page.request и route.fetch() не используют этот прокси. Для запросов через маршрут браузера используйте fetch() внутри страницы. Мост не подключает автоматическое предупреждение CloakBrowser.