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

hkopenai/hk_climate_mcp_server/__init__.py

@@ -1,21 +1,6 @@
 """Hong Kong climate MCP Server package."""
-from .app import main
-from .tool_weather import (
-    get_current_weather,
-    get_9_day_weather_forecast,
-    get_local_weather_forecast,
-    get_weather_warning_summary,
-    get_weather_warning_info,
-    get_special_weather_tips
-)
+from .server import main
+
 
 __version__ = "0.1.0"
-__all__ = [
-    'main',
-    'get_current_weather',
-    'get_9_day_weather_forecast',
-    'get_local_weather_forecast',
-    'get_weather_warning_summary',
-    'get_weather_warning_info',
-    'get_special_weather_tips'
-]
+__all__ = ['main']

hkopenai/hk_climate_mcp_server/__main__.py

@@ -1,4 +1,4 @@
-from hkopenai.hk_climate_mcp_server.app import main
+from hkopenai.hk_climate_mcp_server.server import main
 
 if __name__ == "__main__":
     main()

hkopenai/hk_climate_mcp_server/server.py

@@ -0,0 +1,247 @@
+import argparse
+from fastmcp import FastMCP
+from typing import Dict, Annotated, Optional
+from pydantic import Field
+from hkopenai.hk_climate_mcp_server.tools import astronomical
+from hkopenai.hk_climate_mcp_server.tools import current_weather
+from hkopenai.hk_climate_mcp_server.tools import forecast
+from hkopenai.hk_climate_mcp_server.tools import lightning
+from hkopenai.hk_climate_mcp_server.tools import radiation
+from hkopenai.hk_climate_mcp_server.tools import temperature
+from hkopenai.hk_climate_mcp_server.tools import tides
+from hkopenai.hk_climate_mcp_server.tools import visibility
+from hkopenai.hk_climate_mcp_server.tools import warnings
+
+def create_mcp_server():
+    """Create and configure the HKO MCP server"""
+    mcp = FastMCP(name="HKOServer")
+
+    @mcp.tool(
+        description="Get current weather observations, warnings, temperature, humidity and rainfall in Hong Kong from Hong Kong Observatory, with optional region or place in Hong Kong",
+    )
+    def get_current_weather(region: str = "Hong Kong Observatory") -> Dict:
+        return current_weather.get_current_weather(region)
+
+    @mcp.tool(
+        description="Get the 9-day weather forecast for Hong Kong including general situation, daily forecasts, sea and soil temperatures",
+    )
+    def get_9_day_weather_forecast(lang: str = "en") -> Dict:
+        return forecast.get_9_day_weather_forecast(lang)
+
+    @mcp.tool(
+        description="Get local weather forecast for Hong Kong including forecast description, outlook and update time",
+    )
+    def get_local_weather_forecast(lang: str = "en") -> Dict:
+        return forecast.get_local_weather_forecast(lang)
+
+    @mcp.tool(
+        description="Get weather warning summary for Hong Kong including warning messages and update time",
+    )
+    def get_weather_warning_summary(lang: str = "en") -> Dict:
+        return warnings.get_weather_warning_summary(lang)
+
+    @mcp.tool(
+        description="Get detailed weather warning information for Hong Kong including warning statement and update time",
+    )
+    def get_weather_warning_info(lang: str = "en") -> Dict:
+        return warnings.get_weather_warning_info(lang)
+
+    @mcp.tool(
+        description="Get special weather tips for Hong Kong including tips list and update time",
+    )
+    def get_special_weather_tips(lang: str = "en") -> Dict:
+        return warnings.get_special_weather_tips(lang)
+
+    @mcp.tool(
+        description="Get latest 10-minute mean visibility data for Hong Kong",
+    )
+    def get_visibility_data(lang: str = "en") -> Dict:
+        return visibility.get_visibility_data(lang)
+
+    @mcp.tool(
+        description="Get cloud-to-ground and cloud-to-cloud lightning count data",
+    )
+    def get_lightning_data(lang: str = "en") -> Dict:
+        return lightning.get_lightning_data(lang)
+
+    @mcp.tool(
+        description="Get times of moonrise, moon transit and moonset",
+    )
+    def get_moon_times(
+        year: int,
+        month: Optional[int] = None,
+        day: Optional[int] = None,
+        lang: str = "en"
+    ) -> Dict:
+        return astronomical.get_moon_times(
+            year=year,
+            month=month,
+            day=day,
+            lang=lang
+        )
+
+    @mcp.tool(
+        description="Get hourly heights of astronomical tides for a specific station in Hong Kong",
+    )
+    def get_hourly_tides(
+        station: str,
+        year: int,
+        month: Optional[int] = None,
+        day: Optional[int] = None,
+        hour: Optional[int] = None,
+        lang: str = "en"
+    ) -> Dict:
+        return tides.get_hourly_tides(
+            station=station,
+            year=year,
+            month=month,
+            day=day,
+            hour=hour,
+            lang=lang
+        )
+
+    @mcp.tool(
+        description="Get times and heights of astronomical high and low tides for a specific station in Hong Kong",
+    )
+    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:
+        return tides.get_high_low_tides(
+            station=station,
+            year=year,
+            month=month,
+            day=day,
+            hour=hour,
+            lang=lang
+        )
+
+    @mcp.tool(
+        description="Get a list of tide station codes and their corresponding names for tide reports in Hong Kong.",
+    )
+    def get_tide_station_codes(lang: str = "en") -> Dict:
+        return tides.get_tide_station_codes(lang)
+
+    @mcp.tool(
+        description="Get times of sunrise, sun transit and sunset for Hong Kong",
+    )
+    def get_sunrise_sunset_times(
+        year: int,
+        month: Optional[int] = None,
+        day: Optional[int] = None,
+        lang: str = "en"
+    ) -> Dict:
+        return astronomical.get_sunrise_sunset_times(
+            year=year,
+            month=month,
+            day=day,
+            lang=lang
+        )
+
+    @mcp.tool(
+        description="Get Gregorian-Lunar calendar conversion data",
+    )
+    def get_gregorian_lunar_calendar(
+        year: int,
+        month: Optional[int] = None,
+        day: Optional[int] = None,
+        lang: str = "en"
+    ) -> Dict:
+        return astronomical.get_gregorian_lunar_calendar(
+            year=year,
+            month=month,
+            day=day,
+            lang=lang
+        )
+
+    @mcp.tool(
+        description="Get daily mean temperature data for a specific station in Hong Kong",
+    )
+    def get_daily_mean_temperature(
+        station: str,
+        year: Optional[int] = None,
+        month: Optional[int] = None,
+        lang: str = "en"
+    ) -> Dict:
+        return temperature.get_daily_mean_temperature(
+            station=station,
+            year=year,
+            month=month,
+            lang=lang
+        )
+
+    @mcp.tool(
+        description="Get daily maximum temperature data for a specific station in Hong Kong",
+    )
+    def get_daily_max_temperature(
+        station: str,
+        year: Optional[int] = None,
+        month: Optional[int] = None,
+        lang: str = "en"
+    ) -> Dict:
+        return temperature.get_daily_max_temperature(
+            station=station,
+            year=year,
+            month=month,
+            lang=lang
+        )
+
+    @mcp.tool(
+        description="Get daily minimum temperature data for a specific station in Hong Kong",
+    )
+    def get_daily_min_temperature(
+        station: str,
+        year: Optional[int] = None,
+        month: Optional[int] = None,
+        lang: str = "en"
+    ) -> Dict:
+        return temperature.get_daily_min_temperature(
+            station=station,
+            year=year,
+            month=month,
+            lang=lang
+        )
+
+    @mcp.tool(
+        description="Get weather and radiation level report for Hong Kong. Date must be in YYYYMMDD format and should be yesterday or before. Station must be a valid code like 'HKO' for Hong Kong Observatory.",
+    )
+    def get_weather_radiation_report(
+        date: Annotated[str, Field(description="Date in yyyyMMdd format, eg, 20250618")],
+        station: Annotated[str, Field(description="Station code in 3 characters in capital letters, eg, HKO")],
+        lang: Annotated[Optional[str], Field(description="Language (en/tc/sc)", json_schema_extra={"enum": ["en", "tc", "sc"]})] = 'en',
+    ) -> Dict:
+        return radiation.get_weather_radiation_report(
+            date=date,
+            station=station,
+            lang=lang or 'en'
+        )
+
+    @mcp.tool(
+        description="Get a list of weather station codes and their corresponding names for radiation reports in Hong Kong.",
+    )
+    def get_radiation_station_codes(lang: str = "en") -> Dict:
+        return radiation.get_radiation_station_codes(lang)
+    
+    return mcp
+
+def main():
+    parser = argparse.ArgumentParser(description='HKO MCP Server')
+    parser.add_argument('-s', '--sse', action='store_true',
+                       help='Run in SSE mode instead of stdio')
+    args = parser.parse_args()
+
+    server = create_mcp_server()
+    
+    if args.sse:
+        server.run(transport="streamable-http")
+        print("HKO MCP Server running in SSE mode on port 8000")
+    else:
+        server.run()
+        print("HKO MCP Server running in stdio mode")
+
+if __name__ == "__main__":
+    main()

hkopenai/hk_climate_mcp_server/tools/astronomical.py

@@ -0,0 +1,109 @@
+import requests
+from typing import Dict, Any, Optional
+
+def get_moon_times(year: int, month: Optional[int] = None, 
+                  day: Optional[int] = None, lang: str = "en") -> Dict[str, Any]:
+    """
+    Get times of moonrise, moon transit and moonset.
+
+    Args:
+        year: Year (2018-2024)
+        month: Optional month (1-12)
+        day: Optional day (1-31)
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing moon times data with fields and data arrays
+    """
+    params = {
+        'dataType': 'MRS',
+        'lang': lang,
+        'rformat': 'json',
+        'year': year
+    }
+    if month: params['month'] = str(month)
+    if day: params['day'] = str(day)
+
+    response = requests.get(
+        'https://data.weather.gov.hk/weatherAPI/opendata/opendata.php',
+        params=params
+    )
+    try:
+        response.raise_for_status()
+        return response.json()
+    except (requests.RequestException, ValueError) as e:
+        return {"error": f"Failed to fetch data: {str(e)}."}
+
+def get_sunrise_sunset_times(
+    year: int,
+    month: Optional[int] = None,
+    day: Optional[int] = None,
+    lang: str = "en"
+) -> Dict[str, Any]:
+    """
+    Get times of sunrise, sun transit and sunset.
+
+    Args:
+        year: Year (2018-2024)
+        month: Optional month (1-12)
+        day: Optional day (1-31)
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing sun times data with fields and data arrays
+    """
+    params = {
+        'dataType': 'SRS',
+        'lang': lang,
+        'rformat': 'json',
+        'year': year
+    }
+    if month: params['month'] = str(month)
+    if day: params['day'] = str(day)
+
+    response = requests.get(
+        'https://data.weather.gov.hk/weatherAPI/opendata/opendata.php',
+        params=params
+    )
+    try:
+        response.raise_for_status()
+        return response.json()
+    except (requests.RequestException, ValueError) as e:
+        return {"error": f"Failed to fetch data: {str(e)}."}
+
+def get_gregorian_lunar_calendar(
+    year: int,
+    month: Optional[int] = None,
+    day: Optional[int] = None,
+    lang: str = "en"
+) -> Dict[str, Any]:
+    """
+    Get Gregorian-Lunar calendar conversion data.
+
+    Args:
+        year: Year (1901-2100)
+        month: Optional month (1-12)
+        day: Optional day (1-31)
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing calendar conversion data
+    """
+    params = {
+        'dataType': 'GLC',
+        'lang': lang,
+        'rformat': 'json',
+        'year': year
+    }
+    if month: params['month'] = str(month)
+    if day: params['day'] = str(day)
+
+    response = requests.get(
+        'https://data.weather.gov.hk/weatherAPI/opendata/opendata.php',
+        params=params
+    )
+    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/current_weather.py

@@ -0,0 +1,106 @@
+import requests
+from typing import Dict
+
+def get_current_weather(region: str = "Hong Kong Observatory", lang: str = "en") -> Dict:
+    """
+    Get current weather observations for a specific region in Hong Kong
+
+    Args:
+        region: The region to get weather for (default: "Hong Kong Observatory")
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing:
+        - warning: Current weather warnings
+        - temperature: Current temperature in Celsius
+        - humidity: Current humidity percentage
+        - rainfall: Current rainfall in mm
+    """
+    response = requests.get(
+        f"https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=rhrread&lang={lang}"
+    )
+    data = response.json()
+
+    # Handle warnings
+    warning = "No warning in force"
+    if "warningMessage" in data:
+        if isinstance(data["warningMessage"], list) and data["warningMessage"]:
+            warning = data["warningMessage"][0]
+        elif data["warningMessage"]:  # Handle string case
+            warning = data["warningMessage"]
+
+    # Get default values from HKO data
+    default_temp = next(
+        (
+            t
+            for t in data.get("temperature", {}).get("data", [])
+            if t.get("place") == "Hong Kong Observatory"
+        ),
+        {"value": 25, "unit": "C", "recordTime": ""},
+    )
+    default_humidity = next(
+        (
+            h
+            for h in data.get("humidity", {}).get("data", [])
+            if h.get("place") == "Hong Kong Observatory"
+        ),
+        {"value": 60, "unit": "percent", "recordTime": ""},
+    )
+    # Find matching region temperature
+    temp_data = data.get("temperature", {}).get("data", [])
+    matched_temp = next(
+        (t for t in temp_data if t["place"].lower() == region.lower()),
+        {
+            "place": "Hong Kong Observatory",
+            "value": default_temp["value"],
+            "unit": default_temp["unit"],
+        },
+    )
+    matched_temp["recordTime"] = data["temperature"]["recordTime"]
+
+    # Get humidity
+    humidity = next(
+        (
+            h
+            for h in data.get("humidity", {}).get("data", [])
+            if h.get("place") == matched_temp["place"]
+        ),
+        default_humidity,
+    )
+    humidity["recordTime"] = data["humidity"]["recordTime"]
+
+    # Get rainfall (0 if no rain)
+    rainfall = 0
+    if "rainfall" in data:
+        rainfall = max(float(r.get("max", 0)) for r in data["rainfall"]["data"])
+        rainfall_start = data["rainfall"]["startTime"]
+        rainfall_end = data["rainfall"]["endTime"]
+
+    return {
+        "generalSituation": warning,
+        "weatherObservation": {
+            "temperature": {
+                "value": matched_temp["value"],
+                "unit": matched_temp["unit"],
+                "recordTime": matched_temp["recordTime"],
+                "place": matched_temp["place"]
+            },
+            "humidity": {
+                "value": humidity["value"],
+                "unit": humidity["unit"],
+                "recordTime": humidity["recordTime"],
+                "place": matched_temp["place"]
+            },
+            "rainfall": {
+                "value": rainfall,
+                "min": min(float(r.get("min", 0)) for r in data["rainfall"]["data"]),
+                "unit": "mm",
+                "startTime": rainfall_start,
+                "endTime": rainfall_end
+            },
+            "uvindex": data.get("uvindex", {})
+        },
+        "updateTime": data["updateTime"],
+        "icon": data.get("icon", []),
+        "iconUpdateTime": data.get("iconUpdateTime", "")
+    }

hkopenai/hk_climate_mcp_server/tools/forecast.py

@@ -0,0 +1,82 @@
+import requests
+from typing import Dict, Any
+
+def get_9_day_weather_forecast(lang: str = "en") -> Dict[str, Any]:
+    """
+    Get the 9-day weather forecast for Hong Kong.
+
+    Args:
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing:
+            - generalSituation: General weather situation
+            - weatherForecast: List of daily forecast dicts (date, week, wind, weather, temp/humidity, etc.)
+            - updateTime: Last update time
+            - seaTemp: Sea temperature info
+            - soilTemp: List of soil temperature info
+    """
+    url = f"https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=fnd&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)}."}
+
+    # Structure the output
+    forecast = {
+        "generalSituation": data.get("generalSituation", ""),
+        "weatherForecast": [],
+        "updateTime": data.get("updateTime", ""),
+        "seaTemp": data.get("seaTemp", {}),
+        "soilTemp": data.get("soilTemp", []),
+    }
+
+    # Extract 9-day forecast
+    for day in data.get("weatherForecast", []):
+        forecast["weatherForecast"].append({
+            "forecastDate": day.get("forecastDate", ""),
+            "week": day.get("week", ""),
+            "forecastWind": day.get("forecastWind", ""),
+            "forecastWeather": day.get("forecastWeather", ""),
+            "forecastMaxtemp": day.get("forecastMaxtemp", {}),
+            "forecastMintemp": day.get("forecastMintemp", {}),
+            "forecastMaxrh": day.get("forecastMaxrh", {}),
+            "forecastMinrh": day.get("forecastMinrh", {}),
+            "ForecastIcon": day.get("ForecastIcon", ""),
+            "PSR": day.get("PSR", ""),
+        })
+    return forecast
+
+def get_local_weather_forecast(lang: str = "en") -> Dict[str, Any]:
+    """
+    Get local weather forecast for Hong Kong.
+
+    Args:
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing:
+            - forecastDesc: Forecast description
+            - outlook: Outlook forecast
+            - updateTime: Last update time
+            - forecastPeriod: Forecast period
+            - forecastDate: Forecast date
+    """
+    url = f"https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=flw&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 {
+        "generalSituation": data.get("generalSituation", ""),
+        "forecastDesc": data.get("forecastDesc", ""),
+        "outlook": data.get("outlook", ""),
+        "updateTime": data.get("updateTime", ""),
+        "forecastPeriod": data.get("forecastPeriod", ""),
+        "forecastDate": data.get("forecastDate", ""),
+    }

hkopenai/hk_climate_mcp_server/tools/lightning.py

@@ -0,0 +1,20 @@
+import requests
+from typing import Dict, Any
+
+def get_lightning_data(lang: str = "en") -> Dict[str, Any]:
+    """
+    Get cloud-to-ground and cloud-to-cloud lightning count data.
+
+    Args:
+        lang: Language code (en/tc/sc, default: en)
+
+    Returns:
+        Dict containing lightning data with fields and data arrays
+    """
+    url = f"https://data.weather.gov.hk/weatherAPI/opendata/opendata.php?dataType=LHL&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)}."}