Metadata-Version: 2.4
Name: stofs-mcp
Version: 0.1.0
Summary: MCP server for NOAA STOFS storm surge forecast access and validation against CO-OPS observations
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/stofs-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: adcirc,coastal-flooding,mcp,model-context-protocol,noaa,oceanography,schism,stofs,storm-surge
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
Requires-Dist: xarray>=2024.1.0
Description-Content-Type: text/markdown

# STOFS MCP Server

<!-- mcp-name: io.github.mansurjisan/stofs-mcp -->

MCP server providing AI assistants with access to NOAA's Storm Tide Operational Forecast System (STOFS) — operational storm surge and water level forecasts, and validation against CO-OPS observations.

**Status: Ready**

## Tools

| Tool | Description |
|------|-------------|
| `stofs_list_cycles` | List available STOFS forecast cycles on AWS S3 |
| `stofs_get_station_forecast` | Get water level forecast time series at a CO-OPS station |
| `stofs_get_point_forecast` | Get forecast at arbitrary lat/lon (nearest STOFS station) |
| `stofs_get_gridded_forecast` | Forecast at any lat/lon via OPeNDAP (regular grid, no download) |
| `stofs_compare_with_observations` | Compare STOFS forecast vs CO-OPS observations (bias, RMSE, correlation) |
| `stofs_get_max_water_level` | Get top stations by peak predicted water level in a cycle |
| `stofs_get_system_info` | STOFS model specifications, datums, cycle schedule |
| `stofs_list_stations` | List STOFS output stations, filter by state/region/proximity |

## STOFS Models

### STOFS-2D-Global (ADCIRC)
- **Domain**: Global unstructured mesh (~12.8M nodes)
- **Cycles**: 4x daily — 00, 06, 12, 18 UTC
- **Forecast**: 180 hours (7.5 days)
- **Stations**: ~385 output points at 6-minute resolution
- **Datum**: LMSL (Local Mean Sea Level)
- **Data**: [s3://noaa-gestofs-pds](https://noaa-gestofs-pds.s3.amazonaws.com)

### STOFS-3D-Atlantic (SCHISM)
- **Domain**: US East Coast + Gulf of Mexico + Puerto Rico (~2.9M nodes)
- **Cycles**: 1x daily — 12 UTC
- **Forecast**: 96 hours (4 days)
- **Stations**: ~108 output points at 6-minute resolution
- **Datum**: NAVD88
- **Data**: [s3://noaa-nos-stofs3d-pds](https://noaa-nos-stofs3d-pds.s3.amazonaws.com)

## Vertical Datums

> ⚠️ Datum differences matter when comparing models and observations:
> - **STOFS-2D station files**: LMSL (Local Mean Sea Level)
> - **STOFS-3D station files**: NAVD88
> - **CO-OPS API**: Use `datum=MSL` for 2D comparison, `datum=NAVD` for 3D comparison
> - Small systematic offsets (1–5 cm) between LMSL and MSL are expected

## Quick Start

```bash
git clone https://github.com/mansurjisan/ocean-mcp.git
cd ocean-mcp/servers/stofs-mcp
uv sync
```

### Configure your MCP client

```json
{
  "mcpServers": {
    "stofs": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ocean-mcp/servers/stofs-mcp", "python", "-m", "stofs_mcp"]
    }
  }
}
```

## Example Queries

- "What is the latest STOFS-2D-Global forecast cycle?"
- "Get the water level forecast for The Battery, NY (station 8518750)"
- "Compare STOFS forecast vs observations at Boston for the past 24 hours"
- "Find STOFS stations within 50 km of New Orleans"
- "What are the top 10 stations with highest predicted water levels?"
- "Get the surge-only forecast at Charleston, SC"
- "Show me the STOFS forecast near lat 29.95, lon -90.07"
- "Get the STOFS forecast at lat 36.85, lon -75.98 (Virginia Beach) using the gridded product"

## Running Tests

```bash
# Unit tests (fast, no network)
uv run pytest tests/test_utils.py -v

# Live integration tests (requires internet, downloads ~5–10 MB)
uv run pytest tests/test_live.py -v -s
```

## Data Sources

- **AWS S3** (primary): `noaa-gestofs-pds` (2D-Global), `noaa-nos-stofs3d-pds` (3D-Atlantic)
- **NOMADS OPeNDAP**: `nomads.ncep.noaa.gov/dods/stofs_2d_glo/` (remote slice of regular-grid data, ~2-day window)
- **CO-OPS API**: `api.tidesandcurrents.noaa.gov` (for observation validation)

## License

MIT
