⏺ mcp__callcenter_js__simple_call(phone_number: "+15551234567", 
                                    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", 
                                    caller_name: "John")
  ⎿ # Simple Call Result
    
    **Status:** ✅ Success  
    **Duration:** 3 minutes 24 seconds
    **Call ID:** abc123xyz
    
    ## Call Transcript
    
    [14:23:15] 🎤 HUMAN: Tony's Pizza, how can I help you?
    [14:23:15] 🤖 ASSISTANT: Hi! I'm calling on behalf of John to place a delivery order.
    [14:23:20] 🎤 HUMAN: Sure! What would you like?
    [14:23:20] 🤖 ASSISTANT: I'd like to order one large pepperoni pizza for delivery please.
    [14:23:25] 🎤 HUMAN: Large pepperoni, got it. What's the delivery address?
    [14:23:25] 🤖 ASSISTANT: The address is 123 Main Street.
    [14:23:30] 🎤 HUMAN: And your phone number?
    [14:23:30] 🤖 ASSISTANT: The phone number is 555-0123.
    [14:23:35] 🎤 HUMAN: Perfect! That'll be $18.99. We'll have it delivered in about 30 minutes.
    [14:23:40] 🤖 ASSISTANT: That sounds great! Thank you so much.
    [14:23:42] 🎤 HUMAN: You're welcome! Have a great day.

graph TB
    subgraph "User Interface"
        A[Claude Code/MCP Client]
        B[CLI Tool]
        C[TypeScript API]
    end
    
    subgraph "CallCenter.js Core"
        D[MCP Server]
        E[VoiceAgent]
        F[Call Brief Processor<br/>o3-mini model]
    end
    
    subgraph "Communication Layer"
        G[SIP Client<br/>Provider Support]
        H[Audio Bridge<br/>RTP Streaming]
    end
    
    subgraph "Audio Processing"
        I[G.722 Codec<br/>16kHz Wideband]
        J[G.711 Codec<br/>8kHz Fallback]
    end
    
    subgraph "External Services"
        K[OpenAI Real-Time API<br/>gpt-realtime model]
        L[VoIP Network<br/>Fritz!Box/Asterisk/etc]
    end
    
    A --> D
    B --> E
    C --> E
    D --> E
    E --> F
    E --> G
    E --> H
    F --> K
    G --> L
    H --> I
    H --> J
    H --> K
    
    style F fill:#e1f5fe
    style K fill:#fff3e0
    style L fill:#f3e5f5

# Add to Claude Code with one command:
claude mcp add --env SIP_USERNAME=your_actual_extension \
  --env SIP_PASSWORD="your_actual_password" \
  --env SIP_SERVER_IP=192.168.1.1 \
  --env OPENAI_API_KEY="sk-your_actual_openai_key" \
  --env USER_NAME="Your Actual Name" \
  -- callcenter.js npx -- github:gerkensm/callcenter.js-mcp --mcp

# Set environment variables (or create .env file)
export SIP_USERNAME="your_extension"
export SIP_PASSWORD="your_password"
export SIP_SERVER_IP="192.168.1.1"
export OPENAI_API_KEY="sk-your-key-here"

# Run directly from GitHub (no installation needed!)
npx github:gerkensm/callcenter.js-mcp call "+1234567890" --brief "Call restaurant for reservation" --user-name "Your Name"

# Create .env file
cat > .env << EOF
SIP_USERNAME=your_extension
SIP_PASSWORD=your_password
SIP_SERVER_IP=192.168.1.1
OPENAI_API_KEY=sk-your-key-here
SIP_PROVIDER=fritz-box
OPENAI_VOICE=auto
EOF

# Run from GitHub (loads .env automatically)  
npx github:gerkensm/callcenter.js-mcp call "+1234567890" --brief "Call restaurant"

# Clone and install
git clone https://github.com/gerkensm/callcenter.js-mcp
cd callcenter.js-mcp
npm install

# Copy example configuration
cp config.example.json config.json

{
  "sip": {
    "username": "your_sip_username",
    "password": "your_sip_password", 
    "serverIp": "192.168.1.1",
    "serverPort": 5060,
    "provider": "fritz-box"
  },
  "ai": {
    "openaiApiKey": "sk-your-openai-api-key-here",
    "voice": "alloy",
    "instructions": "You are a helpful AI assistant making phone calls on behalf of users.",
    "userName": "Your Name"
  }
}

# Replace with your ACTUAL credentials before running:
claude mcp add --env SIP_USERNAME=your_actual_extension \
  --env SIP_PASSWORD="your_actual_password" \
  --env SIP_SERVER_IP=192.168.1.1 \
  --env OPENAI_API_KEY="sk-your_actual_openai_key" \
  --env USER_NAME="Your Actual Name" \
  -- callcenter.js npx -- github:gerkensm/callcenter.js-mcp --mcp

{
  "mcpServers": {
    "callcenter.js": {
      "command": "npx",
      "args": ["github:gerkensm/callcenter.js-mcp", "--mcp"],
      "env": {
        "SIP_USERNAME": "your_extension",
        "SIP_PASSWORD": "your_password",
        "SIP_SERVER_IP": "192.168.1.1",
        "OPENAI_API_KEY": "sk-your-key-here",
        "USER_NAME": "Your Name"
      }
    }
  }
}

npm start --mcp

{
  "mcpServers": {
    "callcenter.js": {
      "command": "node",
      "args": ["dist/cli.js", "--mcp"],
      "cwd": "/path/to/voip-agent"
    }
  }
}

You: "Can you call Bocca di Bacco restaurant and book a table for 2 people tonight at 7:30pm? My name is John Doe."

MCP Client: I'll call Bocca di Bacco restaurant to book a table for 2 people tonight at 7:30pm.

🔧 mcp__ai-voice-agent__simple_call(
  phone_number: "+1234567890",
  brief: "Call Bocca di Bacco restaurant and book a table for 2 people tonight at 7:30pm",
  caller_name: "John Doe"
)

✅ Call completed successfully! 
📞 Duration: 2 minutes 15 seconds
📝 Reservation confirmed for 2 people at 7:30pm tonight

You: "My internet is down. Can you call my ISP and get a status update? I'm Sarah Johnson, account #12345."

MCP Client: I'll call your internet service provider to check on the outage status.

🔧 mcp__ai-voice-agent__simple_call(
  phone_number: "+18005551234", 
  brief: "Call ISP about internet outage, customer Sarah Johnson account #12345",
  caller_name: "Sarah Johnson"
)

You: "Call Dr. Smith's office to reschedule my 3pm appointment to next week. I'm Mike Chen."

MCP Client: I'll call Dr. Smith's office to reschedule your appointment.

🔧 mcp__ai-voice-agent__simple_call(
  phone_number: "+15551234567",
  brief: "Call Dr. Smith's office to reschedule Mike Chen's 3pm appointment to next week", 
  caller_name: "Mike Chen"
)

# ✅ RECOMMENDED: Use brief for natural language goals
npm start call "+1234567890" --brief "Call the restaurant and book a table for 2 at 7pm tonight" --user-name "John Doe"

# ✅ RECOMMENDED: Brief works for any call type
npm start call "+1234567890" --brief "Call to check appointment availability for John Doe"

# ⚠️ ONLY use instructions for very specific, custom behavior
npm start call "+1234567890" --instructions "You must follow this exact script: Say hello, ask for manager, then hang up"

# Other examples with brief
npm start call "+1234567890" --record "meeting.wav" --duration 300 --brief "Conference call to discuss project status"
npm start call "+1234567890" --log-level verbose --brief "Test call to verify connectivity"

npm start call <number> [options]

Options:
  -c, --config <path>           Configuration file path (default: config.json)
  -d, --duration <seconds>      Maximum call duration in seconds (default: 600)
  -v, --verbose                 Verbose mode - show all debug information
  -q, --quiet                   Quiet mode - show only transcripts, errors, and warnings
  --log-level <level>           Set log level (quiet|error|warn|info|debug|verbose) (default: info)
  --no-colors                   Disable colored output
  --no-timestamp                Disable timestamps in logs
  --record [filename]           Enable stereo call recording (optional filename)
  --brief <text>                Call brief to generate instructions from (RECOMMENDED)
  --instructions <text>         Direct AI instructions (use only for specific custom behavior)
  --user-name <name>            Your name for the AI to use when calling
  --voice <name>                Voice to use (default: auto) - see Voice Selection section
  --help                        Display help information

import { makeCall, createAgent } from 'callcenter.js';

// Simple call with brief
const result = await makeCall({
  number: '+1234567890',
  brief: 'Call Bocca di Bacco and book a table for 2 at 19:30 for Torben',
  userName: 'Torben',
  config: 'config.json'
});

console.log(`Call duration: ${result.duration}s`);
console.log(`Transcript: ${result.transcript}`);

// Advanced usage with agent instance
const agent = await createAgent('config.json');

agent.on('callEnded', () => {
  console.log('Call finished!');
});

await agent.makeCall({ 
  targetNumber: '+1234567890',
  duration: 300 
});

interface CallOptions {
  number: string;                    // Phone number to call
  duration?: number;                 // Call duration in seconds
  config?: string | Config;          // Configuration file path or object
  instructions?: string;             // Direct AI instructions (highest priority)
  brief?: string;                    // Call brief to generate instructions from
  userName?: string;                 // Your name for the AI to use
  recording?: boolean | string;      // Enable recording with optional filename
  logLevel?: 'quiet' | 'error' | 'warn' | 'info' | 'debug' | 'verbose';
  colors?: boolean;                  // Enable colored output
  timestamps?: boolean;              // Enable timestamps in logs
}

interface CallResult {
  callId?: string;                   // Call ID if successful
  duration: number;                  // Call duration in seconds
  transcript?: string;               // Full conversation transcript
  success: boolean;                  // Whether call was successful
  error?: string;                    // Error message if failed
}

const agent = await createAgent('config.json', {
  enableCallRecording: true,
  recordingFilename: 'call.wav'
});

// Event handlers
agent.on('callInitiated', ({ callId, target }) => {
  console.log(`Call ${callId} started to ${target}`);
});

agent.on('callEnded', () => {
  console.log('Call ended');
});

agent.on('error', (error) => {
  console.error('Call error:', error.message);
});

interface Config {
  sip: {
    username: string;
    password: string;
    serverIp: string;
    serverPort?: number;
    provider?: string;
    stunServers?: string[];
    turnServers?: TurnServer[];
  };
  ai: {
    openaiApiKey: string;
    voice?: 'auto' | 'alloy' | 'ash' | 'ballad' | 'cedar' | 'coral' | 'echo' | 'marin' | 'sage' | 'shimmer' | 'verse';
    instructions?: string;
    brief?: string;
    userName?: string;
  };
  logging?: {
    level?: string;
  };
}

SIP_USERNAME=your_extension
SIP_PASSWORD=your_password  
SIP_SERVER_IP=192.168.1.1
OPENAI_API_KEY=sk-your-key-here
USER_NAME="Your Name"                                     # Required when using --brief

# SIP Configuration
SIP_SERVER_PORT=5060
SIP_LOCAL_PORT=5060
SIP_PROVIDER=fritz-box                                    # fritz-box, asterisk, cisco, 3cx, generic
STUN_SERVERS="stun:stun.l.google.com:19302,stun:stun2.l.google.com:19302"
SIP_TRANSPORTS="udp,tcp"

# OpenAI Configuration  
OPENAI_VOICE=auto                                        # auto (recommended), marin, cedar, alloy, echo, shimmer, coral, sage, ash, ballad, verse
OPENAI_INSTRUCTIONS="Your custom AI instructions"

# Advanced SIP Features
SESSION_TIMERS_ENABLED=true
SESSION_EXPIRES=1800
SESSION_MIN_SE=90
SESSION_REFRESHER=uac

# Basic validation - checks syntax and required fields
npm run validate config.json

# Detailed validation with network connectivity tests  
npm run validate:detailed

# Get specific fix suggestions for issues
npm run validate:fix

# Call your own extension to verify audio quality (safe test)
npm start call "**620" --brief "Test call to check audio quality" --user-name "Your Name" --duration 30

# Or use your mobile number for end-to-end test
npm start call "+49123456789" --brief "Quick test call" --user-name "Your Name" --duration 15

# Basic validation
npm run validate config.json

# Detailed validation with network connectivity tests
npm run validate:detailed

# Get specific fix suggestions for issues
npm run validate:fix

# Test example configurations for different providers
npm run validate:fritz-box       # AVM Fritz!Box
npm run validate:asterisk        # Asterisk PBX  
npm run validate:cisco           # Cisco CUCM
npm run validate:3cx             # 3CX Phone System
npm run validate:generic         # Generic SIP provider

flowchart TD
    A[Choose Your SIP Provider] --> B{Fritz!Box Router?}
    B -->|Yes| C[✅ Use fritz-box profile<br/>UDP transport<br/>No STUN needed]
    B -->|No| D{Enterprise System?}
    
    D -->|Cisco CUCM| E[⚠️ Use cisco profile<br/>TCP transport<br/>STUN required<br/>Session timers + PRACK]
    D -->|3CX| F[⚠️ Use 3cx profile<br/>TCP/UDP transport<br/>STUN recommended]
    D -->|Asterisk/FreePBX| G[⚠️ Use asterisk profile<br/>UDP/TCP transport<br/>STUN for NAT]
    D -->|Other| H[⚠️ Use generic profile<br/>Start with UDP<br/>Add STUN if needed]
    
    C --> I[Configure Basic Settings]
    E --> J[Configure Enterprise Settings]
    F --> J
    G --> J
    H --> J
    
    I --> K[Set SIP credentials<br/>serverIp = router IP<br/>typically 192.168.1.1]
    J --> L[Set SIP credentials<br/>serverIp = server IP<br/>Add STUN servers]
    
    K --> M{Network Location?}
    L --> M
    
    M -->|Local Network| N[✅ Basic setup complete<br/>Should work reliably]
    M -->|Cloud/Remote| O[❓ May need additional<br/>STUN/TURN configuration]
    
    style C fill:#c8e6c9
    style E fill:#ffecb3
    style F fill:#ffecb3
    style G fill:#ffecb3
    style H fill:#ffecb3
    style N fill:#c8e6c9
    style O fill:#ffe0b2

# Test codec availability
npm run test:codecs

# Rebuild all codec artifacts (native + WASM + TS) if you changed the C sources
npm run build:all

# Disable G.722 entirely if you only want the G.711 fallback
npm run build:no-g722

# Vague brief - Real-Time Voice API will be confused and unfocused
npm start call "+1234567890" --brief "Call the restaurant and book a table"

# Writing detailed instructions manually every time
npm 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..."

# Simple brief - o3 model generates sophisticated instructions
npm start call "+1234567890" --brief "Call Bocca di Bacco and book a table for 2 at 7pm tonight" --user-name "John Doe"

sequenceDiagram
    participant U as User/Claude
    participant V as VoiceAgent
    participant B as Brief Processor<br/>(o3-mini)
    participant S as SIP Client
    participant A as Audio Bridge
    participant O as OpenAI Realtime<br/>(gpt-realtime)
    participant P as Phone/VoIP

    U->>V: makeCall({brief, number, userName})
    V->>B: Process brief with o3-mini
    B->>B: Generate detailed instructions<br/>& conversation states
    B->>V: Sophisticated call instructions
    
    V->>S: Connect to SIP server
    S->>P: INVITE (start call)
    P->>S: 200 OK (call answered)
    S->>V: Call established
    
    V->>A: Initialize audio bridge
    V->>O: Connect to OpenAI Realtime
    O->>V: WebSocket connected
    V->>O: Send generated instructions
    
    loop During Call
        P->>A: RTP audio packets
        A->>A: Decode G.722/G.711 → PCM
        A->>O: Stream PCM audio
        O->>O: Process speech → text
        O->>O: Generate AI response
        O->>A: Stream AI audio (PCM)
        A->>A: Encode PCM → G.722/G.711
        A->>P: RTP audio packets
        
        Note over V: Monitor call progress<br/>& transcript logging
    end
    
    alt Call completed naturally
        O->>V: Call completion signal
        V->>S: Send BYE
    else Duration limit reached
        V->>V: Safety timeout triggered
        V->>S: Send BYE
    end
    
    S->>P: BYE (end call)
    P->>S: 200 OK
    V->>U: CallResult{transcript, duration, success}

"Call Bocca di Bacco and book a table for 2 at 7pm tonight"

## Personality and Tone
Identity: I am an assistant calling on behalf of John Doe to make a restaurant reservation.
Task: I am responsible for booking a table for 2 people at Bocca di Bacco today at 7:00 PM.
Tone: Professional, warm, and respectful.

## Instructions
1. Open the conversation immediately: "Hello, this is an assistant calling on behalf of John Doe."
2. Read back critical data: Repeat times and details for confirmation.
3. Handle objections: Respond politely and offer alternatives between 6-8 PM.
...

## Conversation States
[
  {
    "id": "1_greeting",
    "description": "Greeting and introduction of call purpose",
    "instructions": ["Introduce yourself as an assistant", "Immediately mention the reservation request"],
    "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."]
  }
]

# Auto mode - AI selects the best voice
npm start call "+1234567890" --brief "Call doctor's office to schedule appointment" --user-name "John"
# Might select: sage (calm, professional for healthcare)

# Auto mode adapts to context
npm start call "+1234567890" --brief "Call pizza place to order delivery" --user-name "Sarah"  
# Might select: coral or echo (friendly, casual for food service)

# Use a specific voice
npm start call "+1234567890" --voice marin --brief "Call to book reservation" --user-name "Alex"

# Professional contexts
npm start call "+1234567890" --voice cedar --brief "Call bank about account" --user-name "Pat"

# Friendly service calls
npm start call "+1234567890" --voice coral --brief "Call flower shop for delivery" --user-name "Sam"

// config.json
{
  "ai": {
    "voice": "auto",  // or specific voice like "marin", "cedar", etc.
    // ...
  }
}

# Environment variable
export OPENAI_VOICE=auto  # or marin, cedar, alloy, etc.

// Simple call - auto voice selection
mcp__callcenter_js__simple_call({
  phone_number: "+1234567890",
  brief: "Call restaurant for reservation",
  caller_name: "John",
  voice: "auto"  // Optional, defaults to auto
})

// Advanced call - manual voice selection
mcp__callcenter_js__advanced_call({
  phone_number: "+1234567890",
  goal: "Schedule medical appointment",
  user_name: "Jane",
  voice: "sage"  // Override for specific voice
})

# Default build (WASM refresh + TypeScript, skips if artifacts already exist)
npm run build

# Build components separately (useful for maintainers)  
npm run build:wasm     # Regenerate the G.722 WebAssembly codec
npm run build:native   # Rebuild the native addon (requires toolchain)
npm run build:all      # Run native + WASM + TypeScript in one go
npm run build:ts       # TypeScript compilation only

# Development with hot reload
npm run dev

# Clean all build artifacts
npm run clean

# Validate any config file
npm run validate path/to/config.json

# Test with different providers
npm run validate -- --provider asterisk config.json

# Get detailed network diagnostics
npm run validate -- --detailed --network config.json

# Show fix suggestions for issues
npm run validate -- --fix-suggestions config.json

src/
├── voice-agent.ts          # Main orchestration with ConnectionManager
├── connection-manager.ts   # Smart connection handling & reconnection
├── sip-client.ts          # Enhanced SIP protocol with provider support
├── audio-bridge.ts        # RTP streaming and codec management
├── openai-client.ts       # OpenAI Real-Time Voice API integration
├── call-brief-processor.ts # o3-mini model call brief processing
├── mcp-server.ts          # MCP (Model Context Protocol) server
├── validation.ts          # Configuration validation engine
├── config.ts             # Enhanced config loading with provider profiles
├── logger.ts             # Comprehensive logging with transcript capture
├── index.ts              # Main programmatic API exports
├── providers/
│   └── profiles.ts       # Provider-specific configuration database
├── testing/
│   └── network-tester.ts # Real network connectivity testing
├── codecs/               # Codec abstraction layer
│   ├── g722.ts          # G.722 wideband implementation
│   └── g711.ts          # G.711 fallback codecs
└── cli.ts               # Command-line interface

scripts/
└── validate-config.js   # Comprehensive validation CLI tool

config.*.example.json    # Provider-specific example configurations

🔍 CallCenter.js Configuration Validator

📋 Provider: AVM Fritz!Box (auto-detected)
🎯 Provider Compatibility Score: 100%

✅ Configuration is valid and ready for use!

🌐 Network Connectivity:
   ✅ SIP Server: Reachable (12ms latency)
   ✅ G.722 codec: Available for high-quality audio

💡 Optimization Suggestions:
   💡 G.722 wideband codec available (already enabled)
   💡 Excellent latency - local network performance optimal

🚀 Next steps: npm start call "<number>"