Phone Carrier Detector MCP Server

Instructions

Implementation Reference

• mcp_server.py:28-57 (handler)

  The core handler function for the 'detect_carrier' tool. Validates the 11-digit Chinese phone number format using regex, extracts the 7-digit prefix, and queries the PHONE_DATABASE for carrier and location info.

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

• mcp_server.py:107-120 (schema)

  The JSON schema definition for the 'detect_carrier' tool, including input schema requiring a 'phone_number' string.

  {
      "name": "detect_carrier",
      "description": "Detect carrier and location for a single phone number",
      "inputSchema": {
          "type": "object",
          "properties": {
              "phone_number": {
                  "type": "string",
                  "description": "Phone number to detect (11 digits)",
              }
          },
          "required": ["phone_number"],
      },
  },

• mcp_server.py:143-168 (registration)

  Registration and dispatch logic in call_tool method: checks if tool name is 'detect_carrier', validates arguments, calls the handler, and formats the JSON-RPC response.

  if name == "detect_carrier":
      phone_number = arguments.get("phone_number")
      if not phone_number:
          return {
              "jsonrpc": "2.0",
              "id": self.request_id,
              "error": {
                  "code": -32602,
                  "message": "Missing required parameter: phone_number",
              },
          }
      result = detect_carrier(phone_number)
      return {
          "jsonrpc": "2.0",
          "id": self.request_id,
          "result": {
              "content": [
                  {
                      "type": "text",
                      "text": json.dumps(
                          result, ensure_ascii=False, indent=2
                      ),
                  }
              ]
          },
      }

• mcp_server.py:14-22 (helper)

  Helper function to load the phone carrier database from JSON file, used by the global PHONE_DATABASE variable essential for carrier detection.

  def load_phone_database():
      """加载手机号数据库"""
      try:
          with open("data/phone_database.json", "r", encoding="utf-8") as f:
              return json.load(f)
      except FileNotFoundError:
          print("警告: phone_database.json 文件不存在，使用默认数据库")
          return {}

• mcp_server.py:25-25 (helper)

  Global PHONE_DATABASE initialized by load_phone_database(), providing the lookup data for detect_carrier.

  PHONE_DATABASE = load_phone_database()