hkopenai.hk-climate-mcp-server 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

hkopenai/hk_climate_mcp_server/tools/radiation.py

@@ -0,0 +1,206 @@
+import requests
+from datetime import datetime, timedelta
+from typing import Dict, Any, Optional
+
+# Station names in different languages: en (English), tc (Traditional Chinese), sc (Simplified Chinese)
+VALID_STATIONS = {
+    'en': {
+        'CCH': 'Cheung Chau',
+        'CLK': 'Chek Lap Kok',
+        'EPC': 'Ping Chau',
+        'HKO': 'Hong Kong Observatory',
+        'HKP': 'Hong Kong Park',
+        'HKS': 'Wong Chuk Hang',
+        'HPV': 'Happy Valley',
+        'JKB': 'Tseung Kwan O',
+        'KAT': 'Kat O',
+        'KLT': 'Kowloon City',
+        'KP': 'Kings Park',
+        'KTG': 'Kwun Tong',
+        'LFS': 'Lau Fau Shan',
+        'PLC': 'Tai Mei Tuk',
+        'SE1': 'Kai Tak Runway Park',
+        'SEK': 'Shek Kong',
+        'SHA': 'Sha Tin',
+        'SKG': 'Sai Kung',
+        'SKW': 'Shau Kei Wan',
+        'SSP': 'Sham Shui Po',
+        'STK': 'Sha Tau Kok',
+        'STY': 'Stanley',
+        'SWH': 'Sai Wan Ho',
+        'TAP': 'Tap Mun',
+        'TBT': 'Tsim Bei Tsui',
+        'TKL': 'Ta Kwu Ling',
+        'TUN': 'Tuen Mun',
+        'TW': 'Tsuen Wan Shing Mun Valley',
+        'TWN': 'Tsuen Wan Ho Koon',
+        'TY1': 'Tsing Yi',
+        'WTS': 'Wong Tai Sin',
+        'YCT': 'Tai Po',
+        'YLP': 'Yuen Long Park',
+        'YNF': 'Yuen Ng Fan'
+    },
+    'tc': {
+        'CCH': '長洲',
+        'CLK': '赤鱲角',
+        'EPC': '平洲',
+        'HKO': '香港天文台',
+        'HKP': '香港公園',
+        'HKS': '黃竹坑',
+        'HPV': '跑馬地',
+        'JKB': '將軍澳',
+        'KAT': '吉澳',
+        'KLT': '九龍城',
+        'KP': '京士柏',
+        'KTG': '觀塘',
+        'LFS': '流浮山',
+        'PLC': '大美督',
+        'SE1': '啟德跑道公園',
+        'SEK': '石崗',
+        'SHA': '沙田',
+        'SKG': '西貢',
+        'SKW': '筲箕灣',
+        'SSP': '深水埗',
+        'STK': '沙頭角',
+        'STY': '赤柱',
+        'SWH': '西灣河',
+        'TAP': '塔門',
+        'TBT': '尖鼻咀',
+        'TKL': '打鼓嶺',
+        'TUN': '屯門',
+        'TW': '荃灣城門谷',
+        'TWN': '荃灣可觀',
+        'TY1': '青衣',
+        'WTS': '黃大仙',
+        'YCT': '大埔',
+        'YLP': '元朗公園',
+        'YNF': '元五墳'
+    },
+    'sc': {
+        'CCH': '长洲',
+        'CLK': '赤鱲角',
+        'EPC': '平洲',
+        'HKO': '香港天文台',
+        'HKP': '香港公园',
+        'HKS': '黄竹坑',
+        'HPV': '跑马地',
+        'JKB': '将军澳',
+        'KAT': '吉澳',
+        'KLT': '九龙城',
+        'KP': '京士柏',
+        'KTG': '观塘',
+        'LFS': '流浮山',
+        'PLC': '大美督',
+        'SE1': '启德跑道公园',
+        'SEK': '石岗',
+        'SHA': '沙田',
+        'SKG': '西贡',
+        'SKW': '筲箕湾',
+        'SSP': '深水埗',
+        'STK': '沙头角',
+        'STY': '赤柱',
+        'SWH': '西湾河',
+        'TAP': '塔门',
+        'TBT': '尖鼻咀',
+        'TKL': '打鼓岭',
+        'TUN': '屯门',
+        'TW': '荃湾城门谷',
+        'TWN': '荃湾可观',
+        'TY1': '青衣',
+        'WTS': '黄大仙',
+        'YCT': '大埔',
+        'YLP': '元朗公园',
+        'YNF': '元五坟'
+    }
+}
+
+
+def get_weather_radiation_report(
+    date: str = "Unknown",
+    station: str = "Unknown",
+    lang: str = "en"
+) -> Dict[str, Any]:
+    """
+    Get weather and radiation level report for Hong Kong.
+
+    Args:
+        date: Mandatory date in YYYYMMDD format (e.g., 20250618)
+        station: Mandatory station code (e.g., 'HKO' for Hong Kong Observatory). 
+                 If not provided or invalid, returns an error message.
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing weather and radiation data or an error message if station is invalid
+    """
+    
+    # Select the station dictionary based on the language, default to English
+    stations_dict = VALID_STATIONS.get(lang, VALID_STATIONS['en'])
+
+    if not station or station not in stations_dict:
+        return {"error": "Invalid or missing station code. Use the 'get_radiation_station_codes' tool to retrieve the list of valid station codes."}
+        
+    if not date:
+        return {"error": "Date parameter is mandatory in YYYYMMDD format (e.g., 20250618)"}
+        
+    try:
+        datetime.strptime(date, '%Y%m%d')
+    except ValueError:
+        return {"error": "Invalid date format. Date must be in YYYYMMDD format (e.g., 20250618)"}
+        
+    if is_date_in_future(date):
+        yesterday = (datetime.now() - timedelta(days=1)).strftime('%Y%m%d')
+        return {"error": f"Date must be yesterday or before in YYYYMMDD format. Expected {yesterday} or earlier, but got {date}"}
+        
+    params = {
+        'dataType': 'RYES',
+        'lang': lang,
+        'rformat': 'json',
+        'date': date,
+        'station': station
+    }
+
+    try:
+        response = requests.get(
+            'https://data.weather.gov.hk/weatherAPI/opendata/opendata.php',
+            params=params
+        )
+        response.raise_for_status()
+        try:
+            return response.json()
+        except ValueError:
+            return {"error": "Failed to parse response as JSON. This could be due to invalid parameters or data not being updated. Please try again later."}
+    except requests.RequestException as e:
+        return {"error": f"Failed to fetch data: {str(e)}. Please try again later."}
+
+
+def get_radiation_station_codes(lang: str = "en") -> Dict[str, str]:
+    """
+    Get a dictionary of station codes and their corresponding names for weather and radiation reports in Hong Kong used in radiation API.
+    
+    Args:
+        lang: Language code (en/tc/sc, default: en)
+    
+    Returns:
+        Dict mapping station codes to station names in the specified language.
+    """
+    # Return the dictionary for the specified language, default to English
+    return VALID_STATIONS.get(lang, VALID_STATIONS['en'])
+
+
+def is_date_in_future(date_str: str) -> bool:
+    """
+    Check if the provided date is in the future compared to today.
+    
+    Args:
+        date_str: Date string in YYYYMMDD format.
+        
+    Returns:
+        bool: True if the date is today or in the future, False otherwise.
+    """
+    try:
+        input_date = datetime.strptime(date_str, '%Y%m%d')
+        today = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
+        input_date = input_date.replace(hour=0, minute=0, second=0, microsecond=0)
+        return input_date >= today
+    except ValueError:
+        return False

hkopenai/hk_climate_mcp_server/tools/temperature.py

@@ -0,0 +1,119 @@
+import requests
+from typing import Dict, Any, Optional
+
+def get_daily_mean_temperature(
+    station: str,
+    year: Optional[int] = None,
+    month: Optional[int] = None,
+    lang: str = "en"
+) -> Dict[str, Any]:
+    """
+    Get daily mean temperature data for a specific station.
+
+    Args:
+        station: Station code (e.g. 'HKO' for Hong Kong Observatory)
+        year: Optional year (varies by station)
+        month: Optional month (1-12)
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing temperature data with fields and data arrays
+    """
+    params = {
+        'dataType': 'CLMTEMP',
+        'lang': lang,
+        'rformat': 'json',
+        'station': station
+    }
+    if year: params['year'] = str(year)
+    if month: params['month'] = str(month)
+
+    response = requests.get(
+        'https://data.weather.gov.hk/weatherAPI/opendata/opendata.php',
+        params=params
+    )
+    try:
+        response.raise_for_status()
+        return response.json()
+    except requests.exceptions.JSONDecodeError as e:
+        return {"error": f"Failed to parse API response: {str(e)}. This might indicate invalid parameters or no data for the given request."}
+    except requests.RequestException as e:
+        return {"error": f"Failed to fetch data: {str(e)}."}
+
+def get_daily_max_temperature(
+    station: str,
+    year: Optional[int] = None,
+    month: Optional[int] = None,
+    lang: str = "en"
+) -> Dict[str, Any]:
+    """
+    Get daily maximum temperature data for a specific station.
+
+    Args:
+        station: Station code (e.g. 'HKO' for Hong Kong Observatory)
+        year: Optional year (varies by station)
+        month: Optional month (1-12)
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing temperature data with fields and data arrays
+    """
+    params = {
+        'dataType': 'CLMMAXT',
+        'lang': lang,
+        'rformat': 'json',
+        'station': station
+    }
+    if year: params['year'] = str(year)
+    if month: params['month'] = str(month)
+
+    response = requests.get(
+        'https://data.weather.gov.hk/weatherAPI/opendata/opendata.php',
+        params=params
+    )
+    try:
+        response.raise_for_status()
+        return response.json()
+    except requests.exceptions.JSONDecodeError as e:
+        return {"error": f"Failed to parse API response: {str(e)}. This might indicate invalid parameters or no data for the given request."}
+    except requests.RequestException as e:
+        return {"error": f"Failed to fetch data: {str(e)}."}
+
+def get_daily_min_temperature(
+    station: str,
+    year: Optional[int] = None,
+    month: Optional[int] = None,
+    lang: str = "en"
+) -> Dict[str, Any]:
+    """
+    Get daily minimum temperature data for a specific station.
+
+    Args:
+        station: Station code (e.g. 'HKO' for Hong Kong Observatory)
+        year: Optional year (varies by station)
+        month: Optional month (1-12)
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing temperature data with fields and data arrays
+    """
+    params = {
+        'dataType': 'CLMMINT',
+        'lang': lang,
+        'rformat': 'json',
+        'station': station
+    }
+    if year: params['year'] = str(year)
+    if month: params['month'] = str(month)
+
+    response = requests.get(
+        'https://data.weather.gov.hk/weatherAPI/opendata/opendata.php',
+        params=params
+    )
+    try:
+        response.raise_for_status()
+        return response.json()
+    except requests.exceptions.JSONDecodeError as e:
+        return {"error": f"Failed to parse API response: {str(e)}. This might indicate invalid parameters or no data for the given request."}
+    except requests.RequestException as e:
+        return {"error": f"Failed to fetch data: {str(e)}."}

hkopenai/hk_climate_mcp_server/tools/tides.py

@@ -0,0 +1,165 @@
+import requests
+from typing import Dict, Any, Optional
+
+# Station names for tide data in different languages: en (English), tc (Traditional Chinese), sc (Simplified Chinese)
+VALID_TIDE_STATIONS = {
+    'en': {
+        'CCH': 'Cheung Chau',
+        'CLK': 'Chek Lap Kok',
+        'CMW': 'Chi Ma Wan',
+        'KCT': 'Kwai Chung',
+        'KLW': 'Ko Lau Wan',
+        'LOP': 'Lok On Pai',
+        'MWC': 'Ma Wan',
+        'QUB': 'Quarry Bay',
+        'SPW': 'Shek Pik',
+        'TAO': 'Tai O',
+        'TBT': 'Tsim Bei Tsui',
+        'TMW': 'Tai Miu Wan',
+        'TPK': 'Tai Po Kau',
+        'WAG': 'Waglan Island'
+    },
+    'tc': {
+        'CCH': '長洲',
+        'CLK': '赤鱲角',
+        'CMW': '芝麻灣',
+        'KCT': '葵涌',
+        'KLW': '高流灣',
+        'LOP': '樂安排',
+        'MWC': '馬灣',
+        'QUB': '鰂魚涌',
+        'SPW': '石壁',
+        'TAO': '大澳',
+        'TBT': '尖鼻咀',
+        'TMW': '大廟灣',
+        'TPK': '大埔滘',
+        'WAG': '橫瀾島'
+    },
+    'sc': {
+        'CCH': '长洲',
+        'CLK': '赤鱲角',
+        'CMW': '芝麻湾',
+        'KCT': '葵涌',
+        'KLW': '高流湾',
+        'LOP': '乐安排',
+        'MWC': '马湾',
+        'QUB': '鲗鱼涌',
+        'SPW': '石壁',
+        'TAO': '大澳',
+        'TBT': '尖鼻咀',
+        'TMW': '大庙湾',
+        'TPK': '大埔滘',
+        'WAG': '横澜岛'
+    }
+}
+
+def get_hourly_tides(
+    station: str,
+    year: int,
+    month: Optional[int] = None,
+    day: Optional[int] = None,
+    hour: Optional[int] = None,
+    lang: str = "en"
+) -> Dict[str, Any]:
+    """
+    Get hourly heights of astronomical tides for a specific station in Hong Kong.
+
+    Args:
+        station: Station code (e.g. 'CCH' for Cheung Chau)
+        year: Year (2022-2024)
+        month: Optional month (1-12)
+        day: Optional day (1-31)
+        hour: Optional hour (1-24)
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing tide data with fields and data arrays
+    """
+    params = {
+        'dataType': 'HHOT',
+        'lang': lang,
+        'rformat': 'json',
+        'station': station,
+        'year': year
+    }
+    if month: params['month'] = str(month)
+    if day: params['day'] = str(day)
+    if hour: params['hour'] = str(hour)
+
+    response = requests.get(
+        'https://data.weather.gov.hk/weatherAPI/opendata/opendata.php',
+        params=params
+    )
+    try:
+        response.raise_for_status()
+        # Decode response content with utf-8-sig to handle potential BOM
+        content = response.content.decode('utf-8-sig')
+        import json
+        return json.loads(content)
+    except (requests.RequestException, UnicodeDecodeError, ValueError) as e:
+        return {"error": f"Failed to fetch data: {str(e)}."}
+
+def get_tide_station_codes(lang: str = "en") -> Dict[str, str]:
+    """
+    Get a dictionary of station codes and their corresponding names for tide reports in Hong Kong.
+    
+    Args:
+        lang: Language code (en/tc/sc, default: en)
+    
+    Returns:
+        Dict mapping station codes to station names in the specified language.
+    """
+    # Return the dictionary for the specified language, default to English
+    return VALID_TIDE_STATIONS.get(lang, VALID_TIDE_STATIONS['en'])
+
+def get_high_low_tides(
+    station: str,
+    year: int,
+    month: Optional[int] = None,
+    day: Optional[int] = None,
+    hour: Optional[int] = None,
+    lang: str = "en",
+) -> Dict[str, Any]:
+    """
+    Get times and heights of astronomical high and low tides for a specific station.
+
+    Args:
+        station: Station code (e.g. 'CCH' for Cheung Chau)
+        year: Year (2022-2024)
+        month: Optional month (1-12)
+        day: Optional day (1-31)
+        hour: Optional hour (1-24)
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing tide data with fields and data arrays or an error message if station is invalid
+    """
+    # Select the station dictionary based on the language, default to English
+    stations_dict = VALID_TIDE_STATIONS.get(lang, VALID_TIDE_STATIONS['en'])
+    
+    if not station or station not in stations_dict:
+        return {"error": "Invalid or missing station code. Use the 'get_tide_station_codes' tool to retrieve the list of valid station codes."}
+        
+    params = {
+        'dataType': 'HLT',
+        'lang': lang,
+        'rformat': 'json',
+        'station': station,
+        'year': year
+    }
+    if month: params['month'] = str(month)
+    if day: params['day'] = str(day)
+    if hour: params['hour'] = str(hour)
+
+    response = requests.get(
+        'https://data.weather.gov.hk/weatherAPI/opendata/opendata.php',
+        params=params
+    )
+    try:
+        response.raise_for_status()
+        # Decode response content with utf-8-sig to handle potential BOM
+        content = response.content.decode('utf-8-sig')
+        import json
+        return json.loads(content)
+    except (requests.RequestException, UnicodeDecodeError, ValueError) as e:
+        return {"error": f"Failed to fetch data: {str(e)}."}

hkopenai/hk_climate_mcp_server/tools/visibility.py

@@ -0,0 +1,20 @@
+import requests
+from typing import Dict, Any
+
+def get_visibility_data(lang: str = "en") -> Dict[str, Any]:
+    """
+    Get latest 10-minute mean visibility data for Hong Kong.
+
+    Args:
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing visibility data with fields and data arrays
+    """
+    url = f"https://data.weather.gov.hk/weatherAPI/opendata/opendata.php?dataType=LTMV&lang={lang}&rformat=json"
+    response = requests.get(url)
+    try:
+        response.raise_for_status()
+        return response.json()
+    except (requests.RequestException, ValueError) as e:
+        return {"error": f"Failed to fetch data: {str(e)}."}

hkopenai/hk_climate_mcp_server/tools/warnings.py

@@ -0,0 +1,77 @@
+import requests
+from typing import Dict, Any
+
+def get_weather_warning_summary(lang: str = "en") -> Dict[str, Any]:
+    """
+    Get weather warning summary for Hong Kong.
+
+    Args:
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing:
+            - warningMessage: List of warning messages
+            - updateTime: Last update time
+    """
+    url = f"https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=warnsum&lang={lang}"
+    response = requests.get(url)
+    try:
+        response.raise_for_status()
+        data = response.json()
+    except (requests.RequestException, ValueError) as e:
+        return {"error": f"Failed to fetch data: {str(e)}."}
+    
+    return {
+        "warningMessage": data.get("warningMessage", []),
+        "updateTime": data.get("updateTime", ""),
+    }
+
+def get_weather_warning_info(lang: str = "en") -> Dict[str, Any]:
+    """
+    Get detailed weather warning information for Hong Kong.
+
+    Args:
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing:
+            - warningStatement: Warning statement
+            - updateTime: Last update time
+    """
+    url = f"https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=warningInfo&lang={lang}"
+    response = requests.get(url)
+    try:
+        response.raise_for_status()
+        data = response.json()
+    except (requests.RequestException, ValueError) as e:
+        return {"error": f"Failed to fetch data: {str(e)}."}
+    
+    return {
+        "warningStatement": data.get("warningStatement", ""),
+        "updateTime": data.get("updateTime", ""),
+    }
+
+def get_special_weather_tips(lang: str = "en") -> Dict[str, Any]:
+    """
+    Get special weather tips for Hong Kong.
+
+    Args:
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing:
+            - specialWeatherTips: List of special weather tips
+            - updateTime: Last update time
+    """
+    url = f"https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=swt&lang={lang}"
+    response = requests.get(url)
+    try:
+        response.raise_for_status()
+        data = response.json()
+    except (requests.RequestException, ValueError) as e:
+        return {"error": f"Failed to fetch data: {str(e)}."}
+    
+    return {
+        "specialWeatherTips": data.get("specialWeatherTips", []),
+        "updateTime": data.get("updateTime", ""),
+    }