Serveur MCP « sensaas-connecteur »¶

En bref

sensaas-connecteur est un petit serveur MCP (Model Context Protocol) qui donne à une IA deux capacités sur l'API v2 : découvrir la surface (groupes, opérations, paramètres, conventions) à partir du contrat OpenAPI, et l'appeler réellement (connexion JWT, paramètres transverses, enveloppe déballée, erreurs ProblemDetails). Six outils, aucune configuration côté connecteur.

C'est l'outil à mettre en place quand une IA — un assistant de développement, un agent d'intégration — doit écrire ou exécuter du code contre l'API SenSaaS v2 sans qu'on lui recopie la documentation.

Il complète deux autres serveurs MCP qui visent la bibliothèque d'interopérabilité et le schéma SQL de Sage : ici, la cible est l'API HTTP v2 telle que le connecteur l'expose.

Prérequis¶

pip install "mcp[cli]>=1.0" httpx

Le connecteur doit servir la spécification OpenAPI v2. C'est le cas par défaut : le contrat JSON est toujours exposé (anonyme, aucune donnée métier), même quand l'outil de test HTML est désactivé. Voir Démarrer avec l'API v2.

Le script se trouve dans le dépôt du connecteur, sous Serveur/mcp/sensaas_connecteur_mcp_server.py.

Variables d'environnement¶

Variable	Rôle	Défaut
`SENSAAS_BASE_URL`	URL de base du connecteur	`https://localhost`
`SENSAAS_USER`	identifiant pour la connexion automatique (`sensaas_login` sans argument)	—
`SENSAAS_PASSWORD`	mot de passe associé	—
`SENSAAS_TOKEN`	jeton JWT déjà obtenu ; court-circuite la connexion	—
`SENSAAS_VERIFY_TLS`	`1` pour vérifier le certificat TLS	`0` (accepte un certificat auto-signé interne)
`SENSAAS_OPENAPI`	URL ou chemin d'un contrat v2 exporté, pour une découverte hors ligne	—

Le mot de passe est un secret

SENSAAS_PASSWORD et SENSAAS_TOKEN sont des identifiants de connexion au connecteur : passez par le gestionnaire de secrets de votre poste ou de votre chaîne d'intégration, jamais par un fichier versionné. SENSAAS_VERIFY_TLS=0 ne doit rester à 0 que face au certificat auto-signé d'une installation interne.

Déclaration¶

Le serveur se déclare dans un fichier .mcp.json, à la racine du projet où travaille l'IA :

{
  "mcpServers": {
    "sensaas-connecteur": {
      "command": "python",
      "args": ["C:\\Projets\\SenSaaS\\Serveur\\mcp\\sensaas_connecteur_mcp_server.py"],
      "env": { "SENSAAS_BASE_URL": "https://localhost" }
    }
  }
}

Adaptez le chemin du script et SENSAAS_BASE_URL à votre installation. Les identifiants se renseignent dans env ou dans l'environnement du poste.

Les six outils¶

Découverte¶

Outil	Rôle
`sensaas_groups`	Liste les groupes fonctionnels (les `tags` du contrat) avec leur nombre d'opérations, regroupés par catégorie de tête.
`sensaas_endpoints`	Liste les opérations — méthode, chemin, groupe, résumé. Filtres `groupe` (préfixe de groupe) et `recherche` (sous-chaîne dans le chemin, le groupe ou le résumé).
`sensaas_endpoint`	Détail d'une opération : paramètres de chemin et de requête, schéma du corps, réponses. Le chemin se donne sous sa forme de gabarit, par exemple `/v2/entites/{entite}/{cle}`.
`sensaas_conventions`	Rappelle l'enveloppe, le format d'erreur, les paramètres transverses et la règle des écritures. À lire avant tout appel.

Intégration¶

Outil	Rôle
`sensaas_login`	Authentifie (`POST /v2/auth/login`) et mémorise le jeton pour les appels suivants. Sans argument, utilise `SENSAAS_USER` et `SENSAAS_PASSWORD`. Ne renvoie jamais le jeton en clair.
`sensaas_call`	Appelle une opération : méthode, chemin concret, paramètres de requête, corps. Injecte le jeton mémorisé, sauf si `auth` vaut `False` pour les opérations anonymes.

sensaas_call normalise déjà la réponse :

Situation	Ce que l'outil renvoie
Succès JSON emballé	`{ status, data, meta }` — l'enveloppe est déballée
Succès JSON non emballé	`{ status, data }`
Erreur, ou `application/problem+json`	`{ status, problem }` — le ProblemDetails complet
Contenu binaire (PDF, image)	`{ status, contentType, bytes }` — le contenu n'est pas renvoyé, à récupérer en HTTP direct

Le serveur expose en plus une ressource sensaas-connecteur://overview : un aperçu court du connecteur et de la surface v2, que l'IA peut lire d'entrée de jeu.

Scénario d'intégration par une IA¶

L'enchaînement recommandé, du général au particulier :

sensaas_conventions()                      # comprendre l'enveloppe et les paramètres
sensaas_groups()                           # Auth, Kpi, Catalogue, Documents, …
sensaas_endpoints(groupe="Kpi")            # GET /v2/kpi, /v2/kpi/{type}, …
sensaas_login()                            # via SENSAAS_USER / SENSAAS_PASSWORD
sensaas_call("GET", "/v2/kpi/clients-ca", query={"targets": "DEMO", "limit": 50})
sensaas_call("POST", "/v2/entites/famille", body={"reference": "F001", "intitule": "…"})

Trois règles à donner à l'IA en même temps que l'accès :

Lire les conventions avant d'appeler. L'enveloppe, targets et le format d'erreur conditionnent tout le code qu'elle produira.
Une écriture vise un seul dossier. Plusieurs valeurs dans targets renvoient DOSSIER.AMBIGUOUS.
Se brancher sur code, pas sur title. La taxonomie est stable, les textes ne le sont pas.

Écritures sur un dossier réel

sensaas_call écrit vraiment dans Sage dès que les écritures v2 sont activées sur le connecteur. Faites travailler l'IA sur un dossier de démonstration, jamais sur un dossier de production.

Vérifier l'installation¶

python sensaas_connecteur_mcp_server.py --selftest

Le test valide le chargement du script et les conventions ; si le connecteur est joignable, il enchaîne sur la découverte du contrat OpenAPI et compte les opérations du groupe Kpi. Sortie attendue, en résumé :

Base : https://localhost | VerifyTLS : False | OpenAPI override : (défaut)
[ OK ] conventions : 5 sections, paramètres = ['targets', 'limit', 'offset']
[ OK ] groupes : N catégories, N endpoints
[ OK ] endpoints Kpi : 3

Un [SKIP] sur la découverte signifie que le contrat n'a pas été atteint : vérifiez SENSAAS_BASE_URL, que le connecteur est démarré et joignable en TLS, ou fournissez un contrat exporté via SENSAAS_OPENAPI.

Questions fréquentes¶

Faut-il que le connecteur soit joignable pour la découverte ?

Non. En renseignant SENSAAS_OPENAPI avec le chemin d'un contrat v2 exporté, la découverte fonctionne hors ligne. Seuls sensaas_login et sensaas_call exigent un connecteur joignable.

L'IA peut-elle récupérer un PDF ou une image ?

Elle voit le type et la taille du contenu, mais pas le contenu lui-même : les binaires ne transitent pas par le serveur MCP. Il faut un appel HTTP direct.

Le jeton est-il exposé ?

Non. sensaas_login confirme seulement que le jeton a été mémorisé ; il reste en mémoire du processus et est injecté par sensaas_call.