Voice Assistant MCP Server

音声アシスタント MCP サーバー

Twilio Voice、Deepgram AI、OpenAIを統合し、インテリジェントな音声ベースの人事自動化ツールを作成する、強力なModel Context Protocol（MCP）サーバーです。このシステムを使うと、Claude などの AI アシスタントが、自然な音声会話を通じて電話面接を実施したり、通知を送信したり、人事関連の連絡を管理したりできます。

デモ動画

https://github.com/user-attachments/assets/6c47a8b7-7428-4711-bf26-00d5951ec66f

機能

主な機能

• AI を活用した音声面接：AI を使って候補者と電話でプロフェッショナルな面接を実施します
• 面接結果の通知：候補者に電話で面接結果とフィードバックを自動的に伝えます
• 求人情報の案内：新しいポジションについて、候補者候補者に連絡します
• リアルタイム音声処理：Deepgram の Voice Agent API を活用します
• MCP 統合：Claude やその他の MCP 対応 AI アシスタントとシームレスに統合します

技術的な機能

• WebSocket ベースのメディアストリーミング：Twilio Media Streams によるリアルタイム音声処理
• 動的なプロンプト挿入：通話の目的に応じたコンテキスト付き AI プロンプト
• 関数呼び出しの処理：通話管理のための高度な AI 関数呼び出し
• 包括的なログ記録：デバッグと監視のための詳細なログ記録
• 環境設定：認証情報を安全に管理します

アーキテクチャ

sequenceDiagram
    participant Claude as MCP Client(Claude App)
    participant MCP as MCP Server
    participant Twilio as Twilio Voice
    participant Deepgram as Deepgram
    participant AI as OpenAI

    %% Step 1: Initiate interaction
    Claude->>MCP: Initiate voice action (e.g., interview, notification)
    MCP->>Twilio: Setup voice call
    Twilio-->>MCP: Call status updates

    %% Step 2: Real-time audio processing
    Twilio->>Deepgram: Start audio stream
    Deepgram-->>AI: Transcribed text
    AI->>Deepgram: LLM response
    Deepgram->>Twilio: Stream audio

前提条件

プロジェクトをセットアップする前に、以下をご用意ください。

1. Node.js（v22 以降）
2. Twilio アカウント：
   • Account SID
   • Auth Token
   • 電話番号（発信通話用）
3. Deepgram アカウントと API Key
4. Webhook 用のパブリック URL（ngrok または本番サーバー）

インストール

1. リポジトリをクローンします。

   git clone https://github.com/prakharbhardwaj/voice-agent-mcp-server.git
   cd voice-agent-mcp-server
   

2. 依存関係をインストールします。

   npm install
   

3. 環境を設定します。 ルートディレクトリに .env ファイルを作成します。

   # Server Configuration
   PORT=3000
   SERVER_URL=your_ngrok_url_or_server_url
   
   # Twilio Credentials
   TWILIO_ACCOUNT_SID=your_twilio_account_sid
   TWILIO_AUTH_TOKEN=your_twilio_auth_token
   TWILIO_PHONE_NUMBER=+your_twilio_phone_number
   
   # Deepgram API Key
   DEEPGRAM_API_KEY=your_deepgram_api_key
   

4. MCP サーバーを設定します。 mcp-config.json を更新して、実際のパスと認証情報を設定します。

   {
     "mcpServers": {
       "voice-agent-mcp-server": {
         "type": "stdio",
         "command": "node",
         "args": ["/path/to/your/voice-agent-mcp-server/mcp-server.js"],
         "env": {
           "NODE_ENV": "production",
           "SERVER_URL": "your_ngrok_url_or_server_url",
           "TWILIO_ACCOUNT_SID": "your_twilio_account_sid",
           "TWILIO_AUTH_TOKEN": "your_twilio_auth_token",
           "TWILIO_PHONE_NUMBER": "+your_twilio_phone_number"
         }
       }
     }
   }
   

使い方

Web サーバーを起動する

npm run dev

Claude Desktop で使用する

1. MCP サーバーの設定を Claude Desktop の設定に追加します。
   • macOS の場合：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows の場合：%APPDATA%\Claude\claude_desktop_config.json
2. Claude Desktop を再起動します
3. Claude との会話で利用可能なツールを使用します

利用可能な MCP ツール

1. conduct_interview

候補者とのプロフェッショナルな面接を実施するため、音声通話を開始します。

パラメーター：

• candidatePhone（string）：E.164 形式の電話番号
• candidateName（string）：候補者の名前
• position（string）：応募しているポジション
• interviewQuestions（array）：質問の一覧

例：

Conduct an interview with John Doe at +1234567890 for the Software Engineer position.
Ask about their experience with React, their problem-solving approach, and their career goals.

2. notify_interview_result

候補者に電話をかけ、面接結果を伝えます。

パラメーター：

• candidatePhone（string）：E.164 形式の電話番号
• candidateName（string）：候補者の名前
• position（string）：面接を受けたポジション
• result（enum）："accepted"、"rejected"、または "next_round"
• message（string）：追加のフィードバックメッセージ

例：

Call Jane Smith at +1234567890 to let her know she's been accepted for the Product Manager role.

3. discuss_job_opening

求人の機会について、候補者候補者に連絡します。

パラメーター：

• candidatePhone（string）：E.164 形式の電話番号
• candidateName（string）：候補者候補者の名前
• position（string）：案内する求人ポジション
• companyInfo（string）：会社と職務についての簡単な情報
• nextSteps（string）：興味がある場合の次のステップ

4. get_call_status

進行中の音声通話のステータスとシステムの稼働状況を取得します。

5. check_twilio_config

Twilio の設定とサービスの準備状況を確認します。

プロジェクト構成

├── index.js                   # Main Fastify server
├── mcp-server.js              # MCP server implementation
├── mcp-config.json            # MCP configuration
├── package.json               # Dependencies and scripts
└── src/
    ├── SettingsConfiguration.js   # Deepgram agent settings
    ├── config/
    │   └── dotenv.js              # Environment configuration
    ├── mcp/
    │   ├── logger.js              # Logging utilities
    │   ├── prompts.js             # AI prompt generators
    │   ├── server.js              # MCP server logic
    │   └── tools.js               # MCP tool definitions
    ├── routes/
    │   └── twilioRoute.js         # Twilio webhook handlers
    ├── services/
    │   ├── functionCallHandler.js # AI function call processing
    │   └── twilioService.js       # Twilio API wrapper
    └── websockets/
        └── mediaStreamHandler.js  # WebSocket media processing

設定の詳細

Deepgram エージェントの設定

このシステムでは、Deepgram の Voice Agent を次のように使用します。

• 音声認識：Nova-3 モデル
• テキスト読み上げ：Aura-2 Asteria 音声
• LLM 統合：OpenAI GPT-4o-mini
• 音声フォーマット：8kHz の μ-law エンコーディング（Twilio 対応）

Twilio の統合

• メディアストリーム：WebSocket 経由のリアルタイム音声ストリーミング
• TwiML：カスタムパラメーターを使用した動的な通話ルーティング
• 通話管理：ステータスの追跡と通話の制御

トラブルシューティング

よくある問題

1. Twilio の webhook が通話を受信しない：

   • SERVER_URL が公開アクセス可能であることを確認します
   • ngrok が実行中で、URL が更新されていることを確認します
   • TwiML の設定を確認します

2. Deepgram の接続に関する問題：

   • DEEPGRAM_API_KEY が有効であることを確認します
   • WebSocket の接続を確認します
   • 音声フォーマットの互換性を確認します

3. Claude で MCP サーバーが読み込まれない：

   • mcp-config.json のパスが絶対パスであることを確認します
   • すべての環境変数が設定されていることを確認します
   • 設定を変更した後、Claude Desktop を再起動します

デバッグ

コンソール出力と src/mcp/mcp-server.log ファイルを確認して、詳細なログを有効にします。

開発

開発モードでの実行

# Start web server with auto-reload
npm run dev

新しいツールの追加

1. src/mcp/tools.js でツールを定義します
2. src/mcp/prompts.js にプロンプト生成ロジックを追加します
3. src/mcp/server.js にツールハンドラーを実装します

セキュリティに関する考慮事項

• すべての認証情報を環境変数に保存します
• 本番環境では HTTPS/WSS を使用します
• 電話番号と入力データを検証します
• 本番環境で使用する場合はレート制限を実装します
• Twilio のセキュリティに関するベストプラクティスに従います

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. 該当する場合はテストを追加します
5. プルリクエストを送信します

既知の問題

Claude Desktop との ES モジュールの互換性

この MCP サーバーを Claude Desktop で使用する際に SyntaxError: Unexpected identifier が発生する場合、これは Claude Desktop がターミナルと同じ PATH 環境や作業ディレクトリのコンテキストにアクセスできないことが原因です。

根本原因：Claude Desktop が、ターミナルで使用しているものと同じ Node.js バイナリを見つけられない場合（特に nvm を使用している場合）や、"type": "module" を含む package.json を見つけられるプロジェクトディレクトリから実行されない場合があります。

解決策：Claude Desktop の設定で、Node.js バイナリの絶対パスを使用します。

{
  "mcpServers": {
    "voice-agent-mcp-server": {
      "type": "stdio",
      "command": "/Users/yourusername/.nvm/versions/node/v22.16.0/bin/node",
      "args": ["/path/to/your/project/mcp-server.js"],
      "env": {
        // ... your environment variables
      }
    }
  }
}

重要なポイント：

• Node.js バイナリには絶対パスを使用します（which node で確認できます）
• Node.js が package.json を見つけられるように、cwd をプロジェクトディレクトリに設定します
• これにより、Claude Desktop が正しい Node.js とプロジェクトのコンテキストを使用できます

関連する問題：MCP Servers Issue #64

サポート

問題や質問がある場合：

1. トラブルシューティングのセクションを確認します
2. src/mcp/mcp-server.log のログを確認します
3. リポジトリで issue を作成します

---

Twilio、Deepgram、Model Context Protocol を使用して構築