Server MCP di VoiceBooker

Il server MCP (Model Context Protocol) di VoiceBooker consente a un client AI compatibile di gestire le risorse VoiceBooker dell’utente autenticato. Puoi ispezionare e modificare bot e stage, configurare account SIP e analizzare la cronologia delle chiamate senza creare un’integrazione REST separata.

Collegare il server

Il server utilizza MCP Streamable HTTP ed è disponibile all’indirizzo:

https://voicebooker.de/app/api/v1/mcp

Ogni richiesta deve includere un token API VoiceBooker nell’header X-API-TOKEN:

X-API-TOKEN: <il-tuo-token-api>

Il token determina il contesto aziendale; le risorse di altre aziende non possono essere lette o modificate. Condividi il token solo con il client MCP necessario e non inserirlo in configurazioni condivise.

Esempio di configurazione JSON:

{
  "mcpServers": {
    "voicebooker": {
      "url": "https://voicebooker.de/app/api/v1/mcp",
      "headers": { "X-API-TOKEN": "<il-tuo-token-api>" }
    }
  }
}

A seconda del client, il campo può chiamarsi headers, httpHeaders oppure essere fornito tramite una variabile d’ambiente. Ricollega il client dopo aver salvato la configurazione per consentire la scoperta automatica degli strumenti.

Utilizzo

I campi ID delle risorse usano camelCase negli schemi e nelle risposte MCP: botId, stageId, botStageId, sharedBotId e callSessionId. Il server restituisce gli ID delle risorse. Riutilizzali esattamente come vengono restituiti. Per ispezionare un bot, usa list_bots, poi list_stages con il suo ID: gli stage contengono prompt, strumenti, funzioni e comportamento effettivo. Leggi tutti gli stage prima di modificare il bot.

Per analizzare una conversazione, usa prima list_call_history, quindi get_trace_conversation con l’ID della sessione restituito. Il trace include turni, stato, stack e chiamate a funzioni o webhook.

Strumenti disponibili

Bot e stage

prompt e tools hanno ciascuno una propria modalità di esecuzione. I flag settings.promptExec e settings.toolsExec sono indipendenti e si applicano solo al campo corrispondente:

• Se promptExec è assente o false, prompt viene elaborato come testo Liquid e inviato al LLM come messaggio di sistema. Con promptExec: true, prompt deve contenere JavaScript che definisce prompt(params). La funzione deve restituire un oggetto: { prompt: "..." } crea un messaggio di sistema usato dal LLM per la risposta successiva, mentre { text: "..." } crea un messaggio assistant diretto restituito senza modifiche. Se vengono restituiti entrambi, viene usato solo prompt.
• Se toolsExec è assente o false, un valore tools non vuoto deve essere una stringa JSON decodificabile in un array di function tool compatibili con OpenAI. Ogni tool locale richiede anche un handler con lo stesso nome in functions; una funzione presente solo in functions non viene eseguita automaticamente. Con toolsExec: true, tools deve invece contenere JavaScript che definisce tools(params), e la funzione deve restituire { tools: [...] }; restituire direttamente l’array non è valido. Anche i tool generati dinamicamente richiedono handler con lo stesso nome in functions.
• I due campi possono usare modalità diverse. Ad esempio, un prompt JavaScript con tool JSON statici o un prompt Liquid con tool JavaScript generati dinamicamente sono validi. È vietato solo mescolare i formati nello stesso campo: prompt non può contenere contemporaneamente testo Liquid e una funzione JavaScript, e tools non può contenere contemporaneamente una stringa JSON e codice JavaScript.

Per un handler di tool, data viene inviato al LLM come risultato del tool, così che possa formulare la risposta successiva. text viene invece restituito direttamente come risposta assistant invariata. Se vengono restituiti entrambi, data ha la precedenza e text non viene inviato direttamente.

list_stages restituisce anche botEngine: lightweight usa JavaScript sincrono con api() e webhook, mentre extendedNodeJs usa JavaScript basato su Promise e consente fetch. Un settings.packageJson non nullo attiva extendedNodeJs; un valore assente o nullo attiva lightweight. Non usare async, await, fetch, Promise, import o require nel motore leggero.

I nomi degli stage distinguono maiuscole e minuscole. settings.initialStages definisce lo stack iniziale. Il codice del prompt può cambiare stage restituendo lo stack aggiornato:

function prompt(params) {
  params.stack.push("Booking");
  return { state: params.state, stack: params.stack, prompt: "Chiedi la data della prenotazione." };
}

Uno strumento può cambiare stage con transitionTo: "Booking"; dropStage: true rimuove lo stage corrente prima del handler. Gli strumenti dinamici usano function tools(params) { return { tools: [...] }; } e ogni strumento locale richiede un handler con lo stesso nome in functions. toolsState/toolsStack valgono per tools(params); state/stack per il suo handler.

Usa wizard per assistenti semplici a singolo stage. Per flussi esperti o multi-stage, crea o modifica gli stage separatamente.

Test dei bot

Gli strumenti per i test dei bot gestiscono configurazioni per due bot diversi dell’azienda autenticata. Il bot sorgente avvia la conversazione e il bot di destinazione risponde. Le risposte usano la struttura pubblica con srcBotId e destBotId.

settings può includere convInitBot, maxConvTurns, asCall, startTimeout e stateUpdate. Entrambi i bot devono essere visibili, appartenere all’azienda autenticata ed essere diversi.

Account SIP

Le password SIP sono solo scrivibili e non vengono mai restituite. Se una password viene omessa durante un aggiornamento, quella esistente viene conservata; una stringa vuota la cancella.

Cronologia e trace

get_trace_conversation include le chiamate webhook solo come riepilogo in fsCalls. Usa list_call_webhook_events per i dettagli completi. Le conversazioni soggette a conservazione dei dati vengono escluse e vengono applicati i filtri per API nascoste.