Africa's Talking Airtime MCP

Africa's Talking Airtime MCP

このプロジェクトは、Africa's Talking API をシームレスに利用してエアタイム関連の操作を行う Model Context Protocol（MCP）サーバーを実装しています。アカウント残高の確認、エアタイムの送信、取引履歴の表示、チャージデータの要約を行うツールを提供します。サーバーは永続ストレージに SQLite データベースを使用し、アフリカ各国の電話番号を整形するロジックも備えています。

主な機能

• 残高の確認：Africa's Talking アカウントの現在のエアタイム残高をすぐに取得します。
• エアタイムの送信：対応国の任意の電話番号にエアタイムをチャージします。
• 取引の記録：すべての取引をローカルの SQLite データベースに自動保存します。
• 取引履歴：直近のチャージ取引の一覧を表示します。
• チャージの要約：直近の「n」件のチャージ総額を計算します。
• チャージ件数のカウント：指定した電話番号に対する取引件数を数えます。
• 電話番号の整形：正しい国番号を含むように電話番号を自動で整形します。

インストールガイド

前提条件

1. Python 3.10 以降：最新の Python がインストールされていることを確認してください。
2. uv パッケージマネージャー：このプロジェクトでは依存関係の管理に uv を使用します。次のコマンドを実行してインストールしてください。

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

Smithery からのインストール

Smithery を使って Claude Desktop 用の Africa's Talking Airtime Server を自動的にインストールするには、次の手順に従ってください。

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

ローカルでのセットアップ

1. リポジトリをクローンする：

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

2. 依存関係をインストールする： uv を使用して仮想環境をセットアップし、必要なパッケージをインストールします。

   uv sync
   

AI ツールでの使用

Claude Desktop での使用

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
      }
    }
  }
}

Goose での使用

Goose は、お好みの LLM を使い、API キーを設定したい場合に適しています。

• Goose をインストールします。
• 設定パネルを開き、カスタム拡張機能（MCP Server）を追加します。
• 拡張機能に名前を付けます。タイプは STDIO です。
• コマンドを追加して、変更を保存します。
• 環境変数 username、api_key、currency_code、country を追加します。
• 変更を保存します。

ツールリファレンス

MCP サーバーは、エアタイムを管理するための次のツールを公開します。

check_balance

• 説明：Africa's Talking アカウントの現在のエアタイム残高を取得します。
• 使用方法：check_balance()
• 戻り値：アカウント残高を示す文字列（例：「Account Balance: KES 1234.00」）、またはエラーメッセージ。

load_airtime

• 説明：指定した金額のエアタイムを電話番号に送信し、取引を記録します。
• 引数：
  • phone_number (str)：受取人の電話番号。
  • amount (float)：送信するエアタイムの金額。
  • currency_code (str)：通貨コード（例：「KES」、「UGX」）。
• 使用方法：load_airtime(phone_number="0712345678", amount=100.0, currency_code="KES")
• 戻り値：成功時は確認メッセージ、失敗時はエラーメッセージ。

get_last_topups

• 説明：データベースから最新の N 件のエアタイムチャージ取引を取得します。
• 引数：
  • limit（int、任意）：取得する取引の件数です。デフォルトは 3 です。
• 使用方法：get_last_topups(limit=5)
• 戻り値：最近の取引を一覧にした整形済み文字列です。

sum_last_n_topups

• 説明：直近 N 件のチャージの合計を計算します。
• 引数：
  • n（int、任意）：合計する取引の件数です。デフォルトは 3 です。
• 使用方法：sum_last_n_topups(n=5)
• 戻り値：合計額を示す文字列です。取引の通貨が異なる場合はエラーを返します。

count_topups_by_number

• 説明：特定の電話番号へのチャージ成功回数を数えます。
• 引数：
  • phone_number（str）：照会する電話番号です。
• 使用方法：count_topups_by_number(phone_number="0712345678")
• 戻り値：指定した電話番号へのチャージの合計回数です。

プロンプトの例

MCP サーバーとのやり取りに使用できるプロンプトの例を以下に示します。

• 残高を確認する：

  • 「Africa's Talking アカウントの残高はいくらですか？」
  • 「エアタイムの残高を確認してください。」

• エアタイムを送る：

  • 「0712345678 に 100 KES 分のエアタイムを送ってください。」
  • 「電話番号 +254712345678 に 50 bob 分をチャージしてください。」
  • 「0755123456 に 200 UGX 分をチャージしてください。」

• 最近のチャージを表示する：

  • 「直近 3 件のエアタイム取引を表示してください。」
  • 「最近のチャージ 5 件を一覧表示してください。」

• 最近のチャージの合計を計算する：

  • 「直近 3 件のチャージの合計はいくらですか？」
  • 「直近 5 件の取引でいくら使いましたか？」

• チャージ回数を数える：

  • 「0712345678 に何回チャージしましたか？」
  • 「+254712345678 へのチャージ回数を数えてください。」

重要な注意事項

• 資金：エアタイムを送信できるよう、Africa's Talking アカウントに十分な資金があることを確認してください。
• 電話番号の形式：電話番号は、country 環境変数に基づいて自動的にフォーマットされます。
• データベース：SQLite データベース（airtime_transactions.db）は、プロジェクトディレクトリに自動的に作成されます。
• 対応モデル：この MCP サーバーは、Claude 3.7 Sonnet や GPT-4.1 Nano など、ツール呼び出しに対応したモデルで最適に動作します。

クレジット

• Africa's Talking API：基盤となるエアタイムサービスを提供しています。公式ドキュメントを参照してください。