validate_phone

Instructions

Validates a phone number using Abstract API's Phone Validation service.

This function checks the validity and other details of phone numbers from over 190 countries.
It returns detailed information about the phone number including format, country, location,
type, and carrier information.

Args:
    phone (str): The phone number to validate and verify.
    country (str, optional): The country's ISO code to indicate the phone number's country.
                            This helps the API append the corresponding country code to its analysis.
                            For example, use "US" for United States numbers.

Returns:
    dict[str, Any]: A dictionary containing detailed validation results. The dictionary
    includes the following keys:
        - "phone" (str): The phone number submitted for validation.
        - "valid" (bool): True if the phone number is valid, False otherwise.
        - "format" (dict): Object containing international and local formats.
            - "international" (str): International format with country code and "+" prefix.
            - "local" (str): Local/national format without international formatting.
        - "country" (dict): Object containing country details.
            - "code" (str): Two-letter ISO 3166-1 alpha-2 country code.
            - "name" (str): Name of the country where the phone number is registered.
            - "prefix" (str): Country's calling code prefix.
        - "location" (str): Location details (region, state/province, sometimes city).
        - "type" (str): Type of phone number. Possible values: "Landline", "Mobile",
                       "Satellite", "Premium", "Paging", "Special", "Toll_Free", "Unknown".
        - "carrier" (str): The carrier that the number is registered with.

Example:
    >>> await validate_phone("14152007986")
    {
        "phone": "14152007986",
        "valid": true,
        "format": {
            "international": "+14152007986",
            "local": "(415) 200-7986"
        },
        "country": {
            "code": "US",
            "name": "United States",
            "prefix": "+1"
        },
        "location": "California",
        "type": "mobile",
        "carrier": "T-Mobile USA, Inc."
    }

    >>> await validate_phone("2007986", "US")
    # Will validate with US country context

Raises:
    ValueError: If the API key is not found in the environment variables.
    requests.exceptions.HTTPError: If the API request fails (e.g., 4xx or 5xx error).
    Exception: For any other unexpected errors.

Implementation Reference

• server.py:130-217 (handler)

  The handler function for the 'validate_phone' tool. It is decorated with @mcp.tool(), which registers it as an MCP tool. The function validates phone numbers by calling the Abstract API phone validation endpoint, handling the request, parsing the response, and raising appropriate errors.

  @mcp.tool()
  async def validate_phone(phone: str, country: str | None = None) -> dict[str, Any]:
      """
      Validates a phone number using Abstract API's Phone Validation service.
  
      This function checks the validity and other details of phone numbers from over 190 countries.
      It returns detailed information about the phone number including format, country, location,
      type, and carrier information.
  
      Args:
          phone (str): The phone number to validate and verify.
          country (str, optional): The country's ISO code to indicate the phone number's country.
                                  This helps the API append the corresponding country code to its analysis.
                                  For example, use "US" for United States numbers.
  
      Returns:
          dict[str, Any]: A dictionary containing detailed validation results. The dictionary
          includes the following keys:
              - "phone" (str): The phone number submitted for validation.
              - "valid" (bool): True if the phone number is valid, False otherwise.
              - "format" (dict): Object containing international and local formats.
                  - "international" (str): International format with country code and "+" prefix.
                  - "local" (str): Local/national format without international formatting.
              - "country" (dict): Object containing country details.
                  - "code" (str): Two-letter ISO 3166-1 alpha-2 country code.
                  - "name" (str): Name of the country where the phone number is registered.
                  - "prefix" (str): Country's calling code prefix.
              - "location" (str): Location details (region, state/province, sometimes city).
              - "type" (str): Type of phone number. Possible values: "Landline", "Mobile",
                             "Satellite", "Premium", "Paging", "Special", "Toll_Free", "Unknown".
              - "carrier" (str): The carrier that the number is registered with.
  
      Example:
          >>> await validate_phone("14152007986")
          {
              "phone": "14152007986",
              "valid": true,
              "format": {
                  "international": "+14152007986",
                  "local": "(415) 200-7986"
              },
              "country": {
                  "code": "US",
                  "name": "United States",
                  "prefix": "+1"
              },
              "location": "California",
              "type": "mobile",
              "carrier": "T-Mobile USA, Inc."
          }
  
          >>> await validate_phone("2007986", "US")
          # Will validate with US country context
  
      Raises:
          ValueError: If the API key is not found in the environment variables.
          requests.exceptions.HTTPError: If the API request fails (e.g., 4xx or 5xx error).
          Exception: For any other unexpected errors.
      """
      # Check if the API key is available
      if not ABSTRACT_API_KEY:
          raise ValueError("API key not found in environment variables.")
  
      # Construct the API URL
      api_url = f"{PHONE_VALIDATION_API_URL}?api_key={ABSTRACT_API_KEY}&phone={phone}"
  
      # Add country parameter if provided
      if country:
          api_url += f"&country={country}"
  
      try:
          # Make the API request (ignoring SSL verification)
          response = requests.get(api_url, verify=False)
          response.raise_for_status()  # Raise an error for bad responses (4xx, 5xx)
  
          # Parse the JSON response
          result = response.json()
  
          # Return the validation results
          return result
  
      except requests.exceptions.HTTPError as http_err:
          # Handle HTTP errors (e.g., 4xx, 5xx)
          raise requests.exceptions.HTTPError(f"HTTP error occurred: {http_err}")
      except Exception as err:
          # Handle any other errors
          raise Exception(f"An error occurred: {err}")

• server.py:130-130 (registration)

  The @mcp.tool() decorator registers the validate_phone function as a tool in the FastMCP server, automatically handling schema inference from type hints and docstring.

  @mcp.tool()

• server.py:131-131 (schema)

  Input schema defined by function parameters (phone: str required, country: str optional). Output schema described in detail in the docstring as a dict with keys like 'phone', 'valid', 'format', 'country', etc.

  async def validate_phone(phone: str, country: str | None = None) -> dict[str, Any]: