count_topups_by_number
Track and count successful airtime top-ups to a specific phone number using the Africa's Talking API, enabling users to analyze transaction patterns for supported African countries.
Instructions
Count the number of successful top-ups to a specific phone number.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| phone_number | Yes |
Implementation Reference
- main.py:263-290 (handler)The handler function for the 'count_topups_by_number' tool. It formats the phone number using the helper function, queries the SQLite database to count transactions for that number, and returns the count or an error message.@mcp.tool() async def count_topups_by_number(phone_number: str) -> str: """Counts the number of top-ups for a specific phone number. Args: phone_number (str): The phone number to count transactions for. Returns: str: The total count of top-ups for the given number or an error message. """ try: formatted_number = format_phone_number(phone_number) with sqlite3.connect(DB_PATH) as conn: cursor = conn.cursor() cursor.execute( """ SELECT COUNT(*) as count FROM transactions WHERE phone_number = ? """, (formatted_number,), ) count = cursor.fetchone()[0] return f"Number of successful top-ups to {formatted_number}: {count}" except Exception as e: return f"Error counting top-ups: {str(e)}"
- main.py:68-99 (helper)Supporting utility function that formats the input phone number by prepending the appropriate country code based on the configured user country. This is called within the tool handler.def format_phone_number(phone_number): """Formats a phone number to include the international country code. This function takes a phone number as a string and formats it based on the user's country, which is determined by the `user_country` global variable. It handles numbers that start with '0', '+', or a digit. Args: phone_number (str): The phone number to be formatted. Returns: str: The phone number with the country code prepended. Raises: ValueError: If the `user_country` is not in the `COUNTRY_CODES` map. """ phone_number = str(phone_number).strip() if user_country not in COUNTRY_CODES: raise ValueError( f"Invalid or unset country: {user_country}. Supported countries: {list(COUNTRY_CODES.keys())}" ) country_code = COUNTRY_CODES[user_country] if phone_number.startswith("0"): return country_code + phone_number[1:] elif phone_number.startswith("+"): return phone_number else: return country_code + phone_number