MCP de tiempo de emisión de Africa's Talking

Este proyecto implementa un servidor de Protocolo de Contexto de Modelo (MCP ) para gestionar transacciones de tiempo de aire utilizando la API de Africa's Talking. Proporciona un conjunto de herramientas para comprobar el saldo de la cuenta, enviar tiempo de aire, ver las transacciones de recarga recientes, sumar los importes de las recargas recientes y contar las recargas para un número de teléfono específico. La aplicación utiliza SQLite para almacenar los datos de las transacciones y es compatible con los países africanos admitidos por el servicio Africa's Talking Airtime Service con el formato de número de teléfono adecuado.

Descripción

El servidor MCP de Africa's Talking Airtime se integra con la API de Africa's Talking Airtime para facilitar las transferencias de tiempo de llamada. Las características clave incluyen:

• Envío de tiempo de aire a números de teléfono especificados.
• Almacenamiento de los detalles de la transacción en una base de datos SQLite.
• Recuperación y resumen del historial de transacciones.
• Consultar el saldo de la cuenta en Africa's Talking.

La aplicación es compatible con los países que disponen del servicio Africa's Talking Airtime.

Instalación

Instalación mediante Smithery

Para instalar Africa's Talking Airtime Server para Claude Desktop automáticamente a través de Smithery:

npx -y @smithery/cli install @nasoma/africastalking-airtime-mcp --client claude

Requisitos previos

1. Python 3.10 o superior

2. Instalar uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Sigue estos pasos para configurar y ejecutar el proyecto localmente:

1. Clona el repositorio:

git clone https://github.com/nasoma/africastalking-airtime-mcp.git cd africastalking-airtime-mcp

2. Configura el entorno virtual e instala las dependencias ejecutando

uv sync

3. Ya puedes empezar

Utilización con herramientas de IA

Con Claude Desktop

Añade esto a tu claude_desktop_config.json:

{ "mcpServers": { "Airtime Server": { "command": "{{PATH_TO_UV}}", // Ejecuta `que uv` y coloca la salida aquí "args": [ "--directory", "{{PATH_TO_PROJECT}}", // cd into the repo, run `pwd` and enter the output here "run", "main.py" ], "env": { "username": "tu_nombre_de_usuario_africastalking", "api_key": "your_africastalking_api_key", "country": "your_country", # e.g kenya, uganda, dr congo, rwanda, south africa "currency_code": "currency-code" # e.g. KES, UGX, NGN } } }

Con Goose

Goose es una buena opción si quieres utilizar tu LLM preferido y suministrar una clave API.

• Instale Goose.
• Abra el panel de configuración y añada una extensión personalizada (Servidor MCP).
• Dale un nombre a tu extensión. Escribe STDIO.
• Añade el comando. Guarde los cambios
• Añade tus variables de entorno: username, api_key, currency_code y country.
• Guarde los cambios.

Descripción de las herramientas

El MCP proporciona las siguientes herramientas para gestionar las transacciones de tiempo aire:

1. check_balance:

   • Descripción: Recupera el saldo actual de tiempo de emisión de la cuenta Talking de África.
   • Uso: check_balance()
   • Salida: Devuelve el saldo de la cuenta (por ejemplo, "Account Balance: KES 1234.00") o un mensaje de error si no se puede obtener el saldo.

2. load_airtime

   • Descripción: Envía tiempo de aire a un número de teléfono especificado y guarda la transacción en la base de datos.
   • Parámetros
     • número_teléfono: El número de teléfono del destinatario (por ejemplo, "0712345678" o "+254712345678").
     • importe: La cantidad de tiempo de emisión que se va a enviar (por ejemplo, 100).
     • código_moneda: El código de moneda (por ejemplo, "KES").
   • Uso: load_airtime("0712345678", 100.00, "KES")
   • Salida: Confirma el éxito (p. ej., "Enviado con éxito 100,00 KES de tiempo de aire a +254712345678") o informa de un error.

3. get_last_topups:

   • Descripción: Recupera las últimas N transacciones de recarga de tiempo aire de la base de datos.
   • Parámetros
     • limit: Número de transacciones a recuperar (por defecto: 3).
   • Uso: get_last_topups(3)
   • Salida: Lista las transacciones recientes (por ejemplo, "Últimas 3 transacciones de recarga: ...") o indica que no se ha encontrado ninguna transacción.

4. sum_last_n_topups:

   • Descripción: Calcula el importe total de las N últimas recargas realizadas con éxito, asegurándose de que utilizan la misma moneda.
   • Parámetros
     • n: Número de transacciones a sumar (por defecto: 3).
   • Uso: sum_last_n_topups(3)
   • Salida: Devuelve la suma (por ejemplo, "Suma de las 3 últimas recargas con éxito: KES 300.00") o un error si las monedas difieren.

5. count_topups_by_number:

   • Descripción: Cuenta el número de recargas realizadas con éxito en un número de teléfono concreto.
   • Parámetros
     • número_teléfono: El número de teléfono que se desea consultar (por ejemplo, "0712345678").
   • Usage: count_topups_by_number("0712345678")
   • Salida: Devuelve el recuento (por ejemplo, "Número de recargas con éxito a +254712345678: 5") o un error.

Ejemplos de preguntas

Los siguientes son ejemplos de preguntas o comandos que los usuarios pueden formular a la IA para interactuar con el MCP de Tiempo de Conversación de África, basándose en las herramientas disponibles:

Comprobar saldo de cuenta

• ¿Cuál es el saldo de mi cuenta de Africa's Talking?
• ¿Puede mostrarme el saldo actual?
• Comprobar el saldo de mi tiempo de aire.

Enviar tiempo de aire

• Enviar 100 KES de tiempo de aire a 0712345678.
• Recargar mi 0712345678 con 60.
• Recargar 50 NGN a +2348012345678.
• ¿Puede recargar 200 UGX a 0755123456?

Ver Recargas Recientes

• Muéstrame las 3 últimas transacciones de tiempo aire.
• ¿Cuáles son mis recargas más recientes?
• Enumera las últimas 5 recargas de tiempo aire.

Sumar Recargas Recientes

• ¿Cuál es el total de mis 3 últimas recargas?
• Suma los importes de mis últimas 4 transacciones de tiempo aire.
• ¿Cuánto he enviado en mis últimas 5 recargas?

Contar recargas por número de teléfono

• ¿Cuántas veces he recargado 0712345678?
• Cuente las recargas hasta +254712345678.
• Dime cuántas recargas con éxito se hicieron a 0755123456.

Notas

• Asegúrate de que tu cuenta de Africa's Talking tiene fondos para enviar tiempo de llamada.
• Los números de teléfono se formatean automáticamente en función de la variable de país establecida en el cliente o en claude_desktop_config.json.
• La base de datos SQLite(airtime_transactions.db) se crea en el directorio del proyecto durante la inicialización.
• Funciona mejor con modelos que soportan llamadas a herramientas, por ejemplo Claude 3.7 Sonnet. Si eres consciente del precio GPT-4.1 Nano es una opción buena y más barata cuando se utiliza con clientes como Goose.

créditos

• Africa's Talking API Documentación de Africa's Talking.