Skip to Content
Nuova versione 12 disponibile 🎉

Server MCP di Babel Licensing Data Center

Il server MCP di Babel Licensing è un server Model Context Protocol  (MCP) scritto in Python che espone come strumenti tutte le funzioni dell’API di Babel Licensing. Gli assistenti AI come Claude possono così interagire direttamente con il tuo sistema Babel Licensing per la gestione delle licenze, le operazioni sui clienti, la gestione dei prodotti e altro ancora.

Il server MCP Licensing è distribuito con Data Center come componente separato. Non è un endpoint incorporato né uno switch nelle impostazioni Server dell’applicazione web.

Che cos’è MCP?

Il Model Context Protocol (MCP) è uno standard aperto che permette agli assistenti AI di connettersi in modo sicuro a sistemi e origini dati esterni. I server MCP fanno da ponte tra i modelli AI e i tuoi sistemi aziendali, e consentono di interagire in linguaggio naturale con API, database e strumenti.

Funzionalità

Il server trasforma l’API di Babel Licensing in strumenti MCP e si occupa dei dettagli della connessione al posto tuo. Queste sono le sue caratteristiche principali:

  • Copertura completa dell’API: espone come strumenti MCP tutti gli oltre 90 endpoint dell’API di Babel Licensing
  • Configurazione tipizzata: configurazione basata su Pydantic con convalida automatica
  • Supporto dell’autenticazione: supporta l’autenticazione sia con chiave API sia con token Bearer
  • Rotazione giornaliera dei log: registrazione automatica nella cartella logs/ con rotazione giornaliera dei file
  • Set completo di strumenti: include strumenti per:
    • Autenticazione e gestione degli utenti
    • Operazioni sulle licenze (attivazione, disattivazione, convalida, richiesta, rilascio)
    • Gestione di clienti e contatti
    • Gestione di prodotti e ordini
    • Modelli di licenza e token
    • Webhook e gestione degli eventi
    • Report e log
    • Notifiche email
    • Impostazioni e configurazione del sistema

Requisiti

Il server viene eseguito sul tuo computer accanto al client AI e chiama l’API del tuo Babel Licensing Service. Prima di installarlo, assicurati di avere:

  • Python 3.10 o versione successiva
  • Accesso all’API di Babel Licensing (URL di base e credenziali)
  • Un client compatibile con MCP (per esempio Claude Desktop)

Installazione

Il server MCP viene distribuito come archivio ZIP. Puoi lasciare che lo script di configurazione prepari tutto oppure creare tu stesso l’ambiente Python.

Avvio rapido

Lo script di configurazione crea un ambiente virtuale Python in venv, installa le dipendenze da requirements.txt e crea il file .env da .env.example. Successivamente devi solo inserire le tue credenziali in .env.

macOS / Linux

Apri un terminale e segui questi passaggi:

  1. Estrai l’archivio e spostati nella cartella:
unzip babel-licensing-mcp-*.zip cd babel-licensing-mcp-*
  1. Esegui lo script di installazione:
chmod +x setup.sh ./setup.sh
  1. Configura il tuo ambiente:
# Edit .env file with your Babel Licensing API credentials nano .env

Windows

Su Windows gli stessi passaggi vengono eseguiti in PowerShell con lo script setup.ps1:

  1. Estrai l’archivio ZIP e spostati nella cartella in PowerShell

  2. Abilita l’esecuzione degli script PowerShell (se necessario):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  1. Esegui lo script di installazione:
.\setup.ps1
  1. Configura il tuo ambiente:
# Edit .env file with your Babel Licensing API credentials notepad .env

Installazione manuale

Se preferisci non eseguire lo script di configurazione, questi sono gli stessi passaggi eseguiti manualmente dalla cartella dell’archivio estratto.

Crea un ambiente virtuale

Crea un ambiente virtuale nella cartella venv e attivalo, in modo che le dipendenze del server restino separate dal Python di sistema.

python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

Installa le dipendenze

Con l’ambiente virtuale attivo, installa i pacchetti elencati in requirements.txt.

pip install -r requirements.txt

Configura le variabili d’ambiente

Copia .env.example in .env, quindi inserisci l’indirizzo del tuo Babel Licensing Service e le tue credenziali come descritto in Configurazione.

cp .env.example .env # Edit .env with your actual credentials

Configurazione

Il server richiede le seguenti variabili d’ambiente (configurate in .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 logging

Configurazione del tipo di contenuto

Il server supporta due tipi di contenuto per le richieste all’API:

  • application/json (predefinito): formato JSON standard
  • application/toon: formato TOON per casi d’uso specifici

Per usare il formato TOON, imposta la variabile d’ambiente BABEL_CONTENT_TYPE:

BABEL_CONTENT_TYPE=application/toon

Il client imposta automaticamente le intestazioni Content-Type e Accept appropriate per tutte le richieste all’API.

Utilizzo

Una volta configurato, puoi avviare il server da un terminale per verificare che funzioni, quindi registrarlo nel tuo client AI in modo che il client lo avvii quando necessario.

Eseguire il server MCP

Esistono due modi per avviare il server. Esegui uno dei due comandi con l’ambiente virtuale attivo, dalla cartella del server MCP.

Opzione 1: usare il comando installato

Il pacchetto installato fornisce il comando babel-licensing-mcp, che avvia il server.

babel-licensing-mcp

Opzione 2: esecuzione diretta

Puoi anche eseguire direttamente lo script del server con Python.

python src/server.py

Configurare i client AI

Il server MCP di Babel Licensing può essere usato con qualsiasi client AI compatibile con MCP, compresi Claude Desktop e Claude Code.

Configurare Claude Desktop

Aggiungi quanto segue al file di configurazione di 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

Imposta command sull’interprete Python all’interno della cartella venv e args su src/server.py, entrambi con percorsi assoluti. La sezione env passa l’indirizzo del servizio e la chiave API al server, così il client non dipende da un file .env nella sua cartella di lavoro.

{ "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" } } } }

Esempio con percorsi reali (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" } } } }

Esempio con percorsi reali (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" } } } }

Nota: sostituisci /absolute/path/to/ con il percorso effettivo della cartella del tuo progetto. Puoi trovarlo eseguendo pwd (macOS/Linux) o cd (Windows) nella cartella del progetto.

Alternativa: usare il file .env

Invece di specificare le variabili d’ambiente nella configurazione di Claude Desktop, puoi creare un file .env nella cartella principale del progetto:

# 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-here

Poi usa una configurazione di Claude Desktop più semplice:

{ "mcpServers": { "babel-licensing": { "command": "/absolute/path/to/babel-licensing-mcp/venv/bin/python", "args": [ "/absolute/path/to/babel-licensing-mcp/src/server.py" ] } } }

Dopo la configurazione:

  1. Chiudi completamente Claude Desktop e riavvialo
  2. Avvia una nuova conversazione
  3. Cerca l’icona degli strumenti 🔨, che indica che i server MCP sono connessi
  4. Chiedi a Claude: “A quali strumenti di Babel Licensing hai accesso?”

Configurare Claude Code

Claude Code è un’estensione di VS Code che porta l’assistenza dell’AI direttamente nel tuo ambiente di sviluppo. Per usare il server MCP di Babel Licensing con Claude Code:

Passo 1: installa Claude Code

Installa l’estensione Claude Code dal marketplace di VS Code:

  1. Apri VS Code
  2. Vai a Extensions (Cmd+Shift+X su macOS, Ctrl+Shift+X su Windows/Linux)
  3. Cerca “Claude Code”
  4. Fai clic su Install

Passo 2: aggiungi il server MCP alle impostazioni

Apri le impostazioni di VS Code e aggiungi la configurazione del server MCP:

Opzione A: impostazioni dell’area di lavoro (consigliata per l’uso in un progetto specifico)

Crea o modifica .vscode/settings.json nella tua area di lavoro:

{ "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" } } } }

Opzione B: impostazioni utente (per l’accesso globale da tutte le aree di lavoro)

  1. Apri la Command Palette (Cmd+Shift+P su macOS, Ctrl+Shift+P su Windows/Linux)
  2. Digita “Preferences: Open User Settings (JSON)”
  3. Aggiungi la configurazione 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" } } } }

Passo 3: usa le variabili d’ambiente

Nella configurazione puoi fare riferimento alle variabili d’ambiente:

{ "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}" } } } }

Poi imposta le variabili d’ambiente nella shell prima di avviare 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 .

Passo 4: usa il file .env (l’approccio più semplice)

Configura il file .env nella cartella del server MCP con le tue credenziali, poi usa una configurazione minima:

{ "claude.mcpServers": { "babel-licensing": { "command": "/path/to/babel-licensing-mcp/venv/bin/python", "args": ["/path/to/babel-licensing-mcp/src/server.py"] } } }

Il server carica automaticamente le impostazioni dal file .env.

Passo 5: esempi di percorsi per ogni piattaforma

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" ] } } }

Passo 6: usa i percorsi relativi

Per le configurazioni specifiche di un’area di lavoro puoi usare le variabili di 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" } } }

È utile quando il server MCP si trova in una cartella allo stesso livello della tua area di lavoro.

Passo 7: verifica l’installazione

Dopo la configurazione, ricarica VS Code per attivare il server MCP:

  1. Apri la Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
  2. Digita “Developer: Reload Window”
  3. Premi Enter

Per verificare che il server funzioni:

  1. Apri il pannello di Claude in VS Code
  2. Avvia una nuova conversazione
  3. Chiedi: “Quali funzionalità di Babel Licensing hai a disposizione?”
  4. Claude dovrebbe elencare tutti gli 86 strumenti disponibili

Suggerimenti per l’uso di Claude Code:

  1. Richieste che tengono conto del contesto: Claude Code vede il file corrente e l’area di lavoro, quindi puoi chiedere:

    • “In base a questo codice, crea una licenza per questo cliente”
    • “Genera una chiamata di attivazione della licenza per il prodotto in questo file”
  2. Generazione di codice: chiedi a Claude di generare codice che usa l’API di Babel Licensing:

    • “Scrivi un metodo C# che attivi una licenza con questi parametri”
    • “Crea uno script Python che interroghi tutte le licenze attive”
  3. Assistenza inline: seleziona del codice e chiedi a Claude:

    • “Controlla se questa chiave di licenza è valida”
    • “Trova il cliente associato a questa chiave utente”
  4. Operazioni su più file: Claude può aiutarti a coordinare la gestione delle licenze tra più file:

    • “Aggiorna le chiavi di licenza in tutti i file di configurazione”
    • “Trova tutte le chiavi di licenza scritte direttamente nel codice di questo progetto”

Risoluzione dei problemi di Claude Code:

Se il server MCP non si connette:

  1. Controlla lo stato dell’estensione: assicurati che l’estensione Claude Code sia attiva
  2. Verifica il percorso di Python: controlla che il percorso dell’ambiente virtuale sia corretto
  3. Controlla i log: visualizza l’output di Claude Code nel pannello Output di VS Code
  4. Ricarica la finestra: usa “Developer: Reload Window” dopo le modifiche alla configurazione
  5. Controlla i permessi: assicurati che l’eseguibile di Python abbia i permessi di esecuzione

Configurazione di più ambienti:

Puoi configurare ambienti Babel Licensing diversi:

{ "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}" } } } }

In questo modo puoi passare dall’ambiente di produzione a quello di sviluppo mentre lavori con Claude.

Log

Il server registra automaticamente tutte le operazioni in file di log giornalieri nella cartella logs/:

  • Posizione: logs/babel_licensing_YYYYMMDD.log
  • Formato: voci con data e ora, livello e informazioni sul modulo
  • Rotazione: crea automaticamente un nuovo file ogni giorno
  • Output: i log vengono scritti sia su file sia sulla console

Esempio di file di log: 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_customers

Strumenti disponibili

Il server espone 86 strumenti organizzati nelle seguenti categorie:

Nota: l’autenticazione è gestita automaticamente tramite la chiave API o il token Bearer configurati nelle variabili d’ambiente. Gli strumenti di accesso interattivo non sono necessari.

Operazioni sulle licenze (7 strumenti)

Questi strumenti chiamano gli endpoint per le licenze del client, le stesse operazioni che un’applicazione con licenza esegue in fase di esecuzione:

  • babel_activate_license: attiva una licenza
  • babel_deactivate_license: disattiva una licenza
  • babel_request_license: richiede una licenza
  • babel_release_license: rilascia una licenza
  • babel_license_heartbeat: invia l’heartbeat della licenza
  • babel_validate_license: convalida una licenza
  • babel_get_license_info: ottiene le informazioni sulla licenza

Gestione

Gli strumenti di gestione operano sui dati archiviati dal Babel Licensing Service. Di seguito sono raggruppati in base al tipo di record che gestiscono.

Chiavi API (4 strumenti)

Gli strumenti per le chiavi API elencano, creano, modificano ed eliminano le chiavi che danno accesso all’API di Babel Licensing.

  • babel_get_api_keys: elenca le chiavi API
  • babel_insert_api_key: crea una nuova chiave API
  • babel_update_api_key: aggiorna una chiave API
  • babel_delete_api_key: elimina una chiave API

Utenti (7 strumenti)

Gli strumenti per gli utenti gestiscono gli account del Babel Licensing Service e i ruoli a essi assegnati.

  • babel_get_users: elenca gli utenti
  • babel_insert_user: crea un utente
  • babel_update_user: aggiorna un utente
  • babel_delete_user: elimina un utente
  • babel_get_user_roles: ottiene i ruoli di un utente
  • babel_add_user_to_roles: aggiunge un utente ai ruoli
  • babel_remove_user_from_roles: rimuove un utente dai ruoli

Clienti (7 strumenti)

Gli strumenti per i clienti gestiscono i record dei clienti e leggono i contatti, gli ordini e le licenze che appartengono a ciascun cliente.

  • babel_get_customers: elenca i clienti
  • babel_insert_customer: crea un cliente
  • babel_update_customer: aggiorna un cliente
  • babel_delete_customer: elimina un cliente
  • babel_get_customer_contacts: ottiene i contatti di un cliente
  • babel_get_customer_orders: ottiene gli ordini di un cliente
  • babel_get_customer_licenses: ottiene le licenze di un cliente

Prodotti (15 strumenti)

Gli strumenti per i prodotti coprono i prodotti, i relativi rilasci, gli assembly di ciascun rilascio e i modelli di licenza collegati a un rilascio.

  • Gestione dei prodotti (lettura, inserimento, aggiornamento, eliminazione)
  • Gestione dei rilasci dei prodotti
  • Gestione degli assembly dei rilasci
  • Modelli di licenza dei rilasci

Ordini (9 strumenti)

Gli strumenti per gli ordini gestiscono gli ordini, i prodotti di ciascun ordine e le licenze emesse per un ordine.

  • Gestione degli ordini (lettura, inserimento, aggiornamento, eliminazione)
  • Gestione dei prodotti degli ordini
  • Recupero delle licenze degli ordini

Licenze (9 strumenti)

Gli strumenti per le licenze gestiscono i record delle licenze insieme ai relativi token, tracce e modelli.

  • Gestione delle licenze (lettura, inserimento, aggiornamento, eliminazione)
  • Gestione dei token di licenza
  • Tracce delle licenze
  • Modelli di licenza

Webhook (9 strumenti)

Gli strumenti per i webhook gestiscono le sottoscrizioni e i relativi eventi, elencano i tipi di evento disponibili e inviano eventi di test.

  • Gestione delle sottoscrizioni webhook
  • Recupero dei tipi di evento
  • Test dei webhook
  • Gestione degli eventi

Altri strumenti di gestione

Gli strumenti rimanenti coprono gli altri record e le altre funzioni del servizio. Il numero tra parentesi indica quanti strumenti contiene ciascun gruppo.

  • Assembly (4 strumenti)
  • Contatti (4 strumenti)
  • Risorse (4 strumenti)
  • Report (3 strumenti)
  • Log (3 strumenti)
  • Impostazioni (2 strumenti)
  • Email (2 strumenti)
  • Informazioni sul server (1 strumento)

Lavorare con l’API

Questa sezione spiega quali dati gli strumenti si aspettano in input e come il server prepara i tuoi dati prima di chiamare l’API di Babel Licensing.

Formato dei dati per le operazioni di inserimento e aggiornamento

Quando usi gli strumenti che creano o aggiornano risorse (quelli il cui nome inizia con babel_insert_ o babel_update_), il client racchiude automaticamente i tuoi dati nel formato di richiesta previsto dall’API di Babel Licensing.

Devi fornire solo i dati grezzi: l’incapsulamento è gestito automaticamente.

Esempi

Creare un nuovo cliente:

// 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" } }

Creare un nuovo utente:

// 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" }

Aggiornare una licenza:

// 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" } }

Parametri di query

Molti endpoint GET supportano i seguenti parametri di query:

  • select: elenco separato da virgole dei nomi dei campi da includere nella risposta
  • filter: criteri di filtro con la sintassi .NET (vedi Sintassi dei filtri più avanti)
  • include: elenco separato da virgole degli oggetti correlati da includere (vedi Parametro include più avanti)
  • sort: nome del campo, con ‘asc’ o ‘desc’ facoltativi
  • take: limite di paginazione (dimensione della pagina)
  • skip: offset di paginazione

Parametro include

Il parametro include ti permette di recuperare gli oggetti correlati in un’unica richiesta.

Regole IMPORTANTI:

  1. Usa i nomi in PascalCase (con l’iniziale maiuscola): Customer, Order, Product (NON customer, order, product)
  2. DEVI aggiungere a select gli oggetti inclusi: indicali in entrambi i parametri
  3. Più oggetti: separali con una virgola, senza spazi

Esempi:

// 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! } }

Opzioni di include disponibili:

  • babel_get_licenses: Product, Order, Customer, Template, Licensee
  • babel_get_customers: Contacts, Orders, Licenses
  • babel_get_orders: Customer, Reseller, Products, Licenses
  • babel_get_products: Releases, Orders
  • babel_get_users: Roles, Settings, Customer
  • babel_get_api_keys: Owner
  • babel_get_all_license_tokens: License, NodeLockedLicense
  • babel_get_license_templates: Product

Sintassi dei filtri

L’API usa la sintassi dei filtri .NET, NON lo standard OData.

Operatori di confronto:

OperatoreDescrizioneEsempio
>=Maggiore o ugualecreatedAt >= "2025-11-11T00:00:00"
<=Minore o ugualeexpireDate <= "2025-12-31T23:59:59"
>Maggioreid > 100
<Minoreid < 1000
==Ugualerevoked == false
!=Diversostatus != "expired"

Operatori logici:

OperatoreDescrizioneEsempio
&&AND logicorevoked == false && expireDate >= "2025-01-01"
||OR logicostatus == "active" || status == "trial"
!Negazione (NOT)!revoked o !licenseType.Contains("Trial")

Funzioni per le stringhe:

FunzioneDescrizioneEsempio
Contains()Verifica se la stringa contiene una sottostringalicenseType.Contains("Ultimate")
StartsWith()Verifica se la stringa inizia con una sottostringauserKey.StartsWith("ABC")
EndsWith()Verifica se la stringa termina con una sottostringalicenseeEmail.EndsWith("@example.com")

Esempi di filtri complessi:

# 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")

IMPORTANTE: NON usare la sintassi OData (eq, ne, gt, lt, and, or). Questi operatori non funzionano.

Parametro sort:

Il parametro sort accetta:

  • Nome del campo con direzione: createdAt desc (decrescente)
  • Nome del campo con direzione: createdAt asc (crescente)
  • Solo il nome del campo: createdAt (crescente per impostazione predefinita)

Esempio completo:

{ "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" } }

Esempi

Parli con l’assistente AI in linguaggio naturale ed è lui a scegliere lo strumento e a compilare gli argomenti. Gli esempi seguenti mostrano una richiesta e la chiamata allo strumento che ne deriva.

Attivare una licenza

Chiedi a Claude:

“Attiva una licenza con chiave utente ABC-123-DEF, codice prodotto PROD001 e ID hardware HW-12345”

Claude userà lo strumento babel_activate_license:

{ "tool": "babel_activate_license", "arguments": { "license_data": { "userKey": "ABC-123-DEF", "productCode": "PROD001", "hardwareId": "HW-12345" } } }

Ottenere i clienti

Chiedi a Claude:

“Mostrami i primi 10 clienti rivenditori, ordinati per nome dell’azienda”

Claude userà lo strumento babel_get_customers:

{ "tool": "babel_get_customers", "arguments": { "params": { "filter": "isReseller == true", "take": 10, "sort": "company asc" } } }

Creare una sottoscrizione webhook

Chiedi a Claude:

“Crea una sottoscrizione webhook per gli eventi di attivazione e disattivazione delle licenze che punti a https://example.com/webhook ”

Claude userà lo strumento babel_create_webhook_subscription:

{ "tool": "babel_create_webhook_subscription", "arguments": { "subscription_data": { "url": "https://example.com/webhook", "events": ["license.activated", "license.deactivated"], "isActive": true } } }

Esempio di query complessa

Chiedi a Claude:

“Mostrami tutte le licenze Ultimate create dopo l’11 novembre 2025 e non revocate, con i dettagli del cliente e dell’ordine, ordinate per data di creazione”

Claude costruirà una query come questa:

{ "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" } } }

Risoluzione dei problemi

La maggior parte dei problemi deriva dalle impostazioni di connessione, dalle credenziali o dalla quantità di dati restituiti da uno strumento. I log del server nella cartella logs/ di solito mostrano la causa.

Problemi di connessione

Se il server non riesce a raggiungere il servizio Babel Licensing, verifica questi punti in ordine:

  1. Verifica che il valore di BABEL_API_BASE_URL sia corretto
  2. Assicurati che la chiave API o il token Bearer siano validi
  3. Controlla la connettività di rete verso il server di Babel Licensing
  4. Consulta i log del server nella cartella logs/ per i messaggi di errore dettagliati

Problemi con i certificati SSL

Se riscontri errori di verifica del certificato SSL (soprattutto con i certificati autofirmati):

  1. Imposta BABEL_VERIFY_SSL=false nel file .env o nella configurazione dell’ambiente
  2. Per Claude Desktop, aggiungila alla sezione 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" } } } }

Nota di sicurezza: disabilita la verifica SSL solo per i server interni attendibili con certificati autofirmati. Non disabilitarla mai per i sistemi di produzione o per le API pubbliche.

Errori di autenticazione

Quando l’API rifiuta le credenziali, verifica quanto segue:

  1. Assicurati di usare UN SOLO metodo di autenticazione (chiave API OPPURE token Bearer)
  2. Verifica che le tue credenziali non siano scadute
  3. Controlla che la chiave API abbia i permessi necessari

Errori di esecuzione degli strumenti

Se una chiamata a uno strumento non riesce, spesso la causa è un argomento mancante o di tipo errato. Verifica quanto segue:

  1. Controlla lo schema di input dello strumento che stai usando
  2. Assicurati di fornire tutti i parametri obbligatori
  3. Verifica che i tipi dei parametri corrispondano allo schema
  4. Esamina la risposta dell’API per i messaggi di errore specifici

Saturazione dei token con babel_get_logs

Lo strumento babel_get_logs può restituire quantità di dati molto grandi, soprattutto quando includi i campi exception e properties. Questo può saturare i token AI disponibili nella conversazione.

Indicazioni per la scelta dei campi:

  • exception e properties: possono contenere quantità di dati molto grandi; evitali quando richiedi molti record
  • messageTemplate: non è strettamente necessario, perché contiene solo il modello di formattazione; il contenuto informativo vero e proprio è in message
  • Campi consigliati: id, message, level, timeStamp

Procedure consigliate:

  1. Limita i campi in select: evita di includere exception, properties e messageTemplate se non ti servono davvero

    # 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 } }
  2. Usa la paginazione con criterio: quando includi exception o properties, usa valori di take piccoli (10-20 record al massimo)

  3. Filtra prima di recuperare: usa il parametro filter per ridurre il numero di record prima di recuperarli

Documentazione dell’API

Per informazioni dettagliate sugli endpoint, i parametri e le risposte dell’API di Babel Licensing, consulta il file di specifica OpenAPI babel-licensing-api.json incluso nel pacchetto del server MCP.

Assistenza

Per problemi o domande, scrivi a: support@babelfor.net

Risorse

Questi collegamenti portano alla specifica MCP, al download di Claude Desktop e al resto della documentazione di Babel Licensing.

Cronologia delle versioni

Modifiche apportate in ogni versione del server MCP di Babel Licensing:

  • 0.1.0 (versione iniziale)
    • Implementazione completa di tutti gli endpoint dell’API di Babel Licensing
    • Supporto dell’autenticazione, delle operazioni sulle licenze e delle funzioni di gestione
    • Suite di test completa
    • Documentazione completa
Last updated on