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

hkopenai/hk_climate_mcp_server/__init__.py

@@ -0,0 +1,21 @@
+"""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
+)
+
+__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'
+]

hkopenai/hk_climate_mcp_server/__main__.py

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

hkopenai/hk_climate_mcp_server/app.py

@@ -0,0 +1,65 @@
+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
+
+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 tool_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)
+
+    @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)
+
+    @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)
+
+    @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)
+
+    @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 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/tool_weather.py

@@ -0,0 +1,241 @@
+import requests
+from typing import Dict, List, Any
+
+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", "")
+    }
+
+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)
+    data = response.json()
+
+    # 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)
+    data = response.json()
+    
+    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", ""),
+    }
+
+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)
+    data = response.json()
+    
+    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)
+    data = response.json()
+    
+    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)
+    data = response.json()
+    
+    return {
+        "specialWeatherTips": data.get("specialWeatherTips", []),
+        "updateTime": data.get("updateTime", ""),
+    }

hkopenai_hk_climate_mcp_server-0.2.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: hkopenai.hk_climate_mcp_server
+Version: 0.2.0
+Summary: Hong Kong Weather MCP Server providing climate and weather data tools
+Author-email: Neo Chow <neo@01man.com>
+License-Expression: MIT
+Project-URL: repository, https://github.com/hkopenai/hk-climate-mcp-server.git
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pytest>=8.2.0
+Requires-Dist: pytest-cov>=6.1.1
+Dynamic: license-file
+
+# HKO MCP Server
+
+[![GitHub Repository](https://img.shields.io/badge/GitHub-Repository-blue.svg)](https://github.com/hkopenai/hk-climate-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+
+This is an MCP server that provides access to climate and weather data through a FastMCP interface.
+
+## Data Source
+
+* Hong Kong Observatory 
+
+## Features
+
+- Current weather: Get current weather observations from HKO (supports optional region parameter)
+- 9-day forecast: Get extended weather forecast including general situation, daily forecasts, sea and soil temperatures
+- Local weather forecast: Get short-term weather forecast with outlook
+- Weather warnings: Get summary and detailed information about active weather warnings
+- Special weather tips: Get important weather-related safety tips
+
+## API Reference
+
+### Current Weather
+`get_current_weather(region: str = "Hong Kong Observatory") -> Dict`
+- Get current weather observations for a specific region in Hong Kong
+- Parameters:
+  - region: The region to get weather for (default: "Hong Kong Observatory")
+- Returns:
+  - Dict containing:
+    - warning: Current weather warnings
+    - temperature: Current temperature in Celsius
+    - humidity: Current humidity percentage
+    - rainfall: Current rainfall in mm
+
+### 9-Day Weather Forecast
+`get_9_day_weather_forecast(lang: str = "en") -> Dict`
+- Get the 9-day weather forecast for Hong Kong
+- Parameters:
+  - lang: Language code (en/tc/sc, default: en)
+- Returns:
+  - Dict containing:
+    - generalSituation: General weather situation
+    - weatherForecast: List of daily forecast dicts
+    - updateTime: Last update time
+    - seaTemp: Sea temperature info
+    - soilTemp: List of soil temperature info
+
+### Local Weather Forecast  
+`get_local_weather_forecast(lang: str = "en") -> Dict`
+- Get local weather forecast for Hong Kong
+- Parameters:
+  - 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
+
+### Weather Warning Summary
+`get_weather_warning_summary(lang: str = "en") -> Dict`
+- Get weather warning summary for Hong Kong
+- Parameters:
+  - lang: Language code (en/tc/sc, default: en)
+- Returns:
+  - Dict containing:
+    - warningMessage: List of warning messages
+    - updateTime: Last update time
+
+### Weather Warning Information
+`get_weather_warning_info(lang: str = "en") -> Dict`
+- Get detailed weather warning information
+- Parameters:
+  - lang: Language code (en/tc/sc, default: en)
+- Returns:
+  - Dict containing:
+    - warningStatement: Warning statement
+    - updateTime: Last update time
+
+### Special Weather Tips
+`get_special_weather_tips(lang: str = "en") -> Dict`
+- Get special weather tips for Hong Kong
+- Parameters:
+  - lang: Language code (en/tc/sc, default: en)
+- Returns:
+  - Dict containing:
+    - specialWeatherTips: List of special weather tips
+    - updateTime: Last update time
+
+## Setup
+
+1. Clone this repository
+2. Install Python dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+3. Run the server:
+   ```bash
+   python app.py
+   ```
+
+### Running Options
+
+- Default stdio mode: `python app.py`
+- SSE mode (port 8000): `python app.py --sse`
+
+## Cline Integration
+
+To connect this MCP server to Cline using stdio:
+
+1. Add this configuration to your Cline MCP settings (cline_mcp_settings.json):
+```json
+{
+  "hko-server": {
+    "disabled": false,
+    "timeout": 3,
+    "type": "stdio",
+    "command": "python",
+    "args": [
+      "c:/Projects/hkopenai/hk-climate-mcp-server/app.py"
+    ]
+  }
+}
+```
+
+## Testing
+
+Tests are available in `tests`. Run with:
+```bash
+pytest

hkopenai_hk_climate_mcp_server-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+hkopenai/hk_climate_mcp_server/__init__.py,sha256=QgSoOyNq_fnuED4FMOV9aj2ZDyEmezGRy2GCP427G5g,519
+hkopenai/hk_climate_mcp_server/__main__.py,sha256=2rpUSwIvU59qepKyDNMz6AtDrbsRVVIZZP0hL5LoZbs,91
+hkopenai/hk_climate_mcp_server/app.py,sha256=sTJS-eEBwyZz4KiGSEJ5QVzhiBNAGvUPAukhYNlkiEk,2479
+hkopenai/hk_climate_mcp_server/tool_weather.py,sha256=MitwPrgdE08zszoIqezY-Cxo5Z5fN5HHiZ6T-IpP3N0,8180
+hkopenai_hk_climate_mcp_server-0.2.0.dist-info/licenses/LICENSE,sha256=RzryYGol65qd1yszjiy-hSUsX9EJJkpwEpNXnIs_Bv8,1070
+hkopenai_hk_climate_mcp_server-0.2.0.dist-info/METADATA,sha256=CQb8Er_uk1Ms9ZQEKfS7l7ytdBo_K06yWrV9d6t-7zI,4415
+hkopenai_hk_climate_mcp_server-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+hkopenai_hk_climate_mcp_server-0.2.0.dist-info/entry_points.txt,sha256=2pPEyDw5KdrNNZIGQsSrY-5IRMgWaWvEQT_BQJhKPMQ,82
+hkopenai_hk_climate_mcp_server-0.2.0.dist-info/top_level.txt,sha256=6PRVKRM9BiU5vzKKGnsq2t0-Bi0TrJvSY35llo4nLFA,9
+hkopenai_hk_climate_mcp_server-0.2.0.dist-info/RECORD,,

hkopenai_hk_climate_mcp_server-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hkopenai_hk_climate_mcp_server-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hk_climate_mcp_server = hkopenai.hk_climate_mcp_server.app:main

hkopenai_hk_climate_mcp_server-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 neo@01man.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hkopenai_hk_climate_mcp_server-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hkopenai