@jambonz/mcp-schema-server 0.1.0

package/schema/verbs/say.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/say",
+  "title": "Say",
+  "description": "Speaks text to the caller using text-to-speech. The text can be plain text or SSML. Optionally streams TTS output incrementally for lower latency. This is one of the most commonly used verbs in jambonz applications.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "say",
+      "description": "The verb name."
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance. Can be used to reference it in other contexts."
+    },
+    "text": {
+      "oneOf": [
+        { "type": "string" },
+        {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      ],
+      "description": "The text to speak. Can be plain text or SSML markup. If an array is provided, one entry is selected at random (useful for variety in prompts).",
+      "examples": [
+        "Hello, welcome to our service.",
+        "<speak>Hello <break time='500ms'/> welcome.</speak>",
+        ["Hello!", "Hi there!", "Welcome!"]
+      ]
+    },
+    "instructions": {
+      "type": "string",
+      "description": "Natural language instructions to guide TTS expression and delivery. Supported by vendors that offer instruction-based synthesis (e.g. ElevenLabs, some OpenAI models).",
+      "examples": ["Speak in a warm, friendly tone", "Sound excited and energetic"]
+    },
+    "stream": {
+      "type": "boolean",
+      "description": "If true, stream TTS audio to the caller incrementally as it is generated, rather than waiting for the complete audio. Reduces time-to-first-byte for long utterances. Requires a vendor that supports streaming synthesis."
+    },
+    "loop": {
+      "oneOf": [
+        { "type": "number" },
+        { "type": "string" }
+      ],
+      "description": "Number of times to repeat the speech. Use 0 or 'forever' to loop indefinitely until interrupted.",
+      "examples": [2, "forever"]
+    },
+    "synthesizer": {
+      "$ref": "../components/synthesizer",
+      "description": "Override the session-level TTS configuration for this specific utterance."
+    },
+    "earlyMedia": {
+      "type": "boolean",
+      "description": "If true, play the audio as early media (before the call is answered). Used for playing announcements or prompts to the caller before the call is formally connected."
+    },
+    "disableTtsCache": {
+      "type": "boolean",
+      "description": "If true, bypass the TTS cache and always generate fresh audio. Useful when the same text should be re-synthesized (e.g. with different SSML or when the voice has been updated)."
+    },
+    "closeStreamOnEmpty": {
+      "type": "boolean",
+      "description": "If true, close the TTS stream when an empty text string is received. Only applies when stream is true."
+    }
+  },
+  "examples": [
+    {
+      "verb": "say",
+      "text": "Hello, welcome to Acme Corp. How can I help you today?"
+    },
+    {
+      "verb": "say",
+      "text": "Please hold while I transfer your call.",
+      "synthesizer": {
+        "vendor": "elevenlabs",
+        "voice": "Rachel"
+      }
+    },
+    {
+      "verb": "say",
+      "text": ["Hello!", "Hi there!", "Welcome!"],
+      "loop": 1
+    }
+  ]
+}

package/schema/verbs/sip-decline.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/sip:decline",
+  "title": "SIP Decline",
+  "description": "Rejects an incoming call with a SIP error response. Used to decline calls with a specific status code and reason (e.g. 486 Busy Here, 603 Decline).",
+  "type": "object",
+  "properties": {
+    "verb": { "const": "sip:decline" },
+    "id": { "type": "string", "description": "An optional unique identifier for this verb instance." },
+    "status": {
+      "type": "number",
+      "description": "The SIP response status code to send.",
+      "examples": [486, 603, 404, 480]
+    },
+    "reason": {
+      "type": "string",
+      "description": "The SIP reason phrase to include in the response.",
+      "examples": ["Busy Here", "Decline", "Not Found"]
+    },
+    "headers": {
+      "type": "object",
+      "description": "Custom SIP headers to include in the response.",
+      "additionalProperties": { "type": "string" }
+    }
+  },
+  "required": ["status"],
+  "examples": [
+    { "verb": "sip:decline", "status": 486, "reason": "Busy Here" },
+    { "verb": "sip:decline", "status": 603, "reason": "Decline" }
+  ]
+}

package/schema/verbs/sip-refer.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/sip:refer",
+  "title": "SIP Refer",
+  "description": "Sends a SIP REFER request to transfer the call to another party. Initiates an attended or unattended (blind) transfer.",
+  "type": "object",
+  "properties": {
+    "verb": { "const": "sip:refer" },
+    "id": { "type": "string", "description": "An optional unique identifier for this verb instance." },
+    "referTo": {
+      "type": "string",
+      "description": "The SIP URI or phone number to transfer the call to.",
+      "examples": ["sip:alice@example.com", "+15085551212"]
+    },
+    "referredBy": {
+      "type": "string",
+      "description": "The SIP URI to use in the Referred-By header."
+    },
+    "referredByDisplayName": {
+      "type": "string",
+      "description": "The display name to use in the Referred-By header."
+    },
+    "headers": {
+      "type": "object",
+      "description": "Custom SIP headers to include in the REFER request.",
+      "additionalProperties": { "type": "string" }
+    },
+    "actionHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when the REFER completes (or fails)."
+    },
+    "eventHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked for NOTIFY events during the REFER process, providing transfer progress updates."
+    }
+  },
+  "required": ["referTo"],
+  "examples": [
+    { "verb": "sip:refer", "referTo": "sip:alice@example.com", "actionHook": "/refer-complete" }
+  ]
+}

package/schema/verbs/sip-request.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/sip:request",
+  "title": "SIP Request",
+  "description": "Sends a SIP request within the current dialog. Used to send INFO, NOTIFY, or other SIP methods to the remote party during an active call.",
+  "type": "object",
+  "properties": {
+    "verb": { "const": "sip:request" },
+    "id": { "type": "string", "description": "An optional unique identifier for this verb instance." },
+    "method": {
+      "type": "string",
+      "description": "The SIP method to send.",
+      "examples": ["INFO", "NOTIFY", "MESSAGE"]
+    },
+    "body": {
+      "type": "string",
+      "description": "The body of the SIP request."
+    },
+    "headers": {
+      "type": "object",
+      "description": "Custom SIP headers to include in the request.",
+      "additionalProperties": { "type": "string" }
+    },
+    "actionHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when the response to the SIP request is received."
+    }
+  },
+  "required": ["method"],
+  "examples": [
+    { "verb": "sip:request", "method": "INFO", "body": "Signal=1\nDuration=250", "headers": { "Content-Type": "application/dtmf-relay" } }
+  ]
+}

package/schema/verbs/stream.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/stream",
+  "title": "Stream",
+  "description": "Streams real-time call audio to an external websocket endpoint. Functionally equivalent to 'listen' — this is an alias provided for naming clarity when the intent is audio streaming rather than recording.",
+  "type": "object",
+  "properties": {
+    "verb": { "const": "stream" },
+    "id": { "type": "string", "description": "An optional unique identifier for this verb instance." },
+    "url": { "type": "string", "format": "uri", "description": "The websocket URL to stream audio to." },
+    "actionHook": { "$ref": "../components/actionHook", "description": "A webhook invoked when the stream ends." },
+    "wsAuth": { "$ref": "../components/auth", "description": "Authentication credentials for the websocket connection." },
+    "mixType": { "type": "string", "enum": ["mono", "stereo", "mixed"], "description": "How to mix audio channels." },
+    "metadata": { "type": "object", "description": "Metadata to send with the initial connection.", "additionalProperties": true },
+    "sampleRate": { "type": "number", "description": "Audio sample rate in Hz.", "examples": [8000, 16000] },
+    "finishOnKey": { "type": "string", "description": "DTMF key that ends the stream." },
+    "maxLength": { "type": "number", "description": "Maximum duration in seconds." },
+    "passDtmf": { "type": "boolean", "description": "Forward DTMF events to the websocket." },
+    "playBeep": { "type": "boolean", "description": "Play a beep before streaming begins." },
+    "disableBidirectionalAudio": { "type": "boolean", "description": "Disable receiving audio from the websocket." },
+    "bidirectionalAudio": { "$ref": "../components/bidirectionalAudio", "description": "Bidirectional audio configuration." },
+    "timeout": { "type": "number", "description": "Inactivity timeout in seconds." },
+    "transcribe": { "type": "object", "description": "Simultaneous transcription configuration.", "additionalProperties": true },
+    "earlyMedia": { "type": "boolean", "description": "Stream audio before the call is answered." }
+  },
+  "required": ["url"],
+  "examples": [
+    { "verb": "stream", "url": "wss://myapp.example.com/audio", "sampleRate": 16000, "mixType": "stereo" }
+  ]
+}

package/schema/verbs/tag.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/tag",
+  "title": "Tag",
+  "description": "Attaches arbitrary metadata to the current call. Tagged data is included in all subsequent webhook requests and in the call detail record (CDR). Useful for tracking business context, routing decisions, or analytics data through the call lifecycle.",
+  "type": "object",
+  "properties": {
+    "verb": { "const": "tag" },
+    "id": { "type": "string", "description": "An optional unique identifier for this verb instance." },
+    "data": {
+      "type": "object",
+      "description": "An object containing the metadata to attach to the call. Keys and values are application-defined.",
+      "additionalProperties": true,
+      "examples": [{ "customerId": "12345", "department": "support", "priority": "high" }]
+    }
+  },
+  "required": ["data"],
+  "examples": [
+    { "verb": "tag", "data": { "customerId": "12345", "intent": "billing-inquiry" } }
+  ]
+}

package/schema/verbs/transcribe.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/transcribe",
+  "title": "Transcribe",
+  "description": "Enables real-time transcription of the call audio. Transcription results are sent to the transcriptionHook as they are produced. Runs as a background process — subsequent verbs execute immediately while transcription continues.",
+  "type": "object",
+  "properties": {
+    "verb": { "const": "transcribe" },
+    "id": { "type": "string", "description": "An optional unique identifier for this verb instance." },
+    "transcriptionHook": {
+      "type": "string",
+      "format": "uri",
+      "description": "The webhook URL to receive transcription results."
+    },
+    "translationHook": {
+      "type": "string",
+      "format": "uri",
+      "description": "The webhook URL to receive translated transcription results."
+    },
+    "recognizer": {
+      "$ref": "../components/recognizer",
+      "description": "STT configuration for the transcription."
+    },
+    "earlyMedia": {
+      "type": "boolean",
+      "description": "If true, begin transcribing before the call is answered."
+    },
+    "channel": {
+      "type": "number",
+      "description": "Specific audio channel to transcribe."
+    }
+  },
+  "examples": [
+    {
+      "verb": "transcribe",
+      "transcriptionHook": "https://myapp.example.com/transcription",
+      "recognizer": {
+        "vendor": "deepgram",
+        "language": "en-US",
+        "deepgramOptions": { "model": "nova-2", "smartFormatting": true }
+      }
+    }
+  ]
+}