CLI del navegador remoto

La CLI incluida en el proyecto MCP de Sa2web inicia el mismo servidor MCP mediante stdio y convierte los comandos en llamadas sa2_* o browser_*. Sirve para pruebas manuales, scripts y comprobaciones de conexión.

El proyecto está publicado en sa2web/sa2web-mcp y en npm como @sa2web/mcp. Una instalación global expone tres entradas.

• sa2: comando CLI recomendado.
• sa2-browser: alias de compatibilidad equivalente a sa2.
• sa2-mcp: entrada stdio server para clientes MCP.

Preparación

Instale el paquete npm de forma global:

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

Después compruebe la instalación:

sa2 help
sa2-browser help

sa2-mcp está pensado para que lo lance un cliente MCP mediante stdio; normalmente no se ejecuta manualmente.

Para desarrollar desde el código fuente, clone el repositorio y compile:

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

# Ejecutar la fuente TypeScript
npm run cli -- help

# Ejecutar el archivo compilado
node dist/cli.js help

La CLI transmite su entorno al servidor MCP hijo. Configure al menos SA2_LOGIN_URL. No deje el clientSecret real en el historial del shell, Git o los registros de CI.

Defina SA2_IGNORE_HTTPS_ERRORS=false si necesita validar estrictamente los certificados HTTPS. El valor predeterminado es true, lo que ignora errores de certificado del sitio de destino o de la página del navegador remoto.

Comando único y shell persistente

Cada llamada directa sa2 <comando> inicia y cierra su propio servidor. Incluya --url o --target-id cuando el comando necesite una página. Para operaciones continuas use sa2 shell; repl es un alias.

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

Salga con exit o quit. Los ref=eN de un snapshot permanecen disponibles dentro del mismo shell.

Comandos

Comando	Función
help	Mostrar ayuda
shell / repl	Sesión persistente
targets	Listar destinos accesibles
open	Abrir una URL o un destino guardado
workspace / saas / inner	Atajos de destinos guardados
snapshot / text	Snapshot semántico / texto visible
click / type / paste / press	Interacción con la página
wait / scroll	Espera / desplazamiento
device / toggle-device	Listar dispositivos o cambiar emulación desktop/mobile
screenshot	Guardar un PNG
back / forward / reload / close	Controles del navegador
tool	Llamar a una herramienta MCP con JSON

Ejemplos

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 de dispositivos

sa2 device list (ls también funciona) muestra los presets Playwright. Seleccione por argumento, --device o --preset; ajuste con --enabled, --width, --height, --device-scale-factor, --has-touch, --user-agent, --orientation portrait|landscape y --reload. toggle-device es un alias. Cambie dentro de sa2 shell para conservar la sesión y tome un snapshot nuevo.

Localice elementos mediante --ref, --selector, --role / --name, texto visible o --x / --y. Los valores ref=eN del snapshot son accionables; id=tN y context=[tN] solo son referencias de texto.

Llamada MCP directa:

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

Se aceptan --clave valor y --clave=valor. Establezca --headless true al iniciar la CLI o el shell; las opciones repetidas como --path forman listas. Los ejemplos sin destino suponen una página ya abierta en el shell persistente. Obtenga confirmación antes de publicar, eliminar, comprar o enviar información externamente.

Solución de problemas

• Falta dist/server.js: ejecute npm run build.
• Falla el acceso: compruebe SA2_LOGIN_URL y los permisos de la cuenta.
• Falta un destino: use el targetId de sa2 targets.
• Falta un elemento: tome un snapshot nuevo y use el último ref=eN.
• Se pierde el estado: use sa2 shell.