リモートブラウザー CLI

Sa2web MCP プロジェクトの CLI は、内部で MCP Server を stdio 起動し、コマンドを sa2_* / browser_* ツール呼び出しに変換します。手動テスト、自動化、接続確認に利用できます。

プロジェクトは sa2web/sa2web-mcp で公開され、npm パッケージは @sa2web/mcp です。グローバルインストール後は次の 3 つの入口が利用できます。

• sa2: 推奨 CLI コマンド。
• sa2-browser: sa2 と同等の互換エイリアス。
• sa2-mcp: MCP クライアント用の stdio server 入口。

準備

npm パッケージをグローバルインストールします。

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

インストール後に確認します。

sa2 help
sa2-browser help

sa2-mcp は MCP クライアントから stdio で起動されるため、通常は手動実行しません。

ソース開発時はリポジトリを clone してビルドします。

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 Server に渡します。少なくとも SA2_LOGIN_URL を設定してください。実際の clientSecret を shell 履歴、Git、CI ログに残さないでください。

HTTPS 証明書を厳密に検証する場合は SA2_IGNORE_HTTPS_ERRORS=false を設定します。既定値は true で、対象サイトまたはリモートブラウザーページの HTTPS 証明書エラーを無視します。

1 コマンドと永続 shell

通常の sa2 <command> は実行ごとに Server を起動して終了します。ページ状態が必要な場合は、同じコマンドに --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 で終了します。shell では snapshot の ref=eN が後続コマンドでも有効です。

コマンド

コマンド	機能
help	ヘルプ表示
shell / repl	永続セッション
targets	利用可能な対象を一覧
open	URL または保存済み対象を開く
workspace / saas / inner	保存済み対象のショートカット
snapshot / text	ページの意味スナップショット / テキスト抽出
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 で指定できます。snapshot の ref=eN は操作に使用できますが、id=tN と context=[tN] はテキスト参照です。

原始 MCP ツール:

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

--key value と --key=value の両方を使用できます。--headless true は CLI または shell の起動時に指定し、--path などの繰り返しオプションは配列になります。対象指定のない例は、ページを開いた永続 shell 内で実行してください。公開、削除、購入、送信など外部に影響する操作の前にはユーザー確認が必要です。

トラブルシューティング

• dist/server.js がない: npm run build を実行します。
• ログインできない: SA2_LOGIN_URL とアカウント権限を確認します。
• 対象がない: sa2 targets の targetId を使用します。
• 要素がない: snapshot を更新し、最新の ref=eN を使用します。
• 1 コマンドで状態が失われる: sa2 shell を使用します。