MCP S2s Asterisk

🚀 🌟 Asterisk S2S MCP 服務器

Asterisk S2S MCP 服務器藉助語音到語音（S2S）技術，利用 Asterisk 實現自動對話式電話呼叫，讓電話溝通變得像輸入提示一樣簡單！

🚀 快速開始

本項目可通過 NPX 或全局安裝的方式進行部署，以下為具體操作步驟。

🎯 方式一：NPX（推薦）

# 一鍵部署，快速開啟！🚀
npx @grec0/mcp-s2s-asterisk@latest

🔧 方式二：全局安裝

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

✨ 主要特性

• 系統架構清晰：涵蓋 MCP 客戶端、MCP 服務器、後端服務及監控等模塊，各部分協同工作，確保系統穩定運行。
• 電話流程自動化：從用戶發起呼叫請求到通話結束，整個流程自動化處理，提高通話效率。
• 豐富的 MCP 組件：提供多種核心工具、監控功能及歷史記錄查詢功能，滿足不同場景需求。
• 多場景應用：適用於自動化提醒、客戶支持及銷售等多個領域，具有廣泛的應用前景。
• 詳細的監控與日誌：提供健康檢查、指標監控、日誌記錄及通話歷史查詢等功能，方便系統管理與維護。

📦 安裝指南

📋 本地開發要求

• 🟢 Node.js >= 18.0.0
• 📦 npm 或 pnpm
• 🔧 TypeScript

🛠️ 快速設置

# 📥 克隆倉庫
git clone <repository-url>
cd mcp-s2s-asterisk

# 📦 安裝依賴
npm install

# 🔨 構建項目
npm run build

# 🚀 啟動服務器
npm run start

📋 可用腳本

💻 使用示例

🎬 場景：醫療預約確認

// 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[預約提醒] 
        B[預訂確認]
        C[自動調查]
    end
    
    subgraph "支持"
        D[客戶服務]
        E[工單跟進]
        F[數據驗證]
    end
    
    subgraph "銷售"
        G[自動潛在客戶開發]
        H[潛在客戶跟進]
        I[客戶資格審查]
    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 : 實時語音到語音
    note right of Completed : 結果處理並保存

🚦 監控儀表盤

pie title 按狀態劃分的呼叫分佈
    "已完成" : 65
    "進行中" : 15
    "失敗" : 12
    "已取消" : 8

xychart-beta
    title "每日呼叫量（上週）"
    x軸 [週一, 週二, 週三, 週四, 週五, 週六, 週日]
    y軸 "呼叫數量" 0 --> 50
    柱狀圖 [23, 34, 28, 41, 38, 15, 8]

📊 性能指標

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：符合隱私法規要求。

🔧 技術細節

本項目基於 Node.js 和 TypeScript 構建，利用 Asterisk 實現電話呼叫功能，結合語音到語音（S2S）API 實現實時對話。系統架構設計合理，各模塊之間通過 API 進行交互，確保系統的可擴展性和穩定性。同時，提供了詳細的監控和日誌功能，方便系統管理員進行管理和維護。

📄 許可證

本項目採用 MIT 許可證，你可以自由使用、修改和分發。