Telephony MCP Server

Realiza llamadas de voz y envía mensajes SMS utilizando la API de Vonage.

Documentación

📖 Entrada de blog: Aprende más sobre este proyecto en la entrada de blog detallada: Telephony MCP Server para IA Agéntica y Modelos de Lenguaje

Telephony MCP Server

Demostración con Claude Desktop

Conversación Telefónica Agéntica con Reconocimiento de Voz

Agentic Telephony Conversation with Speech Recognition

Usar SMS durante una conversación

Consulta por SMS (Enviar y Recibir)

Demostración con GitHub Copilot

Introducción

Este directorio contiene herramientas de servidor MCP (Protocolo de Contexto de Modelo) para operaciones de telefonía, como realizar llamadas de voz y enviar mensajes SMS mediante la API de Vonage. Estas herramientas están diseñadas para integrarse con aplicaciones de Modelos de Lenguaje Grande (LLM), permitiendo que los LLM realicen acciones del mundo real más allá de la simple generación de texto.

LLMs e Integración de Herramientas

Los LLM (Modelos de Lenguaje Grande) son generadores avanzados de tokens: pueden generar texto, imágenes o incluso video basándose en indicaciones de entrada. Sin embargo, su capacidad principal se limita a generar contenido; no pueden acceder a datos externos ni realizar acciones en el mundo real por sí solos.

Para ampliar su funcionalidad, los LLM pueden conectarse a herramientas externas. Por ejemplo, cuando un usuario pregunta "¿Qué tiempo hace hoy?", el LLM puede invocar una herramienta de API backend como get_weather(city) mediante una indicación del sistema, analizar la respuesta y devolver el resultado al usuario. Este mecanismo de llamada a herramientas transforma un LLM básico en una potente Aplicación LLM.

Llamada a Herramientas con MCP y LangChain

LangChain es un marco popular para desarrollar aplicaciones impulsadas por LLM. Proporciona una colección de herramientas preconstruidas (llamada Toolkit) que los LLM pueden usar para interactuar con sistemas externos.
MCP (Protocolo de Contexto de Modelo) sigue el mismo concepto: ofrece una colección de herramientas preconstruidas y un marco para escribir nuevas herramientas y manejar la llamada a funciones.
Ambos marcos permiten que los LLM invoquen herramientas, analicen sus salidas e integren los resultados en sus respuestas.

Cómo Funciona Esto

Definición de Herramientas: En este proyecto, herramientas como voice_call y send_sms se definen usando el marco MCP. Cada herramienta es una función que puede ser llamada por una aplicación LLM.
Aplicación LLM: Cuando se integra con un LLM (como GPT de OpenAI, Claude de Anthropic, etc.), el LLM puede decidir llamar a estas herramientas basándose en las indicaciones del usuario.
Flujo de Ejecución:
- El LLM recibe una indicación (por ejemplo, "Llama a Alice y salúdala").
- El LLM determina que se necesita una invocación de herramienta y llama a la herramienta MCP adecuada (por ejemplo, voice_call).
- La herramienta se ejecuta (por ejemplo, inicia una llamada telefónica mediante Vonage) y devuelve el resultado.
- El LLM analiza la respuesta y la presenta al usuario.

Ejecución de las Herramientas MCP

Requisitos Previos

Python 3.13+
CLI de MCP (mcp[cli]), FastAPI, httpx, pyjwt, python-dotenv, uvicorn, pydantic (consulta pyproject.toml para más detalles)
Credenciales de la API de Vonage (clave de API, secreto, ID de aplicación, clave privada)
URL pública para el servidor de devoluciones de llamada (para uso en producción)

Configuración

Instalar dependencias:

pip install -r requirements.txt

O, si usas Poetry:

poetry install

Configurar variables de entorno:

Crea un archivo .env con tus credenciales de Vonage:

VONAGE_API_KEY=your_api_key
VONAGE_API_SECRET=your_api_secret
VONAGE_APPLICATION_ID=your_app_id
VONAGE_PRIVATE_KEY_PATH=path/to/private.key
VONAGE_LVN=your_virtual_number
VONAGE_API_URL=https://api.nexmo.com/v1/calls
VONAGE_SMS_URL=https://rest.nexmo.com/sms/json
CALLBACK_SERVER_URL=https://your-public-url  # URL for Vonage event callbacks

Para el CALLBACK_SERVER_URL:

En desarrollo: Puedes usar http://localhost:8080 (predeterminado si no se especifica)
En producción: Usa una URL pública (como una URL de ngrok o tu servidor desplegado)

Ejecutar el servidor MCP:
```
python telephony_server.py
```
El servidor se iniciará y expondrá las herramientas definidas para aplicaciones LLM.

Ejecución con Docker

También puedes ejecutar el servidor MCP de telefonía usando Docker:

Construir e iniciar el contenedor Docker:
```
docker compose up --build
```
O para ejecutar en segundo plano:
```
docker compose up --build -d
```
Detener el contenedor Docker:
```
docker compose down
```
Ver registros del contenedor Docker:
```
docker compose logs -f
```

Uso con Aplicaciones LLM

Integración Directa: Conecta tu aplicación LLM (por ejemplo, usando LangChain mediante Adapter o un cliente MCP personalizado) al servidor MCP en ejecución. El LLM ahora puede invocar herramientas de telefonía según sea necesario.
Ejemplo: Cuando el LLM recibe una indicación como "Marca este número +123 y lee las últimas noticias de hoy", llamará a la herramienta voice_call, pasando los parámetros requeridos.
Ejemplo: Cuando el LLM recibe una indicación como "Llama a este número con acento británico", llamará a la herramienta voice_call con parámetros específicos de idioma y estilo.
Ejemplo: Cuando el LLM recibe una indicación como "Envía las noticias por texto en su lugar", llamará a la herramienta send_sms, pasando los parámetros requeridos.

Uso con Claude Desktop u otros clientes MCP

Para configurar un cliente MCP (como Claude Desktop) para usar tu servidor MCP de telefonía:

Actualiza tu archivo de configuración del cliente MCP (por ejemplo, claude_desktop_config.json):

{
  "mcpServers": {
    "telephony": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "-e", "DOCKER_CONTAINER=true", "telephony-mcp-server"]
    }
  }
}

Construye la imagen Docker (si no usas docker compose):
```
docker build -t telephony-mcp-server .
```
Reinicia tu cliente MCP para aplicar los cambios.

Conceptos Clave

Los LLM son generadores de contenido: Generan texto, imágenes o video, pero necesitan herramientas externas para acciones como búsqueda web, telefonía o acceso a bases de datos.
Llamada a herramientas: Los LLM pueden invocar APIs backend (herramientas) para obtener datos o realizar acciones, luego analizar y presentar los resultados.
Marcos: Tanto LangChain como MCP proporcionan una estructura para definir, registrar e invocar herramientas desde LLM.
MCP: Te ayuda a escribir nuevas herramientas y gestionar la llamada a funciones, facilitando la extensión de aplicaciones LLM con capacidades personalizadas.

Servidor de Devoluciones de Llamada para Eventos de Vonage

El Telephony MCP Server también incluye un Servidor de Devoluciones de Llamada de Vonage que escucha en el puerto 8080. Este servidor se utiliza para recibir notificaciones de eventos de la API de Voz de Vonage, que se envían cuando se inician, completan o encuentran errores en las llamadas de voz.

Características

Recibe y almacena devoluciones de llamada de eventos de Vonage
Proporciona endpoints para ver y gestionar eventos almacenados
Se ejecuta como un servicio separado dentro de la misma aplicación

Endpoints

GET / - Endpoint de verificación de salud
POST /event - Endpoint principal para recibir devoluciones de llamada de Vonage
GET /events - Listar todos los eventos almacenados (con paginación)
GET /events/{event_id} - Obtener un evento específico por ID
DELETE /events - Borrar todos los eventos almacenados

Configuración

Para usar el servidor de devoluciones de llamada con la API de Voz de Vonage, debes configurar la variable de entorno CALLBACK_SERVER_URL con la URL pública de tu servidor. Esta URL se usará como el parámetro event_url en las llamadas a la API de Vonage.

export CALLBACK_SERVER_URL="https://your-public-url"

Para desarrollo local, puedes usar un servicio como ngrok para exponer tu servidor local a internet:

ngrok http 8080

Luego configura el CALLBACK_SERVER_URL con la URL de ngrok.