Africa's Talking Airtime MCP

Este projecte implementa un Model Context Protocol (MCP) server per gestionar transaccions d'aerotime utilitzant l'Africa's Talking API. Proporciona un conjunt d'eines per comprovar el saldo del compte, enviar aerotime, veure les últimes transaccions de càrrega, sumar els imports de les últimes càrregues i comptar càrregues per a un número de telèfon específic. L'aplicació utilitza SQLite per emmagatzemar les dades de transacció i admet els països africans suportats per l'API d'Africa's Talking amb el format correcte de números de telèfon.

Descripció

El Africa's Talking Airtime MCP Server s'integra amb l'API d'Africa's Talking Airtime per facilitar les transferències d'aerotime. Les característiques clau inclouen:

• Enviar aerotime a números de telèfon especificats.
• Emmagatzemar detalls de transacció en una base de dades SQLite.
• Recuperar i resumir l'historial de transaccions.
• Comprovar el saldo del compte a Africa's Talking.

L'aplicació admet els països on el servei d'Africa's Talking Airtime està disponible.

Instal·lació

Instal·lació via Smithery

Per instal·lar l'Africa's Talking Airtime Server automàticament per a Claude Desktop a través de Smithery:

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

Requisits previs

1. Python 3.10 o superior

2. Instal·la uv

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

Segueix aquests passos per configurar i executar el projecte localment:

1. Clona el repositori:

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

2. Configura l'entorn virtual i instal·la les dependències amb:

uv sync 

3. Estàs llest!

Ús amb Eines d'IA

Amb Claude Desktop

Afegeix això al teu claude_desktop_config.json:

{
  "mcpServers": {
    "Airtime Server": {
      "command": "{{PATH_TO_UV}}", // Executa `which uv` i introdueix el resultat aquí
      "args": [
        "--directory",
        "{{PATH_TO_PROJECT}}", // Canvia al repositori, executa `pwd` i introdueix el resultat aquí
        "run",
        "main.py"
      ],
      "env": {
        "username": "your_africastalking_username",
        "api_key": "your_africastalking_api_key",
        "country":"your_country", // ex: kenya, uganda, dr congo, rwanda, south africa
        "currency_code":"currency-code"  // ex: KES, UGX, NGN
      }
    }
  }
}

Amb Goose

Goose és una bona opció si vols utilitzar el teu LLM preferit i proporcionar una clau d'API.

• Instal·la Goose.
• Obre el panell de configuració i afegeix una extensió personalitzada (MCP Server).
• Assigna un nom a la teva extensió. El tipus és STDIO.
• Afegeix la comanda. Desa els canvis.
• Afegeix les variables d'entorn: username, api_key, currency_code i country.
• Desa els canvis.

Descripcions d'Eines

El MCP ofereix les següents eines per gestionar transaccions d'aerotime:

1. check_balance:

   • Descripció: Recupera el saldo actual d'aerotime del teu compte Africa's Talking.
   • Ús: check_balance()
   • Sortida: Retorna el saldo del compte (ex.: "Account Balance: KES 1234.00") o un missatge d'error si no es pot obtenir.

2. load_airtime:

   • Descripció: Envia aerotime a un número de telèfon especificat i desa la transacció a la base de dades.
   • Paràmetres:
     • phone_number: Número de telèfon del destinatari (ex.: "0712345678" o "+254712345678").
     • amount: Import d'aerotime a enviar (ex.: 100).
     • currency_code: Codi de moneda (ex.: "KES").
   • Ús: load_airtime("0712345678", 100.00, "KES")
   • Sortida: Confirma l'èxit (ex.: "Successfully sent KES 100.00 airtime to +254712345678") o informa d'un error.

3. get_last_topups:

   • Descripció: Recupera les últimes N transaccions de càrrega d'aerotime de la base de dades.
   • Paràmetres:
     • limit: Nombre de transaccions a recuperar (per defecte: 3).
   • Ús: get_last_topups(3)
   • Sortida: Llista les transaccions recents (ex.: "Last 3 top-up transactions: ...") o indica que no s'han trobat transaccions.

4. sum_last_n_topups:

   • Descripció: Calcula el total dels imports de les últimes N càrregues reeixides, assegurant-se que utilitzin la mateixa moneda.
   • Paràmetres:
     • n: Nombre de transaccions a sumar (per defecte: 3).
   • Ús: sum_last_n_topups(3)
   • Sortida: Retorna la suma (ex.: "Sum of last 3 successful top-ups: KES 300.00") o un error si les monedes difereixen.

5. count_topups_by_number:

   • Descripció: Comptabilitza el nombre de càrregues reeixides a un número de telèfon específic.
   • Paràmetres:
     • phone_number: Número de telèfon a consultar (ex.: "0712345678").
   • Ús: count_topups_by_number("0712345678")
   • Sortida: Retorna el compte (ex.: "Number of successful top-ups to +254712345678: 5") o un error.

Prompts d'Exemple

Les següents són preguntes o comandes d'exemple que els usuaris poden fer a l'IA per interactuar amb l'Africa's Talking Airtime MCP, basades en les eines disponibles:

Comprovar el Saldo del Compte

• Quin és el meu saldo d'aerotime a Africa's Talking?
• Em pots mostrar el saldo actual?
• Comprova el meu saldo d'aerotime.

Enviar Aerotime

• Envia 100 KES d'aerotime a 0712345678.
• Carrega el meu 0712345678 amb 60.
• Carrega 50 NGN a +2348012345678.
• Em pots carregar 200 UGX a 0755123456?

Veure les Últimes Càrregues

• Mostra'm les últimes 3 transaccions d'aerotime.
• Quines són les meves càrregues més recents?
• Llista les últimes 5 càrregues d'aerotime.

Sumar les Últimes Càrregues

• Quin és el total de les meves últimes 3 càrregues?
• Sumar els imports de les últimes 4 transaccions d'aerotime.
• Quant he enviat en les últimes 5 càrregues?

Comptar Càrregues per Número de Telèfon

• Quantes vegades he carregat el 0712345678?
• Compta les càrregues a +254712345678.
• Digues-me quantes càrregues reeixides s'han fet a 0755123456.

Notes

• Assegura't que el teu compte Africa's Talking estigui finançat per enviar aerotime.
• Els números de telèfon es formategen automàticament basant-se en la variable country establerta al client o a claude_desktop_config.json.
• La base de dades SQLite (airtime_transactions.db) es crea al directori del projecte durant la inicialització.
• Funciona millor amb models que suporten l'ús d'eines, ex.: Claude 3.7 Sonnet. Si busques una opció més econòmica, GPT-4.1 Nano és una bona alternativa quan s'utilitza amb clients com Goose.

🙏 Crèdits

• Africa's Talking API Africa's Talking Documentation.