Africa's Talking Airtime MCP

Africa's Talking Airtime MCP

Este projeto implementa um servidor Model Context Protocol (MCP) que permite interação perfeita com a API Africa's Talking para operações relacionadas a airtime. Ele fornece um conjunto de ferramentas para verificar saldos de conta, enviar airtime, visualizar histórico de transações e resumir dados de recarga. O servidor usa um banco de dados SQLite para armazenamento persistente e inclui lógica para formatar números de telefone para vários países africanos.

Recursos Principais

• Verificar Saldo: Recupere instantaneamente o saldo de airtime atual da sua conta Africa's Talking.
• Enviar Airtime: Carregue airtime para qualquer número de telefone em países suportados.
• Registro de Transações: Salve automaticamente cada transação em um banco de dados SQLite local.
• Histórico de Transações: Visualize uma lista das transações de recarga mais recentes.
• Resumir Recargas: Calcule o valor total das últimas 'n' recargas.
• Contar Recargas: Conte o número de transações para um número de telefone específico.
• Formatação de Número de Telefone: Formata automaticamente números de telefone para incluir o código do país correto.

Guia de Instalação

Pré-requisitos

1. Python 3.10 ou superior: Certifique-se de ter uma versão moderna do Python instalada.
2. Gerenciador de Pacotes uv: Este projeto usa uv para gerenciamento de dependências. Instale-o executando:

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

Instalando a partir do Smithery

Para instalar o Africa's Talking Airtime Server para Claude Desktop automaticamente via Smithery:

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

Configuração Local

1. Clone o Repositório:

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

2. Instale as Dependências: Configure o ambiente virtual e instale os pacotes necessários usando uv:

   uv sync
   

Usando com Ferramentas de IA

Com Claude Desktop

Adicione isso ao seu 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
      }
    }
  }
}

Com Goose

Goose é uma boa opção se você quiser usar seu LLM preferido e fornecer uma chave de API.

• Instale o Goose.
• Abra o painel de configurações e adicione uma extensão personalizada (Servidor MCP).
• Dê um nome à sua extensão. O tipo é STDIO.
• Adicione o comando. Salve as alterações.
• Adicione suas variáveis de ambiente: username, api_key, currency_code e country.
• Salve as alterações.

Referência de Ferramentas

O servidor MCP expõe as seguintes ferramentas para gerenciar airtime:

check_balance

• Descrição: Recupera o saldo de airtime atual da sua conta Africa's Talking.
• Uso: check_balance()
• Retorna: Uma string exibindo o saldo da conta (ex.: "Account Balance: KES 1234.00") ou uma mensagem de erro.

load_airtime

• Descrição: Envia uma quantidade especificada de airtime para um número de telefone e registra a transação.
• Argumentos:
  • phone_number (str): O número de telefone do destinatário.
  • amount (float): A quantidade de airtime a enviar.
  • currency_code (str): O código da moeda (ex.: "KES", "UGX").
• Uso: load_airtime(phone_number="0712345678", amount=100.0, currency_code="KES")
• Retorna: Uma mensagem de confirmação em caso de sucesso ou uma mensagem de erro.

get_last_topups

• Descrição: Busca as últimas N transações de recarga de airtime do banco de dados.
• Argumentos:
  • limit (int, opcional): O número de transações a recuperar. O padrão é 3.
• Uso: get_last_topups(limit=5)
• Retorna: Uma string formatada listando as transações recentes.

sum_last_n_topups

• Descrição: Calcula a soma das últimas N recargas.
• Argumentos:
  • n (int, opcional): O número de transações a somar. O padrão é 3.
• Uso: sum_last_n_topups(n=5)
• Retorna: Uma string com a soma total, ou um erro se as transações tiverem moedas diferentes.

count_topups_by_number

• Descrição: Conta o número de recargas bem-sucedidas para um número de telefone específico.
• Argumentos:
  • phone_number (str): O número de telefone a consultar.
• Uso: count_topups_by_number(phone_number="0712345678")
• Retorna: A contagem total de recargas para o número fornecido.

Exemplos de Prompts

Aqui estão alguns exemplos de prompts que você pode usar para interagir com o servidor MCP:

• Verificar Saldo:

  • "Qual é o saldo da minha conta Africa's Talking?"
  • "Verifique meu saldo de airtime."

• Enviar Airtime:

  • "Envie 100 KES de airtime para 0712345678."
  • "Recarregue meu telefone +254712345678 com 50 bob."
  • "Carregue 200 UGX para 0755123456."

• Ver Recargas Recentes:

  • "Mostre-me as últimas 3 transações de airtime."
  • "Liste minhas 5 recargas mais recentes."

• Somar Recargas Recentes:

  • "Qual é o total das minhas últimas 3 recargas?"
  • "Quanto gastei nas minhas últimas 5 transações?"

• Contar Recargas:

  • "Quantas vezes recarreguei 0712345678?"
  • "Conte as recargas para +254712345678."

Notas Importantes

• Financiamento: Garanta que sua conta Africa's Talking tenha fundos suficientes para enviar airtime.
• Formatação de Número de Telefone: Os números de telefone são formatados automaticamente com base na variável de ambiente country.
• Banco de Dados: O banco de dados SQLite (airtime_transactions.db) é criado automaticamente no diretório do projeto.
• Modelos Suportados: Este servidor MCP funciona melhor com modelos que suportam chamada de ferramentas, como Claude 3.7 Sonnet ou GPT-4.1 Nano.

Créditos

• API Africa's Talking: Pelo serviço de airtime subjacente. Veja a documentação oficial.