# Asterisk Voice MCP Server

A self-hosted Model Context Protocol (MCP) server that lets an AI agent place VoIP phone calls via Asterisk, play TTS messages, capture DTMF input, and optionally record voice responses to be transcribed.

## Architecture
```mermaid
graph TD
    Agent[AI Agent (Claude/Hermes)] -->|MCP over stdio| MCPServer[MCP Server (Python)]
    MCPServer -->|ARI HTTP/WebSocket| Asterisk[Asterisk PBX (Docker)]
    Asterisk -->|SIP/RTP| Softphone[Linphone Softphone]
    MCPServer -->|TTS API / STT API| Speechmatics[Speechmatics API]
```

## Features
- **Place Calls:** Initiate calls to a SIP endpoint.
- **TTS:** Play dynamically generated speech.
- **DTMF Capture:** Prompt the user for keypad input.
- **Voice Capture & STT:** Record user audio and transcribe it via Speechmatics.
- **Tool integration:** Fully compliant MCP server that exposes tools `place_call`, `send_dtmf`, `hangup_call`, `health_check`.

## Prerequisites
- Docker & Docker Compose
- Python 3.11+
- Linphone app
- Speechmatics API Key (optional, defaults to mock if absent)

## Setup

1. **Clone the repository** (or navigate to directory).
2. **Configure environment variables:**
   ```bash
   cp .env.example .env
   # Edit .env and provide your SPEECHMATICS_API_KEY if desired.
   ```
3. **Start Asterisk:**
   ```bash
   docker compose up -d
   ```
4. **Register Linphone:**
   - SIP Server: your host IP or domain
   - Port: 5060 (UDP/TCP)
   - Username: `linphone-user`
   - Password: the value of `SIP_PASSWORD` from your `.env` (generated at deploy time; see setup.sh)

## Usage

Start the MCP server to expose tools:
```bash
python src/mcp_server.py
```

### Example MCP Client Configuration
See `config/mcp.json` for an example of how to configure an MCP client (like Claude Desktop) to use this server.

## Testing without a phone
Run the self-test script, which spins up a mock PJSIP endpoint and runs an end-to-end call test using a local bot.
```bash
python scripts/self_test.py
```

## Security Notes
- **Never expose ARI/SIP to the public internet** without proper authentication, firewalls, and Fail2Ban.
- **Secrets** should remain in `.env`.
- Use strong endpoint secrets for SIP registrations.
- Lock down RTP ports.

## License
MIT License