CLI du navigateur distant

La CLI fournie avec le projet MCP de Sa2web démarre le même serveur MCP via stdio et convertit les commandes en appels sa2_* ou browser_*. Elle sert aux tests manuels, aux scripts et à la vérification de connexion.

Le projet est publié sur sa2web/sa2web-mcp et sur npm comme @sa2web/mcp. Une installation globale expose trois entrées.

• sa2 : commande CLI recommandée.
• sa2-browser : alias de compatibilité équivalent à sa2.
• sa2-mcp : entrée stdio server pour les clients MCP.

Préparation

Installez le paquet npm globalement :

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

Vérifiez ensuite l'installation :

sa2 help
sa2-browser help

sa2-mcp est lancé par un client MCP via stdio ; vous n'avez normalement pas besoin de l'exécuter à la main.

Pour développer depuis les sources, clonez le dépôt puis compilez :

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

# Exécuter la source TypeScript
npm run cli -- help

# Exécuter le fichier compilé
node dist/cli.js help

La CLI transmet son environnement au serveur MCP enfant. Configurez au minimum SA2_LOGIN_URL. Ne laissez pas le vrai clientSecret dans l'historique du shell, Git ou les journaux CI.

Définissez SA2_IGNORE_HTTPS_ERRORS=false si vous devez valider strictement les certificats HTTPS. La valeur par défaut est true, ce qui ignore les erreurs de certificat du site cible ou de la page du navigateur distant.

Commande unique et shell persistant

Chaque appel direct sa2 <commande> démarre puis arrête son propre serveur. Ajoutez --url ou --target-id aux commandes qui nécessitent une page. Pour une suite d'opérations, utilisez sa2 shell (repl est 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

Quittez avec exit ou quit. Les ref=eN d'un snapshot restent disponibles dans le même shell.

Commandes

Commande	Fonction
help	Afficher l'aide
shell / repl	Session persistante
targets	Lister les cibles accessibles
open	Ouvrir une URL ou une cible enregistrée
workspace / saas / inner	Raccourcis de cibles enregistrées
snapshot / text	Snapshot sémantique / texte visible
click / type / paste / press	Interaction avec la page
wait / scroll	Attente / défilement
device / toggle-device	Lister les appareils ou changer l'émulation desktop/mobile
screenshot	Enregistrer un PNG
back / forward / reload / close	Contrôles du navigateur
tool	Appeler un outil MCP avec un objet JSON

Exemples

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 des appareils

sa2 device list (ls fonctionne aussi) liste les presets Playwright. Choisissez un preset par argument, --device ou --preset, puis surchargez avec --enabled, --width, --height, --device-scale-factor, --has-touch, --user-agent, --orientation portrait|landscape et --reload. toggle-device est un alias. Faites le changement dans sa2 shell pour conserver la connexion, puis reprenez un snapshot.

Localisez un élément avec --ref, --selector, --role / --name, son texte ou --x / --y. Les valeurs ref=eN du snapshot sont exploitables; id=tN et context=[tN] sont uniquement des références textuelles.

Appel MCP direct :

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

La CLI accepte --clé valeur et --clé=valeur. Définissez --headless true au démarrage de la CLI ou du shell; les options répétées comme --path deviennent des listes. Les exemples sans cible supposent une page déjà ouverte dans le shell persistant. Obtenez une confirmation avant toute publication, suppression, acquisition ou communication externe.

Dépannage

• dist/server.js absent : exécutez npm run build.
• Connexion impossible : vérifiez SA2_LOGIN_URL et les droits du compte.
• Cible absente : utilisez le targetId retourné par sa2 targets.
• Élément absent : prenez un nouveau snapshot et utilisez le dernier ref=eN.
• État perdu entre les commandes : utilisez sa2 shell.