Перейти к содержанию

Архитектура

Время выполнения

cloakbrowser-mcp — это внешний сервер MCP, который может предоставлять доступ к stdio или Streamable HTTP. При запуске он:

  1. извлекает или устанавливает бинарный файл CloakBrowser на базе Chromium;
  2. создаёт временный файл конфигурации Playwright MCP;
  3. запускает исходный процесс @playwright/mcp в качестве дочернего процесса через stdio;
  4. подключается к этому дочернему процессу с помощью транспортного протокола клиента MCP SDK;
  5. предоставляет доступ к внешнему серверу MCP клиенту MCP пользователя через выбранный транспортный протокол;
  6. пересылает список инструментов и вызовы инструментов без изменений;
  7. добавляет cloakbrowser_binary_info и cloakbrowser_bridge_info.

Почему именно такой дизайн

Проект Playwright MCP, разрабатываемый на верхнем уровне, уже владеет контрактами браузерных инструментов и быстро развивается. Модель «моста» позволяет сохранить компактность этого проекта и избежать дублирования логики автоматизации браузера.

Управляемое владение CDP

Управляемый CDP — это необязательная вторая панель управления для того же поколения браузера:

MCP client -> outer bridge -> upstream Playwright MCP child -> Chromium
                    |                    |                    |-- Playwright pipe
                    |                    `-- generated config `-- internal loopback CDP
                    `-- external capability proxy <--------- CDP client

Сессия MCP владеет арендой внешнего порта, прокси-способностью, сгенерированной на стороне источника конфигурация, заменяемый вышестоящий дочерний элемент и текущее поколение Chromium. CDP клиент никогда не подключается напрямую к внутренней петлевой конечной точке. Bootstrap размещает однократный вызов страницы браузера через MCP и использование его через CDP до внешняя возможность опубликована. внутренний процесс удаленной отладки Playwright остается активный наряду с управляемой мостом TCP-точкой

Аренда внешнего порта стабильна для сессии MCP, в то время как дочерний процесс, внутренний конец, номер поколения и возможность URL заменяемы. Браузер потеря делает текущую способность недействительной и закрывает её проксированные сокеты, но не запустить ребёнка в фоновом режиме. Первый последующий вызов browser_* MCP применяется правило перезапуска перед пересылкой:

  1. одновременные вызовы браузера используют одну ограниченную перезагрузку;
  2. старый объект child становится недоступным и удаляется;
  3. дочерний процесс замены использует ту же конфигурацию сеанса и новый внутренний порт;
  4. владение и внешняя готовность проверяются перед публикацией;
  5. Ожидающие вызовы браузера перенаправляются к готовой замене точно один раз.

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

Очистка отменяет достижимость: остановить приём, аннулировать возможность, закрыть прокси сокеты, избавиться от вышестоящего дочернего процесса и браузера, закрыть внешний слушатель, затем освободите порт. Это предотвращает скрытый переход старого URL на новый браузер.

Команды MCP и CDP могут выполняться одновременно. Мост не добавляет кросс-протокольность транзакции или определить, какой вызывающий владеет страницей; вызывающие должны координировать деструктивное или противоречивые операции.

Docker

Образ Docker использует закрепленный официальный образ Playwright MCP в качестве базового образа. Бридж установлен под именем /opt/cloakbrowser-mcp, в то время как исходный образ Playwright MCP по-прежнему доступен по адресу /app/cli.js.

Настройка

Бридж записывает временную конфигурацию в формате JSON с параметрами запуска CloakBrowser. Переменные среды PLAYWRIGHT_MCP_* из верхнего уровня по-прежнему передаются в Playwright MCP верхнего уровня.

Транспорт

Транспорт по умолчанию — stdio. Потоковый HTTP явно включается с помощью --transport streamable-http или CLOAK_PLAYWRIGHT_MCP_TRANSPORT=streamable-http.

В случае stdio один внешний сервер управляет одним дочерним процессом Playwright MCP на стороне upstream и сохраняет поведение профиля по умолчанию для Playwright MCP на стороне upstream. В случае Streamable HTTP каждый сеанс MCP имеет собственный внешний сервер, дочерний процесс на стороне Playwright MCP, сгенерированную конфигурацию и состояние транспорта в памяти. Сеансы HTTP запускают Playwright MCP с изолированными профилями браузера, чтобы одновременно работающие пользователи не использовали один и тот же постоянный профиль Chromium и не конкурировали за него.

Бэкенд сессии хранит только метаданные. Встроенным бэкендом является memory; будущие адаптеры Redis, Postgres или SQLite смогут координировать метаданные и блокировки, но они не смогут восстановить активный процесс браузера на стороне клиента после завершения работы серверного процесса, которому он принадлежит. При горизонтальном масштабировании следует использовать «прилипающие» сессии, индексированные по ключу mcp-session-id.

Мост использует MCP SDK StreamableHTTPServerTransport для Streamable HTTP. Он не предоставляет доступ к устаревшему MCP SSEServerTransport или устаревшую конечную точку /sse.