elevenlabs-voice-agent-mcp 1.0.0 → 1.0.1

package/src/tools/agent-tools.ts

@@ -0,0 +1,425 @@
+/**
+ * Agent management tools
+ *
+ * MCP tools for creating, retrieving, updating, deleting, and listing voice agents.
+ */
+
+import { z } from "zod";
+import { getRequest, postRequest, patchRequest, deleteRequest } from "../services/elevenlabs-api.js";
+import { formatResponse } from "../services/formatters.js";
+import { Agent, PaginatedResponse, ResponseFormat } from "../types.js";
+import {
+  CreateAgentSchema,
+  GetAgentSchema,
+  UpdateAgentSchema,
+  DeleteAgentSchema,
+  ListAgentsSchema
+} from "../schemas/agent-schemas.js";
+
+/**
+ * Creates a new ElevenLabs Voice Agent
+ */
+export const elevenlabs_create_agent = {
+  name: "elevenlabs_create_agent",
+  description: `Create a new ElevenLabs Voice Agent with specified configuration.
+
+This tool creates a complete voice agent with conversation settings, including the AI model, voice configuration, ASR settings, and initial behavior. It does NOT start conversations or deploy the agent - it only creates the configuration.
+
+Args:
+  - name (string): Display name for the agent (max 100 chars)
+  - prompt (string): System prompt defining behavior (10-5000 chars)
+  - llm (string): AI model to use (default: "gpt-4o-mini")
+    Options: gpt-4o, gpt-4o-mini, claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, gemini-2.0-flash-exp
+  - voice_id (string): ElevenLabs voice ID (default: "21m00Tcm4TlvDq8ikWAM" - Rachel)
+  - voice_model (string): Voice synthesis model (default: "eleven_flash_v2_5")
+    Options: eleven_turbo_v2_5, eleven_flash_v2_5, eleven_multilingual_v2
+  - first_message (string): Optional greeting message (max 500 chars)
+  - language (string): Primary language code (default: "en")
+  - temperature (number): LLM temperature 0-2 for response randomness (higher = more creative)
+  - max_tokens (number): Maximum tokens for LLM responses (1-4096)
+  - stability (number): Voice stability 0-1 (higher = more consistent)
+  - similarity_boost (number): Voice similarity boost 0-1 (higher = closer to original)
+  - widget_color (string): Widget theme color in hex format (e.g., "#FF5733")
+  - widget_avatar_url (string): Widget avatar image URL
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  For JSON format: Complete agent object with agent_id, name, conversation_config, created_at
+  For Markdown format: Formatted agent details with configuration summary
+
+Examples:
+  - Use when: "Create a customer service agent for tech support"
+  - Use when: "Set up a voice agent for appointment scheduling"
+  - Don't use when: You want to test an existing agent (use elevenlabs_generate_widget_code)
+  - Don't use when: You want to modify an agent (use elevenlabs_update_agent)
+
+Error Handling:
+  - Returns "Error: Invalid voice_id" if voice doesn't exist
+  - Returns "Error: Invalid API key" if authentication fails
+  - Returns "Error: Rate limit exceeded" if too many requests (wait 60s and retry)`,
+
+  zodSchema: CreateAgentSchema,
+
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = CreateAgentSchema.parse(args);
+
+    // Build agent configuration
+    const agentData = {
+      name: parsed.name,
+      conversation_config: {
+        agent: {
+          prompt: {
+            prompt: parsed.prompt,
+            llm: parsed.llm,
+            ...(parsed.temperature !== undefined && { temperature: parsed.temperature }),
+            ...(parsed.max_tokens !== undefined && { max_tokens: parsed.max_tokens })
+          },
+          ...(parsed.first_message && { first_message: parsed.first_message }),
+          language: parsed.language
+        },
+        tts: {
+          voice_id: parsed.voice_id,
+          model_id: parsed.voice_model,
+          ...(parsed.stability !== undefined && { stability: parsed.stability }),
+          ...(parsed.similarity_boost !== undefined && { similarity_boost: parsed.similarity_boost })
+        }
+      },
+      ...(parsed.widget_color || parsed.widget_avatar_url ? {
+        platform_settings: {
+          widget: {
+            ...(parsed.widget_color && { color: parsed.widget_color }),
+            ...(parsed.widget_avatar_url && { avatar_url: parsed.widget_avatar_url })
+          }
+        }
+      } : {})
+    };
+
+    const agent = await postRequest<Agent>("/convai/agents", agentData);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(agent, parsed.response_format, "agent")
+        }
+      ]
+    };
+  }
+};
+
+/**
+ * Retrieves an agent by ID
+ */
+export const elevenlabs_get_agent = {
+  name: "elevenlabs_get_agent",
+  description: `Retrieve complete configuration for an existing ElevenLabs Voice Agent.
+
+This tool fetches all details about an agent including its conversation configuration, tools, knowledge base, and platform settings. Use this to inspect an agent before modifying it or to check current settings.
+
+Args:
+  - agent_id (string): Unique agent identifier (e.g., 'ag_abc123')
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  Complete agent configuration including prompt, LLM settings, voice configuration, tools, and knowledge base.
+
+Examples:
+  - Use when: "Show me the configuration for agent ag_abc123"
+  - Use when: "What's the current prompt for this agent?"
+  - Don't use when: You want to list all agents (use elevenlabs_list_agents)
+
+Error Handling:
+  - Returns "Error: Agent not found" if agent_id doesn't exist
+  - Returns "Error: Invalid API key" if authentication fails`,
+
+  zodSchema: GetAgentSchema,
+
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = GetAgentSchema.parse(args);
+    const agent = await getRequest<Agent>(`/convai/agents/${parsed.agent_id}`);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(agent, parsed.response_format, "agent")
+        }
+      ]
+    };
+  }
+};
+
+/**
+ * Updates an existing agent
+ */
+export const elevenlabs_update_agent = {
+  name: "elevenlabs_update_agent",
+  description: `Update an existing ElevenLabs Voice Agent's configuration.
+
+This tool modifies one or more settings of an existing agent. You only need to provide the fields you want to change - all other settings will remain the same. Changes take effect immediately for new conversations.
+
+Args:
+  - agent_id (string): Unique agent identifier (e.g., 'ag_abc123')
+  - name (string): Updated display name (max 100 chars)
+  - prompt (string): Updated system prompt (10-5000 chars)
+  - llm (string): Updated AI model
+  - voice_id (string): Updated voice ID
+  - voice_model (string): Updated voice model
+  - first_message (string): Updated greeting (max 500 chars)
+  - language (string): Updated language code
+  - temperature (number): Updated temperature (0-2)
+  - max_tokens (number): Updated max tokens (1-4096)
+  - stability (number): Updated voice stability (0-1)
+  - similarity_boost (number): Updated similarity boost (0-1)
+  - widget_color (string): Updated widget color
+  - widget_avatar_url (string): Updated widget avatar URL
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  Updated agent configuration.
+
+Examples:
+  - Use when: "Change the agent's voice to voice ID xyz123"
+  - Use when: "Update the system prompt to be more friendly"
+  - Use when: "Switch the agent to use Claude instead of GPT"
+  - 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 voice_id" if new voice doesn't exist`,
+
+  zodSchema: UpdateAgentSchema,
+
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = UpdateAgentSchema.parse(args);
+
+    // Get current agent config
+    const currentAgent = await getRequest<Agent>(`/convai/agents/${parsed.agent_id}`);
+
+    // Build update payload with only changed fields
+    const updateData: Record<string, unknown> = {};
+
+    if (parsed.name !== undefined) {
+      updateData.name = parsed.name;
+    }
+
+    // Build conversation config updates
+    const conversationConfigUpdates: Record<string, unknown> = {
+      agent: { ...currentAgent.conversation_config.agent } as Record<string, unknown>,
+      tts: { ...currentAgent.conversation_config.tts } as Record<string, unknown>
+    };
+
+    let hasConversationConfigChanges = false;
+
+    // Agent updates
+    if (parsed.prompt !== undefined || parsed.llm !== undefined ||
+        parsed.temperature !== undefined || parsed.max_tokens !== undefined) {
+      conversationConfigUpdates.agent = {
+        ...(conversationConfigUpdates.agent as Record<string, unknown>),
+        prompt: {
+          ...(currentAgent.conversation_config.agent.prompt),
+          ...(parsed.prompt !== undefined && { prompt: parsed.prompt }),
+          ...(parsed.llm !== undefined && { llm: parsed.llm }),
+          ...(parsed.temperature !== undefined && { temperature: parsed.temperature }),
+          ...(parsed.max_tokens !== undefined && { max_tokens: parsed.max_tokens })
+        }
+      };
+      hasConversationConfigChanges = true;
+    }
+
+    if (parsed.first_message !== undefined) {
+      (conversationConfigUpdates.agent as Record<string, unknown>).first_message = parsed.first_message;
+      hasConversationConfigChanges = true;
+    }
+
+    if (parsed.language !== undefined) {
+      (conversationConfigUpdates.agent as Record<string, unknown>).language = parsed.language;
+      hasConversationConfigChanges = true;
+    }
+
+    // TTS updates
+    if (parsed.voice_id !== undefined || parsed.voice_model !== undefined ||
+        parsed.stability !== undefined || parsed.similarity_boost !== undefined) {
+      conversationConfigUpdates.tts = {
+        ...(conversationConfigUpdates.tts as Record<string, unknown>),
+        ...(parsed.voice_id !== undefined && { voice_id: parsed.voice_id }),
+        ...(parsed.voice_model !== undefined && { model_id: parsed.voice_model }),
+        ...(parsed.stability !== undefined && { stability: parsed.stability }),
+        ...(parsed.similarity_boost !== undefined && { similarity_boost: parsed.similarity_boost })
+      };
+      hasConversationConfigChanges = true;
+    }
+
+    if (hasConversationConfigChanges) {
+      updateData.conversation_config = conversationConfigUpdates;
+    }
+
+    // Widget updates
+    if (parsed.widget_color !== undefined || parsed.widget_avatar_url !== undefined) {
+      updateData.platform_settings = {
+        ...(currentAgent.platform_settings || {}),
+        widget: {
+          ...(currentAgent.platform_settings?.widget || {}),
+          ...(parsed.widget_color !== undefined && { color: parsed.widget_color }),
+          ...(parsed.widget_avatar_url !== undefined && { avatar_url: parsed.widget_avatar_url })
+        }
+      };
+    }
+
+    const updatedAgent = await patchRequest<Agent>(
+      `/convai/agents/${parsed.agent_id}`,
+      updateData
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(updatedAgent, parsed.response_format, "agent")
+        }
+      ]
+    };
+  }
+};
+
+/**
+ * Deletes an agent
+ */
+export const elevenlabs_delete_agent = {
+  name: "elevenlabs_delete_agent",
+  description: `Delete an ElevenLabs Voice Agent permanently.
+
+This tool permanently removes an agent and all its configuration. This action CANNOT be undone. All conversations associated with this agent will remain accessible, but the agent itself will be deleted.
+
+Args:
+  - agent_id (string): Unique agent identifier to delete (e.g., 'ag_abc123')
+
+Returns:
+  Confirmation message indicating successful deletion.
+
+Examples:
+  - Use when: "Delete the test agent ag_test123"
+  - Use when: "Remove agent ag_old456 permanently"
+  - Don't use when: You want to temporarily disable an agent (no disable feature - just don't use it)
+  - Don't use when: You're not sure - this is permanent!
+
+Error Handling:
+  - Returns "Error: Agent not found" if agent_id doesn't exist
+  - Returns "Error: Invalid API key" if authentication fails`,
+
+  zodSchema: DeleteAgentSchema,
+
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = DeleteAgentSchema.parse(args);
+    await deleteRequest(`/convai/agents/${parsed.agent_id}`);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Successfully deleted agent: ${parsed.agent_id}`
+        }
+      ]
+    };
+  }
+};
+
+/**
+ * Lists all agents with pagination
+ */
+export const elevenlabs_list_agents = {
+  name: "elevenlabs_list_agents",
+  description: `List all ElevenLabs Voice Agents with pagination.
+
+This tool retrieves a paginated list of all your voice agents. Use the offset and limit parameters to navigate through large agent lists. The response includes pagination metadata to help you fetch additional pages.
+
+Args:
+  - limit (number): Maximum agents to return (1-100, default: 20)
+  - offset (number): Number of agents to skip (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 agents with key details and pagination guidance
+
+Examples:
+  - Use when: "Show me all my voice agents"
+  - Use when: "List the first 10 agents"
+  - Use when: "Get the next page of agents with offset=20"
+  - Don't use when: You want details about a specific agent (use elevenlabs_get_agent)
+
+Error Handling:
+  - Returns empty list if no agents exist
+  - Returns "Error: Invalid API key" if authentication fails`,
+
+  zodSchema: ListAgentsSchema,
+
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = ListAgentsSchema.parse(args);
+
+    const response = await getRequest<{ agents: Agent[] }>(
+      "/convai/agents",
+      {
+        limit: parsed.limit,
+        offset: parsed.offset
+      }
+    );
+
+    const agents = response.agents || [];
+    const total = agents.length; // Note: ElevenLabs API may not return total count
+    const hasMore = agents.length === parsed.limit;
+
+    const paginatedResponse: PaginatedResponse<Agent> = {
+      total,
+      count: agents.length,
+      offset: parsed.offset,
+      items: agents,
+      has_more: hasMore,
+      next_offset: hasMore ? parsed.offset + agents.length : undefined
+    };
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(paginatedResponse, parsed.response_format, "agent_list")
+        }
+      ]
+    };
+  }
+};

package/src/tools/batch-calling-tools.ts

@@ -0,0 +1,237 @@
+/**
+ * Batch calling tools
+ *
+ * MCP tools for submitting batch call jobs, listing batches, and retrieving batch details.
+ */
+
+import { getRequest, postRequest } from "../services/elevenlabs-api.js";
+import { formatResponse } from "../services/formatters.js";
+import { BatchCallResponse, BatchCallDetailedResponse, WorkspaceBatchCallsResponse } from "../types.js";
+import {
+  SubmitBatchCallSchema,
+  ListBatchCallsSchema,
+  GetBatchCallSchema
+} from "../schemas/batch-calling-schemas.js";
+
+/**
+ * Submits a batch calling job
+ */
+export const elevenlabs_submit_batch_call = {
+  name: "elevenlabs_submit_batch_call",
+  description: `Submit a batch calling job to initiate multiple outbound calls simultaneously.
+
+This tool allows you to call multiple phone numbers in parallel using your voice agent. Upload a list of recipients with optional personalization data for each call. Batch calling is ideal for surveys, alerts, reminders, appointment confirmations, and mass outreach.
+
+Prerequisites:
+  - A Twilio phone number must be imported and associated with an agent
+  - Zero Retention Mode (ZRM) must be disabled
+  - Minimum 50% workspace concurrency or 70% agent concurrency available
+
+Args:
+  - call_name (string): Descriptive name for this batch (e.g., "Q4 Customer Survey")
+  - agent_id (string): Agent to use for all calls (e.g., 'ag_abc123')
+  - recipients (array): Array of recipient objects, each containing:
+    - phone_number (string): Phone in E.164 format (e.g., '+1234567890')
+    - OR whatsapp_user_id (string): WhatsApp user ID (alternative)
+    - id (string, optional): Custom tracking ID for this recipient
+    - conversation_initiation_client_data (object, optional): Personalization data
+      - dynamic_variables (object): Dynamic variables for personalization
+        Example: {dynamic_variables: {name: 'John', appointment_time: '3pm'}}
+      - conversation_config_override (object): Override agent settings for this call
+        - Special fields: language, first_message, prompt.prompt, voice_id
+  - scheduled_time_unix (number, optional): Unix timestamp to schedule for future
+  - agent_phone_number_id (string, optional): Phone number ID to use as caller ID
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  Batch job details including ID, status, scheduling info, and call counts.
+
+Limits:
+  - Minimum: 1 recipient
+  - Maximum: 10,000 recipients per batch
+
+Examples:
+  - Use when: "Call 500 customers with appointment reminders"
+  - Use when: "Send survey to all users with personalized greetings"
+  - Use when: "Dispatch agent to call lead list from CSV"
+  - Don't use when: Making a single call (use elevenlabs_start_outbound_call)
+  - Don't use when: Phone number isn't assigned to agent yet
+
+Error Handling:
+  - Returns "Error: Invalid recipient count" if outside 1-10,000 range
+  - Returns "Error: Phone number not assigned" if agent lacks phone number
+  - Returns "Error: ZRM enabled" if Zero Retention Mode is active`,
+
+  zodSchema: SubmitBatchCallSchema,
+
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = SubmitBatchCallSchema.parse(args);
+
+    const requestData = {
+      call_name: parsed.call_name,
+      agent_id: parsed.agent_id,
+      recipients: parsed.recipients,
+      ...(parsed.scheduled_time_unix !== undefined && {
+        scheduled_time_unix: parsed.scheduled_time_unix
+      }),
+      ...(parsed.agent_phone_number_id && {
+        agent_phone_number_id: parsed.agent_phone_number_id
+      })
+    };
+
+    const response = await postRequest<BatchCallResponse>(
+      "/convai/batch-calling/submit",
+      requestData
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(response, parsed.response_format, "batch_call")
+        }
+      ]
+    };
+  }
+};
+
+/**
+ * Lists all batch calling jobs in workspace
+ */
+export const elevenlabs_list_batch_calls = {
+  name: "elevenlabs_list_batch_calls",
+  description: `List all batch calling jobs in your workspace with pagination.
+
+This tool retrieves all batch call jobs you've submitted, showing their status, scheduling, and progress. Use cursor-based pagination to navigate through large lists.
+
+Args:
+  - limit (number): Maximum items to return (1-100, default: 20)
+  - last_doc (string, optional): Pagination cursor from previous response
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  - batch_calls: Array of batch job objects with status and metrics
+  - next_doc: Cursor for next page (null if no more pages)
+  - has_more: Whether more batches exist
+
+Pagination:
+  - First page: Don't include last_doc parameter
+  - Next pages: Use next_doc value from previous response as last_doc
+
+Examples:
+  - Use when: "Show me all my batch calling jobs"
+  - Use when: "List recent batch calls"
+  - Use when: "Get next page of batches with cursor xyz123"
+  - Don't use when: You want details about a specific batch (use elevenlabs_get_batch_call)
+
+Error Handling:
+  - Returns empty list if no batches exist
+  - Returns "Error: Invalid API key" if authentication fails`,
+
+  zodSchema: ListBatchCallsSchema,
+
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = ListBatchCallsSchema.parse(args);
+
+    const params: Record<string, unknown> = {
+      limit: parsed.limit
+    };
+
+    if (parsed.last_doc) {
+      params.last_doc = parsed.last_doc;
+    }
+
+    const response = await getRequest<WorkspaceBatchCallsResponse>(
+      "/convai/batch-calling/workspace",
+      params
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(response, parsed.response_format, "batch_call_list")
+        }
+      ]
+    };
+  }
+};
+
+/**
+ * Gets detailed information about a specific batch call
+ */
+export const elevenlabs_get_batch_call = {
+  name: "elevenlabs_get_batch_call",
+  description: `Get detailed information about a specific batch calling job including all recipient statuses.
+
+This tool retrieves complete details for a batch call job, including the status of each individual recipient. Use this to monitor batch progress, identify failed calls, detect voicemails, and track which recipients have been successfully contacted.
+
+Args:
+  - batch_id (string): Unique batch job identifier (e.g., 'batch_abc123')
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  Complete batch details including:
+  - Batch metadata (name, agent, status, timing)
+  - Call metrics (dispatched, scheduled counts)
+  - Recipients array with individual statuses:
+    - pending: Not yet called
+    - initiated: Call started
+    - in_progress: Currently in conversation
+    - completed: Call finished successfully
+    - failed: Call failed
+    - cancelled: Call was cancelled
+    - voicemail: Went to voicemail
+  - Each recipient includes conversation_id for transcript lookup
+
+Examples:
+  - Use when: "Check status of batch job batch_abc123"
+  - Use when: "Show me which recipients answered in the sales batch"
+  - Use when: "Get details on appointment reminder batch"
+  - Use when: "Find failed calls in batch xyz789"
+  - Don't use when: You want to list all batches (use elevenlabs_list_batch_calls)
+
+Error Handling:
+  - Returns "Error: Batch not found" if batch_id doesn't exist
+  - Returns "Error: Invalid API key" if authentication fails`,
+
+  zodSchema: GetBatchCallSchema,
+
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+
+  handler: async (args: unknown) => {
+    const parsed = GetBatchCallSchema.parse(args);
+
+    const response = await getRequest<BatchCallDetailedResponse>(
+      `/convai/batch-calling/${parsed.batch_id}`
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatResponse(response, parsed.response_format, "batch_call_detail")
+        }
+      ]
+    };
+  }
+};