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

Инструменты

cloakbrowser-mcp предоставляет upstream-инструменты Playwright MCP без изменений. Имена инструментов, описания, схемы, аннотации и ответы поступают из @playwright/mcp.

Upstream-инструменты

Ожидается, что стандартная поверхность upstream-инструментов браузера соответствует закрепленной зависимости Playwright MCP. Она включает основные браузерные инструменты: навигацию, snapshot, клики, ввод текста, скриншоты, вкладки, сообщения консоли, проверку сети, загрузку файлов, диалоги и небезопасные инструменты выполнения.

Стабильный источник для Playwright MCP @playwright/mcp@0.0.83 — тест возможностей на коммите этого пакета: стандартные инструменты и инструменты дополнительных возможностей. Текущий набор инструментов определяется установленной зависимостью.

Этот проект считает upstream Playwright MCP авторитетным источником и не поддерживает копию справочника схем.

Базовый набор содержит 25 upstream-инструментов, включая browser_emulate_media. PLAYWRIGHT_MCP_CAPS=devtools передаёт возможность devtools дочернему процессу без флага моста --caps; результирующие upstream-инструменты и схемы передаются без изменений, включая browser_start_recording и browser_stop_recording.

Ограничение записи с публичным бинарным файлом CloakBrowser v146

Инструменты записи доступны, однако публичный бинарный файл Chromium 146 без ключа намеренно отключает связь Playwright между страницей и хостом ради скрытности. Поэтому browser_stop_recording может возвращать неполный код: навигация записывается, а успешно выполненные ввод и клики пропускаются. Проверяйте сгенерированные записи перед повторным использованием.

Совместимость с явным включением отслеживается в CloakBrowser #532. Решение об отключении базовой связи обсуждается в #340 и #176.

Динамические инструменты WebMCP

Поддержка WebMCP зависит от выбранной сборки браузера и включённых возможностей. Установленный Playwright MCP ожидает document.modelContext или navigator.modelContext с методом getTools(). Если WebMCP необходим, используйте совместимую сборку CloakBrowser или PLAYWRIGHT_MCP_BROWSER_ENGINE=playwright.

Документация Chrome по WebMCP описывает origin trial начиная с Chrome 149, флаг для локальной проверки и ограничения headless-режима. Один номер версии Chromium не гарантирует совместимость с API, ожидаемым Playwright MCP.

Когда Chromium запускается с --enable-features=WebMCP, Playwright MCP может добавлять предоставляемые страницей инструменты с именами webmcp_*, пока страница открыта. Эти инструменты динамические: мост объявляет tools.listChanged, сбрасывает весь кеш постраничного списка инструментов, когда upstream отправляет notifications/tools/list_changed, и пересылает уведомление MCP-клиенту соответствующей сессии. Клиентам следует слушать это уведомление и повторно вызывать tools/list. Клиент Streamable HTTP получает уведомление только при открытом потоке уведомлений своей сессии; следующий вызов tools/list всё равно возвращает актуальный список, даже если поток не был открыт.

Динамические инструменты принадлежат только MCP-сессии и текущему поколению браузера managed CDP, которое их обнаружило. Их имена, описания, схемы, аннотации и результаты являются недоверенным содержимым страницы и пересылаются без изменений со стороны моста. Проверяйте их перед вызовом. Установите PLAYWRIGHT_MCP_WEBMCP=false, чтобы отключить сбор. Мост никогда не включает Chromium WebMCP автоматически.

Локальные инструменты

cloakbrowser_binary_info

Возвращает структурированную информацию о пакете CloakBrowser, текущей платформе, каталоге кэша, ожидаемом пути к бинарному файлу, состоянии установки и разрешенном executable path, который использует мост.

cloakbrowser_bridge_info

Возвращает структурированные метаданные моста:

  • имя и версию MCP-сервера;
  • режим выполнения;
  • пакет и версию upstream Playwright MCP;
  • количество upstream-инструментов;
  • имена локальных Cloak-specific инструментов.

Дополнительный объект structuredContent.cdp сообщает состояние managed CDP вызывающей сессии:

{ "enabled": false }
{
  "enabled": true,
  "state": "ready",
  "generation": 1,
  "bindHost": "127.0.0.1",
  "port": 9222,
  "advertisedHost": null,
  "discoveryUrl": "http://127.0.0.1:9222/cdp/<capability>",
  "activeConnections": 0
}
{
  "enabled": true,
  "state": "unavailable",
  "generation": 1,
  "bindHost": "127.0.0.1",
  "port": 9222,
  "advertisedHost": null,
  "discoveryUrl": null,
  "activeConnections": 0
}

generation увеличивается, а discoveryUrl меняется после замены браузера. activeConnections считает принятые проксируемые соединения WebSocket, не раскрывая идентификаторы клиентов, идентификаторы целей или содержимое протокола. Считайте каждый URL обнаружения, отличный от null, учётными данными.

Используйте URL обнаружения с клиентом, поддерживающим CDP:

import { chromium } from 'playwright';

const browser = await chromium.connectOverCDP(discoveryUrl);

Managed CDP не является протоколом Playwright Server. Метод Playwright chromium.connect() и текущая интеграция Open WebUI PLAYWRIGHT_WS_URL ожидают конечную точку Playwright Server и несовместимы с этим URL.

Для закреплённой версии клиента Playwright проверено, что вызов browser.close() у браузера, возвращённого connectOverCDP(), отключает этот клиент, оставляя Chromium и поколение браузера готовыми к работе. Это наблюдение относится к конкретному клиенту и не является гарантией для других библиотек CDP. Отправка команды CDP Browser.close напрямую разрушительна: она завершает общее поколение Chromium, аннулирует capability и влияет на вызывающие MCP клиенты. Координируйте операции MCP и CDP, поскольку мост не упорядочивает конфликтующие операции навигации, закрытия страниц, ввода или изменения хранилища.

Набор локальных инструментов ограничен этими двумя инструментами диагностики. SessionSeats и getSessionSeats не предоставляются как MCP-инструмент, поскольку поддерживаемая публичная точка входа CloakBrowser не экспортирует этот API.

Совместимость

CI собирает Docker-образ и запускает npm run bridge:compare. Этот скрипт параллельно запускает официальный образ Playwright MCP и образ моста CloakBrowser, сравнивает список upstream-инструментов и выполняет стандартные upstream-браузерные инструменты на одной fixture-странице.

Используйте --report, чтобы записать машиночитаемый JSON-отчет:

npm run bridge:compare -- cloakbrowser-mcp:dev --report bridge-parity-report.json

CI загружает этот отчет как артефакт для Docker-сборок и релизных сборок.