CLI удаленного браузера

CLI из MCP-проекта Sa2web запускает тот же MCP-сервер через stdio и преобразует команды в вызовы инструментов sa2_* или browser_*. Он подходит для ручных тестов, сценариев автоматизации и проверки подключения.

Проект опубликован на sa2web/sa2web-mcp и в npm как @sa2web/mcp. Глобальная установка добавляет три входа.

• sa2: рекомендуемая CLI-команда.
• sa2-browser: совместимый псевдоним, эквивалентный sa2.
• sa2-mcp: stdio server для MCP-клиентов.

Подготовка

Установите npm-пакет глобально:

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

После установки проверьте:

sa2 help
sa2-browser help

sa2-mcp запускается MCP-клиентом через stdio, поэтому обычно его не запускают вручную.

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

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

# Запуск TypeScript-исходника
npm run cli -- help

# Запуск собранного файла
node dist/cli.js help

CLI передает окружение дочернему MCP-серверу. Обязательно настройте SA2_LOGIN_URL. Не оставляйте настоящий clientSecret в истории shell, Git или журналах CI.

Установите SA2_IGNORE_HTTPS_ERRORS=false, если нужна строгая проверка HTTPS-сертификатов. По умолчанию значение true, то есть ошибки сертификатов целевого сайта или страницы удаленного браузера игнорируются.

Одна команда и постоянный shell

Каждый прямой вызов sa2 <команда> запускает и затем закрывает отдельный сервер. Для команд, которым нужна страница, передавайте --url или --target-id. Для последовательной работы используйте sa2 shell; repl — его псевдоним.

sa2> open https://example.com
sa2> snapshot
sa2> click --ref e3
sa2> type --selector '#email' --text hello@example.com
sa2> screenshot --output page.png
sa2> exit

Выход — exit или quit. Ссылки ref=eN из snapshot сохраняются в одном shell-сеансе.

Команды

Команда	Назначение
help	Показать справку
shell / repl	Постоянный сеанс
targets	Список доступных целей
open	Открыть URL или сохраненную цель
workspace / saas / inner	Сокращения для сохраненных целей
snapshot / text	Семантический snapshot / видимый текст
click / type / paste / press	Действия на странице
wait / scroll	Ожидание / прокрутка
device / toggle-device	Список устройств или переключение desktop/mobile эмуляции
screenshot	Сохранить PNG
back / forward / reload / close	Управление браузером
tool	Вызвать любой MCP-инструмент с JSON

Примеры

sa2 targets
sa2 open https://example.com
sa2 open --target-id workspace:123
sa2 saas GitHub
sa2 snapshot --url https://example.com --filter 'main article'
sa2 text --url https://example.com --selector main
sa2 click --url https://example.com --selector 'button[type=submit]'
sa2 type --selector '#email' --text hello@example.com --press-enter
sa2 paste --selector '[contenteditable]' --html '<b>Hello</b>'
sa2 scroll down --amount 800
sa2 device list
sa2 device 'Pixel 7'
sa2 device 'iPhone 13' --orientation landscape --reload
sa2 device Desktop
sa2 screenshot --output page.png --full-page

CLI устройств

sa2 device list (также ls) выводит пресеты Playwright. Выберите пресет позиционно, через --device или --preset; переопределяйте --enabled, --width, --height, --device-scale-factor, --has-touch, --user-agent, --orientation portrait|landscape, --reload. toggle-device — псевдоним. Переключайте внутри sa2 shell, чтобы сохранить вход, затем обновите snapshot.

Элемент можно указать через --ref, --selector, --role / --name, видимый текст или --x / --y. Значения ref=eN из snapshot пригодны для действий; id=tN и context=[tN] — только текстовые ссылки.

Прямой вызов MCP:

sa2 tool browser_resize --json '{"width":1280,"height":720}'

Поддерживаются формы --ключ значение и --ключ=значение. Указывайте --headless true при запуске CLI или shell; повторяющиеся параметры вроде --path образуют список. Примеры без цели предполагают уже открытую страницу в постоянном shell. Перед публикацией, удалением, покупкой или отправкой данных получите подтверждение пользователя.

Устранение неполадок

• Нет dist/server.js: выполните npm run build.
• Ошибка входа: проверьте SA2_LOGIN_URL и права аккаунта.
• Нет цели: используйте targetId из sa2 targets.
• Нет элемента: создайте новый snapshot и используйте последний ref=eN.
• Между командами теряется состояние: используйте sa2 shell.