Workflow d'approbation HITL — /api/site-connectors/:id/mcp/*

Toute mutation sur un site connecté (WordPress ou PrestaShop) pilotée depuis StormeoOS passe par un workflow human-in-the-loop : la commande est rédigée, prévisualisée, approuvée par un humain, puis exécutée — et reste réversible par snapshot.

draft ──► preview ──► approve ──► execute ──► (rollback)

Ces routes sont des routes session de l'application StormeoOS (isAuthenticated), pas des routes de l'API publique spk_*. Elles sont documentées ici pour les développeurs d'intégrations internes et l'UI (onglet MCP d'un connecteur).

Routes

Base : /api/site-connectors/:id/mcp

Méthode	Route	Description
GET	/tools	Catalogue des outils disponibles pour ce connecteur (posts, pages, produits, utilisateurs, médias, menus, catégories, commandes, commentaires, réglages…)
PATCH	/capabilities	Bascules UI par catégorie d'outils
PATCH	/approval-policy	Politique d'approbation du connecteur
POST	/commands	Créer une commande (brouillon)
POST	/draft-and-preview	Créer + prévisualiser en un appel
POST	/preview/:commandId	Prévisualiser une commande existante
POST	/approve/:commandId	Approuver (rôles approbateurs uniquement)
POST	/execute/:commandId	Exécuter une commande approuvée
POST	/rollback/:commandId	Retour arrière via snapshot
GET	/commands	Historique des commandes
GET	/commands/:commandId	Détail d'une commande
GET	/commands/:commandId/result	Résultat d'exécution
POST	/preview · /execute	Variantes directes (préviz/exécution sans brouillon persisté)
GET	/health	Santé du canal MCP du connecteur

Des routes batch existent également pour prévisualiser/exécuter sur plusieurs sites d'un coup (opérations de flotte).

Approbation

• La politique par défaut est fail-closed : seuls les rôles d'agence habilités (et super_admin) peuvent approuver.
• Une commande non approuvée ne part jamais vers le site.
• Chaque exécution mutante crée un snapshot préalable côté site, référencé par la commande — c'est lui qui rend le rollback possible.

Transport vers le site

Malgré le nom des routes, le transport n'est pas le protocole MCP : c'est un RPC propriétaire chiffré, adressé au plugin :

CMS	Endpoint cible
WordPress	{site}/wp-json/stormeo/v1/mcp-execute · mcp-preview · mcp-rollback
PrestaShop	{site}/module/stormeoconnector/mcpexecute · mcppreview · mcprollback

Sécurité du canal :

• Chiffrement : payload AES-256-GCM, clé dérivée du secret d'appairage (PBKDF2-SHA256, 100 000 itérations)
• Intégrité : HMAC-SHA256 du ciphertext, vérifié en comparaison timing-safe des deux côtés
• Headers : X-Stormeo-Api-Key, X-Connect-Api-Secret, X-Stormeo-MCP: 1

Articulation avec le serveur MCP natif

	Serveur MCP natif (site)	Workflow HITL (StormeoOS)
Sens	Client MCP → site	StormeoOS → site
Opérations	Lecture + pré-contrôles (10 abilities)	Mutations + opérations (préviz/approbation)
Protocole	MCP (Adapter WordPress)	RPC chiffré propriétaire
Approbation	Capabilities WP	Rôles approbateurs StormeoOS

Quand un connecteur est mcp-ready, StormeoOS peut router ses lectures par le serveur MCP natif ; les mutations restent exclusivement sur le workflow HITL.