elevenlabs-voice-agent-mcp 1.0.0 → 1.0.1

package/src/utils/error-handlers.ts

@@ -0,0 +1,98 @@
+/**
+ * Error handling utilities for ElevenLabs API requests
+ *
+ * Provides consistent error handling and user-friendly error messages
+ * for various API error scenarios.
+ */
+
+import axios from "axios";
+
+/**
+ * Handles errors from ElevenLabs API requests
+ *
+ * @param error - The error object from axios or other sources
+ * @param context - Additional context about the operation (e.g., "creating agent")
+ * @returns User-friendly error message with actionable guidance
+ */
+export function handleElevenLabsError(error: unknown, context?: string): string {
+  const prefix = context ? `Error ${context}: ` : "Error: ";
+
+  if (axios.isAxiosError(error)) {
+    if (error.response) {
+      // Server responded with error status
+      const status = error.response.status;
+      const data = error.response.data as { detail?: string; message?: string };
+      const detail = data?.detail || data?.message;
+
+      switch (status) {
+        case 400:
+          return `${prefix}Invalid request - ${detail || "Check your parameters"}`;
+        case 401:
+          return `${prefix}Invalid API key. Please check your ELEVENLABS_API_KEY environment variable.`;
+        case 403:
+          return `${prefix}Access forbidden. Your API key may not have permission for this operation.`;
+        case 404:
+          return `${prefix}Resource not found. Please verify the ID is correct.`;
+        case 409:
+          return `${prefix}Conflict - ${detail || "Resource already exists or is in use"}`;
+        case 422:
+          return `${prefix}Validation error - ${detail || "Invalid data format"}`;
+        case 429:
+          return `${prefix}Rate limit exceeded. Please wait 60 seconds before retrying.`;
+        case 500:
+          return `${prefix}ElevenLabs server error. Please try again in a few moments.`;
+        case 503:
+          return `${prefix}Service temporarily unavailable. Please try again later.`;
+        default:
+          return `${prefix}API request failed with status ${status}${detail ? `: ${detail}` : ""}`;
+      }
+    } else if (error.code === "ECONNABORTED") {
+      return `${prefix}Request timed out. Please try again or check your network connection.`;
+    } else if (error.code === "ENOTFOUND" || error.code === "ECONNREFUSED") {
+      return `${prefix}Cannot connect to ElevenLabs API. Please check your internet connection.`;
+    } else if (error.message) {
+      return `${prefix}Network error - ${error.message}`;
+    }
+  }
+
+  // Generic error handling
+  if (error instanceof Error) {
+    return `${prefix}${error.message}`;
+  }
+
+  return `${prefix}Unexpected error occurred: ${String(error)}`;
+}
+
+/**
+ * Validates that the API key is present in environment
+ *
+ * @throws Error if ELEVENLABS_API_KEY is not set
+ */
+export function validateApiKey(): void {
+  if (!process.env.ELEVENLABS_API_KEY) {
+    throw new Error(
+      "ELEVENLABS_API_KEY environment variable is not set. " +
+      "Please set it to your ElevenLabs API key."
+    );
+  }
+}
+
+/**
+ * Wraps an async function with error handling
+ *
+ * @param fn - The async function to wrap
+ * @param context - Context for error messages
+ * @returns Wrapped function that handles errors consistently
+ */
+export function withErrorHandling<T extends unknown[], R>(
+  fn: (...args: T) => Promise<R>,
+  context?: string
+): (...args: T) => Promise<R> {
+  return async (...args: T): Promise<R> => {
+    try {
+      return await fn(...args);
+    } catch (error) {
+      throw new Error(handleElevenLabsError(error, context));
+    }
+  };
+}

package/src/utils/truncation.ts

@@ -0,0 +1,97 @@
+/**
+ * Response truncation utilities
+ *
+ * Handles truncation of large responses to stay within MCP character limits
+ * while providing clear guidance to users.
+ */
+
+import { CHARACTER_LIMIT } from "../constants.js";
+
+/**
+ * Truncates content if it exceeds the character limit
+ *
+ * @param content - The content to potentially truncate
+ * @param context - Additional context or guidance for the user
+ * @returns Original or truncated content with indicator
+ */
+export function truncateIfNeeded(content: string, context?: string): string {
+  if (content.length <= CHARACTER_LIMIT) {
+    return content;
+  }
+
+  const truncated = content.substring(0, CHARACTER_LIMIT);
+  const guidance = context || "Consider using filters or pagination to see more results";
+
+  return `${truncated}\n\n[TRUNCATED: Response exceeded ${CHARACTER_LIMIT} characters. ${guidance}]`;
+}
+
+/**
+ * Truncates an array of items and provides pagination guidance
+ *
+ * @param items - Array of items that might need truncation
+ * @param formatter - Function to format each item as a string
+ * @param currentOffset - Current pagination offset
+ * @param context - Additional context for users
+ * @returns Formatted and potentially truncated string
+ */
+export function truncateArray<T>(
+  items: T[],
+  formatter: (item: T, index: number) => string,
+  currentOffset: number = 0,
+  context?: string
+): string {
+  let result = "";
+  let count = 0;
+
+  for (let i = 0; i < items.length; i++) {
+    const formatted = formatter(items[i], i);
+
+    if (result.length + formatted.length > CHARACTER_LIMIT) {
+      const nextOffset = currentOffset + count;
+      const guidance = context || `Use offset=${nextOffset} to continue from where truncation occurred`;
+      result += `\n\n[TRUNCATED: Response exceeded ${CHARACTER_LIMIT} characters. ${guidance}]`;
+      break;
+    }
+
+    result += formatted;
+    count++;
+  }
+
+  return result;
+}
+
+/**
+ * Safely truncates a string in the middle, preserving start and end
+ *
+ * @param content - Content to truncate
+ * @param maxLength - Maximum length
+ * @returns Truncated string with "..." indicator
+ */
+export function truncateMiddle(content: string, maxLength: number): string {
+  if (content.length <= maxLength) {
+    return content;
+  }
+
+  const halfLength = Math.floor((maxLength - 3) / 2);
+  const start = content.substring(0, halfLength);
+  const end = content.substring(content.length - halfLength);
+
+  return `${start}...${end}`;
+}
+
+/**
+ * Formats a large JSON object with optional truncation
+ *
+ * @param obj - Object to format
+ * @param indent - Indentation spaces (default: 2)
+ * @returns JSON string, potentially truncated
+ */
+export function formatJSON(obj: unknown, indent: number = 2): string {
+  const json = JSON.stringify(obj, null, indent);
+
+  if (json.length > CHARACTER_LIMIT) {
+    return truncateIfNeeded(json, "Response is very large. Consider using filters or requesting specific fields");
+  }
+
+  return json;
+}

package/test-call-wait-for-hello.ts

@@ -0,0 +1,76 @@
+/**
+ * Test call using Demo Agent with first_message override
+ * This makes the agent wait for the human to say hello first
+ */
+
+import axios from 'axios';
+
+const apiKey = process.env.ELEVENLABS_API_KEY;
+
+if (!apiKey) {
+  console.error('❌ Error: ELEVENLABS_API_KEY environment variable not set');
+  process.exit(1);
+}
+
+async function makeTestCall() {
+  try {
+    console.log('🔄 Initiating test call to Connor...');
+    console.log('📱 Using: Demo Agent with first_message override');
+    console.log('⏳ Agent will WAIT for human to speak first\n');
+
+    const response = await axios.post(
+      'https://api.elevenlabs.io/v1/convai/twilio/outbound-call',
+      {
+        agent_id: 'agent_2601kahgbheaftnr7150xp0x8jbf', // Demo Agent
+        agent_phone_number_id: 'phnum_4501kayyj6xtfak80g09czq6yzxm', // Atlas St Louis
+        to_number: '+16184072273', // Connor
+        conversation_initiation_client_data: {
+          dynamic_variables: {
+            lead_name: 'Connor',
+            rep_name: 'Connor',
+            lead_email: 'connor@atlasdigitalusa.com',
+            their_timezone: 'Central Time'
+          },
+          // Override the agent's first message to empty string
+          // This makes it wait for the human to speak first
+          conversation_config_override: {
+            agent: {
+              first_message: ''  // Empty string = wait for human
+            }
+          }
+        }
+      },
+      {
+        headers: {
+          'xi-api-key': apiKey,
+          'Content-Type': 'application/json'
+        }
+      }
+    );
+
+    console.log('✅ Call initiated successfully!\n');
+    console.log('📞 Call Details:');
+    console.log('─────────────────────────────────────');
+    console.log(`Conversation ID: ${response.data.conversation_id}`);
+    console.log(`Twilio Call SID: ${response.data.callSid}`);
+    console.log('─────────────────────────────────────\n');
+    console.log('⚠️  CRITICAL: Agent configured to WAIT for human to speak first!');
+    console.log('   Connor should say "hello" first, THEN agent will respond.\n');
+    console.log('Full Response:');
+    console.log(JSON.stringify(response.data, null, 2));
+
+  } catch (error) {
+    if (axios.isAxiosError(error)) {
+      console.error('❌ API Error:', error.response?.status);
+      console.error('Message:', error.response?.data?.detail || error.message);
+      if (error.response?.data) {
+        console.error('Full error:', JSON.stringify(error.response.data, null, 2));
+      }
+    } else {
+      console.error('❌ Unexpected error:', error);
+    }
+    process.exit(1);
+  }
+}
+
+makeTestCall();

package/test-call.json

@@ -0,0 +1,5 @@
+{
+  "agent_id": "agent_2601kahgbheaftnr7150xp0x8jbf",
+  "agent_phone_number_id": "phnum_7801kay1k5qjekb9eqakq1x6a8h0",
+  "to_number": "+19788066657"
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Griffin Long
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.