Africa's Talking Airtime MCP

Africa's Talking Airtime MCP

Este proyecto implementa un servidor de Protocolo de Contexto de Modelo (MCP) que permite una interacción fluida con la API de Africa's Talking para operaciones relacionadas con aire. Proporciona un conjunto de herramientas para consultar saldos de cuenta, enviar aire, ver historial de transacciones y resumir datos de recargas. El servidor utiliza una base de datos SQLite para almacenamiento persistente e incluye lógica para formatear números de teléfono de varios países africanos.

Características Clave

• Consultar Saldo: Recupera al instante el saldo de aire actual de tu cuenta de Africa's Talking.
• Enviar Aire: Carga aire a cualquier número de teléfono en países compatibles.
• Registro de Transacciones: Guarda automáticamente cada transacción en una base de datos SQLite local.
• Historial de Transacciones: Consulta una lista de las transacciones de recarga más recientes.
• Resumir Recargas: Calcula el monto total de las últimas 'n' recargas.
• Contar Recargas: Cuenta el número de transacciones para un número de teléfono específico.
• Formato de Números de Teléfono: Formatea automáticamente los números de teléfono para incluir el código de país correcto.

Guía de Instalación

Requisitos Previos

1. Python 3.10 o superior: Asegúrate de tener una versión moderna de Python instalada.
2. uv Administrador de Paquetes: Este proyecto utiliza uv para la gestión de dependencias. Instálalo ejecutando:

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

Instalación desde 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

Configuración Local

1. Clonar el Repositorio:

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

2. Instalar Dependencias: Configura el entorno virtual e instala los paquetes requeridos usando uv:

   uv sync
   

Uso con Herramientas de IA

Con Claude Desktop

Agrega esto a tu claude_desktop_config.json:

{
  "mcpServers": {
    "Airtime Server": {
      "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
      "args": [
        "--directory",
        "{{PATH_TO_PROJECT}}", // cd into the repo, run `pwd` and enter the output here
        "run",
        "main.py"
      ],
      "env": {
        "username": "your_africastalking_username",
        "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 deseas usar tu LLM preferido y proporcionar una clave API.

• Instala Goose.
• Abre el panel de configuración y agrega una extensión personalizada (Servidor MCP).
• Asigna un nombre a tu extensión. El tipo es STDIO.
• Agrega el comando. Guarda los cambios.
• Agrega tus variables de entorno: username, api_key, currency_code y country.
• Guarda los cambios.

Referencia de Herramientas

El servidor MCP expone las siguientes herramientas para gestionar aire:

check_balance

• Descripción: Recupera el saldo de aire actual de tu cuenta de Africa's Talking.
• Uso: check_balance()
• Devuelve: Una cadena que muestra el saldo de la cuenta (por ejemplo, "Saldo de la Cuenta: KES 1234.00") o un mensaje de error.

load_airtime

• Descripción: Envía una cantidad específica de aire a un número de teléfono y registra la transacción.
• Argumentos:
  • phone_number (str): El número de teléfono del destinatario.
  • amount (float): La cantidad de aire a enviar.
  • currency_code (str): El código de moneda (por ejemplo, "KES", "UGX").
• Uso: load_airtime(phone_number="0712345678", amount=100.0, currency_code="KES")
• Devuelve: Un mensaje de confirmación al tener éxito o un mensaje de error.

get_last_topups

• Descripción: Obtiene las últimas N transacciones de recarga de aire de la base de datos.
• Argumentos:
  • limit (int, opcional): El número de transacciones a recuperar. El valor predeterminado es 3.
• Uso: get_last_topups(limit=5)
• Devuelve: Una cadena formateada que lista las transacciones recientes.

sum_last_n_topups

• Descripción: Calcula la suma de las últimas N recargas.
• Argumentos:
  • n (int, opcional): El número de transacciones a sumar. El valor predeterminado es 3.
• Uso: sum_last_n_topups(n=5)
• Devuelve: Una cadena con la suma total, o un error si las transacciones tienen monedas diferentes.

count_topups_by_number

• Descripción: Cuenta el número de recargas exitosas a un número de teléfono específico.
• Argumentos:
  • phone_number (str): El número de teléfono a consultar.
• Uso: count_topups_by_number(phone_number="0712345678")
• Devuelve: El recuento total de recargas para el número dado.

Ejemplos de Prompts

Aquí hay algunos ejemplos de prompts que puedes usar para interactuar con el servidor MCP:

• Consultar Saldo:

  • "¿Cuál es el saldo de mi cuenta de Africa's Talking?"
  • "Consulta mi saldo de aire."

• Enviar Aire:

  • "Envía 100 KES de aire a 0712345678."
  • "Recarga mi teléfono +254712345678 con 50 bob."
  • "Carga 200 UGX a 0755123456."

• Ver Recargas Recientes:

  • "Muéstrame las últimas 3 transacciones de aire."
  • "Lista mis 5 recargas más recientes."

• Sumar Recargas Recientes:

  • "¿Cuál es el total de mis últimas 3 recargas?"
  • "¿Cuánto he gastado en mis últimas 5 transacciones?"

• Contar Recargas:

  • "¿Cuántas veces he recargado 0712345678?"
  • "Cuenta las recargas a +254712345678."

Notas Importantes

• Fondos: Asegúrate de que tu cuenta de Africa's Talking tenga fondos suficientes para enviar aire.
• Formato de Números de Teléfono: Los números de teléfono se formatean automáticamente según la variable de entorno country.
• Base de Datos: La base de datos SQLite (airtime_transactions.db) se crea automáticamente en el directorio del proyecto.
• Modelos Compatibles: Este servidor MCP funciona mejor con modelos que admiten llamadas a herramientas, como Claude 3.7 Sonnet o GPT-4.1 Nano.

Créditos

• API de Africa's Talking: Por el servicio de aire subyacente. Consulta la documentación oficial.