CLI trình duyệt từ xa

CLI trong dự án MCP của Sa2web khởi động cùng MCP Server qua stdio và chuyển lệnh thành lời gọi công cụ sa2_* hoặc browser_*. CLI phù hợp để kiểm thử thủ công, viết script và kiểm tra kết nối.

Dự án có trên sa2web/sa2web-mcp và npm với tên @sa2web/mcp. Cài đặt toàn cục cung cấp ba entry.

• sa2: lệnh CLI được khuyến nghị.
• sa2-browser: bí danh tương thích, tương đương sa2.
• sa2-mcp: entry stdio server cho máy khách MCP.

Chuẩn bị

Cài gói npm toàn cục:

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

Sau khi cài đặt, kiểm tra:

sa2 help
sa2-browser help

sa2-mcp được máy khách MCP khởi động qua stdio, nên thường không cần chạy thủ công.

Để phát triển từ source, clone repository rồi build:

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

# Chạy source TypeScript
npm run cli -- help

# Chạy file đã build
node dist/cli.js help

CLI truyền environment cho MCP Server con. Cần cấu hình ít nhất SA2_LOGIN_URL. Không để clientSecret thật trong lịch sử shell, Git hoặc log CI.

Đặt SA2_IGNORE_HTTPS_ERRORS=false nếu cần kiểm tra chứng chỉ HTTPS nghiêm ngặt. Mặc định là true, tức là bỏ qua lỗi chứng chỉ từ trang đích hoặc trang trình duyệt từ xa.

Lệnh đơn và shell duy trì trạng thái

Mỗi lần gọi trực tiếp sa2 <lệnh> sẽ khởi động rồi đóng Server riêng. Hãy truyền --url hoặc --target-id nếu lệnh cần trạng thái trang. Với chuỗi thao tác liên tục, dùng sa2 shell; repl là bí danh.

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

Thoát bằng exit hoặc quit. Các giá trị ref=eN của snapshot vẫn dùng được trong cùng shell.

Lệnh

Lệnh	Chức năng
help	Hiển thị trợ giúp
shell / repl	Phiên duy trì trạng thái
targets	Liệt kê đích có thể truy cập
open	Mở URL hoặc đích đã lưu
workspace / saas / inner	Lệnh tắt cho đích đã lưu
snapshot / text	Snapshot ngữ nghĩa / văn bản hiển thị
click / type / paste / press	Tương tác trang
wait / scroll	Chờ / cuộn
device / toggle-device	Liệt kê thiết bị hoặc đổi giả lập desktop/mobile
screenshot	Lưu PNG
back / forward / reload / close	Điều khiển trình duyệt
tool	Gọi công cụ MCP bằng đối tượng JSON

Ví dụ

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 thiết bị

sa2 device list (ls cũng dùng được) liệt kê preset Playwright. Chọn qua đối số, --device hoặc --preset; ghi đè bằng --enabled, --width, --height, --device-scale-factor, --has-touch, --user-agent, --orientation portrait|landscape và --reload. toggle-device là bí danh. Hãy đổi trong sa2 shell để giữ đăng nhập, rồi tạo snapshot mới.

Định vị phần tử bằng --ref, --selector, --role / --name, văn bản hiển thị hoặc --x / --y. ref=eN từ snapshot có thể thao tác; id=tN và context=[tN] chỉ là tham chiếu văn bản.

Gọi MCP trực tiếp:

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

CLI nhận cả --key value và --key=value. Đặt --headless true khi khởi động CLI hoặc shell; tùy chọn lặp như --path tạo thành danh sách. Các ví dụ không có đích giả định trang đã mở trong shell duy trì trạng thái. Phải xin xác nhận trước khi xuất bản, xóa, mua hoặc gửi dữ liệu ra ngoài.

Xử lý sự cố

• Thiếu dist/server.js: chạy npm run build.
• Đăng nhập thất bại: kiểm tra SA2_LOGIN_URL và quyền tài khoản.
• Thiếu đích: dùng targetId từ sa2 targets.
• Thiếu phần tử: tạo snapshot mới và dùng ref=eN mới nhất.
• Mất trạng thái giữa các lệnh: dùng sa2 shell.