elevenlabs-voice-agent-mcp 1.0.0 → 1.0.2

package/src/schemas/outbound-schemas.ts

@@ -0,0 +1,70 @@
+/**
+ * Zod validation schemas for outbound calling operations
+ *
+ * Provides strict input validation for making single outbound calls via Twilio.
+ */
+
+import { z } from "zod";
+import { ResponseFormatSchema, AgentIdSchema } from "./common-schemas.js";
+
+/**
+ * Phone number schema with E.164 format validation
+ */
+export const PhoneNumberSchema = z.string()
+  .min(1, "Phone number is required")
+  .regex(/^\+?[1-9]\d{1,14}$/, "Phone number must be in E.164 format (e.g., +1234567890)")
+  .describe("Phone number in E.164 format (e.g., '+1234567890')");
+
+/**
+ * Phone number ID schema
+ */
+export const PhoneNumberIdSchema = z.string()
+  .min(1, "Phone number ID is required")
+  .regex(/^[a-zA-Z0-9_-]+$/, "Phone number ID must contain only alphanumeric characters, hyphens, and underscores")
+  .describe("Unique identifier for the phone number");
+
+/**
+ * Config overrides schema for conversation customization
+ */
+export const ConfigOverridesSchema = z.object({
+  agent: z.object({
+    first_message: z.string().optional(),
+    system_prompt: z.string().optional(),
+    language: z.string().optional()
+  }).optional(),
+  tts: z.object({
+    voice_id: z.string().optional(),
+    model_id: z.string().optional()
+  }).optional(),
+  turn: z.object({
+    mode: z.string().optional()
+  }).optional(),
+  conversation: z.object({
+    max_duration_seconds: z.number().int().positive().optional()
+  }).optional()
+}).optional().describe("Configuration overrides for this specific call");
+
+/**
+ * Conversation initiation data schema
+ */
+export const ConversationInitDataSchema = z.record(z.any())
+  .optional()
+  .describe("Dynamic variables and configuration overrides for personalization");
+
+/**
+ * Schema for starting an outbound call
+ */
+export const StartOutboundCallSchema = z.object({
+  agent_id: AgentIdSchema,
+
+  agent_phone_number_id: PhoneNumberIdSchema,
+
+  to_number: PhoneNumberSchema
+    .describe("Destination phone number to call"),
+
+  conversation_initiation_client_data: z.record(z.any())
+    .optional()
+    .describe("Personalization data including dynamic_variables object (e.g., {dynamic_variables: {name: 'John', user_id: '123'}})"),
+
+  response_format: ResponseFormatSchema
+}).passthrough();

package/src/schemas/phone-number-schemas.ts

@@ -0,0 +1,140 @@
+/**
+ * Zod validation schemas for phone number management operations
+ *
+ * Provides strict input validation for listing, importing, updating,
+ * and deleting phone numbers connected to voice agents.
+ */
+
+import { z } from "zod";
+import { ResponseFormatSchema, AgentIdSchema } from "./common-schemas.js";
+import { PhoneNumberSchema, PhoneNumberIdSchema } from "./outbound-schemas.js";
+
+/**
+ * Phone provider enum
+ */
+export const PhoneProviderSchema = z.enum(["twilio", "sip_trunk"], {
+  errorMap: () => ({ message: "Provider must be 'twilio' or 'sip_trunk'" })
+}).describe("Phone number provider");
+
+/**
+ * Region ID schema
+ */
+export const RegionIdSchema = z.enum(["us1", "ie1", "au1"], {
+  errorMap: () => ({ message: "Region must be 'us1', 'ie1', or 'au1'" })
+}).describe("ElevenLabs region identifier");
+
+/**
+ * Edge location schema
+ */
+export const EdgeLocationSchema = z.enum([
+  "ashburn", "dublin", "frankfurt", "sao-paulo",
+  "singapore", "sydney", "tokyo", "umatilla", "roaming"
+], {
+  errorMap: () => ({ message: "Invalid edge location" })
+}).describe("Twilio edge location");
+
+/**
+ * LiveKit stack schema
+ */
+export const LiveKitStackSchema = z.enum(["standard", "static"], {
+  errorMap: () => ({ message: "LiveKit stack must be 'standard' or 'static'" })
+}).describe("LiveKit stack configuration");
+
+/**
+ * Region config schema for Twilio
+ */
+export const RegionConfigSchema = z.object({
+  region_id: RegionIdSchema,
+  token: z.string().min(1, "Region token is required"),
+  edge_location: EdgeLocationSchema
+}).describe("Regional configuration for Twilio phone numbers");
+
+/**
+ * Schema for listing phone numbers
+ */
+export const ListPhoneNumbersSchema = z.object({
+  response_format: ResponseFormatSchema
+}).passthrough();
+
+/**
+ * Schema for getting a phone number
+ */
+export const GetPhoneNumberSchema = z.object({
+  phone_number_id: PhoneNumberIdSchema,
+
+  response_format: ResponseFormatSchema
+}).passthrough();
+
+/**
+ * Schema for importing a Twilio phone number
+ */
+export const ImportPhoneNumberSchema = z.object({
+  phone_number: PhoneNumberSchema
+    .describe("Phone number to import from Twilio"),
+
+  label: z.string()
+    .min(1, "Label is required")
+    .max(100, "Label must not exceed 100 characters")
+    .describe("Descriptive label for this phone number"),
+
+  sid: z.string()
+    .min(1, "Twilio Account SID is required")
+    .describe("Twilio Account SID"),
+
+  token: z.string()
+    .min(1, "Twilio Auth Token is required")
+    .describe("Twilio Auth Token"),
+
+  provider: z.literal("twilio")
+    .describe("Must be 'twilio' for Twilio phone numbers"),
+
+  supports_inbound: z.boolean()
+    .default(true)
+    .describe("Enable inbound call handling"),
+
+  supports_outbound: z.boolean()
+    .default(true)
+    .describe("Enable outbound call capability"),
+
+  region_config: RegionConfigSchema
+    .optional()
+    .describe("Optional regional configuration for Twilio"),
+
+  response_format: ResponseFormatSchema
+}).passthrough();
+
+/**
+ * Schema for updating a phone number
+ */
+export const UpdatePhoneNumberSchema = z.object({
+  phone_number_id: PhoneNumberIdSchema,
+
+  agent_id: AgentIdSchema
+    .optional()
+    .nullable()
+    .describe("Assign or unassign agent (null to unassign)"),
+
+  inbound_trunk_config: z.record(z.any())
+    .optional()
+    .nullable()
+    .describe("SIP trunk configuration for inbound calls"),
+
+  outbound_trunk_config: z.record(z.any())
+    .optional()
+    .nullable()
+    .describe("SIP trunk configuration for outbound calls"),
+
+  livekit_stack: LiveKitStackSchema
+    .optional()
+    .nullable()
+    .describe("LiveKit stack configuration"),
+
+  response_format: ResponseFormatSchema
+}).passthrough();
+
+/**
+ * Schema for deleting a phone number
+ */
+export const DeletePhoneNumberSchema = z.object({
+  phone_number_id: PhoneNumberIdSchema
+}).passthrough();

package/src/schemas/tool-schemas.ts

@@ -0,0 +1,161 @@
+/**
+ * Zod validation schemas for tool and knowledge base operations
+ *
+ * Provides strict input validation for managing agent tools and knowledge bases.
+ */
+
+import { z } from "zod";
+import { AgentIdSchema, ResponseFormatSchema, URLSchema } from "./common-schemas.js";
+
+/**
+ * Tool parameter schema
+ */
+const ToolParameterSchema = z.object({
+  name: z.string()
+    .min(1, "Parameter name is required")
+    .describe("Name of the parameter"),
+
+  type: z.enum(["string", "number", "boolean", "object", "array"], {
+    errorMap: () => ({ message: "Type must be: string, number, boolean, object, or array" })
+  }).describe("Data type of the parameter"),
+
+  description: z.string()
+    .min(1, "Parameter description is required")
+    .describe("Description of what this parameter does"),
+
+  required: z.boolean()
+    .describe("Whether this parameter is required"),
+
+  enum: z.array(z.string())
+    .optional()
+    .describe("Optional array of allowed values for this parameter")
+}).passthrough();
+
+/**
+ * Schema for creating a webhook tool
+ */
+export const CreateWebhookToolSchema = z.object({
+  agent_id: AgentIdSchema,
+
+  name: z.string()
+    .min(1, "Tool name is required")
+    .max(64, "Tool name must not exceed 64 characters")
+    .regex(/^[a-zA-Z0-9_-]+$/, "Tool name must contain only alphanumeric characters, hyphens, and underscores")
+    .describe("Unique name for the tool (e.g., 'check_order_status')"),
+
+  description: z.string()
+    .min(10, "Description must be at least 10 characters")
+    .max(500, "Description must not exceed 500 characters")
+    .describe("Clear description of what this tool does"),
+
+  url: URLSchema
+    .describe("Webhook URL that will be called when the tool is invoked"),
+
+  method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"], {
+    errorMap: () => ({ message: "Method must be: GET, POST, PUT, PATCH, or DELETE" })
+  })
+    .default("POST")
+    .describe("HTTP method to use (default: POST)"),
+
+  headers: z.record(z.string(), z.string())
+    .optional()
+    .describe("Optional custom headers to send with the request"),
+
+  parameters: z.array(ToolParameterSchema)
+    .min(0, "Parameters array is required (can be empty)")
+    .describe("Array of parameters the tool accepts"),
+
+  response_format: ResponseFormatSchema
+}).passthrough();
+
+/**
+ * Schema for listing tools
+ */
+export const ListToolsSchema = z.object({
+  agent_id: AgentIdSchema,
+  response_format: ResponseFormatSchema
+}).passthrough();
+
+/**
+ * Schema for deleting a tool
+ */
+export const DeleteToolSchema = z.object({
+  agent_id: AgentIdSchema,
+
+  tool_name: z.string()
+    .min(1, "Tool name is required")
+    .describe("Name of the tool to delete")
+}).passthrough();
+
+/**
+ * Knowledge base document schema
+ */
+const KnowledgeBaseDocumentSchema = z.object({
+  type: z.enum(["text", "url"], {
+    errorMap: () => ({ message: "Document type must be 'text' or 'url'" })
+  }).describe("Type of document to add"),
+
+  content: z.string()
+    .min(1, "Document content is required")
+    .describe("For 'text' type: the actual text content. For 'url' type: the URL to fetch"),
+
+  metadata: z.record(z.string(), z.string())
+    .optional()
+    .describe("Optional metadata about the document")
+}).passthrough();
+
+/**
+ * Schema for adding knowledge base documents
+ */
+export const AddKnowledgeBaseSchema = z.object({
+  agent_id: AgentIdSchema,
+
+  documents: z.array(KnowledgeBaseDocumentSchema)
+    .min(1, "At least one document is required")
+    .max(100, "Cannot add more than 100 documents at once")
+    .describe("Array of documents to add to the agent's knowledge base"),
+
+  response_format: ResponseFormatSchema
+}).passthrough();
+
+/**
+ * Schema for generating widget code
+ */
+export const GenerateWidgetCodeSchema = z.object({
+  agent_id: AgentIdSchema,
+
+  color: z.string()
+    .regex(/^#[0-9A-Fa-f]{6}$/, "Must be a valid hex color (e.g., #FF5733)")
+    .optional()
+    .describe("Optional widget color (hex format)"),
+
+  avatar_url: URLSchema
+    .optional()
+    .describe("Optional avatar image URL for the widget")
+}).passthrough();
+
+/**
+ * Schema for listing voices
+ */
+export const ListVoicesSchema = z.object({
+  language: z.string()
+    .optional()
+    .describe("Filter by language code (e.g., 'en', 'es')"),
+
+  gender: z.enum(["male", "female"])
+    .optional()
+    .describe("Filter by gender"),
+
+  age: z.enum(["young", "middle_aged", "old"])
+    .optional()
+    .describe("Filter by age category"),
+
+  limit: z.number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(20)
+    .describe("Maximum number of voices to return"),
+
+  response_format: ResponseFormatSchema
+}).passthrough();

package/src/services/elevenlabs-api.ts

@@ -0,0 +1,113 @@
+/**
+ * ElevenLabs API client service
+ *
+ * Provides core HTTP request functionality for interacting with the
+ * ElevenLabs Voice Agent API, including authentication and error handling.
+ */
+
+import axios, { AxiosRequestConfig, AxiosResponse } from "axios";
+import { API_BASE_URL, REQUEST_TIMEOUT } from "../constants.js";
+import { handleElevenLabsError } from "../utils/error-handlers.js";
+
+/**
+ * Makes an authenticated request to the ElevenLabs API
+ *
+ * @param method - HTTP method (GET, POST, PUT, DELETE, etc.)
+ * @param endpoint - API endpoint path (e.g., "/convai/agents")
+ * @param data - Request body data (for POST, PUT, PATCH)
+ * @param params - URL query parameters
+ * @returns Response data from the API
+ */
+export async function makeElevenLabsRequest<T = unknown>(
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
+  endpoint: string,
+  data?: unknown,
+  params?: Record<string, unknown>
+): Promise<T> {
+  const apiKey = process.env.ELEVENLABS_API_KEY;
+
+  if (!apiKey) {
+    throw new Error(
+      "ELEVENLABS_API_KEY environment variable is not set. " +
+      "Please set it to your ElevenLabs API key."
+    );
+  }
+
+  const config: AxiosRequestConfig = {
+    method,
+    url: `${API_BASE_URL}${endpoint}`,
+    headers: {
+      "xi-api-key": apiKey,
+      "Content-Type": "application/json",
+    },
+    timeout: REQUEST_TIMEOUT,
+  };
+
+  if (data) {
+    config.data = data;
+  }
+
+  if (params) {
+    config.params = params;
+  }
+
+  try {
+    const response: AxiosResponse<T> = await axios(config);
+    return response.data;
+  } catch (error) {
+    throw new Error(handleElevenLabsError(error));
+  }
+}
+
+/**
+ * GET request helper
+ */
+export async function getRequest<T>(
+  endpoint: string,
+  params?: Record<string, unknown>
+): Promise<T> {
+  return makeElevenLabsRequest<T>("GET", endpoint, undefined, params);
+}
+
+/**
+ * POST request helper
+ */
+export async function postRequest<T>(
+  endpoint: string,
+  data: unknown,
+  params?: Record<string, unknown>
+): Promise<T> {
+  return makeElevenLabsRequest<T>("POST", endpoint, data, params);
+}
+
+/**
+ * PUT request helper
+ */
+export async function putRequest<T>(
+  endpoint: string,
+  data: unknown,
+  params?: Record<string, unknown>
+): Promise<T> {
+  return makeElevenLabsRequest<T>("PUT", endpoint, data, params);
+}
+
+/**
+ * PATCH request helper
+ */
+export async function patchRequest<T>(
+  endpoint: string,
+  data: unknown,
+  params?: Record<string, unknown>
+): Promise<T> {
+  return makeElevenLabsRequest<T>("PATCH", endpoint, data, params);
+}
+
+/**
+ * DELETE request helper
+ */
+export async function deleteRequest<T>(
+  endpoint: string,
+  params?: Record<string, unknown>
+): Promise<T> {
+  return makeElevenLabsRequest<T>("DELETE", endpoint, undefined, params);
+}