MCP S2s Asterisk

🚀 🌟 Asterisk S2S MCP Server

このプロジェクトは、Asteriskを使用した自動音声通話用のMCPサーバーで、音声対話をプロンプトのように簡単に行えるようにします。📞✨

🚀 クイックスタート

このサーバーを使用することで、自動化された通話を簡単に実現できます。以下のセクションで、インストール方法や使用例、システムアーキテクチャなどを説明します。

✨ 主な機能

• 自動化された通話をサポートし、予約確認や調査などの様々なシナリオで利用できます。
• リアルタイムの音声対話を実現し、通話中の情報をリアルタイムに処理します。
• 通話の監視やログの取得、通話状態の管理が可能です。

📦 インストール

🎯 オプション1: NPX（推奨）

# 1つのコマンドですぐに使えます！ 🚀
npx @grec0/mcp-s2s-asterisk@latest

🔧 オプション2: グローバルインストール

npm install -g @grec0/mcp-s2s-asterisk
mcp-s2s-asterisk

💻 使用例

🎬 シナリオ: 医療予約の確認

// 1️⃣ ユーザーがClaudeに指示する:
"Call María González at 555-0123 to confirm her appointment tomorrow at 3pm"

// 2️⃣ Claudeが自動的に以下を使用する:
phone_make_call({
  usuario: "María González",
  telefono: "555-0123", 
  proposito: "Confirm medical appointment for tomorrow 3pm",
  timeout: 60
})

// 3️⃣ 自動的な結果:
"✅ Call completed. María confirmed her appointment for tomorrow at 3pm. 
She also asked to change the time to 2:30pm if possible."

📚 ドキュメント

🏗️ システムアーキテクチャ

graph TB
    subgraph "MCP Client"
        A[Claude Desktop] --> B[MCP Client]
    end
    
    subgraph "MCP Server"
        B --> C[Asterisk S2S MCP]
        C --> D[Phone Tools]
        C --> E[Real-time Assistant]
    end
    
    subgraph "Backend Services"
        D --> F[Asterisk Server]
        E --> G[Speech-to-Speech API]
        F --> H[Phone Network]
    end
    
    subgraph "Monitoring"
        C --> I[Health Check]
        C --> J[Metrics & Logs]
        C --> K[Call History]
    end
    
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style F fill:#fff3e0
    style G fill:#e8f5e8

📞 通話フロー

sequenceDiagram
    participant U as User
    participant C as Claude/MCP
    participant S as MCP Server
    participant A as Asterisk API
    participant P as Phone
    
    U->>C: "Call John to remind about appointment"
    C->>S: phone_make_call()
    S->>A: POST /make-call
    A->>P: Initiate call
    P-->>A: Connection established
    A-->>S: CallID + Status
    S-->>C: Call initiated ✅
    C-->>U: "📞 Call started with John"
    
    Note over A,P: Real-time S2S conversation
    
    A->>S: Callback with result
    S->>S: Process transcript
    U->>C: "How did the call go?"
    C->>S: phone_get_last_result()
    S-->>C: Detailed result
    C-->>U: "✅ John confirmed the appointment"

🛠️ MCPコンポーネント

mindmap
  root((Asterisk S2S MCP))
    Core Tools
      phone_make_call
      phone_get_status
      phone_cancel_call
    Monitoring
      phone_health_check
      phone_get_metrics
      phone_get_logs
    History
      phone_get_conversation_history
      phone_get_active_calls
      phone_get_last_result
    Configuration
      Environment Variables
      MCP Client Config
      Asterisk Integration

⚙️ ステップバイステップの設定

🔐 環境変数

# 🌐 Asterisk API URL
export PHONE_API_URL="http://192.168.4.44:8000"

# 🔑 認証キー
export PHONE_API_KEY="api-key"

# 🔄 結果のコールバックURL
export MCP_CALLBACK_URL="http://localhost:3000"

📱 MCPクライアント設定

{
  "mcpServers": {
    "asterisk-s2s": {
      "command": "npx",
      "args": ["@grec0/mcp-s2s-asterisk@latest"],
      "env": {
        "PHONE_API_URL": "http://192.168.4.44:8000",
        "PHONE_API_KEY": "api-key",
        "MCP_CALLBACK_URL": "http://localhost:3000"
      }
    }
  }
}

🧰 利用可能なツール

💡 ユースケース

graph LR
    subgraph "自動化"
        A[予約<br/>リマインダー] 
        B[予約<br/>確認]
        C[自動化<br/>調査]
    end
    
    subgraph "サポート"
        D[顧客<br/>サービス]
        E[チケット<br/>フォローアップ]
        F[データ<br/>検証]
    end
    
    subgraph "販売"
        G[自動化<br/>見込み客開拓]
        H[リード<br/>フォローアップ]
        I[顧客<br/>資格審査]
    end
    
    style A fill:#ffcdd2
    style B fill:#f8bbd9
    style C fill:#e1bee7
    style D fill:#c5cae9
    style E fill:#bbdefb
    style F fill:#b3e5fc
    style G fill:#b2dfdb
    style H fill:#c8e6c9
    style I fill:#dcedc8

🔄 通話状態

stateDiagram-v2
    [*] --> Starting
    Starting --> Connecting: API Request
    Connecting --> Speaking: Connection OK
    Connecting --> Failed: No answer
    Speaking --> Completed: Conversation OK
    Speaking --> Cancelled: User Cancel
    Completed --> [*]
    Failed --> [*]
    Cancelled --> [*]
    
    note right of Speaking : リアルタイム<br/>音声対話
    note right of Completed : 結果が処理され<br/>保存されます

🚦 監視ダッシュボード

pie title 通話状態別の分布
    "完了" : 65
    "進行中" : 15
    "失敗" : 12
    "キャンセル" : 8

xychart-beta
    title "過去1週間の日別通話数"
    x軸 [月, 火, 水, 木, 金, 土, 日]
    y軸 "通話数" 0 --> 50
    bar [23, 34, 28, 41, 38, 15, 8]

🔧 ローカル開発

📋 要件

• 🟢 Node.js >= 18.0.0
• 📦 npmまたはpnpm
• 🔧 TypeScript

🛠️ クイックセットアップ

# 📥 リポジトリをクローンする
git clone <repository-url>
cd mcp-s2s-asterisk

# 📦 依存関係をインストールする
npm install

# 🔨 プロジェクトをビルドする
npm run build

# 🚀 サーバーを起動する
npm run start

📋 利用可能なスクリプト

📊 パフォーマンスメトリクス

graph TB
    subgraph "応答時間"
        A[接続: ~2s]
        B[確立: ~3s] 
        C[会話: 可変]
        D[処理: ~1s]
    end
    
    subgraph "成功率"
        E[接続: 95%]
        F[完了: 87%]
        G[満足度: 92%]
    end
    
    style E fill:#c8e6c9
    style F fill:#c8e6c9
    style G fill:#c8e6c9

🔒 セキュリティとコンプライアンス

• 🔐 認証: 必須のAPIキーが必要です。
• 🛡️ 暗号化: 通信中にTLS/SSLを使用しています。
• 📝 ログ: 完全な通話監査ログが保存されます。
• 🔒 プライバシー: データはローカルで処理されます。
• ✅ GDPR: プライバシーコンプライアンスを満たしています。

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。自由に使用、変更、配布することができます。