Интеграция агентов MCP

MCP-сервер Sa2web предоставляет удаленный браузер как стандартные MCP-инструменты для Claude Code, Claude Desktop, Cursor, Windsurf, VS Code Copilot, Cline, Roo Code, opencode, Gemini CLI, Zed, Hermes Agent и OpenClaw.

Проект MCP открыт на sa2web/sa2web-mcp и опубликован в npm как @sa2web/mcp.

Для прямой работы из терминала см. CLI удаленного браузера.

Целевой сайт отображается в iframe#rbi-frame, которым сервер управляет через Playwright.

Установка

Установите Node.js 18 или новее, затем установите npm-пакет глобально:

bash

npm install @sa2web/mcp -g
npx playwright install --with-deps

После этого доступны sa2, sa2-browser и MCP-вход sa2-mcp.

Для разработки из исходников клонируйте публичный репозиторий и соберите проект:

bash

git clone https://github.com/sa2web/sa2web-mcp.git
cd sa2web-mcp
npm install
npx playwright install --with-deps
npm run build

Настройка клиента

После глобальной установки укажите sa2-mcp напрямую:

json

{
  "mcpServers": {
    "sa2-remote-browser": {
      "command": "sa2-mcp",
      "env": {
        "SA2_LOGIN_URL": "https://<APP_DOMAIN>/agent/login?clientId=...&clientSecret=...",
        "SA2_LOGIN_REDIRECT_PATH": "/app/login",
        "SA2_HEADLESS": "false",
        "SA2_IGNORE_HTTPS_ERRORS": "true"
      }
    }
  }
}

Если клиент не находит глобальные команды, укажите полный путь к sa2-mcp или используйте node /absolute/path/to/sa2web-mcp/dist/server.js из локальной сборки.

json

{
  "mcpServers": {
    "sa2-remote-browser": {
      "command": "node",
      "args": ["/absolute/path/to/sa2web-mcp/dist/server.js"],
      "env": {
        "SA2_LOGIN_URL": "https://<APP_DOMAIN>/agent/login?clientId=...&clientSecret=...",
        "SA2_LOGIN_REDIRECT_PATH": "/app/login",
        "SA2_HEADLESS": "false",
        "SA2_IGNORE_HTTPS_ERRORS": "true"
      }
    }
  }
}

VS Code Copilot использует корневое поле servers, opencode — mcp, Zed — context_servers. Для Hermes Agent добавьте сервер в mcp_servers файла ~/.hermes/config.yaml, для OpenClaw — в mcp.servers конфигурации Gateway. Перезапустите клиент и убедитесь, что появился sa2_help.

Учетные данные

Не сохраняйте настоящий clientSecret в Git или документации. Немедленно заменяйте раскрытые учетные данные.

Основные переменные

Переменная	По умолчанию	Назначение
`SA2_LOGIN_URL`	нет	Обязательный URL входа; из него определяется origin удаленного браузера
`SA2_AUTO_LOGIN_BEFORE_NAVIGATE`	`true`	Автоматический вход перед открытием цели
`SA2_HEADLESS`	`false`	Запуск Playwright без интерфейса
`SA2_BROWSER`	`chromium`	`chromium`, `firefox` или `webkit`
`SA2_IGNORE_HTTPS_ERRORS`	`true`	Игнорировать ошибки HTTPS-сертификатов; `false` требует действительные сертификаты
`SA2_RBI_FRAME_CONTENT_WAIT_MS`	`15000`	Ожидание содержимого iframe
`SA2_NAVIGATION_TIMEOUT_MS`	`45000`	Тайм-аут навигации
`SA2_ACTION_TIMEOUT_MS`	`15000`	Тайм-аут действий
`SA2_LOG_STDERR`	`true`	Вывод журналов в stderr; stdout остается для MCP
`SA2_LOG_FILE`	нет	Необязательный файл журнала

Устаревшие SA2_REMOTE_BROWSER_PREFIX и SA2_REMOTE_BROWSER_BASE_URL настраивать не нужно.

Полный справочник инструментов

Ниже описаны все инструменты текущего сервера. Параметры относятся к объекту MCP arguments.

Инструмент	Назначение, основные параметры и результат
`sa2_help`	Без параметров. Возвращает рекомендуемый процесс, примеры и список совместимых инструментов.
`sa2_list_available_targets`	Перечисляет прокси, SaaS, аккаунты workspace и внутренние сайты со стабильными `targetId`.
`sa2_open_target`	Рекомендуемая навигация: `type=cloud` + `url`, либо `targetId`/тип + `id`/`name`; поддерживает `surf`, `waitUntil`.
`browser_open_login`	Открывает `SA2_LOGIN_URL`; необязательный `waitUntil`. Используется для диагностики входа.
`browser_navigate`	Совместимая навигация по URL: обязателен `url`, необязательны `surf`, `waitUntil`.
`browser_navigate_back`	Назад через внешнюю панель. После этого обновите snapshot.
`browser_navigate_forward`	Вперед через внешнюю панель.
`browser_reload`	Перезагрузка через внешнюю панель; старые refs становятся недействительными.
`browser_list_proxies`	Возвращает free-browse, прокси и options, включая `direct`.
`browser_list_saas_sites`	Возвращает категории SaaS и плоский список `sites`.
`browser_enter_saas_site`	Открывает SaaS по `id` или `name`; необязательный `waitUntil`.
`browser_list_workspaces`	Возвращает данные workspace и цели на уровне аккаунтов.
`browser_enter_workspace`	Открывает аккаунт по `accountId` либо `siteId` + `username`.
`browser_list_inner_sites`	Возвращает доступные внутренние сайты.
`browser_enter_inner_site`	Открывает внутренний сайт по `id` или `name`.
`browser_snapshot`	Необязательный настоящий CSS `filter`. Возвращает семантический snapshot; для действий используйте `ref=eN`, не `id=tN`.
`browser_extract_text`	Необязательный настоящий CSS `selector`. Возвращает видимый текст дерева iframe.
`browser_click`	Клик по ref, selector, `role`/`name`, `text` или координатам `x`/`y`.
`browser_type`	Обязателен `text`; цель по ref/selector/role, поддерживает `append`, `pressEnter`.
`browser_press`	Обязателен `key`, например `Enter`, `Escape`, `Control+A`.
`browser_press_key`	Совместимый псевдоним `browser_press` с теми же параметрами.
`browser_wait`	Ожидает `selector`, `text`, `urlIncludes` или `ms` (по умолчанию 1000).
`browser_scroll`	Прокрутка root/элемента в режиме `by`, `to`, `intoView`; без параметров вниз на 600 px.
`browser_hover`	Наведение по ref, selector, role/name или тексту.
`browser_drag`	Перетаскивание от `startRef`/`startSelector` к `endRef`/`endSelector`.
`browser_fill_form`	Последовательно заполняет массив `fields` с locator и обязательным `value`.
`browser_select_option`	Находит select по ref/selector, выбирает по `values`, `value`, `label` или `index`.
`browser_check`	Устанавливает checkbox/radio по ref, selector, role/name или тексту.
`browser_uncheck`	Снимает checkbox; radio не поддерживается.
`browser_file_upload`	Загружает доступные серверу `path`/`paths` через найденный file input.
`browser_paste`	Вставляет `text`, `html`, `rtf` и/или файлы в цель или активный элемент.
`browser_handle_dialog`	Принимает/отклоняет alert, confirm, prompt; `accept` по умолчанию true, доступны `promptText`, `timeoutMs`.
`browser_resize`	Требует положительные `width`, `height`; меняет desktop или размеры активной эмуляции.
`browser_list_devices`	Без параметров и открытия страницы. Возвращает `Desktop` и устройства Playwright с viewport, screen, DPR, touch/mobile и браузером.
`browser_toggle_device`	Меняет эмуляцию без пересоздания context. Принимает `enabled`, `device`, размеры, DPR, touch, UA, orientation, reload; возвращает state, `observed`, `targetObserved`, warnings.
`browser_screenshot`	Возвращает PNG; `fullPage` по умолчанию `false`.
`browser_take_screenshot`	Совместимый снимок; `fullPage` по умолчанию `true`.
`browser_evaluate`	Выполняет `expression` с необязательным `arg` в iframe, возвращает JSON.
`browser_run_code`	Выполняет асинхронный `code` с `page`, `rootFrame`, helpers. Только доверенный код.
`browser_close`	Закрывает browser/context и очищает refs, вход, dialogs, CDP и состояние устройства.

Переключение устройства

Сначала вызовите browser_list_devices, затем, например, browser_toggle_device с { "device": "Pixel 7", "orientation": "portrait" }. Cookies и вход сохраняются. reload: true применяет новый UA к последующим запросам, а { "device": "Desktop" } восстанавливает прежний desktop viewport.

Chromium через CDP изменяет viewport, screen, DPR, touch, orientation и UA. Firefox/WebKit динамически меняют только viewport и возвращают ограничение в warnings. observed измеряет внешнюю оболочку, targetObserved — целевой iframe. После переключения обновите snapshot.

Безопасность и устранение неполадок

Перед публикацией, отправкой, удалением, покупкой, авторизацией, денежным переводом или отправкой сообщений обязательно получите явное подтверждение пользователя.

Инструменты не появились: проверьте сборку и абсолютные пути к node и dist/server.js, затем перезапустите клиент.
Ошибка входа: проверьте SA2_LOGIN_URL, учетные данные и состояние аккаунта.
Видна только панель: вызовите browser_wait или увеличьте время ожидания iframe.
Элемент не найден: сделайте новый snapshot и используйте последний ref=eN.

Интеграция агентов MCP ​

Установка ​

Настройка клиента ​

Основные переменные ​

Рекомендуемый порядок ​

Полный справочник инструментов ​

Переключение устройства ​

Безопасность и устранение неполадок ​