Serveur MCP Babel Licensing Data Center
Le serveur MCP Babel Licensing est un serveur Model Context Protocol (MCP) écrit en Python qui expose toutes les fonctions de l’API Babel Licensing sous forme d’outils. Des assistants IA tels que Claude peuvent ainsi interagir directement avec votre système Babel Licensing pour la gestion des licences, les opérations sur les clients, la gestion des produits et d’autres tâches.
Le serveur MCP Licensing est distribué avec Data Center comme composant distinct. Ce n’est ni un point d’accès intégré ni un interrupteur des paramètres Server de l’application web.
Qu’est-ce que MCP ?
Le Model Context Protocol (MCP) est un standard ouvert qui permet aux assistants IA de se connecter de manière sécurisée à des systèmes et à des sources de données externes. Les serveurs MCP font le lien entre les modèles d’IA et vos systèmes métier, et permettent d’interagir en langage naturel avec des API, des bases de données et des outils.
Fonctionnalités
Le serveur transforme l’API Babel Licensing en outils MCP et gère les détails de connexion pour vous. Voici ses principales caractéristiques :
- Couverture complète de l’API : expose sous forme d’outils MCP tous les points de terminaison de l’API Babel Licensing (plus de 90)
- Configuration typée : configuration basée sur Pydantic, avec validation automatique
- Prise en charge de l’authentification : authentification par clé API ou par jeton du porteur (bearer token)
- Rotation quotidienne des journaux : journalisation automatique dans le répertoire
logs/, avec un nouveau fichier chaque jour - Jeu d’outils complet : comprend des outils pour :
- L’authentification et la gestion des utilisateurs
- Les opérations sur les licences (activer, désactiver, valider, demander, libérer)
- La gestion des clients et des contacts
- La gestion des produits et des commandes
- Les modèles de licence et les jetons
- Les webhooks et la gestion des événements
- Les rapports et la journalisation
- Les notifications par e-mail
- Les paramètres et la configuration du système
Configuration requise
Le serveur s’exécute sur votre machine aux côtés du client IA et appelle l’API de votre Babel Licensing Service. Avant de l’installer, assurez-vous de disposer des éléments suivants :
- Python 3.10 ou version ultérieure
- Un accès à l’API Babel Licensing (URL de base et identifiants)
- Un client compatible MCP (par exemple Claude Desktop)
Installation
Le serveur MCP est fourni sous forme d’archive ZIP. Vous pouvez laisser le script d’installation tout préparer ou créer vous-même l’environnement Python.
Démarrage rapide
Le script d’installation crée un environnement virtuel Python dans venv, installe les dépendances à partir de requirements.txt et crée le fichier .env à partir de .env.example. Ensuite, il vous suffit de saisir vos identifiants dans .env.
macOS / Linux
Ouvrez un terminal et suivez ces étapes :
- Extrayez l’archive et placez-vous dans le répertoire :
unzip babel-licensing-mcp-*.zip
cd babel-licensing-mcp-*- Exécutez le script d’installation :
chmod +x setup.sh
./setup.sh- Configurez votre environnement :
# Edit .env file with your Babel Licensing API credentials
nano .envWindows
Sous Windows, les mêmes étapes s’exécutent dans PowerShell avec le script setup.ps1 :
-
Extrayez l’archive ZIP et placez-vous dans le répertoire avec PowerShell
-
Autorisez l’exécution des scripts PowerShell (si nécessaire) :
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser- Exécutez le script d’installation :
.\setup.ps1- Configurez votre environnement :
# Edit .env file with your Babel Licensing API credentials
notepad .envInstallation manuelle
Si vous préférez ne pas exécuter le script d’installation, voici les mêmes étapes à effectuer manuellement depuis le dossier de l’archive extraite.
Créer un environnement virtuel
Créez un environnement virtuel dans le dossier venv et activez-le afin que les dépendances du serveur restent séparées de l’installation Python de votre système.
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activateInstaller les dépendances
Une fois l’environnement virtuel activé, installez les paquets répertoriés dans requirements.txt.
pip install -r requirements.txtConfigurer les variables d’environnement
Copiez .env.example vers .env, puis saisissez l’adresse de votre Babel Licensing Service et vos identifiants comme décrit dans Configuration.
cp .env.example .env
# Edit .env with your actual credentialsConfiguration
Le serveur a besoin des variables d’environnement suivantes (configurées dans .env) :
# Babel Licensing API Base URL
BABEL_API_BASE_URL=https://your-babel-licensing-server.com
# Authentication - Use ONE of the following:
# Option 1: API Key
BABEL_API_KEY=your-api-key-here
# Option 2: Bearer Token
# BABEL_BEARER_TOKEN=your-bearer-token-here
# Optional Configuration
# BABEL_VERIFY_SSL=true # Set to false for self-signed certificates
# BABEL_TIMEOUT=30 # Request timeout in seconds
# BABEL_CONTENT_TYPE=application/json # Content type: application/json or application/toon
# DEBUG=false # Enable debug loggingConfiguration du type de contenu
Le serveur prend en charge deux types de contenu pour les requêtes d’API :
application/json(par défaut) : format JSON standardapplication/toon: format TOON pour des cas d’utilisation spécialisés
Pour utiliser le format TOON, définissez la variable d’environnement BABEL_CONTENT_TYPE :
BABEL_CONTENT_TYPE=application/toonLe client définit automatiquement les en-têtes Content-Type et Accept appropriés pour toutes les requêtes d’API.
Utilisation
Une fois configuré, vous pouvez démarrer le serveur depuis un terminal pour vérifier qu’il fonctionne, puis l’enregistrer auprès de votre client IA afin que celui-ci le démarre lorsque nécessaire.
Exécuter le serveur MCP
Il existe deux façons de démarrer le serveur. Exécutez l’une des deux commandes avec l’environnement virtuel activé, depuis le dossier du serveur MCP.
Option 1 : utiliser la commande installée
Le paquet installé fournit la commande babel-licensing-mcp, qui démarre le serveur.
babel-licensing-mcpOption 2 : exécution directe
Vous pouvez également exécuter directement le script du serveur avec Python.
python src/server.pyConfigurer les clients IA
Le serveur MCP Babel Licensing peut être utilisé avec tout client IA compatible MCP, notamment Claude Desktop et Claude Code.
Configurer Claude Desktop
Ajoutez ce qui suit au fichier de configuration de Claude Desktop :
macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
Windows : %APPDATA%\Claude\claude_desktop_config.json
Linux : ~/.config/Claude/claude_desktop_config.json
Configuration recommandée (chemin direct)
Faites pointer command vers l’interpréteur Python situé dans le dossier venv et args vers src/server.py, tous deux avec des chemins absolus. La section env transmet l’adresse du service et la clé API au serveur, afin que le client ne dépende pas d’un fichier .env dans son dossier de travail.
{
"mcpServers": {
"babel-licensing": {
"command": "/absolute/path/to/babel-licensing-mcp/venv/bin/python",
"args": [
"/absolute/path/to/babel-licensing-mcp/src/server.py"
],
"env": {
"BABEL_API_BASE_URL": "https://your-babel-server.com",
"BABEL_API_KEY": "your-api-key-here"
}
}
}
}Exemple avec des chemins réels (macOS) :
{
"mcpServers": {
"babel-licensing": {
"command": "/Users/username/Projects/babel-licensing-mcp/venv/bin/python",
"args": [
"/Users/username/Projects/babel-licensing-mcp/src/server.py"
],
"env": {
"BABEL_API_BASE_URL": "https://api.babel-licensing.com",
"BABEL_API_KEY": "abc123def456"
}
}
}
}Exemple avec des chemins réels (Windows) :
{
"mcpServers": {
"babel-licensing": {
"command": "C:\\Users\\username\\Projects\\babel-licensing-mcp\\venv\\Scripts\\python.exe",
"args": [
"C:\\Users\\username\\Projects\\babel-licensing-mcp\\src\\server.py"
],
"env": {
"BABEL_API_BASE_URL": "https://api.babel-licensing.com",
"BABEL_API_KEY": "abc123def456"
}
}
}
}Remarque : remplacez /absolute/path/to/ par le chemin réel du répertoire de votre projet. Pour le connaître, exécutez pwd (macOS/Linux) ou cd (Windows) dans le dossier du projet.
Autre possibilité : utiliser un fichier .env
Au lieu d’indiquer les variables d’environnement dans la configuration de Claude Desktop, vous pouvez créer un fichier .env à la racine du projet :
# Copy the example file
cp .env.example .env
# Edit with your credentials
BABEL_API_BASE_URL=https://your-babel-server.com
BABEL_API_KEY=your-api-key-hereUtilisez ensuite une configuration Claude Desktop plus simple :
{
"mcpServers": {
"babel-licensing": {
"command": "/absolute/path/to/babel-licensing-mcp/venv/bin/python",
"args": [
"/absolute/path/to/babel-licensing-mcp/src/server.py"
]
}
}
}Après la configuration :
- Quittez complètement Claude Desktop, puis redémarrez-le
- Démarrez une nouvelle conversation
- Repérez l’icône d’outils 🔨, qui indique que des serveurs MCP sont connectés
- Demandez à Claude : « À quels outils Babel Licensing avez-vous accès ? »
Configurer Claude Code
Claude Code est une extension de VS Code qui apporte l’assistance de l’IA directement dans votre environnement de développement. Pour utiliser le serveur MCP Babel Licensing avec Claude Code :
Étape 1 : installer Claude Code
Installez l’extension Claude Code depuis la marketplace de VS Code :
- Ouvrez VS Code
- Accédez à Extensions (Cmd+Shift+X sous macOS, Ctrl+Shift+X sous Windows/Linux)
- Recherchez « Claude Code »
- Cliquez sur Install
Étape 2 : ajouter le serveur MCP aux paramètres
Ouvrez les paramètres de VS Code et ajoutez la configuration du serveur MCP :
Option A : paramètres de l’espace de travail (recommandé pour une utilisation propre à un projet)
Créez ou modifiez .vscode/settings.json dans votre espace de travail :
{
"claude.mcpServers": {
"babel-licensing": {
"command": "/absolute/path/to/babel-licensing-mcp/venv/bin/python",
"args": [
"/absolute/path/to/babel-licensing-mcp/src/server.py"
],
"env": {
"BABEL_API_BASE_URL": "https://licensing.example.com",
"BABEL_API_KEY": "your-api-key-here"
}
}
}
}Option B : paramètres utilisateur (pour un accès global dans tous les espaces de travail)
- Ouvrez la palette de commandes (Cmd+Shift+P sous macOS, Ctrl+Shift+P sous Windows/Linux)
- Saisissez « Preferences: Open User Settings (JSON) »
- Ajoutez la configuration
claude.mcpServers:
{
"claude.mcpServers": {
"babel-licensing": {
"command": "/Users/username/Projects/babel-licensing-mcp/venv/bin/python",
"args": [
"/Users/username/Projects/babel-licensing-mcp/src/server.py"
],
"env": {
"BABEL_API_BASE_URL": "https://licensing.example.com",
"BABEL_API_KEY": "your-api-key-here"
}
}
}
}Étape 3 : utiliser des variables d’environnement
Vous pouvez faire référence à des variables d’environnement dans votre configuration :
{
"claude.mcpServers": {
"babel-licensing": {
"command": "/path/to/babel-licensing-mcp/venv/bin/python",
"args": ["/path/to/babel-licensing-mcp/src/server.py"],
"env": {
"BABEL_API_BASE_URL": "${env:BABEL_URL}",
"BABEL_API_KEY": "${env:BABEL_KEY}"
}
}
}
}Définissez ensuite les variables d’environnement dans votre shell avant de démarrer VS Code :
# macOS/Linux
export BABEL_URL="https://licensing.example.com"
export BABEL_KEY="your-api-key-here"
code .
# Windows PowerShell
$env:BABEL_URL = "https://licensing.example.com"
$env:BABEL_KEY = "your-api-key-here"
code .Étape 4 : utiliser un fichier .env (l’approche la plus simple)
Configurez le fichier .env du répertoire du serveur MCP avec vos identifiants, puis utilisez une configuration minimale :
{
"claude.mcpServers": {
"babel-licensing": {
"command": "/path/to/babel-licensing-mcp/venv/bin/python",
"args": ["/path/to/babel-licensing-mcp/src/server.py"]
}
}
}Le serveur charge automatiquement les paramètres depuis le fichier .env.
Étape 5 : exemples de chemins selon la plateforme
macOS :
{
"claude.mcpServers": {
"babel-licensing": {
"command": "/Users/username/Projects/babel-licensing-mcp/venv/bin/python",
"args": [
"/Users/username/Projects/babel-licensing-mcp/src/server.py"
]
}
}
}Windows :
{
"claude.mcpServers": {
"babel-licensing": {
"command": "C:\\Users\\username\\Projects\\babel-licensing-mcp\\venv\\Scripts\\python.exe",
"args": [
"C:\\Users\\username\\Projects\\babel-licensing-mcp\\src\\server.py"
]
}
}
}Linux :
{
"claude.mcpServers": {
"babel-licensing": {
"command": "/home/username/projects/babel-licensing-mcp/venv/bin/python",
"args": [
"/home/username/projects/babel-licensing-mcp/src/server.py"
]
}
}
}Étape 6 : utiliser des chemins relatifs
Pour les configurations propres à un espace de travail, vous pouvez utiliser les variables de VS Code :
{
"claude.mcpServers": {
"babel-licensing": {
"command": "${workspaceFolder}/../babel-licensing-mcp/venv/bin/python",
"args": [
"${workspaceFolder}/../babel-licensing-mcp/src/server.py"
],
"cwd": "${workspaceFolder}/../babel-licensing-mcp"
}
}
}C’est utile lorsque le serveur MCP se trouve dans un répertoire voisin de celui de votre espace de travail.
Étape 7 : vérifier l’installation
Après la configuration, rechargez VS Code pour activer le serveur MCP :
- Ouvrez la palette de commandes (Cmd+Shift+P / Ctrl+Shift+P)
- Saisissez « Developer: Reload Window »
- Appuyez sur Enter
Pour vérifier que le serveur fonctionne :
- Ouvrez le panneau Claude dans VS Code
- Démarrez une nouvelle conversation
- Demandez : « De quelles fonctionnalités Babel Licensing disposez-vous ? »
- Claude doit répertorier les 86 outils disponibles
Conseils d’utilisation de Claude Code :
-
Demandes tenant compte du contexte : Claude Code voit votre fichier en cours et votre espace de travail, vous pouvez donc demander :
- « À partir de ce code, créez une licence pour ce client »
- « Générez un appel d’activation de licence pour le produit de ce fichier »
-
Génération de code : demandez à Claude de générer du code qui utilise l’API Babel Licensing :
- « Écrivez une méthode C# qui active une licence avec ces paramètres »
- « Créez un script Python qui interroge toutes les licences actives »
-
Assistance dans l’éditeur : sélectionnez du code et demandez à Claude :
- « Vérifiez si cette clé de licence est valide »
- « Trouvez le client associé à cette clé utilisateur »
-
Opérations sur plusieurs fichiers : Claude peut vous aider à coordonner la gestion des licences dans plusieurs fichiers :
- « Mettez à jour les clés de licence dans tous les fichiers de configuration »
- « Trouvez toutes les clés de licence codées en dur dans ce projet »
Dépannage de Claude Code :
Si le serveur MCP ne se connecte pas :
- Vérifier l’état de l’extension : assurez-vous que l’extension Claude Code est activée
- Vérifier le chemin de Python : confirmez que le chemin de l’environnement virtuel est correct
- Consulter les journaux : affichez la sortie de Claude Code dans le panneau Output de VS Code
- Recharger la fenêtre : utilisez « Developer: Reload Window » après toute modification de la configuration
- Vérifier les autorisations : assurez-vous que l’exécutable Python dispose des autorisations d’exécution
Configuration de plusieurs environnements :
Vous pouvez configurer différents environnements Babel Licensing :
{
"claude.mcpServers": {
"babel-licensing-prod": {
"command": "/path/to/venv/bin/python",
"args": ["/path/to/src/server.py"],
"env": {
"BABEL_API_BASE_URL": "https://licensing.production.com",
"BABEL_API_KEY": "${env:BABEL_PROD_KEY}"
}
},
"babel-licensing-dev": {
"command": "/path/to/venv/bin/python",
"args": ["/path/to/src/server.py"],
"env": {
"BABEL_API_BASE_URL": "https://licensing.dev.com",
"BABEL_API_KEY": "${env:BABEL_DEV_KEY}"
}
}
}
}Vous pouvez ainsi passer de l’environnement de production à l’environnement de développement lorsque vous travaillez avec Claude.
Journalisation
Le serveur consigne automatiquement toutes les opérations dans des fichiers journaux quotidiens, dans le répertoire logs/ :
- Emplacement :
logs/babel_licensing_YYYYMMDD.log - Format : entrées horodatées, avec le niveau et le module
- Rotation : un nouveau fichier est créé automatiquement chaque jour
- Sortie : les journaux sont écrits à la fois dans le fichier et sur la console
Exemple de fichier journal : logs/babel_licensing_20251111.log
2025-11-11 10:30:15 - server - INFO - MCP server starting...
2025-11-11 10:30:16 - server - INFO - Babel Licensing client initialized
2025-11-11 10:31:22 - server - INFO - Tool called: babel_get_customersOutils disponibles
Le serveur expose 86 outils répartis dans les catégories suivantes :
Remarque : l’authentification est gérée automatiquement au moyen de la clé API ou du jeton du porteur configurés dans les variables d’environnement. Les outils de connexion interactive ne sont pas nécessaires.
Opérations de licence (7 outils)
Ces outils appellent les points de terminaison de licence du client, c’est-à-dire les mêmes opérations que celles effectuées par une application sous licence à l’exécution :
babel_activate_license: activer une licencebabel_deactivate_license: désactiver une licencebabel_request_license: demander une licencebabel_release_license: libérer une licencebabel_license_heartbeat: envoyer le signal de présence d’une licencebabel_validate_license: valider une licencebabel_get_license_info: obtenir les informations d’une licence
Gestion
Les outils de gestion traitent les données stockées par le Babel Licensing Service. Ils sont regroupés ci-dessous selon le type d’enregistrement qu’ils gèrent.
Clés API (4 outils)
Les outils de clés API répertorient, créent, modifient et suppriment les clés qui donnent accès à l’API Babel Licensing.
babel_get_api_keys: lister les clés APIbabel_insert_api_key: créer une clé APIbabel_update_api_key: mettre à jour une clé APIbabel_delete_api_key: supprimer une clé API
Utilisateurs (7 outils)
Les outils utilisateurs gèrent les comptes du Babel Licensing Service et les rôles qui leur sont attribués.
babel_get_users: lister les utilisateursbabel_insert_user: créer un utilisateurbabel_update_user: mettre à jour un utilisateurbabel_delete_user: supprimer un utilisateurbabel_get_user_roles: obtenir les rôles d’un utilisateurbabel_add_user_to_roles: ajouter un utilisateur à des rôlesbabel_remove_user_from_roles: retirer un utilisateur de rôles
Clients (7 outils)
Les outils clients gèrent les enregistrements des clients et lisent les contacts, les commandes et les licences qui appartiennent à chaque client.
babel_get_customers: lister les clientsbabel_insert_customer: créer un clientbabel_update_customer: mettre à jour un clientbabel_delete_customer: supprimer un clientbabel_get_customer_contacts: obtenir les contacts d’un clientbabel_get_customer_orders: obtenir les commandes d’un clientbabel_get_customer_licenses: obtenir les licences d’un client
Produits (15 outils)
Les outils produits couvrent les produits, leurs versions, les assemblies de chaque version et les modèles de licence liés à une version.
- Gestion des produits (get, insert, update, delete)
- Gestion des versions des produits
- Gestion des assemblies des versions
- Modèles de licence des versions
Commandes (9 outils)
Les outils de commandes gèrent les commandes, les produits de chaque commande et les licences émises pour une commande.
- Gestion des commandes (get, insert, update, delete)
- Gestion des produits des commandes
- Récupération des licences des commandes
Licences (9 outils)
Les outils de licences gèrent les enregistrements de licences ainsi que leurs jetons, traces et modèles.
- Gestion des licences (get, insert, update, delete)
- Gestion des jetons de licence
- Traces de licence
- Modèles de licence
Webhooks (9 outils)
Les outils webhook gèrent les abonnements et leurs événements, répertorient les types d’événements disponibles et envoient des événements de test.
- Gestion des abonnements webhook
- Récupération des types d’événements
- Test des webhooks
- Gestion des événements
Autres outils de gestion
Les autres outils couvrent les autres enregistrements et fonctions du service. Le nombre entre crochets indique combien d’outils chaque groupe comprend.
- Assemblies (4 outils)
- Contacts (4 outils)
- Ressources (4 outils)
- Rapports (3 outils)
- Journalisation (3 outils)
- Paramètres (2 outils)
- E-mail (2 outils)
- Informations sur le serveur (1 outil)
Travailler avec l’API
Cette section explique quelles entrées les outils attendent et comment le serveur prépare vos données avant d’appeler l’API Babel Licensing.
Format des données pour les opérations d’insertion et de mise à jour
Lorsque vous utilisez des outils qui créent ou mettent à jour des ressources (ceux dont le nom commence par babel_insert_ ou babel_update_), le client encapsule automatiquement vos données dans le format de requête qu’exige l’API Babel Licensing.
Il vous suffit de fournir les données brutes : l’encapsulation est gérée automatiquement.
Exemples
Créer un client :
// You provide:
{
"customer_data": {
"name": "Acme Corporation",
"email": "contact@acme.com"
}
}
// The client automatically wraps it as:
{
"customer": {
"name": "Acme Corporation",
"email": "contact@acme.com"
}
}Créer un utilisateur :
// You provide:
{
"user_data": {
"userName": "johndoe",
"email": "john@example.com",
"password": "SecureP@ssw0rd"
}
}
// The client automatically wraps it as:
{
"user": {
"userName": "johndoe",
"email": "john@example.com"
},
"password": "SecureP@ssw0rd"
}Mettre à jour une licence :
// You provide:
{
"license_data": {
"id": 123,
"revoked": false,
"description": "Updated description"
}
}
// The client automatically wraps it as:
{
"license": {
"id": 123,
"revoked": false,
"description": "Updated description"
}
}Paramètres de requête
De nombreux points de terminaison GET prennent en charge les paramètres de requête suivants :
select: liste des noms de champs à inclure dans la réponse, séparés par des virgulesfilter: critères de filtrage dans la syntaxe .NET (voir Syntaxe des filtres ci-dessous)include: liste des objets liés à inclure, séparés par des virgules (voir Paramètre include ci-dessous)sort: nom de champ, suivi éventuellement de « asc » ou de « desc »take: limite de pagination (taille de page)skip: décalage de pagination
Paramètre include
Le paramètre include vous permet de récupérer des objets liés en une seule requête.
Règles importantes :
- Utilisez des noms en PascalCase (avec une majuscule initiale) :
Customer,Order,Product(et noncustomer,order,product) - Ajoutez obligatoirement les objets inclus à select : indiquez-les dans les deux paramètres
- Plusieurs objets : séparez-les par une virgule, sans espace
Exemples :
// Correct - Get licenses with customer and order objects
{
"params": {
"select": "id,licenseId,licenseType,createdAt,customerId,orderId,Customer,Order", // Include Customer,Order here
"include": "Customer,Order" // PascalCase, no spaces
}
}
// Wrong - lowercase names
{
"params": {
"select": "id,licenseId,customer,order", // L Lowercase
"include": "customer,order" // L Will fail
}
}
// Wrong - missing from select
{
"params": {
"select": "id,licenseId,licenseType", // L Missing Customer,Order
"include": "Customer,Order" // Objects won't be returned!
}
}Options d’inclusion disponibles :
babel_get_licenses: Product, Order, Customer, Template, Licenseebabel_get_customers: Contacts, Orders, Licensesbabel_get_orders: Customer, Reseller, Products, Licensesbabel_get_products: Releases, Ordersbabel_get_users: Roles, Settings, Customerbabel_get_api_keys: Ownerbabel_get_all_license_tokens: License, NodeLockedLicensebabel_get_license_templates: Product
Syntaxe des filtres
L’API utilise la syntaxe de filtre .NET, et non le standard OData.
Opérateurs de comparaison :
| Opérateur | Description | Exemple |
|---|---|---|
>= | Supérieur ou égal | createdAt >= "2025-11-11T00:00:00" |
<= | Inférieur ou égal | expireDate <= "2025-12-31T23:59:59" |
> | Supérieur | id > 100 |
< | Inférieur | id < 1000 |
== | Égal | revoked == false |
!= | Différent | status != "expired" |
Opérateurs logiques :
| Opérateur | Description | Exemple |
|---|---|---|
&& | ET logique | revoked == false && expireDate >= "2025-01-01" |
|| | OU logique | status == "active" || status == "trial" |
! | Négation (NON) | !revoked ou !licenseType.Contains("Trial") |
Fonctions de chaîne :
| Fonction | Description | Exemple |
|---|---|---|
Contains() | Vérifie si la chaîne contient une sous-chaîne | licenseType.Contains("Ultimate") |
StartsWith() | Vérifie si la chaîne commence par une sous-chaîne | userKey.StartsWith("ABC") |
EndsWith() | Vérifie si la chaîne se termine par une sous-chaîne | licenseeEmail.EndsWith("@example.com") |
Exemples de filtres complexes :
# Active licenses of Ultimate type created after Nov 11
revoked == false && licenseType.Contains("Ultimate") && createdAt >= "2025-11-11T00:00:00"
# Exclude Enterprise licenses
!licenseType.Contains("Enterprise")
# User keys starting with ABC or XYZ
userKey.StartsWith("ABC") || userKey.StartsWith("XYZ")
# Expired licenses excluding trial
expireDate < "2025-01-01T00:00:00" && !licenseType.Contains("Trial")Important : n’utilisez pas la syntaxe OData (eq, ne, gt, lt, and, or). Ces opérateurs ne fonctionnent pas.
Paramètre sort :
Le paramètre sort accepte :
- Un nom de champ avec un sens de tri :
createdAt desc(décroissant) - Un nom de champ avec un sens de tri :
createdAt asc(croissant) - Un nom de champ seul :
createdAt(croissant par défaut)
Exemple complet :
{
"params": {
"filter": "revoked == false && licenseType.Contains(\"Ultimate\") && expireDate >= \"2025-01-01T00:00:00\"",
"select": "id,licenseId,userKey,expireDate,licenseType",
"take": 10,
"skip": 0,
"sort": "createdAt desc"
}
}Exemples
Vous échangez avec l’assistant IA en langage naturel, et il choisit l’outil et renseigne les arguments. Les exemples ci-dessous montrent une demande et l’appel d’outil qui en résulte.
Activer une licence
Demandez à Claude :
« Activez une licence avec la clé utilisateur ABC-123-DEF, le code produit PROD001 et l’identifiant matériel HW-12345 »
Claude utilise l’outil babel_activate_license :
{
"tool": "babel_activate_license",
"arguments": {
"license_data": {
"userKey": "ABC-123-DEF",
"productCode": "PROD001",
"hardwareId": "HW-12345"
}
}
}Obtenir des clients
Demandez à Claude :
« Affichez les 10 premiers clients revendeurs, triés par nom de société »
Claude utilise l’outil babel_get_customers :
{
"tool": "babel_get_customers",
"arguments": {
"params": {
"filter": "isReseller == true",
"take": 10,
"sort": "company asc"
}
}
}Créer un abonnement webhook
Demandez à Claude :
« Créez un abonnement webhook pour les événements d’activation et de désactivation de licence, qui pointe vers https://example.com/webhook »
Claude utilise l’outil babel_create_webhook_subscription :
{
"tool": "babel_create_webhook_subscription",
"arguments": {
"subscription_data": {
"url": "https://example.com/webhook",
"events": ["license.activated", "license.deactivated"],
"isActive": true
}
}
}Exemple de requête complexe
Demandez à Claude :
« Affichez toutes les licences Ultimate créées après le 11 novembre 2025 et non révoquées, avec les détails du client et de la commande, triées par date de création »
Claude construit une requête de ce type :
{
"tool": "babel_get_licenses",
"arguments": {
"params": {
"filter": "revoked == false && licenseType.Contains(\"Ultimate\") && createdAt >= \"2025-11-11T00:00:00\"",
"select": "id,licenseId,userKey,expireDate,licenseType,createdAt,Customer,Order",
"include": "Customer,Order",
"sort": "createdAt desc"
}
}
}Dépannage
La plupart des problèmes proviennent des paramètres de connexion, des identifiants ou de la quantité de données renvoyées par un outil. Les journaux du serveur dans le répertoire logs/ indiquent généralement la cause.
Problèmes de connexion
Si le serveur ne parvient pas à joindre le service Babel Licensing, vérifiez les points suivants dans l’ordre :
- Vérifiez que votre
BABEL_API_BASE_URLest correcte - Assurez-vous que votre clé API ou votre jeton du porteur est valide
- Vérifiez la connectivité réseau vers le serveur Babel Licensing
- Consultez les journaux du serveur dans le répertoire
logs/pour obtenir des messages d’erreur détaillés
Problèmes de certificat SSL
Si vous rencontrez des erreurs de vérification du certificat SSL (en particulier avec des certificats auto-signés) :
- Définissez
BABEL_VERIFY_SSL=falsedans votre fichier.envou dans la configuration de l’environnement - Pour Claude Desktop, ajoutez cette variable à la section
env:{ "mcpServers": { "babel-licensing": { "command": "/path/to/venv/bin/python", "args": ["/path/to/src/server.py"], "env": { "BABEL_API_BASE_URL": "https://your-server.com", "BABEL_API_KEY": "your-key", "BABEL_VERIFY_SSL": "false" } } } }
Remarque de sécurité : ne désactivez la vérification SSL que pour des serveurs internes approuvés qui utilisent des certificats auto-signés. Ne la désactivez jamais pour des systèmes de production ou des API publiques.
Erreurs d’authentification
Lorsque l’API rejette les identifiants, vérifiez les points suivants :
- Assurez-vous de n’utiliser qu’une seule méthode d’authentification (clé API ou jeton du porteur)
- Vérifiez que vos identifiants n’ont pas expiré
- Vérifiez que votre clé API dispose des autorisations nécessaires
Erreurs d’exécution des outils
Si un appel d’outil échoue, la cause est souvent un argument manquant ou d’un type incorrect. Vérifiez les points suivants :
- Vérifiez le schéma d’entrée de l’outil que vous utilisez
- Assurez-vous que tous les paramètres obligatoires sont fournis
- Vérifiez que les types des paramètres correspondent au schéma
- Examinez la réponse de l’API pour y trouver des messages d’erreur précis
Saturation des jetons avec babel_get_logs
L’outil babel_get_logs peut renvoyer de très grandes quantités de données, surtout si vous incluez les champs exception et properties. Cela peut saturer les jetons dont l’IA dispose dans la conversation.
Conseils pour la sélection des champs :
exceptionetproperties: peuvent contenir de très grandes quantités de données ; évitez-les lorsque vous demandez de nombreux enregistrementsmessageTemplate: pas strictement nécessaire, car il ne contient que le modèle de mise en forme ; le contenu réellement informatif se trouve dansmessage- Champs recommandés :
id,message,level,timeStamp
Bonnes pratiques :
-
Limitez les champs dans
select: évitez d’inclureexception,propertiesetmessageTemplate, sauf besoin précis# Good - excludes large/unnecessary fields { "params": { "select": "id,message,level,timeStamp", "take": 50 } } # Risky - includes large fields { "params": { "select": "id,message,level,timeStamp,exception,properties", "take": 50 # May saturate tokens } } -
Utilisez la pagination à bon escient : lorsque vous incluez
exceptionouproperties, utilisez de petites valeurs detake(de 10 à 20 enregistrements au maximum) -
Filtrez avant de récupérer : utilisez le paramètre
filterpour réduire le nombre d’enregistrements avant de les récupérer
Documentation de l’API
Pour des informations détaillées sur les points de terminaison, les paramètres et les réponses de l’API Babel Licensing, reportez-vous au fichier de spécification OpenAPI babel-licensing-api.json inclus dans le paquet du serveur MCP.
Assistance
Pour tout problème ou toute question, écrivez à support@babelfor.net
Ressources
Ces liens mènent à la spécification MCP, au téléchargement de Claude Desktop et au reste de la documentation de Babel Licensing.
- Documentation du Model Context Protocol
- Claude Desktop
- Documentation de Babel Licensing
- Référence de l’API Babel Licensing
Historique des versions
Modifications apportées à chaque version du serveur MCP Babel Licensing :
- 0.1.0 (version initiale)
- Implémentation complète de tous les points de terminaison de l’API Babel Licensing
- Prise en charge de l’authentification, des opérations de licence et des fonctions de gestion
- Suite de tests complète
- Documentation complète