README.md•8.49 kB
# 🌟 Asterisk S2S MCP Server
<div align="center">
**🚀 MCP Server for automated conversational phone calls using Asterisk with Speech-to-Speech**
*Make phone conversations as easy as a prompt!* 📞✨
</div>
---
## 🏗️ System Architecture
```mermaid
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
```
---
## 📞 Phone Call Flow
```mermaid
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 Components
```mermaid
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
```
---
## 🚀 Installation & Usage
### 🎯 Option 1: NPX (Recommended)
```bash
# One command and you're ready! 🚀
npx @grec0/mcp-s2s-asterisk@latest
```
### 🔧 Option 2: Global Installation
```bash
npm install -g @grec0/mcp-s2s-asterisk
mcp-s2s-asterisk
```
---
## ⚙️ Step-by-Step Configuration
```mermaid
flowchart LR
A[1. Install MCP] --> B[2. Configure Variables]
B --> C[3. Configure MCP Client]
C --> D[4. Ready to use! 🎉]
style A fill:#ffcdd2
style B fill:#fff3e0
style C fill:#e8f5e8
style D fill:#e1f5fe
```
### 🔐 Environment Variables
```bash
# 🌐 Asterisk API URL
export PHONE_API_URL="http://192.168.4.44:8000"
# 🔑 Authentication key
export PHONE_API_KEY="api-key"
# 🔄 Callback URL for results
export MCP_CALLBACK_URL="http://localhost:3000"
```
### 📱 MCP Client Configuration
```json
{
"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"
}
}
}
}
```
---
## 🧰 Available Tools
<table>
<tr>
<td width="50%">
### 📞 **Calls**
- 🔥 `phone_make_call` - Make phone calls
- 📊 `phone_get_status` - Get call status
- ❌ `phone_cancel_call` - Cancel calls
- 📱 `phone_get_active_calls` - Active calls
</td>
<td width="50%">
### 📈 **Monitoring**
- ❤️ `phone_health_check` - System health
- 📊 `phone_get_metrics` - Advanced metrics
- 📝 `phone_get_logs` - Detailed logs
- 🗂️ `phone_get_conversation_history` - History
</td>
</tr>
</table>
---
## 💡 Use Cases
```mermaid
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
```
---
## 🔄 Call States
```mermaid
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
```
---
## 📖 Complete Usage Example
### 🎬 Scenario: Medical Appointment Confirmation
```typescript
// 1️⃣ User tells Claude:
"Call María González at 555-0123 to confirm her appointment tomorrow at 3pm"
// 2️⃣ Claude automatically uses:
phone_make_call({
usuario: "María González",
telefono: "555-0123",
proposito: "Confirm medical appointment for tomorrow 3pm",
timeout: 60
})
// 3️⃣ Automatic result:
"✅ Call completed. María confirmed her appointment for tomorrow at 3pm.
She also asked to change the time to 2:30pm if possible."
```
---
## 🚦 Monitoring Dashboard
```mermaid
pie title Call Distribution by Status
"Completed" : 65
"In Progress" : 15
"Failed" : 12
"Cancelled" : 8
```
```mermaid
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]
```
---
## 🔧 Local Development
### 📋 Requirements
- 🟢 Node.js >= 18.0.0
- 📦 npm or pnpm
- 🔧 TypeScript
### 🛠️ Quick Setup
```bash
# 📥 Clone repository
git clone <repository-url>
cd mcp-s2s-asterisk
# 📦 Install dependencies
npm install
# 🔨 Build project
npm run build
# 🚀 Run server
npm run start
```
### 📋 Available Scripts
| Script | Description | Command |
|--------|-------------|---------|
| 🔨 | Compile TypeScript | `npm run build` |
| 👀 | Development mode | `npm run dev` |
| 🧪 | Run tests | `npm run test` |
| 🔍 | MCP Inspector | `npm run inspector` |
| 📦 | Release patch | `npm run release:patch` |
---
## 📊 Performance Metrics
```mermaid
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
```
---
## 🔒 Security & Compliance
- 🔐 **Authentication**: Mandatory API Key
- 🛡️ **Encryption**: TLS/SSL in transit
- 📝 **Logs**: Complete call auditing
- 🔒 **Privacy**: Locally processed data
- ✅ **GDPR**: Privacy compliance
---
## 🤝 Contributing
<div align="center">
Do you like the project? We'd love your contribution!
[](https://github.com/grec0/mcp-s2s-asterisk)
[](https://github.com/grec0/mcp-s2s-asterisk/issues)
[](https://github.com/grec0/mcp-s2s-asterisk/pulls)
</div>
---
## 📄 License
<div align="center">
**MIT License** - Use it, modify it, distribute it freely
[](https://opensource.org/licenses/MIT)
</div>
---
<div align="center">
### 🌟 Give it a star if you like the project! ⭐
**Made with ❤️ by [@grec0](https://github.com/grec0)**
*Transforming phone communication with conversational AI*
</div>