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 许可证，你可以自由使用、修改和分发。