elevenlabs-voice-agent-mcp 1.0.0 → 1.0.1

package/src/tools/conversation-tools.ts

@@ -0,0 +1,167 @@
+/**
+ * Conversation retrieval tools
+ *
+ * MCP tools for accessing conversation histories, transcripts, and analytics.
+ */
+
+import { getRequest } from "../services/elevenlabs-api.js";
+import { formatResponse } from "../services/formatters.js";
+import { ConversationMetadata, PaginatedResponse } from "../types.js";
+import {
+  GetConversationSchema,
+  ListConversationsSchema
+} from "../schemas/conversation-schemas.js";
+
+/**
+ * Retrieves a single conversation with full transcript
+ */
+export const elevenlabs_get_conversation = {
+  name: "elevenlabs_get_conversation",
+  description: `Retrieve complete details and transcript for a specific conversation.
+
+This tool fetches full conversation details including the complete transcript, tool calls made, analysis metrics, and metadata. Use this to review past conversations, debug issues, or analyze agent performance.
+
+Args:
+  - conversation_id (string): Unique conversation identifier
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  Complete conversation object with:
+  - Conversation metadata (status, timestamps, duration)
+  - Full transcript with user and agent messages
+  - Tool calls made during the conversation
+  - Analysis data (sentiment, performance, key topics)
+
+Examples:
+  - Use when: "Show me the transcript for conversation conv_xyz789"
+  - Use when: "What did the agent say in this conversation?"
+  - Use when: "Review the conversation that failed"
+  - Don't use when: You want to list multiple conversations (use elevenlabs_list_conversations)
+
+Error Handling:
+  - Returns "Error: Conversation not found" if conversation_id doesn't exist
+  - Returns "Error: Invalid API key" if authentication fails`,
+
+  zodSchema: GetConversationSchema,
+
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = GetConversationSchema.parse(args);
+
+    const conversation = await getRequest<ConversationMetadata>(
+      `/convai/conversations/${parsed.conversation_id}`
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(conversation, parsed.response_format, "conversation")
+        }
+      ]
+    };
+  }
+};
+
+/**
+ * Lists conversations with filtering and pagination
+ */
+export const elevenlabs_list_conversations = {
+  name: "elevenlabs_list_conversations",
+  description: `List conversations with optional filtering by agent, status, and date range.
+
+This tool retrieves a paginated list of conversations. You can filter by agent ID, conversation status, or date range to find specific conversations. Use this for monitoring, analytics, or reviewing agent interactions.
+
+Args:
+  - agent_id (string): Optional - filter by specific agent
+  - status ('in_progress' | 'completed' | 'failed'): Optional - filter by status
+  - date_range (object): Optional - filter by date range with:
+    - start (string): Start date in ISO 8601 format
+    - end (string): End date in ISO 8601 format
+  - limit (number): Maximum conversations to return (1-100, default: 20)
+  - offset (number): Number to skip for pagination (default: 0)
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  For JSON format: Object with total count, items array, offset, has_more, and next_offset
+  For Markdown format: Formatted list of conversations with key details and pagination guidance
+
+Examples:
+  - Use when: "Show me all conversations from yesterday"
+  - Use when: "List failed conversations for agent ag_abc123"
+  - Use when: "Get the last 50 conversations"
+  - Use when: "Show conversations that are still in progress"
+  - Don't use when: You want full transcript (use elevenlabs_get_conversation)
+
+Error Handling:
+  - Returns empty list if no conversations match filters
+  - Returns "Error: Invalid date format" if date_range is malformed`,
+
+  zodSchema: ListConversationsSchema,
+
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = ListConversationsSchema.parse(args);
+
+    const params: Record<string, unknown> = {
+      limit: parsed.limit,
+      offset: parsed.offset
+    };
+
+    if (parsed.agent_id) {
+      params.agent_id = parsed.agent_id;
+    }
+
+    if (parsed.status) {
+      params.status = parsed.status;
+    }
+
+    if (parsed.date_range) {
+      if (parsed.date_range.start) {
+        params.start_date = parsed.date_range.start;
+      }
+      if (parsed.date_range.end) {
+        params.end_date = parsed.date_range.end;
+      }
+    }
+
+    const response = await getRequest<{ conversations: ConversationMetadata[] }>(
+      "/convai/conversations",
+      params
+    );
+
+    const conversations = response.conversations || [];
+    const total = conversations.length;
+    const hasMore = conversations.length === parsed.limit;
+
+    const paginatedResponse: PaginatedResponse<ConversationMetadata> = {
+      total,
+      count: conversations.length,
+      offset: parsed.offset,
+      items: conversations,
+      has_more: hasMore,
+      next_offset: hasMore ? parsed.offset + conversations.length : undefined
+    };
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(paginatedResponse, parsed.response_format, "conversation_list")
+        }
+      ]
+    };
+  }
+};

package/src/tools/knowledge-tools.ts

@@ -0,0 +1,73 @@
+/**
+ * Knowledge base management tools
+ *
+ * MCP tools for adding documents and URLs to agent knowledge bases.
+ */
+
+import { postRequest } from "../services/elevenlabs-api.js";
+import { formatResponse } from "../services/formatters.js";
+import { ResponseFormat } from "../types.js";
+import { AddKnowledgeBaseSchema } from "../schemas/tool-schemas.js";
+
+/**
+ * Adds documents to an agent's knowledge base
+ */
+export const elevenlabs_add_knowledge_base = {
+  name: "elevenlabs_add_knowledge_base",
+  description: `Add documents or URLs to an agent's knowledge base.
+
+This tool enables agents to reference custom knowledge when responding to users. You can add text documents or URLs that will be fetched and indexed. The agent will automatically use this information when relevant to the conversation.
+
+Args:
+  - agent_id (string): Agent identifier to add knowledge to
+  - documents (array): Array of document objects with:
+    - type ('text' | 'url'): Type of document
+    - content (string): For 'text': the actual text. For 'url': the URL to fetch
+    - metadata (object): Optional key-value metadata about the document
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  Confirmation message indicating successful knowledge base update.
+
+Examples:
+  - Use when: "Add this FAQ document to the agent's knowledge base"
+  - Use when: "Index the company policy page at https://example.com/policies"
+  - Use when: "Give the agent access to product documentation"
+  - Don't use when: You want to add webhook tools (use elevenlabs_create_webhook_tool)
+
+Error Handling:
+  - Returns "Error: Agent not found" if agent_id doesn't exist
+  - Returns "Error: Invalid URL" if URL document is not accessible
+  - Returns "Error: Document too large" if content exceeds size limits`,
+
+  zodSchema: AddKnowledgeBaseSchema,
+
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = AddKnowledgeBaseSchema.parse(args);
+
+    const result = await postRequest(
+      `/convai/agents/${parsed.agent_id}/knowledge-base`,
+      { documents: parsed.documents }
+    );
+
+    const message = `Successfully added ${parsed.documents.length} document(s) to agent ${parsed.agent_id}'s knowledge base.`;
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: parsed.response_format === ResponseFormat.JSON
+            ? formatResponse({ success: true, message, documents_added: parsed.documents.length }, parsed.response_format, "generic")
+            : message
+        }
+      ]
+    };
+  }
+};

package/src/tools/outbound-tools.ts

@@ -0,0 +1,95 @@
+/**
+ * Outbound calling tools
+ *
+ * MCP tool for initiating single outbound phone calls via Twilio.
+ */
+
+import { postRequest } from "../services/elevenlabs-api.js";
+import { formatResponse } from "../services/formatters.js";
+import { OutboundCallResponse } from "../types.js";
+import { StartOutboundCallSchema } from "../schemas/outbound-schemas.js";
+
+/**
+ * Starts a single outbound call via Twilio
+ */
+export const elevenlabs_start_outbound_call = {
+  name: "elevenlabs_start_outbound_call",
+  description: `Initiate a single outbound phone call using an ElevenLabs Voice Agent via Twilio.
+
+This tool starts an AI-powered phone call to a specific phone number. The agent will use its configured prompt, voice, and tools to have a conversation with the person who answers. You can personalize the call with dynamic variables and override agent settings for this specific call.
+
+Prerequisites:
+  - A Twilio phone number must be imported and associated with an agent
+  - The agent must be properly configured
+  - Destination phone number must be valid
+
+Args:
+  - agent_id (string): Agent to use for this call (e.g., 'ag_abc123')
+  - agent_phone_number_id (string): Phone number ID to use as caller ID
+  - to_number (string): Destination phone number in E.164 format (e.g., '+1234567890')
+  - conversation_initiation_client_data (object): Optional personalization data
+    - dynamic_variables (object): Dynamic variables for personalization
+      Example: {dynamic_variables: {name: 'John', user_id: '123', account_balance: 1500}}
+    - conversation_config_override (object): Override agent settings for this call
+      - agent.first_message: Custom greeting for this call
+      - agent.prompt.prompt: Custom system prompt for this call
+      - agent.language: Language override
+      - tts.voice_id: Voice override
+      - conversation.max_duration_seconds: Maximum call duration
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  - success: Whether the call was initiated
+  - message: Human-readable status message
+  - conversation_id: ID to track this conversation (null if failed)
+  - callSid: Twilio call identifier (null if failed)
+
+Examples:
+  - Use when: "Call +14155551234 with the sales agent"
+  - Use when: "Start outbound call to check appointment with customer John"
+  - Use when: "Dispatch agent to +447911123456 with custom greeting"
+  - Don't use when: You want to make multiple calls at once (use elevenlabs_submit_batch_call)
+  - Don't use when: Phone number isn't set up yet (use elevenlabs_import_phone_number first)
+
+Error Handling:
+  - Returns success: false if call initiation fails
+  - Returns "Error: Phone number not found" if agent_phone_number_id is invalid
+  - Returns "Error: Agent not found" if agent_id doesn't exist
+  - Returns "Error: Invalid phone number format" if to_number is malformed`,
+
+  zodSchema: StartOutboundCallSchema,
+
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = StartOutboundCallSchema.parse(args);
+
+    const requestData = {
+      agent_id: parsed.agent_id,
+      agent_phone_number_id: parsed.agent_phone_number_id,
+      to_number: parsed.to_number,
+      ...(parsed.conversation_initiation_client_data && {
+        conversation_initiation_client_data: parsed.conversation_initiation_client_data
+      })
+    };
+
+    const response = await postRequest<OutboundCallResponse>(
+      "/convai/twilio/outbound-call",
+      requestData
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(response, parsed.response_format, "outbound_call")
+        }
+      ]
+    };
+  }
+};

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

@@ -0,0 +1,346 @@
+/**
+ * Phone number management tools
+ *
+ * MCP tools for listing, importing, updating, and deleting phone numbers
+ * connected to voice agents via Twilio or SIP trunking.
+ */
+
+import { getRequest, postRequest, patchRequest, deleteRequest } from "../services/elevenlabs-api.js";
+import { formatResponse } from "../services/formatters.js";
+import { PhoneNumber, ImportPhoneNumberResponse } from "../types.js";
+import {
+  ListPhoneNumbersSchema,
+  GetPhoneNumberSchema,
+  ImportPhoneNumberSchema,
+  UpdatePhoneNumberSchema,
+  DeletePhoneNumberSchema
+} from "../schemas/phone-number-schemas.js";
+
+/**
+ * Lists all phone numbers connected to the workspace
+ */
+export const elevenlabs_list_phone_numbers = {
+  name: "elevenlabs_list_phone_numbers",
+  description: `List all phone numbers connected to your ElevenLabs workspace.
+
+This tool retrieves all phone numbers you've imported (Twilio or SIP trunk), showing which agents they're assigned to, their capabilities (inbound/outbound), and configuration details.
+
+Args:
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  Array of phone number objects, each containing:
+  - phone_number: The actual phone number
+  - label: Descriptive name
+  - phone_number_id: Unique identifier for API operations
+  - provider: 'twilio' or 'sip_trunk'
+  - supports_inbound: Whether it can receive calls
+  - supports_outbound: Whether it can make calls
+  - assigned_agent: Agent details (if assigned) or null
+
+Examples:
+  - Use when: "Show me all my phone numbers"
+  - Use when: "List available phone numbers for outbound calling"
+  - Use when: "Which phone numbers are assigned to agents?"
+  - Don't use when: You want details about a specific phone number (use elevenlabs_get_phone_number)
+
+Error Handling:
+  - Returns empty array if no phone numbers exist
+  - Returns "Error: Invalid API key" if authentication fails`,
+
+  zodSchema: ListPhoneNumbersSchema,
+
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = ListPhoneNumbersSchema.parse(args);
+
+    const response = await getRequest<PhoneNumber[]>("/convai/phone-numbers");
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(response, parsed.response_format, "phone_number_list")
+        }
+      ]
+    };
+  }
+};
+
+/**
+ * Gets details about a specific phone number
+ */
+export const elevenlabs_get_phone_number = {
+  name: "elevenlabs_get_phone_number",
+  description: `Get detailed information about a specific phone number.
+
+This tool retrieves complete configuration details for a phone number, including provider settings, agent assignment, trunk configurations, and capability flags.
+
+Args:
+  - phone_number_id (string): Unique phone number identifier (e.g., 'pn_abc123')
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  Complete phone number details including provider-specific configuration.
+
+Examples:
+  - Use when: "Show me details for phone number pn_abc123"
+  - Use when: "What agent is assigned to phone pn_xyz789?"
+  - Use when: "Get configuration for phone number ID pn_test456"
+  - Don't use when: You want to list all phone numbers (use elevenlabs_list_phone_numbers)
+
+Error Handling:
+  - Returns "Error: Phone number not found" if phone_number_id doesn't exist
+  - Returns "Error: Invalid API key" if authentication fails`,
+
+  zodSchema: GetPhoneNumberSchema,
+
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = GetPhoneNumberSchema.parse(args);
+
+    const response = await getRequest<PhoneNumber>(
+      `/convai/phone-numbers/${parsed.phone_number_id}`
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(response, parsed.response_format, "phone_number")
+        }
+      ]
+    };
+  }
+};
+
+/**
+ * Imports a Twilio phone number
+ */
+export const elevenlabs_import_phone_number = {
+  name: "elevenlabs_import_phone_number",
+  description: `Import a Twilio phone number to use with ElevenLabs Voice Agents.
+
+This tool connects your existing Twilio phone number to ElevenLabs, enabling it for inbound and/or outbound voice agent calls. You'll need your Twilio Account SID and Auth Token.
+
+Prerequisites:
+  - Active Twilio account with a purchased phone number
+  - Twilio Account SID and Auth Token
+  - Phone number must not already be imported
+
+Args:
+  - phone_number (string): Phone number to import in E.164 format (e.g., '+1234567890')
+  - label (string): Descriptive name for this number (e.g., 'Customer Support Line')
+  - sid (string): Twilio Account SID (starts with 'AC')
+  - token (string): Twilio Auth Token
+  - provider (string): Must be 'twilio'
+  - supports_inbound (boolean, optional): Enable inbound calls (default: true)
+  - supports_outbound (boolean, optional): Enable outbound calls (default: true)
+  - region_config (object, optional): Regional configuration
+    - region_id: 'us1', 'ie1', or 'au1'
+    - token: Regional token
+    - edge_location: Twilio edge location
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  - phone_number_id: Unique identifier for the imported phone number
+
+Examples:
+  - Use when: "Import my Twilio number +1234567890 for customer support"
+  - Use when: "Connect Twilio phone number with SID AC123... for outbound calling"
+  - Use when: "Add new phone number +447911123456 from Twilio account"
+  - Don't use when: Number is already imported (update it instead)
+  - Don't use when: You need to assign it to an agent (use elevenlabs_update_phone_number after)
+
+Error Handling:
+  - Returns "Error: Invalid Twilio credentials" if SID/token are wrong
+  - Returns "Error: Phone number already exists" if already imported
+  - Returns "Error: Invalid phone number format" if not E.164`,
+
+  zodSchema: ImportPhoneNumberSchema,
+
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = ImportPhoneNumberSchema.parse(args);
+
+    const requestData = {
+      phone_number: parsed.phone_number,
+      label: parsed.label,
+      sid: parsed.sid,
+      token: parsed.token,
+      provider: parsed.provider,
+      ...(parsed.supports_inbound !== undefined && {
+        supports_inbound: parsed.supports_inbound
+      }),
+      ...(parsed.supports_outbound !== undefined && {
+        supports_outbound: parsed.supports_outbound
+      }),
+      ...(parsed.region_config && {
+        region_config: parsed.region_config
+      })
+    };
+
+    const response = await postRequest<ImportPhoneNumberResponse>(
+      "/convai/phone-numbers",
+      requestData
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(response, parsed.response_format, "phone_number_import")
+        }
+      ]
+    };
+  }
+};
+
+/**
+ * Updates a phone number (primarily for agent assignment)
+ */
+export const elevenlabs_update_phone_number = {
+  name: "elevenlabs_update_phone_number",
+  description: `Update a phone number's configuration, primarily to assign or unassign agents.
+
+This tool modifies phone number settings. The most common use is assigning an agent to a phone number so the agent can handle calls from that number. You can also configure SIP trunk settings for advanced deployments.
+
+Args:
+  - phone_number_id (string): Phone number identifier to update (e.g., 'pn_abc123')
+  - agent_id (string, optional): Agent ID to assign (set to null to unassign)
+  - inbound_trunk_config (object, optional): SIP trunk configuration for inbound
+  - outbound_trunk_config (object, optional): SIP trunk configuration for outbound
+  - livekit_stack ('standard' | 'static', optional): LiveKit stack configuration
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  Updated phone number object with new configuration.
+
+Examples:
+  - Use when: "Assign agent ag_abc123 to phone number pn_xyz789"
+  - Use when: "Connect my customer support agent to the main phone line"
+  - Use when: "Unassign agent from phone number pn_test456"
+  - Use when: "Update phone number pn_sales to use agent ag_sales"
+  - Don't use when: You need to import a new number (use elevenlabs_import_phone_number)
+
+Error Handling:
+  - Returns "Error: Phone number not found" if phone_number_id doesn't exist
+  - Returns "Error: Agent not found" if agent_id doesn't exist
+  - Returns "Error: Invalid API key" if authentication fails`,
+
+  zodSchema: UpdatePhoneNumberSchema,
+
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = UpdatePhoneNumberSchema.parse(args);
+
+    const updateData: Record<string, unknown> = {};
+
+    if (parsed.agent_id !== undefined) {
+      updateData.agent_id = parsed.agent_id;
+    }
+
+    if (parsed.inbound_trunk_config !== undefined) {
+      updateData.inbound_trunk_config = parsed.inbound_trunk_config;
+    }
+
+    if (parsed.outbound_trunk_config !== undefined) {
+      updateData.outbound_trunk_config = parsed.outbound_trunk_config;
+    }
+
+    if (parsed.livekit_stack !== undefined) {
+      updateData.livekit_stack = parsed.livekit_stack;
+    }
+
+    const response = await patchRequest<PhoneNumber>(
+      `/convai/phone-numbers/${parsed.phone_number_id}`,
+      updateData
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(response, parsed.response_format, "phone_number")
+        }
+      ]
+    };
+  }
+};
+
+/**
+ * Deletes a phone number
+ */
+export const elevenlabs_delete_phone_number = {
+  name: "elevenlabs_delete_phone_number",
+  description: `Delete a phone number from your ElevenLabs workspace.
+
+This tool permanently removes a phone number from ElevenLabs. This does NOT delete the number from your Twilio account - it only disconnects it from ElevenLabs. You can re-import it later if needed.
+
+IMPORTANT: This action cannot be undone. Any agent assignments will be removed.
+
+Args:
+  - phone_number_id (string): Phone number identifier to delete (e.g., 'pn_abc123')
+
+Returns:
+  Confirmation message indicating successful deletion.
+
+Examples:
+  - Use when: "Delete phone number pn_test123"
+  - Use when: "Remove phone number pn_old456 from ElevenLabs"
+  - Use when: "Disconnect Twilio number pn_unused789"
+  - Don't use when: You just want to unassign an agent (use elevenlabs_update_phone_number)
+  - Don't use when: You're not sure - this is permanent!
+
+Error Handling:
+  - Returns "Error: Phone number not found" if phone_number_id doesn't exist
+  - Returns "Error: Invalid API key" if authentication fails`,
+
+  zodSchema: DeletePhoneNumberSchema,
+
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = DeletePhoneNumberSchema.parse(args);
+
+    await deleteRequest(`/convai/phone-numbers/${parsed.phone_number_id}`);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Successfully deleted phone number: ${parsed.phone_number_id}`
+        }
+      ]
+    };
+  }
+};