Telephony MCP Server

Faça chamadas de voz e envie mensagens SMS usando a API Vonage.

GitHub
13

Documentação

Black Ruff

📖 Post no Blog: Saiba mais sobre este projeto no post detalhado: Telephony MCP Server for Agentic AI and Language Models

Telephony MCP Server

Demonstração Usando Claude Desktop

Conversa Telefônica Agentic com Reconhecimento de Fala

Agentic Telephony Conversation with Speech Recognition

Use SMS durante a conversa

Telephony MCP Server Demo

Consulta por SMS (Enviar e Receber)

SMS Enquiry

Demonstração Usando GitHub Copilot

Telephony MCP Server Demo

Introdução

Este diretório contém ferramentas de servidor MCP (Model Context Protocol) para operações de telefonia, como fazer chamadas de voz e enviar mensagens SMS usando a API Vonage. Essas ferramentas são projetadas para serem integradas a aplicações de Large Language Model (LLM), permitindo que LLMs realizem ações no mundo real além da simples geração de texto.

LLMs e Integração de Ferramentas

LLMs (Large Language Models) são geradores avançados de tokens—eles podem gerar texto, imagens ou até vídeo com base em prompts de entrada. No entanto, sua capacidade principal é limitada à geração de conteúdo; eles não podem acessar dados externos ou realizar ações no mundo real por conta própria.

Para estender sua funcionalidade, LLMs podem ser conectados a ferramentas externas. Por exemplo, quando um usuário pergunta: "Como está o tempo hoje?" o LLM pode invocar uma ferramenta de API de backend como get_weather(city) por meio de um prompt de sistema, analisar a resposta e retornar o resultado ao usuário. Esse mecanismo de chamada de ferramentas transforma um LLM básico em uma poderosa Aplicação LLM.

Chamada de Ferramentas com MCP e LangChain

  • LangChain é um framework popular para desenvolver aplicações alimentadas por LLMs. Ele fornece uma coleção de ferramentas pré-construídas (chamada de Toolkit) que LLMs podem usar para interagir com sistemas externos.
  • MCP (Model Context Protocol) segue o mesmo conceito: oferece uma coleção de ferramentas pré-construídas e um framework para escrever novas ferramentas e lidar com chamadas de função.
  • Ambos os frameworks permitem que LLMs invoquem ferramentas, analisem suas saídas e integrem os resultados em suas respostas.

Como Isso Funciona

  1. Definição de Ferramentas: Neste projeto, ferramentas como voice_call e send_sms são definidas usando o framework MCP. Cada ferramenta é uma função que pode ser chamada por uma aplicação LLM.
  2. Aplicação LLM: Quando integrado a um LLM (como GPT da OpenAI, Claude da Anthropic, etc.), o LLM pode decidir chamar essas ferramentas com base nos prompts do usuário.
  3. Fluxo de Execução:
    • O LLM recebe um prompt (ex.: "Ligue para Alice e diga olá").
    • O LLM determina que uma invocação de ferramenta é necessária e chama a ferramenta MCP apropriada (ex.: voice_call).
    • A ferramenta executa (ex.: inicia uma chamada telefônica via Vonage) e retorna o resultado.
    • O LLM analisa a resposta e a apresenta ao usuário.

Executando as Ferramentas MCP

Pré-requisitos

  • Python 3.13+
  • MCP CLI (mcp[cli]), FastAPI, httpx, pyjwt, python-dotenv, uvicorn, pydantic (veja pyproject.toml para detalhes)
  • Credenciais da API Vonage (chave de API, segredo, ID do aplicativo, chave privada)
  • URL pública para o servidor de callback (para uso em produção)

Configuração

  1. Instale as dependências:

    pip install -r requirements.txt

    Ou, se estiver usando Poetry:

    poetry install

  2. Configure as variáveis de ambiente:

    • Crie um arquivo .env com suas credenciais 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 o CALLBACK_SERVER_URL:

      • Em desenvolvimento: Você pode usar http://localhost:8080 (padrão se não especificado)
      • Em produção: Use uma URL pública (como uma URL ngrok ou seu servidor implantado)

  3. Execute o servidor MCP:

    python telephony_server.py

    O servidor iniciará e exporá as ferramentas definidas para aplicações LLM.

Executando com Docker

Você também pode executar o servidor MCP de telefonia usando Docker:

  1. Construa e inicie o contêiner Docker:

    docker compose up --build

    Ou para executar em segundo plano:

    docker compose up --build -d

  2. Pare o contêiner Docker:

    docker compose down

  3. Veja os logs do contêiner Docker:

    docker compose logs -f

Usando com Aplicações LLM

  • Integração Direta: Conecte sua aplicação LLM (ex.: usando LangChain via Adapter ou um cliente MCP personalizado) ao servidor MCP em execução. O LLM agora pode invocar ferramentas de telefonia conforme necessário.
  • Exemplo: Quando o LLM recebe um prompt como "Disque este número +123 e leia as últimas notícias de hoje", ele chamará a ferramenta voice_call, passando os parâmetros necessários.
  • Exemplo: Quando o LLM recebe um prompt como "Ligue para este número usando um sotaque britânico", ele chamará a ferramenta voice_call com parâmetros específicos de idioma e estilo.
  • Exemplo: Quando o LLM recebe um prompt como "Envie as notícias por texto", ele chamará a ferramenta send_sms, passando os parâmetros necessários.

Usando com Claude Desktop ou outros clientes MCP

Para configurar um cliente MCP (como Claude Desktop) para usar seu servidor MCP de telefonia:

  1. Atualize seu arquivo de configuração do cliente MCP (ex.: claude_desktop_config.json):

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

  2. Construa a imagem Docker (se não estiver usando docker compose):

    docker build -t telephony-mcp-server .

  3. Reinicie seu cliente MCP para aplicar as alterações.

Conceitos-Chave

  • LLMs são geradores de conteúdo: Eles geram texto, imagens ou vídeo, mas precisam de ferramentas externas para ações como busca na web, telefonia ou acesso a banco de dados.
  • Chamada de ferramentas: LLMs podem invocar APIs de backend (ferramentas) para buscar dados ou realizar ações, depois analisar e apresentar os resultados.
  • Frameworks: Tanto LangChain quanto MCP fornecem uma estrutura para definir, registrar e invocar ferramentas a partir de LLMs.
  • MCP: Ajuda você a escrever novas ferramentas e gerenciar chamadas de função, facilitando a extensão de aplicações LLM com capacidades personalizadas.

Servidor de Callback para Eventos Vonage

O Telephony MCP Server também inclui um Servidor de Callback Vonage que escuta na porta 8080. Este servidor é usado para receber notificações de eventos da API de Voz Vonage, que são enviadas quando chamadas de voz são iniciadas, concluídas ou encontram erros.

Recursos

  • Recebe e armazena callbacks de eventos Vonage
  • Fornece endpoints para visualizar e gerenciar eventos armazenados
  • Executa como um serviço separado dentro da mesma aplicação

Endpoints

  • GET / - Endpoint de verificação de saúde
  • POST /event - Endpoint principal para receber callbacks Vonage
  • GET /events - Listar todos os eventos armazenados (com paginação)
  • GET /events/{event_id} - Obter um evento específico por ID
  • DELETE /events - Limpar todos os eventos armazenados

Configuração

Para usar o servidor de callback com a API de Voz Vonage, você precisa definir a variável de ambiente CALLBACK_SERVER_URL para a URL pública do seu servidor. Esta URL será usada como o parâmetro event_url nas chamadas da API Vonage.

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

Para desenvolvimento local, você pode usar um serviço como ngrok para expor seu servidor local à internet:

ngrok http 8080

Em seguida, defina o CALLBACK_SERVER_URL para a URL do ngrok.