Сопоставление прокси-серверов по GeoIP¶

Сопоставление прокси по GeoIP обеспечивает согласованность настроек «отпечатка» браузера с местоположением прокси, используемого вышестоящим Playwright MCP. Это полезно, когда региональное тестирование качества зависит от постоянного прокси, часового пояса, языка и профиля локали.

Мост сам по себе не создает и не маршрутизирует прокси-трафик. Маршрутизация прокси-трафика по-прежнему осуществляется вышестоящим Playwright MCP через PLAYWRIGHT_MCP_PROXY_SERVER. Когда включено сопоставление, MCP CloakBrowser определяет настроенное местоположение прокси и добавляет соответствующие флаги запуска CloakBrowser для часового пояса, языка браузера и локаля отпечатка.

Что изменится¶

Когда CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true, мост может добавить следующие параметры запуска для CloakBrowser:

• --fingerprint-timezone
• --lang
• --fingerprint-locale

Это позволяет обеспечить внутреннюю согласованность профиля браузера с регионом прокси-сервера. Схемы инструментов 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.

Настройка Docker¶

Передайте те же переменные в контейнер. По возможности храните учетные данные прокси в вашем менеджере секретов или в среде клиента MCP.

docker run --rm --init -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 --init -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-кодированного значения и передавать его через секретные данные или конфигурацию среды выполнения клиента, а не фиксировать в файлах проекта.

Варианты использования¶

Приоритет и ограничения¶

Данные о местоположении по GeoIP являются приблизительными и зависят от IP-адреса прокси-сервера и базы данных GeoIP CloakBrowser. CloakBrowser загружает и кэширует эту автономную базу данных при первом использовании, когда в ней возникает необходимость.

Используйте эту функцию для проведения надлежащего контроля качества, локализации и тестирования согласованности сред. Её не следует рассматривать как способ обойти средства контроля доступа или проверки региональных политик.

Связанные настройки¶

• Конфигурация содержит список всех переменных среды для моста и вышестоящих компонентов.
• Docker объясняет настройки по умолчанию среды выполнения контейнеров и публикацию Streamable HTTP.
• Инструменты объясняет, почему браузерные инструменты Playwright MCP, расположенные выше по потоку, перенаправляются без изменений.

Дополнительные практические сценарии¶

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