Callcenter.js MCP

🚀 CallCenter.js MCP + CLI

CallCenter.js MCP + CLIは、VoIPを利用して自動で電話をかけることができるMCPサーバー、CLIツール、およびAPIです。Claudeに目的を伝えるだけで、自動的に電話をかけ、会話を処理します。これは本質的に、OpenAIのリアルタイム音声APIとVoIP接続を橋渡しするMCPサーバーで、あなたの代わりに電話をかけることができます。

🚀 クイックスタート

オプション1: npxで即座に実行（インストール不要） ⚡

これが最速の試用方法です。

# 環境変数を設定する（または.envファイルを作成する）
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"

# GitHubから直接実行する（インストール不要！）
npx github:gerkensm/callcenter.js-mcp call "+1234567890" --brief "Call restaurant for reservation" --user-name "Your Name"

または、.envファイルを使用することもできます。

# .envファイルを作成する
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=alloy
EOF

# GitHubから実行する（自動的に.envを読み込む）
npx github:gerkensm/callcenter.js-mcp call "+1234567890" --brief "Call restaurant"

注意: 初回実行時に、C++ビルドツールがインストールされていない場合、ビルド警告が表示されることがありますが、G.711コーデックのフォールバック（標準の電話品質）で正常に動作します。より良い音質を得るには、まずビルドツールをインストールして、G.722広帯域コーデックを有効にしてください。

オプション2: ローカルインストール

前提条件

• Node.js 20+
• Python 3.x + ビルドツール（G.722広帯域音声用 - はるかに良い通話品質）
  • macOS: Xcodeコマンドラインツール (xcode-select --install)
  • Windows: Visual Studioビルドツール
  • Linux: build-essentialパッケージ
• OpenAI APIキー

注意: ビルドツールがない場合、システムは自動的にG.711（標準の電話品質）にフォールバックします。G.722は2倍の帯域幅を提供し、より明瞭で自然な会話を実現します。

インストール

# クローンしてインストールする
git clone https://github.com/gerkensm/callcenter.js-mcp
cd callcenter.js-mcp
npm install

# サンプル設定をコピーする
cp config.example.json config.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"
  }
}

✨ 主な機能

• 🎙️ 複数のコーデックサポート: G.722広帯域（16kHz）+ G.711フォールバックで、幅広い互換性を実現
• 🤖 AIによる会話処理: OpenAIのリアルタイム音声APIを使用して実際の通話を行い、o3-miniモデル（OpenAIの推論モデル）を使用して指示を生成
• 🌐 拡張SIPサポート: 一般的なSIPプロバイダーの設定（Fritz!Boxでテスト済み、その他は実験的）
• 🔧 スマートな設定: プロバイダーの要件を自動検出し、設定を最適化
• 📞 エンタープライズ対応: 高度なSIP機能（STUN/TURN、セッションタイマー、トランスポートフォールバック）をサポート
• 🔄 堅牢な接続管理: インテリジェントなエラーハンドリングで自動的に再接続
• ✅ 組み込みの検証: 包括的な設定検証とネットワークテスト
• 🎯 プロバイダープロファイル: 人気のSIPシステム用の事前設定済みの設定
• 🔌 MCPサーバー: Claude Codeや他のMCPクライアントと統合
• 📚 TypeScript API: 音声アプリケーションを構築するためのプログラムライブラリ
• 📝 通話概要処理: o3-miniモデルを使用して自然言語の通話指示を生成
• 🎵 オプションの通話録音: 通話者とAIを分離したステレオWAV録音

📦 インストール

ローカルインストール

# クローンしてインストールする
git clone https://github.com/gerkensm/callcenter.js-mcp
cd callcenter.js-mcp
npm install

# サンプル設定をコピーする
cp config.example.json config.json

💻 使用例

基本的な使用法

# npxで即座に実行する
npx github:gerkensm/callcenter.js-mcp call "+1234567890" --brief "Call restaurant for reservation" --user-name "Your Name"

高度な使用法

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

// 簡単な通話
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}`);

// エージェントインスタンスを使用した高度な使用法
const agent = await createAgent('config.json');

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

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

📚 ドキュメント

makeCall(options: CallOptions): Promise<CallResult>

AIエージェントで電話をかけます。

CallOptions

interface CallOptions {
  number: string;                    // 電話する相手の番号
  duration?: number;                 // 通話時間（秒）
  config?: string | Config;          // 設定ファイルのパスまたはオブジェクト
  instructions?: string;             // 直接的なAI指示（最優先）
  brief?: string;                    // 指示を生成するための通話概要
  userName?: string;                 // AIが通話時に使用するあなたの名前
  recording?: boolean | string;      // 録音を有効にする（オプションのファイル名）
  logLevel?: 'quiet' | 'error' | 'warn' | 'info' | 'debug' | 'verbose';
  colors?: boolean;                  // カラー出力を有効にする
  timestamps?: boolean;              // ログにタイムスタンプを付ける
}

CallResult

interface CallResult {
  callId?: string;                   // 通話が成功した場合の通話ID
  duration: number;                  // 通話時間（秒）
  transcript?: string;               // 全ての会話のトランスクリプト
  success: boolean;                  // 通話が成功したかどうか
  error?: string;                    // 通話が失敗した場合のエラーメッセージ
}

createAgent(config, options?): Promise<VoiceAgent>

高度な使用ケース用のVoiceAgentインスタンスを作成します。

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

// イベントハンドラー
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?: 'alloy' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer';
    instructions?: string;
    brief?: string;
    userName?: string;
  };
  logging?: {
    level?: string;
  };
}

環境変数

すべての設定オプションは、環境変数を介して設定することができます（npxでの使用に便利）。

必須変数:

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"                                     # --briefを使用する場合は必須

オプション変数:

# SIP設定
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設定  
OPENAI_VOICE=alloy                                        # alloy, echo, fable, onyx, nova, shimmer
OPENAI_INSTRUCTIONS="Your custom AI instructions"

# 高度なSIP機能
SESSION_TIMERS_ENABLED=true
SESSION_EXPIRES=1800
SESSION_MIN_SE=90
SESSION_REFRESHER=uac

優先順位: CLIフラグ > 設定ファイル > 環境変数

🔧 技術詳細

コーデックの優先順位とネゴシエーション

1. G.722（推奨） - 16kHz広帯域、優れた音声品質
2. G.711 μ-law（フォールバック） - 8kHz狭帯域、普遍的な互換性
3. G.711 A-law（フォールバック） - 8kHz狭帯域、ヨーロッパ標準

G.722の実装

• ネイティブC++アドオンで最適なパフォーマンスを実現
• CMUとSippy Softwareのリファレンス実装に基づく
• コンパイルが失敗した場合、自動的にG.711にフォールバック
• 低遅延でリアルタイムエンコード/デコード

オプションの通話録音

• ステレオWAV形式で、通話者を左チャンネル、AIを右チャンネルに分離
• オプションのファイル名指定
• 同期された音声ストリームで完全なアライメント
• ネイティブサンプルレートでの高品質PCM録音

音質のテスト

# コーデックの可用性をテストする
npm run test:codecs

# 必要に応じてG.722なしでビルドする
npm run build:no-g722

AI通話概要処理

なぜこれが重要か: リアルタイム音声APIにはより良い指示が必要

OpenAIのリアルタイム音声APIは速度に最適化されており、洗練された処理には向いていません。自然な会話には優れていますが、非常に具体的な指示がないと、複雑な目標指向のタスクに苦労します。問題は次のとおりです。

❌ うまくいかない例:

# 曖昧な概要 - リアルタイム音声APIが混乱し、焦点がぼやける
npm start call "+1234567890" --brief "Call the restaurant and book a table"

❌ 面倒でエラーが起こりやすい例:

# 毎回詳細な指示を手動で書く
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..."

✅ 非常にうまくいく例:

# 簡単な概要 - o3モデルが洗練された指示を生成する
npm start call "+1234567890" --brief "Call Bocca di Bacco and book a table for 2 at 7pm tonight" --user-name "John Doe"

仕組み

システムはOpenAIのo3-mini推論モデル（最新の小型推論モデル - 賢くて高速）を使用して、あなたの簡単な概要から詳細で洗練された指示を自動的に生成します。o3-miniモデルは次のように動作します。

1. あなたの概要を分析し、目標を理解する
2. 会話状態とフローロジックを作成する
3. 通話の各フェーズに対する具体的な指示を生成する
4. ボイスメール、異議申し立て、代替案などのエッジケースを処理する
5. コンテキストに基づいて言語とトーンを適応させる
6. 予定通りにいかない場合のフォールバック戦略を提供する

前後の例

あなたの簡単な入力:

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

o3-miniが生成するもの（抜粋）:

## パーソナリティとトーン
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.

## 指示
1. すぐに会話を開始する: "Hello, this is an assistant calling on behalf of John Doe."
2. 重要なデータを読み返す: 時間と詳細を確認するために繰り返す。
3. 異議申し立てを処理する: 丁寧に応答し、6-8時の間の代替時間を提案する。
...

## 会話状態
[
  {
    "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."]
  }
]

自動適応

o3-mini概要プロセッサは自動的に次のことを行います。

• あなたの概要から言語を検出し、その言語で指示を生成する
• 論理的な状態と遷移を持つ会話フローを作成する
• ドイツのレストラン、アメリカのレストラン、日本のレストランなどの文化的コンテキストを処理する
• 実際のフレーズ（プレースホルダーなし）で適切な例を生成する
• 誰も応答しない場合のボイスメールスクリプトを提供する
• 異議申し立てと代替解決策を計画する

各アプローチの使用時期

• 95%の通話で--briefを使用する - 簡単で、より良い結果が得られる
• 非常に具体的なカスタム動作が必要な場合のみ--instructionsを使用する
• 概要処理は、予約、予定、ビジネス通話、カスタマーサービスなどに最適
• 直接的な指示は、高度に特殊化されたシナリオ、テスト、またはすでにプロンプトを完成させている場合に適しています。

スマートな接続管理

• 自動再接続: プロバイダー固有のエラーハンドリングで指数関数的なバックオフ
• トランスポートフォールバック: UDP → TCP → TLSの順で動作するものを使用
• プロバイダーを意識したエラー回復: Fritz Box、Asterisk、Ciscoなどの異なるプロバイダーに対する異なる戦略
• ネットワーク変更の対応: ネットワーク接続の変更に適応

拡張SIPプロトコルサポート

• STUN/TURN統合: クラウドおよびエンタープライズデプロイメントのためのNATトラバーサル
• セッションタイマー（RFC 4028）: 長時間の通話のための接続安定性
• PRACKサポート（RFC 3262）: エンタープライズシステムのための信頼性の高い暫定応答
• 複数のトランスポート: UDP、TCP、TLSでインテリジェントなフォールバック

設定インテリジェンス

• プロバイダー自動検出: SIPドメイン/IPからプロバイダーを識別する
• 要件検証: すべてのプロバイダー固有の要件が満たされていることを確認する
• ネットワークテスト: SIPサーバーとSTUNサーバーへの実際の接続テスト
• 最適化提案: より良いパフォーマンスのための実行可能な推奨事項

📄 ライセンス

MITライセンス - 詳細はLICENSEを参照してください。

サードパーティコンポーネント

• G.722コーデック: パブリックドメインおよびBSDライセンスの実装
• SIPプロトコル: sipjs-udp（MITライセンス）に基づく
• 依存関係: 様々なオープンソースライセンス（package.jsonを参照）

⚠️ 重要提示

このプロジェクトは実験的なものです。Fritz!Boxでの動作はテスト済みですが、他のプロバイダーでの動作は保証できません。自己責任で使用してください。

💡 使用建议

95%の通話で--briefオプションを使用することをおすすめします。これにより、簡単により良い結果を得ることができます。--instructionsオプションは、非常に具体的なカスタム動作が必要な場合のみ使用してください。