hkopenai.hk-climate-mcp-server 0.3.0__tar.gz → 0.4.0__tar.gz

hkopenai_hk_climate_mcp_server-0.4.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include hkopenai/hk_climate_mcp_server/tools *.py

{hkopenai_hk_climate_mcp_server-0.3.0 → hkopenai_hk_climate_mcp_server-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hkopenai.hk_climate_mcp_server
-Version: 0.3.0
+Version: 0.4.0
 Summary: Hong Kong Weather MCP Server providing climate and weather data tools
 Author-email: Neo Chow <neo@01man.com>
 License-Expression: MIT
@@ -107,37 +107,34 @@ This is an MCP server that provides access to climate and weather data through a
     - updateTime: Last update time
 
 ### Visibility Data
-`get_visibility_data(lang: str = "en", rformat: str = "json") -> Dict`
+`get_visibility_data(lang: str = "en") -> Dict`
 - Get latest 10-minute mean visibility data for Hong Kong
 - Parameters:
   - lang: Language code (en/tc/sc, default: en)
-  - rformat: Return format (json/csv, default: json)
 - Returns:
   - Dict containing visibility data with fields and data arrays
 
 ### Lightning Data  
-`get_lightning_data(lang: str = "en", rformat: str = "json") -> Dict`
+`get_lightning_data(lang: str = "en") -> Dict`
 - Get cloud-to-ground and cloud-to-cloud lightning count data
 - Parameters:
   - lang: Language code (en/tc/sc, default: en)
-  - rformat: Return format (json/csv, default: json)
 - Returns:
   - Dict containing lightning data with fields and data arrays
 
 ### Moon Times
-`get_moon_times(year: int, month: Optional[int] = None, day: Optional[int] = None, lang: str = "en", rformat: str = "json") -> Dict`
+`get_moon_times(year: int, month: Optional[int] = None, day: Optional[int] = None, lang: str = "en") -> Dict`
 - Get times of moonrise, moon transit and moonset
 - Parameters:
   - year: Year (2018-2024)
   - month: Optional month (1-12)
   - day: Optional day (1-31)
   - lang: Language code (en/tc/sc, default: en)
-  - rformat: Return format (json/csv, default: json)
 - Returns:
   - Dict containing moon times data with fields and data arrays
 
 ### Hourly Tides
-`get_hourly_tides(station: str, year: int, month: Optional[int] = None, day: Optional[int] = None, hour: Optional[int] = None, lang: str = "en", rformat: str = "json") -> Dict`
+`get_hourly_tides(station: str, year: int, month: Optional[int] = None, day: Optional[int] = None, hour: Optional[int] = None, lang: str = "en") -> Dict`
 - Get hourly heights of astronomical tides for a specific station
 - Parameters:
   - station: Station code (e.g. 'CCH' for Cheung Chau)
@@ -146,12 +143,11 @@ This is an MCP server that provides access to climate and weather data through a
   - day: Optional day (1-31)
   - hour: Optional hour (1-24)
   - lang: Language code (en/tc/sc, default: en)
-  - rformat: Return format (json/csv, default: json)
 - Returns:
   - Dict containing tide data with fields and data arrays
 
 ### High/Low Tides
-`get_high_low_tides(station: str, year: int, month: Optional[int] = None, day: Optional[int] = None, hour: Optional[int] = None, lang: str = "en", rformat: str = "json") -> Dict`
+`get_high_low_tides(station: str, year: int, month: Optional[int] = None, day: Optional[int] = None, hour: Optional[int] = None, lang: str = "en") -> Dict`
 - Get times and heights of astronomical high and low tides
 - Parameters:
   - station: Station code (e.g. 'CCH' for Cheung Chau)
@@ -160,10 +156,27 @@ This is an MCP server that provides access to climate and weather data through a
   - day: Optional day (1-31)
   - hour: Optional hour (1-24)
   - lang: Language code (en/tc/sc, default: en)
-  - rformat: Return format (json/csv, default: json)
 - Returns:
   - Dict containing tide data with fields and data arrays
 
+### Weather and Radiation Report
+`get_weather_radiation_report(date: str, station: str, lang: str = "en") -> Dict`
+- Get weather and radiation level report for Hong Kong
+- Parameters:
+  - date: Mandatory date in YYYYMMDD format (e.g., 20250618)
+  - station: Mandatory station code (e.g., 'HKO' for Hong Kong Observatory)
+  - lang: Language code (en/tc/sc, default: en)
+- Returns:
+  - Dict containing weather and radiation data or error message if parameters are invalid
+
+### Station Codes
+`get_radiation_station_codes() -> Dict`
+- Get a list of station codes and their corresponding names for weather and radiation reports in Hong Kong
+- Parameters:
+  - None
+- Returns:
+  - Dict mapping station codes to station names
+
 ## Setup
 
 1. Clone this repository
@@ -173,13 +186,13 @@ This is an MCP server that provides access to climate and weather data through a
    ```
 3. Run the server:
    ```bash
-   python app.py
+   python server.py
    ```
 
 ### Running Options
 
-- Default stdio mode: `python app.py`
-- SSE mode (port 8000): `python app.py --sse`
+- Default stdio mode: `python server.py`
+- SSE mode (port 8000): `python server.py --sse`
 
 ## Cline Integration
 

{hkopenai_hk_climate_mcp_server-0.3.0 → hkopenai_hk_climate_mcp_server-0.4.0}/README.md

@@ -89,37 +89,34 @@ This is an MCP server that provides access to climate and weather data through a
     - updateTime: Last update time
 
 ### Visibility Data
-`get_visibility_data(lang: str = "en", rformat: str = "json") -> Dict`
+`get_visibility_data(lang: str = "en") -> Dict`
 - Get latest 10-minute mean visibility data for Hong Kong
 - Parameters:
   - lang: Language code (en/tc/sc, default: en)
-  - rformat: Return format (json/csv, default: json)
 - Returns:
   - Dict containing visibility data with fields and data arrays
 
 ### Lightning Data  
-`get_lightning_data(lang: str = "en", rformat: str = "json") -> Dict`
+`get_lightning_data(lang: str = "en") -> Dict`
 - Get cloud-to-ground and cloud-to-cloud lightning count data
 - Parameters:
   - lang: Language code (en/tc/sc, default: en)
-  - rformat: Return format (json/csv, default: json)
 - Returns:
   - Dict containing lightning data with fields and data arrays
 
 ### Moon Times
-`get_moon_times(year: int, month: Optional[int] = None, day: Optional[int] = None, lang: str = "en", rformat: str = "json") -> Dict`
+`get_moon_times(year: int, month: Optional[int] = None, day: Optional[int] = None, lang: str = "en") -> Dict`
 - Get times of moonrise, moon transit and moonset
 - Parameters:
   - year: Year (2018-2024)
   - month: Optional month (1-12)
   - day: Optional day (1-31)
   - lang: Language code (en/tc/sc, default: en)
-  - rformat: Return format (json/csv, default: json)
 - Returns:
   - Dict containing moon times data with fields and data arrays
 
 ### Hourly Tides
-`get_hourly_tides(station: str, year: int, month: Optional[int] = None, day: Optional[int] = None, hour: Optional[int] = None, lang: str = "en", rformat: str = "json") -> Dict`
+`get_hourly_tides(station: str, year: int, month: Optional[int] = None, day: Optional[int] = None, hour: Optional[int] = None, lang: str = "en") -> Dict`
 - Get hourly heights of astronomical tides for a specific station
 - Parameters:
   - station: Station code (e.g. 'CCH' for Cheung Chau)
@@ -128,12 +125,11 @@ This is an MCP server that provides access to climate and weather data through a
   - day: Optional day (1-31)
   - hour: Optional hour (1-24)
   - lang: Language code (en/tc/sc, default: en)
-  - rformat: Return format (json/csv, default: json)
 - Returns:
   - Dict containing tide data with fields and data arrays
 
 ### High/Low Tides
-`get_high_low_tides(station: str, year: int, month: Optional[int] = None, day: Optional[int] = None, hour: Optional[int] = None, lang: str = "en", rformat: str = "json") -> Dict`
+`get_high_low_tides(station: str, year: int, month: Optional[int] = None, day: Optional[int] = None, hour: Optional[int] = None, lang: str = "en") -> Dict`
 - Get times and heights of astronomical high and low tides
 - Parameters:
   - station: Station code (e.g. 'CCH' for Cheung Chau)
@@ -142,10 +138,27 @@ This is an MCP server that provides access to climate and weather data through a
   - day: Optional day (1-31)
   - hour: Optional hour (1-24)
   - lang: Language code (en/tc/sc, default: en)
-  - rformat: Return format (json/csv, default: json)
 - Returns:
   - Dict containing tide data with fields and data arrays
 
+### Weather and Radiation Report
+`get_weather_radiation_report(date: str, station: str, lang: str = "en") -> Dict`
+- Get weather and radiation level report for Hong Kong
+- Parameters:
+  - date: Mandatory date in YYYYMMDD format (e.g., 20250618)
+  - station: Mandatory station code (e.g., 'HKO' for Hong Kong Observatory)
+  - lang: Language code (en/tc/sc, default: en)
+- Returns:
+  - Dict containing weather and radiation data or error message if parameters are invalid
+
+### Station Codes
+`get_radiation_station_codes() -> Dict`
+- Get a list of station codes and their corresponding names for weather and radiation reports in Hong Kong
+- Parameters:
+  - None
+- Returns:
+  - Dict mapping station codes to station names
+
 ## Setup
 
 1. Clone this repository
@@ -155,13 +168,13 @@ This is an MCP server that provides access to climate and weather data through a
    ```
 3. Run the server:
    ```bash
-   python app.py
+   python server.py
    ```
 
 ### Running Options
 
-- Default stdio mode: `python app.py`
-- SSE mode (port 8000): `python app.py --sse`
+- Default stdio mode: `python server.py`
+- SSE mode (port 8000): `python server.py --sse`
 
 ## Cline Integration
 

hkopenai_hk_climate_mcp_server-0.4.0/hkopenai/hk_climate_mcp_server/__init__.py

@@ -0,0 +1,6 @@
+"""Hong Kong climate MCP Server package."""
+from .server import main
+
+
+__version__ = "0.1.0"
+__all__ = ['main']

hkopenai_hk_climate_mcp_server-0.4.0/hkopenai/hk_climate_mcp_server/__main__.py

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

hkopenai_hk_climate_mcp_server-0.3.0/hkopenai/hk_climate_mcp_server/app.py → hkopenai_hk_climate_mcp_server-0.4.0/hkopenai/hk_climate_mcp_server/server.py

@@ -1,8 +1,16 @@
 import argparse
 from fastmcp import FastMCP
-from hkopenai.hk_climate_mcp_server import tool_weather
 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"""
@@ -12,49 +20,49 @@ def create_mcp_server():
         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 tool_weather.get_current_weather(region)
+        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 tool_weather.get_9_day_weather_forecast(lang)
+        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 tool_weather.get_local_weather_forecast(lang)
+        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 tool_weather.get_weather_warning_summary(lang)
+        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 tool_weather.get_weather_warning_info(lang)
+        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 tool_weather.get_special_weather_tips(lang)
+        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", rformat: str = "json") -> Dict:
-        return tool_weather.get_visibility_data(lang, rformat)
+    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", rformat: str = "json") -> Dict:
-        return tool_weather.get_lightning_data(lang, rformat)
+    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",
@@ -63,15 +71,13 @@ def create_mcp_server():
         year: int,
         month: Optional[int] = None,
         day: Optional[int] = None,
-        lang: str = "en",
-        rformat: str = "json"
+        lang: str = "en"
     ) -> Dict:
-        return tool_weather.get_moon_times(
+        return astronomical.get_moon_times(
             year=year,
             month=month,
             day=day,
-            lang=lang,
-            rformat=rformat
+            lang=lang
         )
 
     @mcp.tool(
@@ -83,17 +89,15 @@ def create_mcp_server():
         month: Optional[int] = None,
         day: Optional[int] = None,
         hour: Optional[int] = None,
-        lang: str = "en",
-        rformat: str = "json"
+        lang: str = "en"
     ) -> Dict:
-        return tool_weather.get_hourly_tides(
+        return tides.get_hourly_tides(
             station=station,
             year=year,
             month=month,
             day=day,
             hour=hour,
-            lang=lang,
-            rformat=rformat
+            lang=lang
         )
 
     @mcp.tool(
@@ -105,19 +109,23 @@ def create_mcp_server():
         month: Optional[int] = None,
         day: Optional[int] = None,
         hour: Optional[int] = None,
-        lang: str = "en",
-        rformat: str = "json"
+        lang: str = "en"
     ) -> Dict:
-        return tool_weather.get_high_low_tides(
+        return tides.get_high_low_tides(
             station=station,
             year=year,
             month=month,
             day=day,
             hour=hour,
-            lang=lang,
-            rformat=rformat
+            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",
     )
@@ -125,15 +133,13 @@ def create_mcp_server():
         year: int,
         month: Optional[int] = None,
         day: Optional[int] = None,
-        lang: str = "en",
-        rformat: str = "json"
+        lang: str = "en"
     ) -> Dict:
-        return tool_weather.get_sunrise_sunset_times(
+        return astronomical.get_sunrise_sunset_times(
             year=year,
             month=month,
             day=day,
-            lang=lang,
-            rformat=rformat
+            lang=lang
         )
 
     @mcp.tool(
@@ -143,15 +149,13 @@ def create_mcp_server():
         year: int,
         month: Optional[int] = None,
         day: Optional[int] = None,
-        lang: str = "en",
-        rformat: str = "json"
+        lang: str = "en"
     ) -> Dict:
-        return tool_weather.get_gregorian_lunar_calendar(
+        return astronomical.get_gregorian_lunar_calendar(
             year=year,
             month=month,
             day=day,
-            lang=lang,
-            rformat=rformat
+            lang=lang
         )
 
     @mcp.tool(
@@ -161,15 +165,13 @@ def create_mcp_server():
         station: str,
         year: Optional[int] = None,
         month: Optional[int] = None,
-        lang: str = "en",
-        rformat: str = "json"
+        lang: str = "en"
     ) -> Dict:
-        return tool_weather.get_daily_mean_temperature(
+        return temperature.get_daily_mean_temperature(
             station=station,
             year=year,
             month=month,
-            lang=lang,
-            rformat=rformat
+            lang=lang
         )
 
     @mcp.tool(
@@ -179,15 +181,13 @@ def create_mcp_server():
         station: str,
         year: Optional[int] = None,
         month: Optional[int] = None,
-        lang: str = "en",
-        rformat: str = "json"
+        lang: str = "en"
     ) -> Dict:
-        return tool_weather.get_daily_max_temperature(
+        return temperature.get_daily_max_temperature(
             station=station,
             year=year,
             month=month,
-            lang=lang,
-            rformat=rformat
+            lang=lang
         )
 
     @mcp.tool(
@@ -197,32 +197,34 @@ def create_mcp_server():
         station: str,
         year: Optional[int] = None,
         month: Optional[int] = None,
-        lang: str = "en",
-        rformat: str = "json"
+        lang: str = "en"
     ) -> Dict:
-        return tool_weather.get_daily_min_temperature(
+        return temperature.get_daily_min_temperature(
             station=station,
             year=year,
             month=month,
-            lang=lang,
-            rformat=rformat
+            lang=lang
         )
 
     @mcp.tool(
-        description="Get weather and radiation level report for Hong Kong",
+        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: Optional[str] = None,
-        station: Optional[str] = None,
-        lang: str = "en",
-        rformat: str = "json"
+        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 tool_weather.get_weather_radiation_report(
+        return radiation.get_weather_radiation_report(
             date=date,
             station=station,
-            lang=lang,
-            rformat=rformat
+            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
 

hkopenai_hk_climate_mcp_server-0.4.0/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)}."}