elevenlabs-voice-agent-mcp 1.0.15 → 1.1.0

package/README.md

@@ -490,6 +490,66 @@ The MCP server accepts any valid ElevenLabs model identifier. Common options inc
 
 `en`, `es`, `fr`, `de`, `it`, `pt`, `pl`, `nl`, `ja`, `zh`, `ko`, `ar`, `hi`
 
+## API Reference
+
+Complete reference for all 23 MCP tools organized by functionality.
+
+### Tier 1: Core Agent Management
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `elevenlabs_create_agent` | Create a new voice agent | `name`, `prompt`, `llm`, `voice_id`, `first_message`, `language` |
+| `elevenlabs_get_agent` | Retrieve agent configuration | `agent_id` |
+| `elevenlabs_update_agent` | Modify agent settings | `agent_id`, plus any fields to update |
+| `elevenlabs_delete_agent` | Permanently delete an agent | `agent_id` |
+| `elevenlabs_list_agents` | List all agents with pagination | `limit`, `offset` |
+
+### Tier 2: Knowledge Base & Tools
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `elevenlabs_add_knowledge_base` | Add documents to agent knowledge | `agent_id`, `documents[]` |
+| `elevenlabs_create_webhook_tool` | Create webhook integration | `agent_id`, `name`, `url`, `method`, `parameters[]` |
+| `elevenlabs_list_tools` | List agent's webhook tools | `agent_id` |
+| `elevenlabs_delete_tool` | Remove a webhook tool | `agent_id`, `tool_name` |
+
+### Tier 3: Testing & Monitoring
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `elevenlabs_get_conversation` | Get conversation transcript | `conversation_id` |
+| `elevenlabs_list_conversations` | List conversations with filtering | `agent_id`, `status`, `limit`, `offset` |
+| `elevenlabs_generate_widget_code` | Generate HTML embed code | `agent_id`, `color`, `avatar_url` |
+
+### Tier 4: Utilities
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `elevenlabs_list_voices` | Browse available voices | `language`, `gender`, `age`, `limit` |
+
+### Tier 5: Outbound Calling & Phone Management
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `elevenlabs_start_outbound_call` | Initiate single call | `agent_id`, `agent_phone_number_id`, `to_number` |
+| `elevenlabs_submit_batch_call` | Submit batch calling job | `call_name`, `agent_id`, `recipients[]` |
+| `elevenlabs_list_batch_calls` | List batch jobs | `limit`, `last_doc` |
+| `elevenlabs_get_batch_call` | Get batch details | `batch_id` |
+| `elevenlabs_list_phone_numbers` | List connected phone numbers | - |
+| `elevenlabs_get_phone_number` | Get phone number details | `phone_number_id` |
+| `elevenlabs_import_phone_number` | Import Twilio number | `phone_number`, `label`, `sid`, `token` |
+| `elevenlabs_update_phone_number` | Assign agent to number | `phone_number_id`, `agent_id` |
+| `elevenlabs_delete_phone_number` | Remove phone number | `phone_number_id` |
+
+### Tool Annotations
+
+All tools include MCP annotations for client guidance:
+
+- `readOnlyHint`: Whether the tool only reads data (no side effects)
+- `destructiveHint`: Whether the tool performs destructive actions (delete)
+- `idempotentHint`: Whether repeated calls have the same effect
+- `openWorldHint`: Whether the tool interacts with external systems
+
 ## Development
 
 ### Project Structure
@@ -497,42 +557,161 @@ The MCP server accepts any valid ElevenLabs model identifier. Common options inc
 ```
 elevenlabs-voice-agent-mcp/
 ├── src/
-│   ├── index.ts                 # Server initialization
-│   ├── types.ts                 # TypeScript interfaces
-│   ├── constants.ts             # API URLs and defaults
+│   ├── index.ts                 # Server initialization & tool registration
+│   ├── types.ts                 # TypeScript interfaces for all entities
+│   ├── constants.ts             # API URLs, limits, and defaults
 │   ├── schemas/                 # Zod validation schemas
-│   │   ├── agent-schemas.ts
-│   │   ├── tool-schemas.ts
+│   │   ├── agent-schemas.ts     # Agent CRUD schemas
+│   │   ├── tool-schemas.ts      # Webhook tool & knowledge base schemas
 │   │   ├── conversation-schemas.ts
-│   │   └── common-schemas.ts
+│   │   ├── outbound-schemas.ts  # Single call schemas
+│   │   ├── batch-calling-schemas.ts
+│   │   ├── phone-number-schemas.ts
+│   │   └── common-schemas.ts    # Shared schemas (pagination, etc.)
 │   ├── services/                # API clients and utilities
-│   │   ├── elevenlabs-api.ts
-│   │   └── formatters.ts
+│   │   ├── elevenlabs-api.ts    # HTTP client with auth
+│   │   └── formatters.ts        # Response formatting (Markdown/JSON)
 │   ├── tools/                   # MCP tool implementations
-│   │   ├── agent-tools.ts
-│   │   ├── knowledge-tools.ts
-│   │   ├── tool-tools.ts
+│   │   ├── agent-tools.ts       # CRUD for agents
+│   │   ├── knowledge-tools.ts   # Knowledge base management
+│   │   ├── tool-tools.ts        # Webhook tool management
 │   │   ├── conversation-tools.ts
-│   │   └── utility-tools.ts
+│   │   ├── utility-tools.ts     # Voices, widgets
+│   │   ├── outbound-tools.ts    # Single outbound calls
+│   │   ├── batch-calling-tools.ts
+│   │   └── phone-number-tools.ts
 │   └── utils/                   # Helper functions
-│       ├── error-handlers.ts
-│       └── truncation.ts
-└── dist/                        # Compiled JavaScript
+│       ├── error-handlers.ts    # Error parsing & messages
+│       ├── truncation.ts        # Response size management
+│       └── phone-normalizer.ts  # E.164 format conversion
+├── dist/                        # Compiled JavaScript (gitignored)
+├── test/                        # Test files
+└── CLAUDE.md                    # AI assistant guidance
 ```
 
 ### Scripts
 
-- `npm run build` - Compile TypeScript to JavaScript
-- `npm run dev` - Run in watch mode with auto-reload
-- `npm start` - Run the compiled server
-- `npm run clean` - Remove build artifacts
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Compile TypeScript to JavaScript in `dist/` |
+| `npm run dev` | Run with auto-reload using `tsx watch` |
+| `npm start` | Run compiled server from `dist/` |
+| `npm run clean` | Remove build artifacts |
+| `npm test` | Run tests (placeholder) |
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ELEVENLABS_API_KEY` | Yes | Your ElevenLabs API key |
+
+### Testing
+
+The project includes a comprehensive test suite with **351 unit tests** achieving **88%+ code coverage**.
+
+#### Running Tests
+
+```bash
+# Run all unit tests
+npm test
+
+# Run tests in watch mode (re-runs on file changes)
+npm run test:watch
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Run tests with UI (browser-based test runner)
+npm run test:ui
+
+# TypeScript type checking for test files
+npm run test:types
+
+# Run integration tests (requires API key)
+npm run test:integration
+```
+
+#### Test Structure
+
+```
+src/__tests__/
+├── mocks/
+│   └── fixtures.ts          # Mock data and test fixtures
+├── schemas/
+│   └── schemas.test.ts      # Zod schema validation tests
+├── services/
+│   ├── elevenlabs-api.test.ts  # API client tests
+│   └── formatters.test.ts      # Response formatter tests
+├── tools/
+│   ├── agent-tools.test.ts        # Agent CRUD tests
+│   ├── batch-calling-tools.test.ts
+│   ├── conversation-tools.test.ts
+│   ├── knowledge-tools.test.ts
+│   ├── outbound-tools.test.ts
+│   ├── phone-number-tools.test.ts
+│   ├── tool-tools.test.ts
+│   └── utility-tools.test.ts
+├── utils/
+│   ├── error-handlers.test.ts
+│   └── truncation.test.ts
+└── setup.ts                 # Test environment setup
+```
+
+#### Coverage Thresholds
+
+The test suite enforces minimum coverage thresholds:
+- **Statements**: 85%
+- **Branches**: 75%
+- **Functions**: 85%
+- **Lines**: 85%
 
 ### Adding New Tools
 
-1. Create tool definition in appropriate file under `src/tools/`
-2. Add Zod schema in `src/schemas/`
-3. Register tool in `src/index.ts`
-4. Rebuild with `npm run build`
+1. **Create schema** in `src/schemas/`:
+   ```typescript
+   export const MyToolSchema = z.object({
+     param: z.string().describe("Parameter description"),
+     response_format: ResponseFormatSchema
+   }).passthrough();
+   ```
+
+2. **Create tool definition** in `src/tools/`:
+   ```typescript
+   export const elevenlabs_my_tool = {
+     name: "elevenlabs_my_tool",
+     description: `Tool description with examples...`,
+     zodSchema: MyToolSchema,
+     annotations: { readOnlyHint: true, ... },
+     handler: async (args: unknown) => {
+       const parsed = MyToolSchema.parse(args);
+       // Implementation
+       return { content: [{ type: "text", text: result }] };
+     }
+   };
+   ```
+
+3. **Register in `src/index.ts`**:
+   ```typescript
+   import { elevenlabs_my_tool } from "./tools/my-tools.js";
+   // Add to tools array
+   ```
+
+4. **Rebuild**: `npm run build`
+
+### Code Style
+
+- TypeScript strict mode enabled
+- ESM modules with `.js` extension in imports
+- Zod schemas for runtime validation
+- Consistent error handling via `handleElevenLabsError`
+- Response formatting supports both Markdown and JSON
+
+### Testing Locally
+
+1. Build the project: `npm run build`
+2. Set API key: `export ELEVENLABS_API_KEY=your_key`
+3. Test with MCP inspector or Claude Desktop
+4. Check server output on stderr for diagnostics
 
 ## Error Handling
 

package/dist/__tests__/mocks/fixtures.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Test fixtures and mock data
+ *
+ * Provides consistent mock data for all tests.
+ */
+import { Agent, ConversationMetadata, ToolConfig, Voice, BatchCallResponse, BatchCallDetailedResponse, WorkspaceBatchCallsResponse, PhoneNumber, OutboundCallResponse, ImportPhoneNumberResponse, ResponseFormat } from "../../types.js";
+export declare const mockAgent: Agent;
+export declare const mockAgentMinimal: Agent;
+export declare const mockAgentsList: Agent[];
+export declare const mockConversation: ConversationMetadata;
+export declare const mockConversationInProgress: ConversationMetadata;
+export declare const mockConversationsList: ConversationMetadata[];
+export declare const mockTool: ToolConfig;
+export declare const mockToolWithEnum: ToolConfig;
+export declare const mockToolsList: ToolConfig[];
+export declare const mockVoice: Voice;
+export declare const mockVoiceMale: Voice;
+export declare const mockVoicesList: Voice[];
+export declare const mockBatchCall: BatchCallResponse;
+export declare const mockBatchCallDetailed: BatchCallDetailedResponse;
+export declare const mockBatchCallsList: WorkspaceBatchCallsResponse;
+export declare const mockPhoneNumber: PhoneNumber;
+export declare const mockPhoneNumberUnassigned: PhoneNumber;
+export declare const mockPhoneNumbersList: import("../../types.js").TwilioPhoneNumber[];
+export declare const mockOutboundCallSuccess: OutboundCallResponse;
+export declare const mockOutboundCallFailed: OutboundCallResponse;
+export declare const mockImportPhoneNumber: ImportPhoneNumberResponse;
+export declare const mockApiError400: {
+    response: {
+        status: number;
+        data: {
+            detail: string;
+        };
+    };
+};
+export declare const mockApiError401: {
+    response: {
+        status: number;
+        data: {
+            detail: string;
+        };
+    };
+};
+export declare const mockApiError404: {
+    response: {
+        status: number;
+        data: {
+            detail: string;
+        };
+    };
+};
+export declare const mockApiError429: {
+    response: {
+        status: number;
+        data: {
+            detail: string;
+        };
+    };
+};
+export declare const mockApiError500: {
+    response: {
+        status: number;
+        data: {
+            detail: string;
+        };
+    };
+};
+export declare const validCreateAgentInput: {
+    name: string;
+    prompt: string;
+    llm: string;
+    voice_id: string;
+    voice_model: "eleven_turbo_v2_5";
+    first_message: string;
+    language: "en";
+    temperature: number;
+    max_tokens: number;
+    response_format: ResponseFormat;
+};
+export declare const validUpdateAgentInput: {
+    agent_id: string;
+    name: string;
+    prompt: string;
+    response_format: ResponseFormat;
+};
+export declare const invalidCreateAgentInputs: {
+    emptyName: {
+        name: string;
+        prompt: string;
+    };
+    shortPrompt: {
+        name: string;
+        prompt: string;
+    };
+    invalidVoiceModel: {
+        name: string;
+        prompt: string;
+        voice_model: string;
+    };
+    invalidTemperature: {
+        name: string;
+        prompt: string;
+        temperature: number;
+    };
+};
+export declare const validBatchCallInput: {
+    call_name: string;
+    agent_id: string;
+    recipients: ({
+        phone_number: string;
+        conversation_initiation_client_data?: undefined;
+    } | {
+        phone_number: string;
+        conversation_initiation_client_data: {
+            dynamic_variables: {
+                name: string;
+            };
+        };
+    })[];
+    response_format: ResponseFormat;
+};
+export declare const invalidBatchCallInputs: {
+    emptyRecipients: {
+        call_name: string;
+        agent_id: string;
+        recipients: never[];
+    };
+    invalidPhoneNumber: {
+        call_name: string;
+        agent_id: string;
+        recipients: {
+            phone_number: string;
+        }[];
+    };
+};
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/__tests__/mocks/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../../src/__tests__/mocks/fixtures.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,EACL,oBAAoB,EACpB,UAAU,EACV,KAAK,EACL,iBAAiB,EACjB,yBAAyB,EACzB,2BAA2B,EAC3B,WAAW,EACX,oBAAoB,EACpB,yBAAyB,EACzB,cAAc,EACf,MAAM,gBAAgB,CAAC;AAMxB,eAAO,MAAM,SAAS,EAAE,KAyCvB,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,KAiB9B,CAAC;AAEF,eAAO,MAAM,cAAc,SAAgC,CAAC;AAM5D,eAAO,MAAM,gBAAgB,EAAE,oBAoC9B,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,oBAKxC,CAAC;AAEF,eAAO,MAAM,qBAAqB,wBAAiD,CAAC;AAMpF,eAAO,MAAM,QAAQ,EAAE,UAuBtB,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,UAqB9B,CAAC;AAEF,eAAO,MAAM,aAAa,cAA+B,CAAC;AAM1D,eAAO,MAAM,SAAS,EAAE,KAYvB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,KAY3B,CAAC;AAEF,eAAO,MAAM,cAAc,SAA6B,CAAC;AAMzD,eAAO,MAAM,aAAa,EAAE,iBAa3B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,yBA+BnC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,2BAIhC,CAAC;AAMF,eAAO,MAAM,eAAe,EAAE,WAW7B,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,WAQvC,CAAC;AAEF,eAAO,MAAM,oBAAoB,8CAA+C,CAAC;AAMjF,eAAO,MAAM,uBAAuB,EAAE,oBAKrC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,oBAKpC,CAAC;AAMF,eAAO,MAAM,qBAAqB,EAAE,yBAEnC,CAAC;AAMF,eAAO,MAAM,eAAe;;;;;;;CAK3B,CAAC;AAEF,eAAO,MAAM,eAAe;;;;;;;CAK3B,CAAC;AAEF,eAAO,MAAM,eAAe;;;;;;;CAK3B,CAAC;AAEF,eAAO,MAAM,eAAe;;;;;;;CAK3B,CAAC;AAEF,eAAO,MAAM,eAAe;;;;;;;CAK3B,CAAC;AAMF,eAAO,MAAM,qBAAqB;;;;;;;;;;;CAWjC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;CAKjC,CAAC;AAEF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;CAmBpC,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;CAQ/B,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;CAWlC,CAAC"}