nhc-mcp 0.1.0__tar.gz

nhc_mcp-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Linting
+.ruff_cache/
+.mypy_cache/
+
+# Lock files (each server manages its own)
+uv.lock
+
+# Environment
+.env
+.env.local

nhc_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mansur Ali Jisan
+
+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.

nhc_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: nhc-mcp
+Version: 0.1.0
+Summary: MCP server for NHC storm tracks, advisories, and hurricane best track data
+Project-URL: Homepage, https://github.com/mansurjisan/ocean-mcp
+Project-URL: Repository, https://github.com/mansurjisan/ocean-mcp
+Project-URL: Bug Tracker, https://github.com/mansurjisan/ocean-mcp/issues
+Project-URL: Documentation, https://github.com/mansurjisan/ocean-mcp/tree/main/servers/nhc-mcp
+Project-URL: Changelog, https://github.com/mansurjisan/ocean-mcp/releases
+Author-email: Mansur Ali Jisan <mansur.jisan@noaa.gov>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: hurdat2,hurricane,mcp,meteorology,model-context-protocol,nhc,noaa,storm-track,tropical-cyclone
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# NHC MCP Server
+
+<!-- mcp-name: io.github.mansurjisan/nhc-mcp -->
+
+MCP server providing AI assistants with access to National Hurricane Center (NHC) storm tracks, advisories, and best track data.
+
+**Status: Ready**
+
+## Tools
+
+| Tool | Description | Status |
+|------|-------------|--------|
+| `nhc_get_active_storms` | Get currently active tropical cyclones | Ready |
+| `nhc_get_forecast_track` | Get official NHC 5-day forecast track positions | Ready |
+| `nhc_get_best_track` | Get best track data for historical or recent storms | Ready |
+| `nhc_search_storms` | Search historical storms by name, year, basin, intensity | Ready |
+| `nhc_get_storm_watches_warnings` | Get active watches and warnings for a storm | Ready |
+| `nhc_generate_parametric_wind` | Generate parametric wind field for a storm | Planned |
+
+## Data Sources
+
+- **CurrentStorms.json** — Real-time active storm information from NHC
+- **ATCF B-deck** — Current-season best track data (Automated Tropical Cyclone Forecasting)
+- **HURDAT2** — Atlantic (1851–2024) and East Pacific (1949–2024) hurricane database
+- **NHC ArcGIS MapServer** — Forecast tracks, cones, and watch/warning polygons
+
+## Quick Start
+
+```bash
+git clone https://github.com/mansurjisan/ocean-mcp.git
+cd ocean-mcp/servers/nhc-mcp
+uv sync
+```
+
+### Configure your MCP client
+
+```json
+{
+  "mcpServers": {
+    "nhc": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/ocean-mcp/servers/nhc-mcp", "python", "-m", "nhc_mcp"]
+    }
+  }
+}
+```
+
+## Example Queries
+
+- "Are there any active tropical cyclones right now?"
+- "Show me Hurricane Katrina's track"
+- "Search for Category 5 hurricanes in the Atlantic since 2000"
+- "What is the forecast track for the active storm AL052024?"
+- "Find all storms named Maria"
+
+## Running Tests
+
+```bash
+# Unit tests (fast, no network)
+uv run pytest tests/test_utils.py tests/test_client.py -v
+
+# Live integration tests (requires internet)
+uv run pytest tests/test_live.py -v -s
+```
+
+## License
+
+MIT

nhc_mcp-0.1.0/README.md

@@ -0,0 +1,68 @@
+# NHC MCP Server
+
+<!-- mcp-name: io.github.mansurjisan/nhc-mcp -->
+
+MCP server providing AI assistants with access to National Hurricane Center (NHC) storm tracks, advisories, and best track data.
+
+**Status: Ready**
+
+## Tools
+
+| Tool | Description | Status |
+|------|-------------|--------|
+| `nhc_get_active_storms` | Get currently active tropical cyclones | Ready |
+| `nhc_get_forecast_track` | Get official NHC 5-day forecast track positions | Ready |
+| `nhc_get_best_track` | Get best track data for historical or recent storms | Ready |
+| `nhc_search_storms` | Search historical storms by name, year, basin, intensity | Ready |
+| `nhc_get_storm_watches_warnings` | Get active watches and warnings for a storm | Ready |
+| `nhc_generate_parametric_wind` | Generate parametric wind field for a storm | Planned |
+
+## Data Sources
+
+- **CurrentStorms.json** — Real-time active storm information from NHC
+- **ATCF B-deck** — Current-season best track data (Automated Tropical Cyclone Forecasting)
+- **HURDAT2** — Atlantic (1851–2024) and East Pacific (1949–2024) hurricane database
+- **NHC ArcGIS MapServer** — Forecast tracks, cones, and watch/warning polygons
+
+## Quick Start
+
+```bash
+git clone https://github.com/mansurjisan/ocean-mcp.git
+cd ocean-mcp/servers/nhc-mcp
+uv sync
+```
+
+### Configure your MCP client
+
+```json
+{
+  "mcpServers": {
+    "nhc": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/ocean-mcp/servers/nhc-mcp", "python", "-m", "nhc_mcp"]
+    }
+  }
+}
+```
+
+## Example Queries
+
+- "Are there any active tropical cyclones right now?"
+- "Show me Hurricane Katrina's track"
+- "Search for Category 5 hurricanes in the Atlantic since 2000"
+- "What is the forecast track for the active storm AL052024?"
+- "Find all storms named Maria"
+
+## Running Tests
+
+```bash
+# Unit tests (fast, no network)
+uv run pytest tests/test_utils.py tests/test_client.py -v
+
+# Live integration tests (requires internet)
+uv run pytest tests/test_live.py -v -s
+```
+
+## License
+
+MIT

nhc_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nhc-mcp"
+version = "0.1.0"
+description = "MCP server for NHC storm tracks, advisories, and hurricane best track data"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [
+    {name = "Mansur Ali Jisan", email = "mansur.jisan@noaa.gov"},
+]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "noaa",
+    "hurricane",
+    "nhc",
+    "tropical-cyclone",
+    "storm-track",
+    "hurdat2",
+    "meteorology",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/mansurjisan/ocean-mcp"
+Repository = "https://github.com/mansurjisan/ocean-mcp"
+"Bug Tracker" = "https://github.com/mansurjisan/ocean-mcp/issues"
+Documentation = "https://github.com/mansurjisan/ocean-mcp/tree/main/servers/nhc-mcp"
+Changelog = "https://github.com/mansurjisan/ocean-mcp/releases"
+
+[project.scripts]
+nhc-mcp = "nhc_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nhc_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[dependency-groups]
+dev = ["pytest>=8.0.0", "pytest-asyncio>=0.24.0", "respx>=0.22.0"]

nhc_mcp-0.1.0/server.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.mansurjisan/nhc-mcp",
+  "title": "NHC MCP Server",
+  "description": "MCP server for NHC storm tracks, forecast advisories, watches/warnings, and HURDAT2 historical hurricane data. No API key required.",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/mansurjisan/ocean-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "nhc-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

nhc_mcp-0.1.0/smithery.yaml

@@ -0,0 +1,9 @@
+# Smithery configuration — https://smithery.ai/docs/config
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    required: []
+    properties: {}
+  commandFunction: |-
+    (config) => ({ command: 'uvx', args: ['nhc-mcp'] })

nhc_mcp-0.1.0/src/nhc_mcp/__init__.py

@@ -0,0 +1 @@
+"""NHC MCP Server — National Hurricane Center Data for AI Assistants."""

nhc_mcp-0.1.0/src/nhc_mcp/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+main()

nhc_mcp-0.1.0/src/nhc_mcp/client.py

@@ -0,0 +1,128 @@
+"""Async HTTP client for NHC data sources."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+# NHC data endpoints
+CURRENT_STORMS_URL = "https://www.nhc.noaa.gov/CurrentStorms.json"
+ATCF_BDECK_URL = "https://ftp.nhc.noaa.gov/atcf/btk/b{basin}{number:02d}{year}.dat"
+HURDAT2_URLS = {
+    "al": "https://www.nhc.noaa.gov/data/hurdat/hurdat2-1851-2024-040425.txt",
+    "ep": "https://www.nhc.noaa.gov/data/hurdat/hurdat2-nepac-1949-2024-031725.txt",
+}
+
+from .utils import ARCGIS_BASE_URL, build_arcgis_query_url
+
+
+class NHCAPIError(Exception):
+    """Custom exception for NHC API errors."""
+    pass
+
+
+class NHCClient:
+    """Async client for NHC data sources (CurrentStorms, ATCF, HURDAT2, ArcGIS)."""
+
+    def __init__(self) -> None:
+        self._client: httpx.AsyncClient | None = None
+        self._hurdat2_cache: dict[str, str] = {}
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(
+                timeout=60.0,
+                follow_redirects=True,
+            )
+        return self._client
+
+    async def get_active_storms(self) -> list[dict]:
+        """Fetch currently active tropical cyclones from CurrentStorms.json.
+
+        Returns:
+            List of active storm dicts. May be empty outside hurricane season.
+        """
+        client = await self._get_client()
+        response = await client.get(CURRENT_STORMS_URL)
+        response.raise_for_status()
+        data = response.json()
+        return data.get("activeStorms", [])
+
+    async def get_best_track_atcf(self, basin: str, number: int, year: int) -> str:
+        """Fetch ATCF B-deck best track data for a specific storm.
+
+        Args:
+            basin: Basin code ('al', 'ep', 'cp').
+            number: Storm number within the season.
+            year: 4-digit year.
+
+        Returns:
+            Raw B-deck text content.
+
+        Raises:
+            httpx.HTTPStatusError: If the file doesn't exist (404).
+        """
+        url = ATCF_BDECK_URL.format(basin=basin, number=number, year=year)
+        client = await self._get_client()
+        response = await client.get(url)
+        response.raise_for_status()
+        return response.text
+
+    async def get_hurdat2(self, basin: str) -> str:
+        """Fetch HURDAT2 data for a basin, with in-memory caching.
+
+        Args:
+            basin: Basin code ('al' or 'ep'). 'cp' falls back to 'ep'.
+
+        Returns:
+            Raw HURDAT2 text content.
+        """
+        # Central Pacific storms are in the East Pacific HURDAT2 file
+        lookup_basin = "ep" if basin == "cp" else basin
+
+        if lookup_basin in self._hurdat2_cache:
+            return self._hurdat2_cache[lookup_basin]
+
+        url = HURDAT2_URLS.get(lookup_basin)
+        if not url:
+            raise ValueError(f"No HURDAT2 data available for basin '{basin}'.")
+
+        client = await self._get_client()
+        response = await client.get(url)
+        response.raise_for_status()
+        text = response.text
+        self._hurdat2_cache[lookup_basin] = text
+        return text
+
+    async def query_arcgis_layer(
+        self,
+        layer_id: int,
+        where: str = "1=1",
+    ) -> dict[str, Any]:
+        """Query an ArcGIS MapServer layer.
+
+        Args:
+            layer_id: MapServer layer ID.
+            where: SQL WHERE clause.
+
+        Returns:
+            ArcGIS JSON response with features.
+        """
+        url = build_arcgis_query_url(layer_id, where=where)
+        client = await self._get_client()
+        response = await client.get(url)
+        response.raise_for_status()
+        data = response.json()
+
+        if "error" in data:
+            error = data["error"]
+            msg = error.get("message", "Unknown ArcGIS error")
+            raise NHCAPIError(f"ArcGIS error: {msg}")
+
+        return data
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client and not self._client.is_closed:
+            await self._client.aclose()

nhc_mcp-0.1.0/src/nhc_mcp/models.py

@@ -0,0 +1,45 @@
+"""Enums and constants for NHC MCP server."""
+
+from enum import Enum
+
+
+class Basin(str, Enum):
+    """NHC tropical cyclone basins."""
+
+    AL = "al"  # Atlantic
+    EP = "ep"  # East Pacific
+    CP = "cp"  # Central Pacific
+
+
+class StormClassification(str, Enum):
+    """Tropical cyclone classification based on wind speed."""
+
+    TD = "TD"  # Tropical Depression (< 34 kt)
+    TS = "TS"  # Tropical Storm (34–63 kt)
+    HU = "HU"  # Hurricane (64+ kt)
+    SD = "SD"  # Subtropical Depression
+    SS = "SS"  # Subtropical Storm
+    EX = "EX"  # Extratropical
+    LO = "LO"  # Low / remnant low
+    DB = "DB"  # Disturbance
+    WV = "WV"  # Tropical Wave
+
+
+# Saffir-Simpson category thresholds (knots)
+SAFFIR_SIMPSON = [
+    (137, "Category 5"),
+    (113, "Category 4"),
+    (96, "Category 3"),
+    (83, "Category 2"),
+    (64, "Category 1"),
+    (34, "Tropical Storm"),
+    (0, "Tropical Depression"),
+]
+
+
+def classify_wind_speed(wind_kt: int) -> str:
+    """Return Saffir-Simpson category string for a given wind speed in knots."""
+    for threshold, label in SAFFIR_SIMPSON:
+        if wind_kt >= threshold:
+            return label
+    return "Tropical Depression"

nhc_mcp-0.1.0/src/nhc_mcp/server.py

@@ -0,0 +1,32 @@
+"""FastMCP server entry point for NHC MCP."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from mcp.server.fastmcp import FastMCP
+
+from .client import NHCClient
+
+
+@asynccontextmanager
+async def app_lifespan(server: FastMCP) -> AsyncIterator[dict]:
+    """Manage the shared NHC API client lifecycle."""
+    client = NHCClient()
+    try:
+        yield {"nhc_client": client}
+    finally:
+        await client.close()
+
+
+mcp = FastMCP("nhc_mcp", lifespan=app_lifespan)
+
+# Import tool modules to register them with the server
+from .tools import active, forecast, history  # noqa: E402, F401
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

nhc_mcp-0.1.0/src/nhc_mcp/tools/__init__.py

@@ -0,0 +1 @@
+"""NHC MCP tool modules."""

nhc_mcp-0.1.0/src/nhc_mcp/tools/active.py

@@ -0,0 +1,89 @@
+"""Tool: nhc_get_active_storms — currently active tropical cyclones."""
+
+from mcp.server.fastmcp import Context
+from mcp.types import ToolAnnotations
+
+from ..client import NHCClient
+from ..models import classify_wind_speed
+from ..server import mcp
+from ..utils import format_tabular_data, handle_nhc_error
+
+
+def _get_client(ctx: Context) -> NHCClient:
+    return ctx.request_context.lifespan_context["nhc_client"]
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    )
+)
+async def nhc_get_active_storms(
+    ctx: Context,
+    response_format: str = "markdown",
+) -> str:
+    """Get currently active tropical cyclones from the National Hurricane Center.
+
+    Returns a list of all active storms with their current classification,
+    location, and advisory information. Returns an empty list outside of
+    hurricane season or when no storms are active.
+
+    Args:
+        response_format: Output format — 'markdown' (default) or 'json'.
+    """
+    try:
+        client = _get_client(ctx)
+        storms = await client.get_active_storms()
+
+        if not storms:
+            return (
+                "## Active Tropical Cyclones\n\n"
+                "No active tropical cyclones at this time.\n\n"
+                "*Tip: Use nhc_search_storms to search historical storms, or "
+                "nhc_get_best_track to retrieve track data for past storms.*"
+            )
+
+        # Enrich storm data with classification
+        rows = []
+        for s in storms:
+            row = {
+                "name": s.get("name", "Unknown"),
+                "classification": s.get("classification", ""),
+                "id": s.get("id", ""),
+                "binNumber": s.get("binNumber", ""),
+                "movementDir": s.get("movementDir", ""),
+                "movementSpeed": s.get("movementSpeed", ""),
+                "pressure": s.get("pressure", ""),
+                "wind": s.get("wind", ""),
+                "lastUpdate": s.get("lastUpdate", ""),
+                "advisory_url": s.get("publicAdvisory", {}).get("url", ""),
+            }
+            rows.append(row)
+
+        if response_format == "json":
+            import json
+            return json.dumps({"active_storms": rows, "count": len(rows)}, indent=2)
+
+        columns = [
+            ("name", "Name"),
+            ("classification", "Type"),
+            ("id", "Storm ID"),
+            ("wind", "Wind"),
+            ("pressure", "Pressure"),
+            ("movementDir", "Movement"),
+            ("movementSpeed", "Speed"),
+            ("lastUpdate", "Last Update"),
+        ]
+
+        return format_tabular_data(
+            data=rows,
+            columns=columns,
+            title="Active Tropical Cyclones",
+            count_label="active storms",
+        )
+
+    except Exception as e:
+        return handle_nhc_error(e, "fetching active storms")