Intégration des agents MCP

Le serveur MCP de Sa2web expose le navigateur distant sous forme d'outils MCP standard pour Claude Code, Claude Desktop, Cursor, Windsurf, VS Code Copilot, Cline, Roo Code, opencode, Gemini CLI, Zed, Hermes Agent et OpenClaw.

Le projet MCP est open source sur sa2web/sa2web-mcp et publié sur npm sous le nom @sa2web/mcp.

Pour une utilisation directe dans le terminal, consultez CLI du navigateur distant.

Le site cible est affiché dans iframe#rbi-frame et contrôlé par le serveur via Playwright.

Installation

Installez Node.js 18 ou une version ultérieure, puis installez le paquet npm globalement :

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

Cela ajoute sa2, sa2-browser et l'entrée MCP sa2-mcp au PATH.

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

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

Configuration du client

Après une installation globale, utilisez directement sa2-mcp :

{
  "mcpServers": {
    "sa2-remote-browser": {
      "command": "sa2-mcp",
      "env": {
        "SA2_LOGIN_URL": "https://<APP_DOMAIN>/agent/login?clientId=...&clientSecret=...",
        "SA2_LOGIN_REDIRECT_PATH": "/app/login",
        "SA2_HEADLESS": "false",
        "SA2_IGNORE_HTTPS_ERRORS": "true"
      }
    }
  }
}

Si le client ne résout pas les commandes globales, indiquez le chemin complet de sa2-mcp ou utilisez node /absolute/path/to/sa2web-mcp/dist/server.js depuis une build source.

{
  "mcpServers": {
    "sa2-remote-browser": {
      "command": "node",
      "args": ["/absolute/path/to/sa2web-mcp/dist/server.js"],
      "env": {
        "SA2_LOGIN_URL": "https://<APP_DOMAIN>/agent/login?clientId=...&clientSecret=...",
        "SA2_LOGIN_REDIRECT_PATH": "/app/login",
        "SA2_HEADLESS": "false",
        "SA2_IGNORE_HTTPS_ERRORS": "true"
      }
    }
  }
}

VS Code Copilot utilise le champ racine servers, opencode mcp et Zed context_servers. Pour Hermes Agent, ajoutez la configuration à mcp_servers dans ~/.hermes/config.yaml; pour OpenClaw, à mcp.servers dans la configuration Gateway. Redémarrez le client et vérifiez que sa2_help apparaît.

Identifiants

Ne stockez jamais un vrai clientSecret dans Git ou dans la documentation. Renouvelez immédiatement tout identifiant exposé.

Variables principales

Variable	Valeur par défaut	Utilisation
SA2_LOGIN_URL	aucune	URL de connexion obligatoire; l'origine du navigateur distant en est déduite
SA2_AUTO_LOGIN_BEFORE_NAVIGATE	true	Connexion automatique avant l'ouverture d'une cible
SA2_HEADLESS	false	Exécution sans interface de Playwright
SA2_BROWSER	chromium	chromium, firefox ou webkit
SA2_IGNORE_HTTPS_ERRORS	true	Ignore les erreurs de certificat HTTPS; utilisez false pour exiger des certificats valides
SA2_RBI_FRAME_CONTENT_WAIT_MS	15000	Attente du contenu de l'iframe
SA2_NAVIGATION_TIMEOUT_MS	45000	Délai de navigation
SA2_ACTION_TIMEOUT_MS	15000	Délai des actions
SA2_LOG_STDERR	true	Envoie les journaux vers stderr et réserve stdout à MCP
SA2_LOG_FILE	aucune	Fichier journal facultatif

N'utilisez pas les anciennes variables SA2_REMOTE_BROWSER_PREFIX et SA2_REMOTE_BROWSER_BASE_URL.

Flux recommandé

sa2_help
  -> sa2_list_available_targets    # seulement pour SaaS, workspace ou site interne
  -> sa2_open_target
  -> browser_snapshot / browser_extract_text
  -> browser_click / browser_type / browser_press / browser_wait

URL publique :

{ "type": "cloud", "url": "https://example.com" }

Cible enregistrée :

{ "targetId": "workspace:123" }

Après l'ouverture, privilégiez browser_snapshot et transmettez ses références ref=eN aux outils d'interaction. id=tN et context=[tN] sont des références textuelles du snapshot, pas des sélecteurs CSS ni des refs exploitables.

Référence complète des outils

Tous les outils enregistrés par le serveur actuel sont décrits ci-dessous. Les paramètres appartiennent à l'objet MCP arguments.

Outil	Usage, paramètres principaux et résultat
sa2_help	Sans paramètre. Renvoie le flux recommandé, des exemples et les outils de compatibilité.
sa2_list_available_targets	Liste proxies, SaaS, comptes workspace et sites internes avec des targetId stables.
sa2_open_target	Navigation conseillée : type=cloud + url, ou targetId/type + id/name; accepte surf et waitUntil.
browser_open_login	Ouvre SA2_LOGIN_URL, avec waitUntil facultatif, pour diagnostiquer la connexion.
browser_navigate	Navigation URL compatible : url requis, surf et waitUntil facultatifs.
browser_navigate_back	Revient via la barre externe. Refaire un snapshot ensuite.
browser_navigate_forward	Avance via la barre externe.
browser_reload	Recharge via la barre externe et invalide les anciennes refs.
browser_list_proxies	Renvoie les paramètres free-browse, les proxies et les options incluant direct.
browser_list_saas_sites	Renvoie les catégories SaaS brutes et une liste sites aplatie.
browser_enter_saas_site	Ouvre un SaaS par id ou name, avec waitUntil facultatif.
browser_list_workspaces	Renvoie les données workspace et les cibles au niveau compte.
browser_enter_workspace	Ouvre un compte par accountId, ou siteId + username.
browser_list_inner_sites	Renvoie les sites internes accessibles.
browser_enter_inner_site	Ouvre un site interne par id ou name.
browser_snapshot	filter CSS réel facultatif. Renvoie un snapshot sémantique; utiliser ref=eN, jamais id=tN, pour agir.
browser_extract_text	selector CSS réel facultatif. Renvoie le texte visible de l'arbre d'iframes.
browser_click	Clique via ref, selector, role/name, text ou coordonnées x/y.
browser_type	text requis; cible par ref/selector/role, avec append et pressEnter.
browser_press	key requis, par exemple Enter, Escape ou Control+A.
browser_press_key	Alias compatible de browser_press, mêmes paramètres.
browser_wait	Attend selector, text, urlIncludes ou ms (1000 par défaut).
browser_scroll	Défile root/élément avec by, to ou intoView; sans paramètre, 600 px vers le bas.
browser_hover	Survole un élément via ref, selector, role/name ou texte.
browser_drag	Glisse de startRef/startSelector vers endRef/endSelector.
browser_fill_form	Remplit dans l'ordre un tableau fields contenant locator et value requis.
browser_select_option	Cible un select par ref/selector et choisit par values, value, label ou index.
browser_check	Coche checkbox/radio via ref, selector, role/name ou texte.
browser_uncheck	Décoche une checkbox; les radios ne sont pas prises en charge.
browser_file_upload	Charge path/paths lisibles par le serveur dans un file input ciblé.
browser_paste	Colle text, html, rtf et/ou fichiers dans une cible ou l'élément actif.
browser_handle_dialog	Accepte/refuse alert, confirm ou prompt; accept vaut true par défaut, promptText et timeoutMs sont facultatifs.
browser_resize	width et height positifs requis; redimensionne le desktop ou le mode appareil actif.
browser_list_devices	Sans paramètre ni ouverture de page. Liste Desktop et tous les appareils Playwright avec viewport, écran, DPR, touch/mobile et navigateur.
browser_toggle_device	Change l'émulation sans recréer le contexte. Accepte enabled, device, dimensions, DPR, touch, UA, orientation, reload; renvoie state, observed, targetObserved, warnings.
browser_screenshot	Renvoie un PNG; fullPage vaut false par défaut.
browser_take_screenshot	Alias de capture; fullPage vaut true par défaut.
browser_evaluate	Exécute expression et arg facultatif dans l'iframe, renvoie JSON.
browser_run_code	Exécute du code asynchrone avec page, rootFrame et helpers. Code de confiance uniquement.
browser_close	Ferme browser/context et efface refs, connexion, dialogs, CDP et état appareil.

Changement d'appareil

Appelez d'abord browser_list_devices, puis par exemple browser_toggle_device avec { "device": "Pixel 7", "orientation": "portrait" }. Les cookies et la connexion sont conservés. Utilisez reload: true pour que les requêtes suivantes utilisent le nouvel UA et { "device": "Desktop" } pour restaurer le viewport précédent.

Chromium applique viewport, écran, DPR, touch, orientation et UA via CDP. Firefox/WebKit ne modifient dynamiquement que le viewport et signalent la limite dans warnings. observed mesure la coque externe et targetObserved l'iframe cible. Reprenez un snapshot après chaque changement.

Sécurité et dépannage

Obtenez une confirmation explicite avant toute publication, soumission, suppression, acquisition, autorisation, transaction ou envoi de message.

• Aucun outil visible : vérifiez le build et les chemins absolus de node et dist/server.js, puis redémarrez le client.
• Échec de connexion : vérifiez SA2_LOGIN_URL, les identifiants et l'état du compte.
• Seule la barre d'outils apparaît : appelez browser_wait ou augmentez le délai de l'iframe.
• Élément introuvable : prenez un nouveau snapshot et utilisez la dernière valeur ref=eN.