Архітектура¶

Час виконання¶

cloakbrowser-mcp — це зовнішній сервер MCP, який може надавати доступ до stdio або Streamable HTTP. Під час запуску він:

розпаковує або встановлює бінарний файл CloakBrowser на базі Chromium;
створює тимчасовий файл конфігурації Playwright MCP;
запускає верхній процес @playwright/mcp як дочірній процес через stdio;
підключається до цього дочірнього процесу за допомогою транспортного протоколу клієнта MCP SDK;
надає доступ до зовнішнього сервера MCP клієнту MCP користувача через обраний транспортний протокол;
пересилає список інструментів та виклики інструментів до верхнього рівня без змін;
додає 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 застосовується правило «перезапуск перед пересиланням»:

паралельні виклики браузера використовують одну обмежену перезавантаження;
стару дитину стає недосяжною і видаляють;
дитина-замінник використовує ту саму конфігурацію сеансу та новий внутрішній порт;
власність та зовнішня готовність перевіряються перед публікацією;
Очікувані виклики браузера пересилаються кожен рівно один раз до готової заміни.

Якщо готовність не вдається, жоден виклик браузера у режимі очікування не досягає верхнього дочірнього елемента, жодних можливостей опубліковано, і наступний виклик браузера може розпочати нову обмежену спробу. Стан браузера такі як вкладки та зберігання в пам'яті не відновлюються після заміни. Локальні інструменти, список інструментів, читання виявлення та звичайні відключення 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 на верхньому рівні та зберігає стандартну поведінку профілю Playwright MCP на верхньому рівні. Для Streamable HTTP кожна сесія MCP має власний зовнішній сервер, дочірній процес, згенеровану конфігурацію та стан транспорту в пам’яті. Сесії HTTP запускають Playwright MCP з ізольованими профілями браузера, щоб одночасні користувачі не ділили між собою й не змагалися за один і той самий постійний профіль Chromium.

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

Міст використовує MCP SDK StreamableHTTPServerTransport для Streamable HTTP. Він не надає доступ до застарілого MCP SSEServerTransport або застарілу кінцеву точку /sse.