Phone Carrier Detector MCP Server

Instructions

Implementation Reference

• mcp_server.py:59-79 (handler)

  The main handler function for the batch_detect_carriers tool. Validates input as a list of up to 100 strings, calls detect_carrier for each valid phone number, and returns aggregated results.

  def batch_detect_carriers(phone_numbers: list) -> Dict[str, Any]:
      """批量检测手机号运营商和归属地"""
      if not isinstance(phone_numbers, list):
          return {"success": False, "error": "Input must be a list of phone numbers"}
  
      if len(phone_numbers) > 100:
          return {
              "success": False,
              "error": "Maximum 100 phone numbers allowed per batch",
          }
  
      results = []
      for phone in phone_numbers:
          if not isinstance(phone, str):
              results.append(
                  {"success": False, "error": f"Invalid phone number type: {type(phone)}"}
              )
          else:
              results.append(detect_carrier(phone))
  
      return {"success": True, "results": results, "total": len(results)}

• mcp_server.py:124-134 (schema)

  Input schema definition for the batch_detect_carriers tool, specifying that it takes an object with a required 'phone_numbers' array of strings.

  "inputSchema": {
      "type": "object",
      "properties": {
          "phone_numbers": {
              "type": "array",
              "items": {"type": "string"},
              "description": "List of phone numbers to detect (max 100)",
          }
      },
      "required": ["phone_numbers"],
  },

• mcp_server.py:121-135 (registration)

  Registration of the batch_detect_carriers tool in the list_tools method, including name, description, and input schema.

  {
      "name": "batch_detect_carriers",
      "description": "Detect carriers and locations for multiple phone numbers",
      "inputSchema": {
          "type": "object",
          "properties": {
              "phone_numbers": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "List of phone numbers to detect (max 100)",
              }
          },
          "required": ["phone_numbers"],
      },
  },

• mcp_server.py:28-56 (helper)

  Helper function used by batch_detect_carriers to detect carrier and location for individual phone numbers using prefix lookup in the PHONE_DATABASE.

  def detect_carrier(phone_number: str) -> Dict[str, Any]:
      """检测手机号运营商和归属地"""
      # 验证手机号格式
      if not re.match(r"^1[3-9]\d{9}$", phone_number):
          return {
              "success": False,
              "error": "Invalid phone number format. Must be 11 digits starting with 1.",
          }
  
      # 提取前缀（前7位）
      prefix = phone_number[:7]
  
      # 查找数据库
      if prefix in PHONE_DATABASE:
          info = PHONE_DATABASE[prefix]
          return {
              "success": True,
              "phone_number": phone_number,
              "carrier": info["carrier"],
              "carrier_cn": info["carrier_cn"],
              "province": info["province"],
              "city": info["city"],
              "prefix": prefix,
          }
      else:
          return {
              "success": False,
              "error": f"Phone number prefix {prefix} not found in database",
          }