JinDaGe - mcp-s2s-asterisk MCP Details

article

README

🚀 🌟 Asterisk S2S MCP Server

Asterisk S2S MCP Server 是一个用于自动语音通话的 MCP 服务器，借助 Asterisk 实现语音到语音的交互，让电话沟通变得像输入提示一样简单！ 📞✨

🚀 快速开始

本项目支持两种安装方式，推荐使用 NPX 方式进行快速安装。

🎯 方式一：NPX（推荐）

# 一键安装，立即使用！ 🚀
npx @grec0/mcp-s2s-asterisk@latest

🔧 方式二：全局安装

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

✨ 主要特性

系统架构清晰：涵盖 MCP 客户端、MCP 服务器、后端服务和监控等多个部分，保证系统的稳定运行。
电话流程自动化：支持从用户发起通话请求到通话结束的全流程自动化处理。
丰富的工具集：提供了包括通话管理、监控、历史记录查询等多种工具。
多场景应用：适用于自动化、支持和销售等多个领域的多种场景。
状态管理完善：清晰定义了通话的各个状态，便于跟踪和管理。
性能指标透明：提供响应时间和成功率等性能指标，方便进行性能评估。
安全合规：支持 API 密钥认证、TLS/SSL 加密传输，保证数据安全和隐私。

📦 安装指南

安装前请确保满足以下要求：

🟢 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

💡 使用场景

graph LR
    subgraph "Automation"
        A[Appointment<br/>Reminders] 
        B[Booking<br/>Confirmations]
        C[Automated<br/>Surveys]
    end
    
    subgraph "Support"
        D[Customer<br/>Service]
        E[Ticket<br/>Follow-up]
        F[Data<br/>Verification]
    end
    
    subgraph "Sales"
        G[Automated<br/>Prospecting]
        H[Lead<br/>Follow-up]
        I[Customer<br/>Qualification]
    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 : Real-time<br/>Speech-to-Speech
    note right of Completed : Result processed<br/>and saved

🚦 监控仪表盘

pie title Call Distribution by Status
    "Completed" : 65
    "In Progress" : 15
    "Failed" : 12
    "Cancelled" : 8

xychart-beta
    title "Daily Calls (Last Week)"
    x-axis [Mon, Tue, Wed, Thu, Fri, Sat, Sun]
    y-axis "Number of Calls" 0 --> 50
    bar [23, 34, 28, 41, 38, 15, 8]

📋 可用脚本

| 脚本 | 描述 | 命令 | |--------|-------------|---------| | 🔨 | 编译 TypeScript | npm run build | | 👀 | 开发模式 | npm run dev | | 🧪 | 运行测试 | npm run test | | 🔍 | MCP 检查器 | npm run inspector | | 📦 | 发布补丁 | npm run release:patch |

🔧 技术细节

📈 性能指标

graph TB
    subgraph "Response Time"
        A[Connection: ~2s]
        B[Establishment: ~3s] 
        C[Conversation: Variable]
        D[Processing: ~1s]
    end
    
    subgraph "Success Rates"
        E[Connection: 95%]
        F[Completed: 87%]
        G[Satisfaction: 92%]
    end
    
    style E fill:#c8e6c9
    style F fill:#c8e6c9
    style G fill:#c8e6c9

🔒 安全与合规

🔐 认证：强制使用 API 密钥进行认证。
🛡️ 加密：传输过程中使用 TLS/SSL 加密。
📝 日志：完整记录通话审计信息。
🔒 隐私：数据在本地处理，保证隐私。
✅ GDPR：符合隐私法规要求。

📄 许可证

本项目采用 MIT 许可证，你可以自由使用、修改和分发。

🌟 贡献与反馈

如果你喜欢这个项目，欢迎贡献代码或提出反馈！

🌟 给项目一个星！ ⭐

由 @grec0 用心打造

借助对话式 AI 变革电话通信

mcp-s2s-asterisk