elevenlabs-voice-agent-mcp 1.0.0 → 1.0.2

package/src/tools/tool-tools.ts

@@ -0,0 +1,195 @@
+/**
+ * Agent tool management
+ *
+ * MCP tools for creating, listing, and deleting webhook tools that agents can invoke.
+ */
+
+import { getRequest, postRequest, deleteRequest } from "../services/elevenlabs-api.js";
+import { formatResponse } from "../services/formatters.js";
+import { ToolConfig, Agent } from "../types.js";
+import {
+  CreateWebhookToolSchema,
+  ListToolsSchema,
+  DeleteToolSchema
+} from "../schemas/tool-schemas.js";
+
+/**
+ * Creates a webhook tool for an agent
+ */
+export const elevenlabs_create_webhook_tool = {
+  name: "elevenlabs_create_webhook_tool",
+  description: `Create a webhook tool that the agent can invoke during conversations.
+
+This tool allows agents to interact with external APIs and services. When the agent determines it needs to use the tool, it will make an HTTP request to the specified URL with the provided parameters. The webhook response can inform the agent's next response.
+
+Args:
+  - agent_id (string): Agent to add the tool to
+  - name (string): Unique tool name (alphanumeric, hyphens, underscores only, max 64 chars)
+  - description (string): Clear description of what the tool does (10-500 chars)
+  - url (string): Webhook URL to call when tool is invoked
+  - method (string): HTTP method (GET, POST, PUT, PATCH, DELETE, default: POST)
+  - headers (object): Optional custom headers as key-value pairs
+  - parameters (array): Array of parameter definitions with:
+    - name (string): Parameter name
+    - type (string): Data type (string, number, boolean, object, array)
+    - description (string): Parameter description
+    - required (boolean): Whether parameter is required
+    - enum (array): Optional array of allowed values
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  Created tool configuration.
+
+Examples:
+  - Use when: "Add a tool to check order status from our API"
+  - Use when: "Create a webhook tool to schedule callbacks"
+  - Use when: "Give the agent ability to search our product catalog"
+  - Don't use when: You want to add knowledge/documents (use elevenlabs_add_knowledge_base)
+
+Error Handling:
+  - Returns "Error: Agent not found" if agent_id doesn't exist
+  - Returns "Error: Tool name already exists" if name is taken
+  - Returns "Error: Invalid URL" if webhook URL is not valid`,
+
+  zodSchema: CreateWebhookToolSchema,
+
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = CreateWebhookToolSchema.parse(args);
+
+    const toolData = {
+      name: parsed.name,
+      description: parsed.description,
+      type: "webhook",
+      url: parsed.url,
+      method: parsed.method,
+      ...(parsed.headers && { headers: parsed.headers }),
+      parameters: parsed.parameters
+    };
+
+    const tool = await postRequest<ToolConfig>(
+      `/convai/agents/${parsed.agent_id}/tools`,
+      toolData
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(tool, parsed.response_format, "tool")
+        }
+      ]
+    };
+  }
+};
+
+/**
+ * Lists all tools configured for an agent
+ */
+export const elevenlabs_list_tools = {
+  name: "elevenlabs_list_tools",
+  description: `List all tools configured for an agent.
+
+This tool retrieves all webhook tools that have been added to an agent. Use this to see what external capabilities the agent currently has access to.
+
+Args:
+  - agent_id (string): Agent identifier
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  Array of tool configurations including names, descriptions, URLs, and parameters.
+
+Examples:
+  - Use when: "Show me all tools for this agent"
+  - Use when: "What APIs can the agent access?"
+  - Use when: "List the webhook tools configured"
+  - Don't use when: You want to see agent configuration (use elevenlabs_get_agent)
+
+Error Handling:
+  - Returns "Error: Agent not found" if agent_id doesn't exist
+  - Returns empty list if agent has no tools`,
+
+  zodSchema: ListToolsSchema,
+
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = ListToolsSchema.parse(args);
+
+    // Get agent to access tools from conversation config
+    const agent = await getRequest<Agent>(`/convai/agents/${parsed.agent_id}`);
+    const tools = agent.conversation_config.agent.prompt.tools || [];
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(tools, parsed.response_format, "tool_list")
+        }
+      ]
+    };
+  }
+};
+
+/**
+ * Deletes a tool from an agent
+ */
+export const elevenlabs_delete_tool = {
+  name: "elevenlabs_delete_tool",
+  description: `Remove a webhook tool from an agent.
+
+This tool permanently deletes a webhook tool from an agent's configuration. The agent will no longer be able to invoke this tool in conversations. This action cannot be undone.
+
+Args:
+  - agent_id (string): Agent identifier
+  - tool_name (string): Name of the tool to delete
+
+Returns:
+  Confirmation message indicating successful deletion.
+
+Examples:
+  - Use when: "Remove the order_status tool from the agent"
+  - Use when: "Delete the deprecated webhook tool"
+  - Don't use when: You want to modify the tool (delete and recreate instead)
+
+Error Handling:
+  - Returns "Error: Agent not found" if agent_id doesn't exist
+  - Returns "Error: Tool not found" if tool_name doesn't exist`,
+
+  zodSchema: DeleteToolSchema,
+
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = DeleteToolSchema.parse(args);
+
+    await deleteRequest(
+      `/convai/agents/${parsed.agent_id}/tools/${parsed.tool_name}`
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Successfully deleted tool "${parsed.tool_name}" from agent ${parsed.agent_id}`
+        }
+      ]
+    };
+  }
+};

package/src/tools/utility-tools.ts

@@ -0,0 +1,147 @@
+/**
+ * Utility tools
+ *
+ * MCP tools for widget generation, voice browsing, and other utilities.
+ */
+
+import { getRequest } from "../services/elevenlabs-api.js";
+import { formatResponse, formatWidgetCode } from "../services/formatters.js";
+import { Voice } from "../types.js";
+import {
+  GenerateWidgetCodeSchema,
+  ListVoicesSchema
+} from "../schemas/tool-schemas.js";
+
+/**
+ * Generates widget embed code for testing an agent
+ */
+export const elevenlabs_generate_widget_code = {
+  name: "elevenlabs_generate_widget_code",
+  description: `Generate HTML embed code to test a voice agent on a webpage.
+
+This tool creates ready-to-use HTML code that embeds a voice agent widget on any webpage. The widget appears as a floating button that users can click to start a voice conversation with the agent. Perfect for testing agents or deploying them on websites.
+
+Args:
+  - agent_id (string): Agent to generate widget code for
+  - color (string): Optional widget color in hex format (e.g., "#FF5733")
+  - avatar_url (string): Optional avatar image URL for the widget
+
+Returns:
+  HTML code snippet with <script> tags ready to paste into a webpage.
+
+Examples:
+  - Use when: "Generate embed code to test this agent"
+  - Use when: "Create a widget for agent ag_abc123"
+  - Use when: "I want to add this agent to my website"
+  - Don't use when: You want to create a new agent (use elevenlabs_create_agent)
+
+Error Handling:
+  - Returns "Error: Agent not found" if agent_id doesn't exist
+  - Returns "Error: Invalid color format" if color is not valid hex`,
+
+  zodSchema: GenerateWidgetCodeSchema,
+
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = GenerateWidgetCodeSchema.parse(args);
+
+    // Verify agent exists
+    await getRequest(`/convai/agents/${parsed.agent_id}`);
+
+    const widgetCode = formatWidgetCode(
+      parsed.agent_id,
+      parsed.color,
+      parsed.avatar_url
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: widgetCode
+        }
+      ]
+    };
+  }
+};
+
+/**
+ * Lists available voices with filtering
+ */
+export const elevenlabs_list_voices = {
+  name: "elevenlabs_list_voices",
+  description: `Browse available ElevenLabs voices with optional filtering.
+
+This tool retrieves voices you can use for your agents. Filter by language, gender, or age to find the perfect voice. Each voice includes a preview URL so you can listen before choosing.
+
+Args:
+  - language (string): Optional - filter by language code (e.g., 'en', 'es', 'fr')
+  - gender ('male' | 'female'): Optional - filter by gender
+  - age ('young' | 'middle_aged' | 'old'): Optional - filter by age category
+  - limit (number): Maximum voices to return (1-100, default: 20)
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  List of voices with:
+  - Voice ID (for use in agent configuration)
+  - Voice name and description
+  - Labels (gender, age, accent, use case)
+  - Preview URL to listen to the voice
+
+Examples:
+  - Use when: "Show me all female voices"
+  - Use when: "Find voices suitable for customer service"
+  - Use when: "List English voices with British accents"
+  - Use when: "I need to choose a voice for my agent"
+  - Don't use when: You already know the voice_id you want to use
+
+Error Handling:
+  - Returns empty list if no voices match filters
+  - Returns "Error: Invalid API key" if authentication fails`,
+
+  zodSchema: ListVoicesSchema,
+
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = ListVoicesSchema.parse(args);
+
+    const params: Record<string, unknown> = {};
+
+    if (parsed.language) {
+      params.language = parsed.language;
+    }
+
+    if (parsed.gender) {
+      params.gender = parsed.gender;
+    }
+
+    if (parsed.age) {
+      params.age = parsed.age;
+    }
+
+    const response = await getRequest<{ voices: Voice[] }>("/voices", params);
+
+    const voices = (response.voices || []).slice(0, parsed.limit);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(voices, parsed.response_format, "voice_list")
+        }
+      ]
+    };
+  }
+};

package/src/types.ts

@@ -0,0 +1,327 @@
+/**
+ * TypeScript type definitions for ElevenLabs Voice Agent API
+ *
+ * Defines interfaces for agents, conversations, tools, and API responses.
+ */
+
+import { SUPPORTED_LLMS, SUPPORTED_VOICE_MODELS, SUPPORTED_LANGUAGES, AUTH_TYPES } from "./constants.js";
+
+// Enums
+export enum ResponseFormat {
+  MARKDOWN = "markdown",
+  JSON = "json"
+}
+
+export type LLMModel = typeof SUPPORTED_LLMS[number];
+export type VoiceModel = typeof SUPPORTED_VOICE_MODELS[number];
+export type Language = typeof SUPPORTED_LANGUAGES[number];
+export type AuthType = typeof AUTH_TYPES[number];
+
+// Agent Configuration
+export interface AgentPromptConfig {
+  prompt: string;
+  llm: LLMModel;
+  temperature?: number;
+  max_tokens?: number;
+  tools?: ToolConfig[];
+  knowledge_base?: string[];
+}
+
+export interface TTSConfig {
+  voice_id: string;
+  model_id: VoiceModel;
+  optimize_streaming_latency?: number;
+  stability?: number;
+  similarity_boost?: number;
+}
+
+export interface ASRConfig {
+  quality?: "low" | "medium" | "high";
+  user_input_audio_format?: "pcm_16000" | "pcm_22050" | "pcm_44100";
+}
+
+export interface ConversationConfig {
+  agent: {
+    prompt: AgentPromptConfig;
+    first_message?: string;
+    language: Language;
+  };
+  tts: TTSConfig;
+  asr?: ASRConfig;
+}
+
+export interface PlatformSettings {
+  widget?: {
+    color?: string;
+    avatar_url?: string;
+  };
+  auth?: {
+    type: AuthType;
+    open_auth_allowed?: boolean;
+  };
+}
+
+export interface Agent {
+  agent_id: string;
+  name: string;
+  conversation_config: ConversationConfig;
+  platform_settings?: PlatformSettings;
+  created_at: string;
+  updated_at?: string;
+}
+
+// Tool Configuration
+export interface ToolParameter {
+  name: string;
+  type: "string" | "number" | "boolean" | "object" | "array";
+  description: string;
+  required: boolean;
+  enum?: string[];
+}
+
+export interface ToolConfig {
+  name: string;
+  description: string;
+  type: "webhook" | "client";
+  url?: string;
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  headers?: Record<string, string>;
+  parameters: ToolParameter[];
+}
+
+// Conversation
+export interface ConversationMetadata {
+  conversation_id: string;
+  agent_id: string;
+  status: "in_progress" | "completed" | "failed";
+  started_at: string;
+  ended_at?: string;
+  duration_seconds?: number;
+  transcript?: TranscriptEntry[];
+  analysis?: ConversationAnalysis;
+}
+
+export interface TranscriptEntry {
+  role: "agent" | "user";
+  message: string;
+  timestamp: string;
+  tool_calls?: ToolCall[];
+}
+
+export interface ToolCall {
+  tool_name: string;
+  parameters: Record<string, unknown>;
+  result?: unknown;
+  error?: string;
+}
+
+export interface ConversationAnalysis {
+  user_sentiment?: "positive" | "neutral" | "negative";
+  agent_performance?: number;
+  key_topics?: string[];
+}
+
+// Voice
+export interface Voice {
+  voice_id: string;
+  name: string;
+  category?: string;
+  description?: string;
+  preview_url?: string;
+  labels?: {
+    accent?: string;
+    description?: string;
+    age?: string;
+    gender?: string;
+    use_case?: string;
+  };
+}
+
+// Pagination
+export interface PaginatedResponse<T> {
+  total: number;
+  count: number;
+  offset: number;
+  items: T[];
+  has_more: boolean;
+  next_offset?: number;
+}
+
+// API Response wrappers
+export interface APIResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: string;
+}
+
+// Knowledge Base
+export interface KnowledgeBaseDocument {
+  type: "text" | "url" | "file";
+  content: string;
+  metadata?: Record<string, string>;
+}
+
+// Widget Configuration
+export interface WidgetConfig {
+  agent_id: string;
+  color?: string;
+  avatar_url?: string;
+}
+
+// Outbound Calling
+export interface OutboundCallRequest {
+  agent_id: string;
+  agent_phone_number_id: string;
+  to_number: string;
+  /**
+   * Conversation initiation data for personalization
+   * @example
+   * {
+   *   dynamic_variables: {
+   *     customer_name: "John Smith",
+   *     account_id: "12345"
+   *   },
+   *   conversation_config_override: {
+   *     agent: {
+   *       first_message: "Custom greeting"
+   *     }
+   *   }
+   * }
+   */
+  conversation_initiation_client_data?: Record<string, unknown> | null;
+}
+
+export interface OutboundCallResponse {
+  success: boolean;
+  message: string;
+  conversation_id: string | null;
+  callSid: string | null;
+}
+
+// Batch Calling
+export type BatchStatus = "pending" | "in_progress" | "completed" | "failed" | "cancelled";
+export type RecipientStatus = BatchStatus | "initiated" | "voicemail";
+export type PhoneProvider = "twilio" | "sip_trunk";
+
+export interface OutboundCallRecipient {
+  id?: string;
+  phone_number?: string;
+  whatsapp_user_id?: string;
+  /**
+   * Conversation initiation data for personalization
+   * @example
+   * {
+   *   dynamic_variables: {
+   *     name: "Alice Johnson",
+   *     account_id: "A123"
+   *   }
+   * }
+   */
+  conversation_initiation_client_data?: Record<string, unknown>;
+}
+
+export interface BatchCallRequest {
+  call_name: string;
+  agent_id: string;
+  recipients: OutboundCallRecipient[];
+  scheduled_time_unix?: number | null;
+  agent_phone_number_id?: string | null;
+}
+
+export interface BatchCallResponse {
+  id: string;
+  name: string;
+  agent_id: string;
+  agent_name: string;
+  status: BatchStatus;
+  created_at_unix: number;
+  scheduled_time_unix: number;
+  last_updated_at_unix: number;
+  total_calls_dispatched: number;
+  total_calls_scheduled: number;
+  phone_number_id: string | null;
+  phone_provider: PhoneProvider | null;
+}
+
+export interface BatchCallRecipient {
+  id: string;
+  phone_number?: string;
+  whatsapp_user_id?: string;
+  status: RecipientStatus;
+  conversation_id: string;
+  created_at_unix: number;
+  updated_at_unix: number;
+  /**
+   * Conversation initiation data for personalization
+   * @example
+   * {
+   *   dynamic_variables: {
+   *     name: "Bob Wilson",
+   *     appointment_time: "3pm"
+   *   }
+   * }
+   */
+  conversation_initiation_client_data?: Record<string, unknown>;
+}
+
+export interface BatchCallDetailedResponse extends BatchCallResponse {
+  recipients: BatchCallRecipient[];
+}
+
+export interface WorkspaceBatchCallsResponse {
+  batch_calls: BatchCallResponse[];
+  next_doc: string | null;
+  has_more: boolean;
+}
+
+// Phone Number Management
+export interface TwilioPhoneNumber {
+  phone_number: string;
+  label: string;
+  phone_number_id: string;
+  supports_inbound: boolean;
+  supports_outbound: boolean;
+  provider: "twilio";
+  assigned_agent: {
+    agent_id: string;
+    agent_name: string;
+  } | null;
+}
+
+export interface SIPTrunkPhoneNumber {
+  phone_number: string;
+  label: string;
+  phone_number_id: string;
+  supports_inbound: boolean;
+  supports_outbound: boolean;
+  provider: "sip_trunk";
+  livekit_stack: "standard" | "static";
+  assigned_agent: {
+    agent_id: string;
+    agent_name: string;
+  } | null;
+  outbound_trunk?: Record<string, unknown> | null;
+  inbound_trunk?: Record<string, unknown> | null;
+  provider_config?: Record<string, unknown> | null;
+}
+
+export type PhoneNumber = TwilioPhoneNumber | SIPTrunkPhoneNumber;
+
+export interface ImportPhoneNumberRequest {
+  phone_number: string;
+  label: string;
+  sid: string;
+  token: string;
+  provider: "twilio";
+  supports_inbound?: boolean;
+  supports_outbound?: boolean;
+  region_config?: {
+    region_id: "us1" | "ie1" | "au1";
+    token: string;
+    edge_location: "ashburn" | "dublin" | "frankfurt" | "sao-paulo" | "singapore" | "sydney" | "tokyo" | "umatilla" | "roaming";
+  };
+}
+
+export interface ImportPhoneNumberResponse {
+  phone_number_id: string;
+}