CLI Browser Jarak Jauh

CLI dalam proyek MCP Sa2web menjalankan MCP Server yang sama melalui stdio dan mengubah perintah menjadi panggilan alat sa2_* atau browser_*. Gunakan untuk pengujian manual, skrip otomatisasi, dan pemeriksaan koneksi.

Proyek ini tersedia di sa2web/sa2web-mcp dan npm sebagai @sa2web/mcp. Instalasi global menyediakan tiga entry.

• sa2: perintah CLI yang direkomendasikan.
• sa2-browser: alias kompatibilitas yang setara dengan sa2.
• sa2-mcp: entry stdio server untuk klien MCP.

Persiapan

Instal paket npm secara global:

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

Setelah instalasi, periksa:

sa2 help
sa2-browser help

sa2-mcp dijalankan oleh klien MCP melalui stdio, jadi biasanya tidak perlu dijalankan secara manual.

Untuk pengembangan dari source, clone repository lalu build:

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

# Menjalankan source TypeScript
npm run cli -- help

# Menjalankan file hasil build
node dist/cli.js help

CLI meneruskan environment ke MCP Server anak. Setidaknya, atur SA2_LOGIN_URL. Jangan tinggalkan clientSecret asli di riwayat shell, Git, atau log CI.

Set SA2_IGNORE_HTTPS_ERRORS=false jika Anda perlu validasi sertifikat HTTPS yang ketat. Default-nya true, yang berarti error sertifikat dari situs target atau halaman browser jarak jauh akan diabaikan.

Satu perintah dan shell persisten

Setiap pemanggilan langsung sa2 <perintah> menjalankan lalu menutup Server sendiri. Sertakan --url atau --target-id jika perintah membutuhkan halaman. Untuk operasi berurutan, gunakan sa2 shell; repl adalah aliasnya.

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

Keluar dengan exit atau quit. Nilai ref=eN dari snapshot tetap tersedia dalam shell yang sama.

Perintah

Perintah	Fungsi
help	Menampilkan bantuan
shell / repl	Sesi persisten
targets	Daftar target yang dapat diakses
open	Membuka URL atau target tersimpan
workspace / saas / inner	Pintasan target tersimpan
snapshot / text	Snapshot semantik / teks terlihat
click / type / paste / press	Interaksi halaman
wait / scroll	Menunggu / menggulir
device / toggle-device	Daftar perangkat atau ubah emulasi desktop/mobile
screenshot	Menyimpan PNG
back / forward / reload / close	Kontrol browser
tool	Memanggil alat MCP dengan objek JSON

Contoh

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 perangkat

sa2 device list (ls juga berlaku) menampilkan preset Playwright. Pilih melalui argumen, --device, atau --preset; ubah dengan --enabled, --width, --height, --device-scale-factor, --has-touch, --user-agent, --orientation portrait|landscape, dan --reload. toggle-device adalah alias. Beralihlah di dalam sa2 shell agar login tetap ada, lalu ambil snapshot baru.

Temukan elemen melalui --ref, --selector, --role / --name, teks terlihat, atau --x / --y. Nilai ref=eN dari snapshot dapat dipakai untuk aksi; id=tN dan context=[tN] hanya referensi teks.

Panggilan MCP langsung:

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

CLI menerima --key value dan --key=value. Atur --headless true saat memulai CLI atau shell; opsi berulang seperti --path menjadi daftar. Contoh tanpa target mengasumsikan halaman sudah terbuka di shell persisten. Minta konfirmasi pengguna sebelum menerbitkan, menghapus, membeli, atau mengirim data ke pihak luar.

Pemecahan masalah

• dist/server.js tidak ada: jalankan npm run build.
• Login gagal: periksa SA2_LOGIN_URL dan izin akun.
• Target tidak ada: gunakan targetId dari sa2 targets.
• Elemen tidak ada: ambil snapshot baru dan gunakan ref=eN terbaru.
• Status hilang antarperintah: gunakan sa2 shell.