CallCenter.js MCP + CLI

1[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/gerkensm/callcenter.js-mcp)
2 
3# CallCenter.js MCP + CLI
4 
5**An MCP Server, CLI tool, and API that makes phone calls on your behalf using VoIP.**
6 
7Just tell Claude what you want to accomplish, and it will call and handle the conversation for you. This is essentially an MCP Server that bridges between OpenAI's Real-Time Voice API and your VoIP connection to call people on your behalf.
8 
9> **⚠️ Vibe-coded side project!** Please do not use this in any kind of professional context. This is a side project coded in a weekend. There are no guard rails. Your MCP client can call *any* number with this, even if you don't ask it to. In fact, it has done so during testing - it called a random number during the night "for testing" and played back scary low-pitched noises - then claimed it called MY number. So YMMV, no warranties. See [disclaimer](#️-important-disclaimer) below.
10 
11## 📞 Example: Order Pizza with Claude
12 
13**You:** "Can you call Tony's Pizza and order a large pepperoni pizza for delivery to 123 Main St? My name is John and my number is 555-0123."
14 
15**Claude automatically calls the restaurant:**
16 
17```
18⏺ mcp__callcenter_js__simple_call(phone_number: "+15551234567", 
19                                    brief: "Call Tony's Pizza and order a large pepperoni pizza for delivery to 123 Main St. Customer name is John, phone number 555-0123", 
20                                    caller_name: "John")
21  ⎿ # Simple Call Result
22    
23    **Status:** ✅ Success  
24    **Duration:** 3 minutes 24 seconds
25    **Call ID:** abc123xyz
26    
27    ## Call Transcript
28    
29    [14:23:15] 🎤 HUMAN: Tony's Pizza, how can I help you?
30    [14:23:15] 🤖 ASSISTANT: Hi! I'm calling on behalf of John to place a delivery order.
31    [14:23:20] 🎤 HUMAN: Sure! What would you like?
32    [14:23:20] 🤖 ASSISTANT: I'd like to order one large pepperoni pizza for delivery please.
33    [14:23:25] 🎤 HUMAN: Large pepperoni, got it. What's the delivery address?
34    [14:23:25] 🤖 ASSISTANT: The address is 123 Main Street.
35    [14:23:30] 🎤 HUMAN: And your phone number?
36    [14:23:30] 🤖 ASSISTANT: The phone number is 555-0123.
37    [14:23:35] 🎤 HUMAN: Perfect! That'll be $18.99. We'll have it delivered in about 30 minutes.
38    [14:23:40] 🤖 ASSISTANT: That sounds great! Thank you so much.
39    [14:23:42] 🎤 HUMAN: You're welcome! Have a great day.
40```
41 
42**Pizza ordered successfully!** 🍕
43 
44## 📚 Quick Context for the Uninitiated
45 
46**VoIP (Voice over IP)** is how you make phone calls over the internet instead of traditional phone lines. **SIP (Session Initiation Protocol)** is the language these systems speak to connect calls. Think of it as HTTP but for phone calls.
47 
48**Fritz!Box** is a popular German router/modem that happens to have a built-in phone system (PBX). If you have one, you already have everything you need to make VoIP calls - this tool just connects to it. Outside Germany, you might know similar devices from other brands, or use dedicated VoIP services like Asterisk, 3CX, or cloud providers.
49 
50**MCP (Model Context Protocol)** is Anthropic's standard for connecting AI assistants like Claude to external tools and services. It's what lets MCP clients actually *do* things instead of just talking about them.
51 
52## 🚀 What This Enables
53 
54- 🔌 **MCP Server** - Use directly in Claude Code or any MCP client (most popular usage)
55- 🖥️ **CLI Tool** - Command-line interface for direct phone calls  
56- 📚 **TypeScript API** - Programmatic library for building voice applications
57 
58Built as a bridge between OpenAI's Real-Time Voice API and VoIP networks, with multiple codec support (G.722, G.711), and expanded SIP protocol support for broad VoIP compatibility. Compatible with the latest `gpt-realtime` model released August 28, 2025.
59 
60## 🏗️ System Architecture
61 
62```mermaid
63graph TB
64    subgraph "User Interface"
65        A[Claude Code/MCP Client]
66        B[CLI Tool]
67        C[TypeScript API]
68    end
69    
70    subgraph "CallCenter.js Core"
71        D[MCP Server]
72        E[VoiceAgent]
73        F[Call Brief Processor<br/>o3-mini model]
74    end
75    
76    subgraph "Communication Layer"
77        G[SIP Client<br/>Provider Support]
78        H[Audio Bridge<br/>RTP Streaming]
79    end
80    
81    subgraph "Audio Processing"
82        I[G.722 Codec<br/>16kHz Wideband]
83        J[G.711 Codec<br/>8kHz Fallback]
84    end
85    
86    subgraph "External Services"
87        K[OpenAI Real-Time API<br/>gpt-realtime model]
88        L[VoIP Network<br/>Fritz!Box/Asterisk/etc]
89    end
90    
91    A --> D
92    B --> E
93    C --> E
94    D --> E
95    E --> F
96    E --> G
97    E --> H
98    F --> K
99    G --> L
100    H --> I
101    H --> J
102    H --> K
103    
104    style F fill:#e1f5fe
105    style K fill:#fff3e0
106    style L fill:#f3e5f5
107```
108 
109> **⚠️ Vibe-coded project!** Developed and tested on Fritz!Box (a German router with built-in VoIP) only. Other provider configs are research-based but untested. YMMV, no warranties. See [disclaimer](#️-important-disclaimer) below.
110 
111![100% vibe-coded](./assets/vibe-coded.svg)
112 
113## 🔌 MCP Client Integration (Most Popular!)
114 
115**Perfect for when your coding agent needs to call library authors to complain about their documentation!** 😄
116 
117### Quick Setup
118 
119```bash
120# Add to Claude Code with one command:
121claude mcp add --env SIP_USERNAME=your_actual_extension \
122  --env SIP_PASSWORD="your_actual_password" \
123  --env SIP_SERVER_IP=192.168.1.1 \
124  --env OPENAI_API_KEY="sk-your_actual_openai_key" \
125  --env USER_NAME="Your Actual Name" \
126  -- callcenter.js npx -- github:gerkensm/callcenter.js-mcp --mcp
127```
128 
129**Then just ask your MCP Client to make calls:**
130 
131> "Can you call the pizza place and order a large pepperoni? My number is 555-0123."
132 
133Your MCP Client will automatically handle the entire conversation using the AI Voice Agent! 🤖📞
134 
135## ✨ Key Features
136 
137- 🎙️ **Multiple Codec Support**: G.722 wideband (16kHz) + G.711 fallback for broad compatibility
138- 🧩 **Compiler-Free WASM Codec**: Ships with a prebuilt G.722 WebAssembly module so `npx` users get wideband audio without installing build tools (native addon still available for max performance)
139- 🤖 **AI-Powered Conversations**: Uses OpenAI's Real-Time Voice API with the latest `gpt-realtime` model (released August 28, 2025) for actual calls, with o3-mini model for instruction generation
140- 🌍 **Automatic Language Detection**: Intelligently detects conversation language from call briefs and configures transcription accordingly
141- 🎭 **Auto Voice Selection**: New 'auto' mode where o3-mini selects optimal voice based on call context (formality, industry, goals)
142- 🔊 **Voice Characteristics**: Full support for all 10 OpenAI Realtime API voices with gender and personality awareness
143- 🌐 **Expanded SIP Support**: Configurations for common SIP providers (Fritz!Box tested, others experimental)
144- 🔧 **Smart Configuration**: Auto-detects provider requirements and optimizes settings
145- 📞 **Enterprise-Ready**: Supports advanced SIP features (STUN/TURN, session timers, transport fallback)
146- 🔄 **Robust Connection Management**: Automatic reconnection with intelligent error handling
147- ✅ **Built-in Validation**: Comprehensive configuration validation with network testing
148- 🎯 **Provider Profiles**: Pre-configured settings for popular SIP systems
149- 🔌 **MCP Server**: Integrate with MCP clients like Claude Code
150- 📚 **TypeScript API**: Programmatic library for building voice applications
151- 📝 **Call Brief Processing**: Natural language call instructions using o3-mini model with structured JSON output
152- 🎵 **Optional Call Recording**: Stereo WAV recording with caller/AI separation
153 
154## 🚀 Quick Start
155 
156### Option 1: Run Instantly with npx (No Installation) ⚡
157 
158**Fastest way to try it out:**
159 
160```bash
161# Set environment variables (or create .env file)
162export SIP_USERNAME="your_extension"
163export SIP_PASSWORD="your_password"
164export SIP_SERVER_IP="192.168.1.1"
165export OPENAI_API_KEY="sk-your-key-here"
166 
167# Run directly from GitHub (no installation needed!)
168npx github:gerkensm/callcenter.js-mcp call "+1234567890" --brief "Call restaurant for reservation" --user-name "Your Name"
169```
170 
171**Or using a .env file:**
172 
173```bash
174# Create .env file
175cat > .env << EOF
176SIP_USERNAME=your_extension
177SIP_PASSWORD=your_password
178SIP_SERVER_IP=192.168.1.1
179OPENAI_API_KEY=sk-your-key-here
180SIP_PROVIDER=fritz-box
181OPENAI_VOICE=auto
182EOF
183 
184# Run from GitHub (loads .env automatically)  
185npx github:gerkensm/callcenter.js-mcp call "+1234567890" --brief "Call restaurant"
186```
187 
188**Note**: High-quality G.722 audio ships as a prebuilt WebAssembly module, so `npx` works even on machines without compilers. If you want the faster native addon instead, run `npm run build:native` (or `npm run build:all`) after cloning.
189 
190### Option 2: Local Installation
191 
192#### Prerequisites
193 
194- Node.js 20+
195- (Optional) **Python 3.x + C/C++ build tools** — only needed if you plan to rebuild the native addon instead of using the bundled WebAssembly codec
196  - macOS: Xcode Command Line Tools (`xcode-select --install`)
197  - Windows: Visual Studio Build Tools 
198  - Linux: `build-essential` package
199- OpenAI API key
200 
201**Note**: The prebuilt WebAssembly codec already provides wideband G.722 audio out of the box. Rebuilding the native addon is optional and mainly useful for squeezing out a little more performance.
202 
203#### Installation
204 
205```bash
206# Clone and install
207git clone https://github.com/gerkensm/callcenter.js-mcp
208cd callcenter.js-mcp
209npm install
210 
211# Copy example configuration
212cp config.example.json config.json
213```
214 
215### Configuration
216 
217Edit `config.json` with your settings:
218 
219```json
220{
221  "sip": {
222    "username": "your_sip_username",
223    "password": "your_sip_password", 
224    "serverIp": "192.168.1.1",
225    "serverPort": 5060,
226    "provider": "fritz-box"
227  },
228  "ai": {
229    "openaiApiKey": "sk-your-openai-api-key-here",
230    "voice": "alloy",
231    "instructions": "You are a helpful AI assistant making phone calls on behalf of users.",
232    "userName": "Your Name"
233  }
234}
235```
236 
237## 🎯 Usage Options
238 
239### 1. MCP Server (Claude Code Integration) ⭐
240 
241**Most popular usage** - integrates with Claude Code for seamless AI-powered calling. Perfect for when your coding agent needs to call library authors to complain about their documentation! 😄
242 
243#### **Quick Setup with npx (Recommended)** 
244 
245**Option 1: Using MCP Client CLI (Easiest)**
246 
247```bash
248# Replace with your ACTUAL credentials before running:
249claude mcp add --env SIP_USERNAME=your_actual_extension \
250  --env SIP_PASSWORD="your_actual_password" \
251  --env SIP_SERVER_IP=192.168.1.1 \
252  --env OPENAI_API_KEY="sk-your_actual_openai_key" \
253  --env USER_NAME="Your Actual Name" \
254  -- callcenter.js npx -- github:gerkensm/callcenter.js-mcp --mcp
255```
256 
257**⚠️ Important:** Replace the placeholder values with your actual SIP credentials and OpenAI API key, or the server will fail to connect.
258 
259**Option 2: Manual Configuration**
260 
261Configure in Claude Code's MCP settings to automatically pull from GitHub:
262 
263```json
264{
265  "mcpServers": {
266    "callcenter.js": {
267      "command": "npx",
268      "args": ["github:gerkensm/callcenter.js-mcp", "--mcp"],
269      "env": {
270        "SIP_USERNAME": "your_extension",
271        "SIP_PASSWORD": "your_password",
272        "SIP_SERVER_IP": "192.168.1.1",
273        "OPENAI_API_KEY": "sk-your-key-here",
274        "USER_NAME": "Your Name"
275      }
276    }
277  }
278}
279```
280 
281#### **Alternative: Local Installation**
282 
283For local development or if you prefer local installation:
284 
285```bash
286npm start --mcp
287```
288 
289Or configure Claude Code with local installation:
290 
291```json
292{
293  "mcpServers": {
294    "callcenter.js": {
295      "command": "node",
296      "args": ["dist/cli.js", "--mcp"],
297      "cwd": "/path/to/voip-agent"
298    }
299  }
300}
301```
302 
303Available MCP tools:
304- `simple_call` - Make calls with automatic instruction generation
305- `advanced_call` - Make calls with granular parameter control
306 
307**Example usage in MCP Client:**
308 
309```
310You: "Can you call Bocca di Bacco restaurant and book a table for 2 people tonight at 7:30pm? My name is John Doe."
311 
312MCP Client: I'll call Bocca di Bacco restaurant to book a table for 2 people tonight at 7:30pm.
313 
314🔧 mcp__ai-voice-agent__simple_call(
315  phone_number: "+1234567890",
316  brief: "Call Bocca di Bacco restaurant and book a table for 2 people tonight at 7:30pm",
317  caller_name: "John Doe"
318)
319 
320✅ Call completed successfully! 
321📞 Duration: 2 minutes 15 seconds
322📝 Reservation confirmed for 2 people at 7:30pm tonight
323```
324 
325**More examples:**
326 
327```
328You: "My internet is down. Can you call my ISP and get a status update? I'm Sarah Johnson, account #12345."
329 
330MCP Client: I'll call your internet service provider to check on the outage status.
331 
332🔧 mcp__ai-voice-agent__simple_call(
333  phone_number: "+18005551234", 
334  brief: "Call ISP about internet outage, customer Sarah Johnson account #12345",
335  caller_name: "Sarah Johnson"
336)
337```
338 
339```
340You: "Call Dr. Smith's office to reschedule my 3pm appointment to next week. I'm Mike Chen."
341 
342MCP Client: I'll call Dr. Smith's office to reschedule your appointment.
343 
344🔧 mcp__ai-voice-agent__simple_call(
345  phone_number: "+15551234567",
346  brief: "Call Dr. Smith's office to reschedule Mike Chen's 3pm appointment to next week", 
347  caller_name: "Mike Chen"
348)
349```
350 
351The MCP Client automatically handles the entire conversation using the AI Voice Agent!
352 
353### 2. Command Line Interface
354 
355**Perfect for when you need to `curl -X POST` your way out of social obligations, or finally implement that O(n log n) `ai-human-sort` algorithm - because nothing says "efficient sorting" like crowdsourcing comparisons to random strangers via VoIP!** 😄
356 
357**💡 Use `--brief` instead of `--instructions` for better results!**
358 
359The `--brief` option uses OpenAI's o3-mini model to generate sophisticated instructions from your simple description, while `--instructions` sends your text directly to the Real-Time Voice API. Since the Real-Time Voice API is optimized for speed (not sophistication), `--brief` typically produces much better call outcomes.
360 
361```bash
362# ✅ RECOMMENDED: Use brief for natural language goals
363npm start call "+1234567890" --brief "Call the restaurant and book a table for 2 at 7pm tonight" --user-name "John Doe"
364 
365# ✅ RECOMMENDED: Brief works for any call type
366npm start call "+1234567890" --brief "Call to check appointment availability for John Doe"
367 
368# ⚠️ ONLY use instructions for very specific, custom behavior
369npm start call "+1234567890" --instructions "You must follow this exact script: Say hello, ask for manager, then hang up"
370 
371# Other examples with brief
372npm start call "+1234567890" --record "meeting.wav" --duration 300 --brief "Conference call to discuss project status"
373npm start call "+1234567890" --log-level verbose --brief "Test call to verify connectivity"
374```
375 
376#### CLI Options
377 
378```bash
379npm start call <number> [options]
380 
381Options:
382  -c, --config <path>           Configuration file path (default: config.json)
383  -d, --duration <seconds>      Maximum call duration in seconds (default: 600)
384  -v, --verbose                 Verbose mode - show all debug information
385  -q, --quiet                   Quiet mode - show only transcripts, errors, and warnings
386  --log-level <level>           Set log level (quiet|error|warn|info|debug|verbose) (default: info)
387  --no-colors                   Disable colored output
388  --no-timestamp                Disable timestamps in logs
389  --record [filename]           Enable stereo call recording (optional filename)
390  --brief <text>                Call brief to generate instructions from (RECOMMENDED)
391  --instructions <text>         Direct AI instructions (use only for specific custom behavior)
392  --user-name <name>            Your name for the AI to use when calling
393  --voice <name>                Voice to use (default: auto) - see Voice Selection section
394  --help                        Display help information
395```
396 
397### 3. Programmatic API
398 
399```typescript
400import { makeCall, createAgent } from 'callcenter.js';
401 
402// Simple call with brief
403const result = await makeCall({
404  number: '+1234567890',
405  brief: 'Call Bocca di Bacco and book a table for 2 at 19:30 for Torben',
406  userName: 'Torben',
407  config: 'config.json'
408});
409 
410console.log(`Call duration: ${result.duration}s`);
411console.log(`Transcript: ${result.transcript}`);
412 
413// Advanced usage with agent instance
414const agent = await createAgent('config.json');
415 
416agent.on('callEnded', () => {
417  console.log('Call finished!');
418});
419 
420await agent.makeCall({ 
421  targetNumber: '+1234567890',
422  duration: 300 
423});
424```
425 
426## 📚 API Reference
427 
428### `makeCall(options: CallOptions): Promise<CallResult>`
429 
430Make a phone call with the AI agent.
431 
432#### CallOptions
433 
434```typescript
435interface CallOptions {
436  number: string;                    // Phone number to call
437  duration?: number;                 // Call duration in seconds
438  config?: string | Config;          // Configuration file path or object
439  instructions?: string;             // Direct AI instructions (highest priority)
440  brief?: string;                    // Call brief to generate instructions from
441  userName?: string;                 // Your name for the AI to use
442  recording?: boolean | string;      // Enable recording with optional filename
443  logLevel?: 'quiet' | 'error' | 'warn' | 'info' | 'debug' | 'verbose';
444  colors?: boolean;                  // Enable colored output
445  timestamps?: boolean;              // Enable timestamps in logs
446}
447```
448 
449#### CallResult
450 
451```typescript
452interface CallResult {
453  callId?: string;                   // Call ID if successful
454  duration: number;                  // Call duration in seconds
455  transcript?: string;               // Full conversation transcript
456  success: boolean;                  // Whether call was successful
457  error?: string;                    // Error message if failed
458}
459```
460 
461### `createAgent(config, options?): Promise<VoiceAgent>`
462 
463Create a VoiceAgent instance for advanced use cases.
464 
465```typescript
466const agent = await createAgent('config.json', {
467  enableCallRecording: true,
468  recordingFilename: 'call.wav'
469});
470 
471// Event handlers
472agent.on('callInitiated', ({ callId, target }) => {
473  console.log(`Call ${callId} started to ${target}`);
474});
475 
476agent.on('callEnded', () => {
477  console.log('Call ended');
478});
479 
480agent.on('error', (error) => {
481  console.error('Call error:', error.message);
482});
483```
484 
485### Configuration Structure
486 
487```typescript
488interface Config {
489  sip: {
490    username: string;
491    password: string;
492    serverIp: string;
493    serverPort?: number;
494    provider?: string;
495    stunServers?: string[];
496    turnServers?: TurnServer[];
497  };
498  ai: {
499    openaiApiKey: string;
500    voice?: 'auto' | 'alloy' | 'ash' | 'ballad' | 'cedar' | 'coral' | 'echo' | 'marin' | 'sage' | 'shimmer' | 'verse';
501    instructions?: string;
502    brief?: string;
503    userName?: string;
504  };
505  logging?: {
506    level?: string;
507  };
508}
509```
510 
511### Environment Variables
512 
513All configuration options can be set via environment variables (useful for npx usage):
514 
515#### **Required Variables:**
516```bash
517SIP_USERNAME=your_extension
518SIP_PASSWORD=your_password  
519SIP_SERVER_IP=192.168.1.1
520OPENAI_API_KEY=sk-your-key-here
521USER_NAME="Your Name"                                     # Required when using --brief
522```
523 
524#### **Optional Variables:**
525```bash
526# SIP Configuration
527SIP_SERVER_PORT=5060
528SIP_LOCAL_PORT=5060
529SIP_PROVIDER=fritz-box                                    # fritz-box, asterisk, cisco, 3cx, generic
530STUN_SERVERS="stun:stun.l.google.com:19302,stun:stun2.l.google.com:19302"
531SIP_TRANSPORTS="udp,tcp"
532 
533# OpenAI Configuration  
534OPENAI_VOICE=auto                                        # auto (recommended), marin, cedar, alloy, echo, shimmer, coral, sage, ash, ballad, verse
535OPENAI_INSTRUCTIONS="Your custom AI instructions"
536 
537# Advanced SIP Features
538SESSION_TIMERS_ENABLED=true
539SESSION_EXPIRES=1800
540SESSION_MIN_SE=90
541SESSION_REFRESHER=uac
542```
543 
544**Priority order:** CLI flags > Config file > Environment variables
545 
546## ✅ Quick Success Check
547 
548Before making real calls, validate your setup with these safe tests:
549 
550### 1. Configuration Validation
551```bash
552# Basic validation - checks syntax and required fields
553npm run validate config.json
554 
555# Detailed validation with network connectivity tests  
556npm run validate:detailed
557 
558# Get specific fix suggestions for issues
559npm run validate:fix
560```
561 
562### 2. Test Call to Yourself (Fritz!Box users)
563```bash
564# Call your own extension to verify audio quality (safe test)
565npm start call "**620" --brief "Test call to check audio quality" --user-name "Your Name" --duration 30
566 
567# Or use your mobile number for end-to-end test
568npm start call "+49123456789" --brief "Quick test call" --user-name "Your Name" --duration 15
569```
570 
571### 3. What to Expect
572- ✅ **Working setup**: Clear audio, proper AI responses, clean call termination
573- ⚠️ **Network issues**: "Connection failed" errors → check firewall/STUN settings  
574- ⚠️ **Auth problems**: "401 Unauthorized" → verify SIP credentials
575- ⚠️ **Codec issues**: Poor audio quality → G.722 compilation may have failed
576 
577> **Pro tip**: Start with `--duration 30` for test calls to avoid long waits if something goes wrong.
578 
579## 📋 Configuration Validation
580 
581The built-in validation system provides comprehensive analysis:
582 
583```bash
584# Basic validation
585npm run validate config.json
586 
587# Detailed validation with network connectivity tests
588npm run validate:detailed
589 
590# Get specific fix suggestions for issues
591npm run validate:fix
592 
593# Test example configurations for different providers
594npm run validate:fritz-box       # AVM Fritz!Box
595npm run validate:asterisk        # Asterisk PBX  
596npm run validate:cisco           # Cisco CUCM
597npm run validate:3cx             # 3CX Phone System
598npm run validate:generic         # Generic SIP provider
599```
600 
601The validator will check:
602- ✅ **Configuration syntax and required fields**
603- ✅ **Provider-specific requirements**
604- ✅ **Network connectivity to SIP server**
605- ✅ **STUN server reachability**
606- ✅ **Codec availability (G.722/G.711)**
607- ✅ **Provider compatibility score**
608 
609## 🌐 SIP Provider Compatibility
610 
611### ✅ **Actually Tested** 
612 
613- **AVM Fritz!Box** - German router brand with built-in VoIP/SIP phone system ✅ **WORKS** (only one actually tested)
614 
615### 🤷 **Vibe-coded Configs** (Educated Guesses)
616 
617- **Asterisk PBX** - Open source PBX (FreePBX, Elastix, etc.) 🤷 **UNTESTED**
618- **Cisco CUCM** - Enterprise Unified Communications 🤷 **UNTESTED** 
619- **3CX Phone System** - Popular business PBX 🤷 **UNTESTED**
620- **Generic SIP Providers** - Standards-compliant SIP trunks 🤷 **UNTESTED**
621 
622### 🔧 **Provider-Specific Features**
623 
624The provider profiles are based on research and documentation, not actual testing:
625 
626| Provider | Transport | NAT Traversal | Session Timers | PRACK | Keepalive |
627|----------|-----------|---------------|----------------|--------|----------|
628| **Fritz Box** | UDP | Not needed | Optional | Disabled | Re-register |
629| **Asterisk** | UDP/TCP | STUN | Supported | Optional | OPTIONS ping |
630| **Cisco CUCM** | TCP preferred | STUN required | Required | Required | OPTIONS ping |
631| **3CX** | TCP/UDP | STUN | Supported | Optional | Re-register |
632 
633### Configuration Decision Tree
634 
635```mermaid
636flowchart TD
637    A[Choose Your SIP Provider] --> B{Fritz!Box Router?}
638    B -->|Yes| C[✅ Use fritz-box profile<br/>UDP transport<br/>No STUN needed]
639    B -->|No| D{Enterprise System?}
640    
641    D -->|Cisco CUCM| E[⚠️ Use cisco profile<br/>TCP transport<br/>STUN required<br/>Session timers + PRACK]
642    D -->|3CX| F[⚠️ Use 3cx profile<br/>TCP/UDP transport<br/>STUN recommended]
643    D -->|Asterisk/FreePBX| G[⚠️ Use asterisk profile<br/>UDP/TCP transport<br/>STUN for NAT]
644    D -->|Other| H[⚠️ Use generic profile<br/>Start with UDP<br/>Add STUN if needed]
645    
646    C --> I[Configure Basic Settings]
647    E --> J[Configure Enterprise Settings]
648    F --> J
649    G --> J
650    H --> J
651    
652    I --> K[Set SIP credentials<br/>serverIp = router IP<br/>typically 192.168.1.1]
653    J --> L[Set SIP credentials<br/>serverIp = server IP<br/>Add STUN servers]
654    
655    K --> M{Network Location?}
656    L --> M
657    
658    M -->|Local Network| N[✅ Basic setup complete<br/>Should work reliably]
659    M -->|Cloud/Remote| O[❓ May need additional<br/>STUN/TURN configuration]
660    
661    style C fill:#c8e6c9
662    style E fill:#ffecb3
663    style F fill:#ffecb3
664    style G fill:#ffecb3
665    style H fill:#ffecb3
666    style N fill:#c8e6c9
667    style O fill:#ffe0b2
668```
669 
670### 📝 **Configuration Examples**
671 
672The project includes ready-to-use configurations for all major providers:
673 
674- `config.example.json` - **AVM Fritz!Box** (home/SMB default)
675- `config.asterisk.example.json` - **Asterisk PBX** with advanced features
676- `config.cisco.example.json` - **Cisco CUCM** enterprise setup
677- `config.3cx.example.json` - **3CX Phone System** configuration
678- `config.generic.example.json` - **Generic SIP provider** template
679 
680## 🎵 Audio Quality & Codecs
681 
682### Codec Priority & Negotiation
683 
6841. **G.722** (Preferred) - 16kHz wideband, superior voice quality
6852. **G.711 μ-law** (Fallback) - 8kHz narrowband, universal compatibility  
6863. **G.711 A-law** (Fallback) - 8kHz narrowband, European standard
687 
688### G.722 Implementation
689 
690- **Prebuilt WebAssembly codec** bundled with the package so every install gets wideband audio out of the box
691- **Native C++ addon** still available for optimal performance when you opt-in with `npm run build:native`
692- **Based on reference implementations** from CMU and Sippy Software
693- **Automatic fallback** to G.711 if codec loading fails for any reason
694- **Real-time encoding/decoding** with low latency
695 
696### Optional Call Recording
697 
698- **Stereo WAV format** with caller on left channel, AI on right channel
699- **Optional filename** specification
700- **Synchronized audio streams** for perfect alignment
701- **High-quality PCM recording** at native sample rates
702 
703### Testing Audio Quality
704 
705```bash
706# Test codec availability
707npm run test:codecs
708 
709# Rebuild all codec artifacts (native + WASM + TS) if you changed the C sources
710npm run build:all
711 
712# Disable G.722 entirely if you only want the G.711 fallback
713npm run build:no-g722
714```
715 
716## 🤖 AI Call Brief Processing
717 
718### Why This Matters: Real-Time Voice API Needs Better Instructions
719 
720OpenAI's Real-Time Voice API is **optimized for speed, not sophistication**. It's great at natural conversation but struggles with complex, goal-oriented tasks without very specific instructions. Here's the problem:
721 
722**❌ What doesn't work well:**
723```bash
724# Vague brief - Real-Time Voice API will be confused and unfocused
725npm start call "+1234567890" --brief "Call the restaurant and book a table"
726```
727 
728**❌ What's tedious and error-prone:**
729```bash
730# Writing detailed instructions manually every time
731npm start call "+1234567890" --instructions "You are calling on behalf of John Doe to make a restaurant reservation for 2 people at Bocca di Bacco for tonight at 7pm. You should start by greeting them professionally, then clearly state your purpose. Ask about availability for 7pm, and if not available, ask for alternative times between 6-8pm. Confirm the booking details including date, time, party size, and get a confirmation number if possible. If you reach voicemail, leave a professional message with callback information..."
732```
733 
734**✅ What works brilliantly:**
735```bash
736# Simple brief - o3 model generates sophisticated instructions
737npm start call "+1234567890" --brief "Call Bocca di Bacco and book a table for 2 at 7pm tonight" --user-name "John Doe"
738```
739 
740### How It Works
741 
742The system uses OpenAI's **o3-mini reasoning model** (their latest small reasoning model - smart but fast) to automatically generate detailed, sophisticated instructions from your simple brief. The o3-mini model:
743 
7441. **Analyzes your brief** and understands the goal
7452. **Creates conversation states** and flow logic  
7463. **Generates specific instructions** for each phase of the call
7474. **Handles edge cases** like voicemail, objections, and alternatives
7485. **Adapts language and tone** based on context
7496. **Provides fallback strategies** when things don't go as planned
750 
751### Call Flow Sequence
752 
753```mermaid
754sequenceDiagram
755    participant U as User/Claude
756    participant V as VoiceAgent
757    participant B as Brief Processor<br/>(o3-mini)
758    participant S as SIP Client
759    participant A as Audio Bridge
760    participant O as OpenAI Realtime<br/>(gpt-realtime)
761    participant P as Phone/VoIP
762 
763    U->>V: makeCall({brief, number, userName})
764    V->>B: Process brief with o3-mini
765    B->>B: Generate detailed instructions<br/>& conversation states
766    B->>V: Sophisticated call instructions
767    
768    V->>S: Connect to SIP server
769    S->>P: INVITE (start call)
770    P->>S: 200 OK (call answered)
771    S->>V: Call established
772    
773    V->>A: Initialize audio bridge
774    V->>O: Connect to OpenAI Realtime
775    O->>V: WebSocket connected
776    V->>O: Send generated instructions
777    
778    loop During Call
779        P->>A: RTP audio packets
780        A->>A: Decode G.722/G.711 → PCM
781        A->>O: Stream PCM audio
782        O->>O: Process speech → text
783        O->>O: Generate AI response
784        O->>A: Stream AI audio (PCM)
785        A->>A: Encode PCM → G.722/G.711
786        A->>P: RTP audio packets
787        
788        Note over V: Monitor call progress<br/>& transcript logging
789    end
790    
791    alt Call completed naturally
792        O->>V: Call completion signal
793        V->>S: Send BYE
794    else Duration limit reached
795        V->>V: Safety timeout triggered
796        V->>S: Send BYE
797    end
798    
799    S->>P: BYE (end call)
800    P->>S: 200 OK
801    V->>U: CallResult{transcript, duration, success}
802```
803 
804### Before/After Example
805 
806**Your simple input:**
807```
808"Call Bocca di Bacco and book a table for 2 at 7pm tonight"
809```
810 
811**What o3-mini generates (excerpt):**
812```
813## Personality and Tone
814Identity: I am an assistant calling on behalf of John Doe to make a restaurant reservation.
815Task: I am responsible for booking a table for 2 people at Bocca di Bacco today at 7:00 PM.
816Tone: Professional, warm, and respectful.
817 
818## Instructions
8191. Open the conversation immediately: "Hello, this is an assistant calling on behalf of John Doe."
8202. Read back critical data: Repeat times and details for confirmation.
8213. Handle objections: Respond politely and offer alternatives between 6-8 PM.
822...
823 
824## Conversation States
825[
826  {
827    "id": "1_greeting",
828    "description": "Greeting and introduction of call purpose",
829    "instructions": ["Introduce yourself as an assistant", "Immediately mention the reservation request"],
830    "examples": ["Hello, this is an assistant calling on behalf of John Doe. I'm calling to book a table for 2 people today at 7:00 PM."]
831  }
832]
833```
834 
835### Automatic Adaptations
836 
837The o3-mini brief processor automatically:
838- **Detects language** from your brief and generates instructions in that language
839- **Creates conversation flow** with logical states and transitions
840- **Handles cultural context** (German restaurants vs. American vs. Japanese)
841- **Generates appropriate examples** with real phrases (no placeholders)
842- **Provides voicemail scripts** for when nobody answers
843- **Plans for objections** and alternative solutions
844 
845### When to Use Each Approach
846 
847- **Use `--brief`** for 95% of calls - it's easier and produces better results
848- **Use `--instructions`** only when you need very specific, custom behavior
849- **Brief processing** is perfect for: reservations, appointments, business calls, customer service
850- **Direct instructions** are better for: highly specialized scenarios, testing, or when you've already perfected your prompt
851 
852## 🎤 Voice Selection
853 
854The AI agent supports 10 different voices from OpenAI's Realtime API, each with unique characteristics. By default, the system uses **auto mode** where o3-mini intelligently selects the optimal voice based on your call's context.
855 
856### Available Voices
857 
858| Voice | Gender | Description | Best For |
859|-------|--------|-------------|----------|
860| **marin** | Female | Clear, professional feminine voice | All-purpose: business calls, customer support, negotiations |
861| **cedar** | Male | Natural masculine voice with warm undertones | All-purpose: professional calls, consultations, service interactions |
862| **alloy** | Neutral | Professional voice with good adaptability | Technical discussions, business contexts, general inquiries |
863| **echo** | Male | Conversational masculine voice | Casual to formal interactions, versatile tone |
864| **shimmer** | Female | Warm, expressive feminine voice | Empathetic conversations, sales, professional contexts |
865| **coral** | Female | Warm and friendly feminine voice | Customer interactions, consultations, support calls |
866| **sage** | Neutral | Calm and thoughtful voice | Medical consultations, advisory roles, serious discussions |
867| **ash** | Neutral | Clear and precise voice | Technical explanations, instructions, educational content |
868| **ballad** | Female | Melodic and smooth feminine voice | Presentations, storytelling, engaging conversations |
869| **verse** | Neutral | Versatile and expressive voice | Dynamic conversations, adaptable to any context |
870 
871### Auto Voice Selection (Recommended)
872 
873The **auto mode** (default) uses o3-mini to analyze your call context and select the most appropriate voice:
874 
875```bash
876# Auto mode - AI selects the best voice
877npm start call "+1234567890" --brief "Call doctor's office to schedule appointment" --user-name "John"
878# Might select: sage (calm, professional for healthcare)
879 
880# Auto mode adapts to context
881npm start call "+1234567890" --brief "Call pizza place to order delivery" --user-name "Sarah"  
882# Might select: coral or echo (friendly, casual for food service)
883```
884 
885### Manual Voice Selection
886 
887You can override auto selection when you have specific requirements:
888 
889```bash
890# Use a specific voice
891npm start call "+1234567890" --voice marin --brief "Call to book reservation" --user-name "Alex"
892 
893# Professional contexts
894npm start call "+1234567890" --voice cedar --brief "Call bank about account" --user-name "Pat"
895 
896# Friendly service calls
897npm start call "+1234567890" --voice coral --brief "Call flower shop for delivery" --user-name "Sam"
898```
899 
900### Configuration Options
901 
902Set default voice in your config file or environment:
903 
904```json
905// config.json
906{
907  "ai": {
908    "voice": "auto",  // or specific voice like "marin", "cedar", etc.
909    // ...
910  }
911}
912```
913 
914```bash
915# Environment variable
916export OPENAI_VOICE=auto  # or marin, cedar, alloy, etc.
917```
918 
919### Voice Selection Guidelines
920 
921The auto mode considers these factors:
922 
923- **Formality Level**: High (cedar, marin, sage) → Medium (alloy, verse) → Low (echo, coral, shimmer)
924- **Industry Context**: Healthcare (sage, shimmer), Finance (cedar, sage), Retail (coral, echo), Tech (alloy, ash)
925- **Goal Type**: Authority needed (cedar, sage), Friendliness (coral, shimmer), Efficiency (marin, alloy)
926- **Language**: Voices adapt to detected language from your call brief
927 
928### MCP Integration
929 
930The MCP tools strongly recommend auto mode but support manual override:
931 
932```typescript
933// Simple call - auto voice selection
934mcp__callcenter_js__simple_call({
935  phone_number: "+1234567890",
936  brief: "Call restaurant for reservation",
937  caller_name: "John",
938  voice: "auto"  // Optional, defaults to auto
939})
940 
941// Advanced call - manual voice selection
942mcp__callcenter_js__advanced_call({
943  phone_number: "+1234567890",
944  goal: "Schedule medical appointment",
945  user_name: "Jane",
946  voice: "sage"  // Override for specific voice
947})
948```
949 
950## 🔄 Advanced Features
951 
952### Smart Connection Management
953 
954- **Automatic Reconnection**: Exponential backoff with provider-specific error handling
955- **Transport Fallback**: UDP → TCP → TLS based on what works
956- **Provider-Aware Error Recovery**: Different strategies for Fritz Box vs. Asterisk vs. Cisco
957- **Network Change Handling**: Adapts to network connectivity changes
958 
959### Enhanced SIP Protocol Support
960 
961- **STUN/TURN Integration**: NAT traversal for cloud and enterprise deployments
962- **Session Timers (RFC 4028)**: Connection stability for long calls
963- **PRACK Support (RFC 3262)**: Reliable provisional responses for enterprise systems
964- **Multiple Transports**: UDP, TCP, TLS with intelligent fallback
965 
966### Configuration Intelligence
967 
968- **Provider Auto-Detection**: Identifies provider from SIP domain/IP
969- **Requirements Validation**: Ensures all provider-specific needs are met  
970- **Network Testing**: Real connectivity tests to SIP servers and STUN servers
971- **Optimization Suggestions**: Actionable recommendations for better performance
972 
973## 🛠️ Development & Testing
974 
975### Build Commands
976 
977```bash
978# Default build (WASM refresh + TypeScript, skips if artifacts already exist)
979npm run build
980 
981# Build components separately (useful for maintainers)  
982npm run build:wasm     # Regenerate the G.722 WebAssembly codec
983npm run build:native   # Rebuild the native addon (requires toolchain)
984npm run build:all      # Run native + WASM + TypeScript in one go
985npm run build:ts       # TypeScript compilation only
986 
987# Development with hot reload
988npm run dev
989 
990# Clean all build artifacts
991npm run clean
992```
993 
994### Configuration Testing
995 
996```bash
997# Validate any config file
998npm run validate path/to/config.json
999 
1000# Test with different providers
1001npm run validate -- --provider asterisk config.json
1002 
1003# Get detailed network diagnostics
1004npm run validate -- --detailed --network config.json
1005 
1006# Show fix suggestions for issues
1007npm run validate -- --fix-suggestions config.json
1008```
1009 
1010### Project Structure
1011 
1012```
1013src/
1014├── voice-agent.ts          # Main orchestration with ConnectionManager
1015├── connection-manager.ts   # Smart connection handling & reconnection
1016├── sip-client.ts          # Enhanced SIP protocol with provider support
1017├── audio-bridge.ts        # RTP streaming and codec management
1018├── openai-client.ts       # OpenAI Real-Time Voice API integration
1019├── call-brief-processor.ts # o3-mini model call brief processing
1020├── mcp-server.ts          # MCP (Model Context Protocol) server
1021├── validation.ts          # Configuration validation engine
1022├── config.ts             # Enhanced config loading with provider profiles
1023├── logger.ts             # Comprehensive logging with transcript capture
1024├── index.ts              # Main programmatic API exports
1025├── providers/
1026│   └── profiles.ts       # Provider-specific configuration database
1027├── testing/
1028│   └── network-tester.ts # Real network connectivity testing
1029├── codecs/               # Codec abstraction layer
1030│   ├── g722.ts          # G.722 wideband implementation
1031│   └── g711.ts          # G.711 fallback codecs
1032└── cli.ts               # Command-line interface
1033 
1034scripts/
1035└── validate-config.js   # Comprehensive validation CLI tool
1036 
1037config.*.example.json    # Provider-specific example configurations
1038```
1039 
1040## 📊 Validation & Diagnostics
1041 
1042The built-in validation system provides comprehensive analysis:
1043 
1044### Configuration Report Example
1045 
1046```
1047🔍 CallCenter.js Configuration Validator
1048 
1049📋 Provider: AVM Fritz!Box (auto-detected)
1050🎯 Provider Compatibility Score: 100%
1051 
1052✅ Configuration is valid and ready for use!
1053 
1054🌐 Network Connectivity:
1055   ✅ SIP Server: Reachable (12ms latency)
1056   ✅ G.722 codec: Available for high-quality audio
1057 
1058💡 Optimization Suggestions:
1059   💡 G.722 wideband codec available (already enabled)
1060   💡 Excellent latency - local network performance optimal
1061 
1062🚀 Next steps: npm start call "<number>"
1063```
1064 
1065### Network Diagnostics
1066 
1067- **Real SIP Server Testing**: Actual UDP/TCP connectivity tests
1068- **STUN Server Validation**: Tests NAT traversal capability
1069- **Latency Measurement**: Network performance assessment
1070- **Provider-Specific Recommendations**: Tailored advice based on detected issues
1071 
1072## 🔧 Troubleshooting
1073 
1074### Configuration Issues
1075 
10761. **Run validation first**:
1077   ```bash
1078   npm run validate:detailed
1079   ```
1080 
10812. **Check provider compatibility**:
1082   ```bash
1083   npm run validate -- --provider fritz-box config.json
1084   ```
1085 
10863. **Get specific fix suggestions**:
1087   ```bash
1088   npm run validate:fix
1089   ```
1090 
1091### Network Connectivity
1092 
1093- **Fritz Box**: Usually works with UDP on local network
1094- **Cloud/Enterprise**: May need STUN servers for NAT traversal
1095- **Firewall Issues**: Ensure SIP port (5060) and RTP ports are open
1096 
1097### Audio Quality
1098 
10991. **Verify G.722 is available**:
1100   ```bash
1101   npm run test:codecs
1102   ```
1103 
11042. **Check codec negotiation in logs**:
1105   ```
1106   ✅ Selected codec: PT 9 (G722/8000)
1107   ```
1108 
11093. **Network issues**: High latency/packet loss affects audio quality
1110 
1111### Build Problems
1112 
11131. **Native compilation fails** (only happens if you explicitly ran `npm run build:native` or `npm run build:all`): stick with the bundled WASM codec unless you specifically need native performance. To drop back to G.711 entirely, run:
1114   ```bash
1115   npm run build:no-g722
1116   ```
1117 
11182. **Provider-specific issues**: Check validation recommendations for your provider
1119 
1120### MCP Integration Issues
1121 
11221. **Server won't start**:
1123   ```bash
1124   # Check for port conflicts or config issues
1125   npm start --mcp
1126   ```
1127 
11282. **Claude Code not connecting**:
1129   - Verify MCP server configuration in Claude Code settings
1130   - Check that the working directory path is correct
1131   - Ensure the server is running and accessible
1132 
1133## 📈 What I Built
1134 
1135This is a personal project that includes:
1136 
1137- **🌐 Fritz!Box Support**: Actually tested and works
1138- **🤷 Other SIP Configs**: Vibe-coded based on documentation reading
1139- **🔄 Connection Handling**: Seems to work, has retry logic
1140- **✅ Config Validation**: Catches obvious mistakes
1141- **📊 Network Testing**: Basic connectivity checks
1142- **🎯 Provider Profiles**: Research-based guesses about different systems
1143- **🔌 MCP Server**: Works with Claude Code (tested)
1144- **📚 TypeScript API**: Clean interfaces for programmatic use
1145- **📝 Call Brief Processing**: Uses o3-mini to generate instructions (works well)
1146- **🎵 Optional Call Recording**: Stereo WAV files with left/right channels
1147- **📋 Transcript Capture**: Real-time conversation logs
1148 
1149## ⚠️ Important Disclaimer
1150 
1151**This project is vibe-coded!** 🚀 
1152 
1153This means:
1154- ✅ **Works on Fritz!Box** - that's what I actually tested
1155- 🤷 **Other providers** - I tried to make it more useful but can't promise anything
1156- 🤷 **Advanced features** - seemed like good ideas based on research, but who knows
1157- ⚠️ **YMMV** - your setup is probably different than mine
1158- ⚠️ **No warranties** - use at your own risk
1159 
1160### What This Means for You
1161 
1162- **Fritz Box users**: Should work great! ✅
1163- **Other providers**: The configuration profiles are educated guesses based on research - they might work, they might not
1164- **Enterprise users**: I tried to add the features that seemed important, but I have no idea if they actually work correctly
1165- **Issues & PRs**: I'll accept pull requests, but I can't promise to fix issues I can't reproduce or test
1166 
1167### If You Want to Contribute
1168 
1169- ✅ **Test it on your setup** and let others know what works
1170- ✅ **Share working configs** if you get something else working
1171- ✅ **Fix stuff that's broken** and submit PRs
1172- ✅ **Tell me if my assumptions were wrong** about how providers work
1173 
1174The validation tools might help debug issues, but honestly, the real test is whether you can make actual calls.
1175 
1176## 📜 License
1177 
1178MIT License - see [LICENSE](LICENSE) for details.
1179 
1180### Third-Party Components
1181 
1182- **G.722 Codec**: Public domain and BSD licensed implementations
1183- **SIP Protocol**: Based on sipjs-udp (MIT licensed)
1184- **Dependencies**: Various open source licenses (see package.json)
1185 
1186## 🤝 Contributing
1187 
11881. Fork the repository
11892. Create a feature branch  
11903. Add/update validation for new providers
11914. Test with `npm run validate:detailed`
11925. Submit a pull request
1193 
1194## 📞 Support
1195 
1196- **Configuration Issues**: Use `npm run validate:detailed` for diagnostics
1197- **Provider Support**: Check compatibility matrix above
1198- **Build Problems**: See troubleshooting section
1199- **Feature Requests**: You can open GitHub issues, but they're unlikely to get attention anytime soon. Pull requests are much preferred!
1200 
1201---
1202 
1203**Ready to get started?** Copy an example config, run `npm run validate:detailed`, and start making AI-powered voice calls! 🚀
1204