ofs-mcp 0.1.0__tar.gz

ofs_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

ofs_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.

ofs_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: ofs-mcp
+Version: 0.1.0
+Summary: MCP server for NOAA Operational Forecast System (OFS) regional ocean model access
+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/ofs-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: fvcom,mcp,model-context-protocol,noaa,ocean-forecast,oceanography,ofs,roms,salinity,temperature,water-level
+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: netcdf4>=1.7.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# OFS MCP Server
+
+<!-- mcp-name: io.github.mansurjisan/ofs-mcp -->
+
+MCP server for NOAA's Operational Forecast System (OFS) — regional hydrodynamic ocean models covering US coastal waters.
+
+**Status**: Ready
+
+## Overview
+
+OFS comprises ~15 regional ocean models providing 48–72 hour forecasts of water levels, temperature, and salinity for US coastal bays, estuaries, and offshore waters. This server provides AI assistants with access to model metadata, cycle availability, and forecast extraction at geographic points.
+
+## Supported Models
+
+| Model | Name | Grid | Region |
+| --- | --- | --- | --- |
+| `cbofs` | Chesapeake Bay OFS | ROMS | Chesapeake Bay, MD/VA |
+| `dbofs` | Delaware Bay OFS | ROMS | Delaware Bay, DE/NJ |
+| `gomofs` | Gulf of Maine OFS | ROMS | Gulf of Maine, ME/MA |
+| `ngofs2` | N. Gulf of Mexico OFS v2 | FVCOM | Gulf Coast, LA/TX |
+| `nyofs` | New York/NJ Harbor OFS | FVCOM | NY Harbor, NY/NJ |
+| `sfbofs` | San Francisco Bay OFS | FVCOM | San Francisco Bay, CA |
+| `tbofs` | Tampa Bay OFS | FVCOM | Tampa Bay, FL |
+| `wcofs` | West Coast OFS | ROMS | US West Coast, CA–WA |
+| `ciofs` | Cook Inlet OFS | FVCOM | Cook Inlet, AK |
+
+All models run 4× daily (2× for WCOFS) at 00, 06, 12, 18 UTC with 6-minute output resolution.
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `ofs_list_models` | List all supported models with metadata |
+| `ofs_get_model_info` | Detailed specs for a specific model |
+| `ofs_list_cycles` | Check S3 for available forecast cycles |
+| `ofs_find_models_for_location` | Which models cover a lat/lon point |
+| `ofs_get_forecast_at_point` | Forecast time series at lat/lon |
+| `ofs_compare_with_coops` | Compare model vs CO-OPS observations |
+
+## Data Access
+
+Model data is accessed via two strategies:
+- **NOAA THREDDS OPeNDAP** (`https://opendap.co-ops.nos.noaa.gov/thredds/`): lazy remote access to BEST aggregations (most efficient, only loads requested variables/points)
+- **AWS S3** (`noaa-nos-ofs-pds`): direct download for single forecast timesteps
+
+## Quick Start
+
+```bash
+cd servers/ofs-mcp
+uv sync
+uv run ofs-mcp
+```
+
+### MCP Client Config
+
+```json
+{
+  "mcpServers": {
+    "ofs": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/ocean-mcp/servers/ofs-mcp", "run", "ofs-mcp"]
+    }
+  }
+}
+```
+
+## Example Queries
+
+- "What OFS models cover the Chesapeake Bay?"
+- "List available CBOFS forecast cycles for today"
+- "Get the water level forecast at lat 38.98, lon -76.48 from CBOFS"
+- "Compare CBOFS water level with CO-OPS observations at station 8571892"
+- "What OFS models are available for San Francisco Bay?"
+- "Get temperature forecast at lat 37.8, lon -122.4 from SFBOFS"
+
+## Variables
+
+All models provide surface-layer output:
+
+| Variable | Units | Description |
+| --- | --- | --- |
+| `water_level` | m | Surface elevation relative to model datum |
+| `temperature` | °C | Water temperature at surface sigma layer |
+| `salinity` | PSU | Salinity at surface sigma layer |
+
+## Datum Notes
+
+Most OFS models use **NAVD88** as their vertical datum. CO-OPS observations use either NAVD or MSL depending on the station. Small systematic offsets (1–5 cm) are expected when comparing model output to observations due to datum differences and distance between CO-OPS stations and model grid points.
+
+## Data Sources
+
+- [NOAA OFS Overview](https://tidesandcurrents.noaa.gov/models.html)
+- [AWS S3: noaa-nos-ofs-pds](https://registry.opendata.aws/noaa-nos-ofs/)
+- [NOAA THREDDS](https://opendap.co-ops.nos.noaa.gov/thredds/)
+- [CO-OPS API](https://api.tidesandcurrents.noaa.gov/api/prod/)
+
+## License
+
+MIT

ofs_mcp-0.1.0/README.md

@@ -0,0 +1,99 @@
+# OFS MCP Server
+
+<!-- mcp-name: io.github.mansurjisan/ofs-mcp -->
+
+MCP server for NOAA's Operational Forecast System (OFS) — regional hydrodynamic ocean models covering US coastal waters.
+
+**Status**: Ready
+
+## Overview
+
+OFS comprises ~15 regional ocean models providing 48–72 hour forecasts of water levels, temperature, and salinity for US coastal bays, estuaries, and offshore waters. This server provides AI assistants with access to model metadata, cycle availability, and forecast extraction at geographic points.
+
+## Supported Models
+
+| Model | Name | Grid | Region |
+| --- | --- | --- | --- |
+| `cbofs` | Chesapeake Bay OFS | ROMS | Chesapeake Bay, MD/VA |
+| `dbofs` | Delaware Bay OFS | ROMS | Delaware Bay, DE/NJ |
+| `gomofs` | Gulf of Maine OFS | ROMS | Gulf of Maine, ME/MA |
+| `ngofs2` | N. Gulf of Mexico OFS v2 | FVCOM | Gulf Coast, LA/TX |
+| `nyofs` | New York/NJ Harbor OFS | FVCOM | NY Harbor, NY/NJ |
+| `sfbofs` | San Francisco Bay OFS | FVCOM | San Francisco Bay, CA |
+| `tbofs` | Tampa Bay OFS | FVCOM | Tampa Bay, FL |
+| `wcofs` | West Coast OFS | ROMS | US West Coast, CA–WA |
+| `ciofs` | Cook Inlet OFS | FVCOM | Cook Inlet, AK |
+
+All models run 4× daily (2× for WCOFS) at 00, 06, 12, 18 UTC with 6-minute output resolution.
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `ofs_list_models` | List all supported models with metadata |
+| `ofs_get_model_info` | Detailed specs for a specific model |
+| `ofs_list_cycles` | Check S3 for available forecast cycles |
+| `ofs_find_models_for_location` | Which models cover a lat/lon point |
+| `ofs_get_forecast_at_point` | Forecast time series at lat/lon |
+| `ofs_compare_with_coops` | Compare model vs CO-OPS observations |
+
+## Data Access
+
+Model data is accessed via two strategies:
+- **NOAA THREDDS OPeNDAP** (`https://opendap.co-ops.nos.noaa.gov/thredds/`): lazy remote access to BEST aggregations (most efficient, only loads requested variables/points)
+- **AWS S3** (`noaa-nos-ofs-pds`): direct download for single forecast timesteps
+
+## Quick Start
+
+```bash
+cd servers/ofs-mcp
+uv sync
+uv run ofs-mcp
+```
+
+### MCP Client Config
+
+```json
+{
+  "mcpServers": {
+    "ofs": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/ocean-mcp/servers/ofs-mcp", "run", "ofs-mcp"]
+    }
+  }
+}
+```
+
+## Example Queries
+
+- "What OFS models cover the Chesapeake Bay?"
+- "List available CBOFS forecast cycles for today"
+- "Get the water level forecast at lat 38.98, lon -76.48 from CBOFS"
+- "Compare CBOFS water level with CO-OPS observations at station 8571892"
+- "What OFS models are available for San Francisco Bay?"
+- "Get temperature forecast at lat 37.8, lon -122.4 from SFBOFS"
+
+## Variables
+
+All models provide surface-layer output:
+
+| Variable | Units | Description |
+| --- | --- | --- |
+| `water_level` | m | Surface elevation relative to model datum |
+| `temperature` | °C | Water temperature at surface sigma layer |
+| `salinity` | PSU | Salinity at surface sigma layer |
+
+## Datum Notes
+
+Most OFS models use **NAVD88** as their vertical datum. CO-OPS observations use either NAVD or MSL depending on the station. Small systematic offsets (1–5 cm) are expected when comparing model output to observations due to datum differences and distance between CO-OPS stations and model grid points.
+
+## Data Sources
+
+- [NOAA OFS Overview](https://tidesandcurrents.noaa.gov/models.html)
+- [AWS S3: noaa-nos-ofs-pds](https://registry.opendata.aws/noaa-nos-ofs/)
+- [NOAA THREDDS](https://opendap.co-ops.nos.noaa.gov/thredds/)
+- [CO-OPS API](https://api.tidesandcurrents.noaa.gov/api/prod/)
+
+## License
+
+MIT

ofs_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ofs-mcp"
+version = "0.1.0"
+description = "MCP server for NOAA Operational Forecast System (OFS) regional ocean model access"
+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",
+    "ocean-forecast",
+    "ofs",
+    "roms",
+    "fvcom",
+    "water-level",
+    "temperature",
+    "salinity",
+    "oceanography",
+]
+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",
+    "netCDF4>=1.7.0",
+    "numpy>=1.26.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/ofs-mcp"
+Changelog = "https://github.com/mansurjisan/ocean-mcp/releases"
+
+[project.scripts]
+ofs-mcp = "ofs_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ofs_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",
+]

ofs_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/ofs-mcp",
+  "title": "NOAA OFS MCP Server",
+  "description": "MCP server for NOAA Operational Forecast System regional ocean models (CBOFS, NGOFS2, WCOFS, etc.) — water level, temperature, salinity. No API key required.",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/mansurjisan/ocean-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "ofs-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

ofs_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: ['ofs-mcp'] })

ofs_mcp-0.1.0/src/ofs_mcp/__init__.py

@@ -0,0 +1 @@
+"""OFS MCP — NOAA Operational Forecast System MCP server."""

ofs_mcp-0.1.0/src/ofs_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running the server with `python -m ofs_mcp`."""
+
+from .server import main
+
+main()

ofs_mcp-0.1.0/src/ofs_mcp/client.py

@@ -0,0 +1,212 @@
+"""Async HTTP client for OFS data on AWS S3, THREDDS/OPeNDAP, and CO-OPS API."""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from .models import COOPS_API_BASE, OFS_MODELS, S3_BASE, THREDDS_BASE
+
+
+class OFSAPIError(Exception):
+    """Custom exception for OFS API errors."""
+    pass
+
+
+class OFSClient:
+    """Async client for OFS data access and CO-OPS observations."""
+
+    def __init__(self) -> None:
+        self._client: httpx.AsyncClient | None = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(
+                timeout=120.0,
+                follow_redirects=True,
+            )
+        return self._client
+
+    async def check_file_exists(self, url: str) -> bool:
+        """Check if a file exists using HTTP HEAD."""
+        client = await self._get_client()
+        try:
+            response = await client.head(url)
+            return response.status_code == 200
+        except Exception:
+            return False
+
+    def build_s3_url(
+        self,
+        model: str,
+        date: str,
+        cycle: str,
+        ftype: str = "f",
+        fhour: int = 1,
+    ) -> str:
+        """Build the S3 URL for an OFS fields NetCDF file.
+
+        Args:
+            model: OFS model key (e.g., 'cbofs').
+            date: Date in YYYYMMDD format.
+            cycle: Cycle hour (e.g., '00', '06', '12', '18').
+            ftype: 'f' for forecast, 'n' for nowcast.
+            fhour: Forecast/nowcast hour number (1-indexed).
+
+        Returns:
+            Full HTTPS URL to the NetCDF file on S3.
+        """
+        y, m, d = date[:4], date[4:6], date[6:8]
+        fname = f"{model}.t{cycle}z.fields.{ftype}{fhour:03d}.nc"
+        return f"{S3_BASE}/{model}/netcdf/{y}/{m}/{d}/{fname}"
+
+    def build_thredds_url(self, model: str) -> str:
+        """Build the THREDDS OPeNDAP URL for the BEST aggregation of an OFS model.
+
+        The BEST aggregation combines the most recent nowcast and forecast data
+        into a continuous time series accessible via OPeNDAP for lazy loading.
+
+        Args:
+            model: OFS model key (e.g., 'cbofs').
+
+        Returns:
+            OPeNDAP URL for the BEST aggregation dataset.
+        """
+        model_info = OFS_MODELS.get(model, {})
+        thredds_id = model_info.get("thredds_id", model.upper())
+        return f"{THREDDS_BASE}/{thredds_id}/{thredds_id}_BEST.nc"
+
+    async def download_netcdf(self, url: str) -> Path:
+        """Download a NetCDF file to a temporary location.
+
+        Args:
+            url: Full HTTPS URL to the NetCDF file.
+
+        Returns:
+            Path to the temporary file. Caller is responsible for deletion.
+
+        Raises:
+            httpx.HTTPStatusError: If the request fails.
+        """
+        client = await self._get_client()
+        response = await client.get(url)
+        response.raise_for_status()
+
+        tmp = tempfile.NamedTemporaryFile(suffix=".nc", delete=False)
+        tmp.write(response.content)
+        tmp.close()
+        return Path(tmp.name)
+
+    def open_opendap(self, model: str):
+        """Open a THREDDS OPeNDAP dataset for lazy remote access.
+
+        Uses netCDF4.Dataset with OPeNDAP — only loads data when variables
+        are actually indexed, enabling efficient point extraction.
+
+        Args:
+            model: OFS model key (e.g., 'cbofs').
+
+        Returns:
+            netCDF4.Dataset opened via OPeNDAP.
+
+        Raises:
+            RuntimeError: If OPeNDAP is not available or connection fails.
+        """
+        import netCDF4
+
+        url = self.build_thredds_url(model)
+        try:
+            nc = netCDF4.Dataset(url)
+            return nc
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to open OPeNDAP dataset for {model.upper()} at {url}. "
+                f"Error: {e}\n\n"
+                "Possible causes:\n"
+                "- THREDDS server temporarily unavailable\n"
+                "- netCDF4 library not compiled with DAP support\n"
+                "- Network connectivity issue\n\n"
+                "Try using a different model or check cycle availability with ofs_list_cycles."
+            ) from e
+
+    async def resolve_latest_cycle(
+        self,
+        model: str,
+        num_days: int = 2,
+    ) -> tuple[str, str] | None:
+        """Find the latest available OFS cycle on AWS S3.
+
+        Args:
+            model: OFS model key (e.g., 'cbofs').
+            num_days: Number of past days to check (default: 2).
+
+        Returns:
+            (date_str, cycle_str) tuple (YYYYMMDD, CC), or None if not found.
+        """
+        from datetime import datetime, timedelta, timezone
+
+        model_info = OFS_MODELS.get(model, {})
+        cycles = model_info.get("cycles", ["00", "06", "12", "18"])
+        # Check newest first
+        cycles_desc = sorted(cycles, reverse=True)
+
+        today = datetime.now(timezone.utc)
+        for day_offset in range(num_days):
+            date = today - timedelta(days=day_offset)
+            date_str = date.strftime("%Y%m%d")
+            for cycle in cycles_desc:
+                url = self.build_s3_url(model, date_str, cycle, "f", 1)
+                if await self.check_file_exists(url):
+                    return date_str, cycle
+
+        return None
+
+    async def fetch_coops_observations(
+        self,
+        station_id: str,
+        begin_date: str,
+        end_date: str,
+        datum: str = "NAVD",
+    ) -> dict[str, Any]:
+        """Fetch CO-OPS observed water levels.
+
+        Args:
+            station_id: CO-OPS station ID (e.g., '8571892').
+            begin_date: Start date (YYYYMMDD or 'YYYYMMDD HH:MM').
+            end_date: End date (YYYYMMDD or 'YYYYMMDD HH:MM').
+            datum: Vertical datum — 'NAVD' for NAVD88, 'MSL', 'MLLW', etc.
+
+        Returns:
+            CO-OPS API JSON response with 'data' list.
+
+        Raises:
+            ValueError: If the CO-OPS API returns an error.
+        """
+        client = await self._get_client()
+        params = {
+            "station": station_id,
+            "product": "water_level",
+            "datum": datum,
+            "units": "metric",
+            "time_zone": "gmt",
+            "format": "json",
+            "begin_date": begin_date,
+            "end_date": end_date,
+            "application": "ofs_mcp",
+        }
+        response = await client.get(COOPS_API_BASE, params=params)
+        response.raise_for_status()
+        data = response.json()
+        if "error" in data:
+            raise ValueError(
+                f"CO-OPS API error: {data['error'].get('message', 'Unknown error')}"
+            )
+        return data
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client and not self._client.is_closed:
+            await self._client.aclose()