@ryancardin/noaa-tides-currents-mcp-server 1.0.0 → 2.0.1

package/README.md

@@ -1,234 +1,199 @@
-# LocalTides MCP Server
+# 🌊 NOAA Tides & Currents MCP Server
 
-[![smithery badge](https://smithery.ai/badge/@RyanCardin15/noaa-tidesandcurrents-mcp)](https://smithery.ai/server/@RyanCardin15/noaa-tidesandcurrents-mcp)
+<div align="center">
 
-This is an MCP (Model Context Protocol) server that provides tools for interacting with the NOAA Tides and Currents API using the FastMCP framework.
+[![npm version](https://img.shields.io/npm/v/@ryancardin/noaa-tides-currents-mcp-server?style=for-the-badge&logo=npm&color=blue)](https://www.npmjs.com/package/@ryancardin/noaa-tides-currents-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![MCP](https://img.shields.io/badge/MCP-Model_Context_Protocol-green?style=for-the-badge)](https://modelcontextprotocol.io/)
 
-## Features
+**A Model Context Protocol server for NOAA CO-OPS Tides and Currents data**
 
-- Water Level data retrieval (real-time and historical)
-- Tide Predictions (high/low or interval-based)
-- Currents data (real-time and historical)
-- Current predictions
-- Station metadata retrieval
-- Wind, air temperature, water temperature, and other meteorological data
-- Moon phase information (past, present, and future)
-- Sun rise/set and position data (past, present, and future)
+Water levels · tide predictions · currents · marine weather · station metadata ·
+tidal datums · harmonic constituents · sea level trends & projections ·
+high tide flooding · sun & moon calculations
 
-## Prerequisites
+</div>
 
-- Node.js (v18 or higher)
-- npm or yarn
+---
 
-## Setup
+## Quick Start
 
-### Installing via Smithery
+```bash
+# Run immediately with npx
+npx @ryancardin/noaa-tides-currents-mcp-server
 
-To install NOAA Tides and Currents for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@RyanCardin15/tidesandcurrents):
+# Or the short alias
+npx noaa-mcp
+```
 
-```bash
-npx -y @smithery/cli install @RyanCardin15/tidesandcurrents --client claude
+### Claude Desktop / Claude Code configuration
+
+```json
+{
+  "mcpServers": {
+    "noaa": {
+      "command": "npx",
+      "args": ["-y", "@ryancardin/noaa-tides-currents-mcp-server"]
+    }
+  }
+}
 ```
 
-### Manual Installation
-1. Clone this repository
-2. Install dependencies
+Claude Code one-liner:
 
 ```bash
-npm install
+claude mcp add noaa -- npx -y @ryancardin/noaa-tides-currents-mcp-server
 ```
 
-3. Build the TypeScript code
+### HTTP mode (optional)
 
 ```bash
-npm run build
+npx noaa-mcp --http --port 3000   # stateless streamable HTTP at http://localhost:3000/mcp
 ```
 
-4. Start the server
+No API key is required — NOAA's CO-OPS APIs are open.
 
-```bash
-npm start
-```
+---
 
-## Usage
+## Tools (23)
 
-This MCP server can be used with any MCP host such as Claude Desktop, which allows you to use the NOAA Tides and Currents API through the MCP protocol.
+### Observations & Predictions (Data API)
 
-You can also test it directly using the `fastmcp` command-line tool:
+| Tool | What it does |
+|---|---|
+| `noaa_get_water_levels` | Observed water levels: 1-minute, 6-minute, or hourly series, preliminary/verified quality flags decoded |
+| `noaa_get_water_level_summaries` | high_low (HH/H/L/LL daily extremes), daily_mean (Great Lakes), daily_max_min, monthly_mean datum tables |
+| `noaa_get_tide_predictions` | Harmonic tide predictions — `hilo` high/low events (up to 10 years) or interval series |
+| `noaa_get_currents` | Observed current speed/direction by depth bin (ADCP), optional beam diagnostics |
+| `noaa_get_current_predictions` | Predicted currents — `max_slack` flood/ebb/slack events or interval series |
+| `noaa_get_meteorological_data` | Wind, air/water temperature, pressure, air gap (bridge clearance), conductivity, visibility, humidity, salinity |
 
-```bash
-npx fastmcp dev dist/index.js
-```
+### Station Discovery & Metadata (Metadata API)
+
+| Tool | What it does |
+|---|---|
+| `noaa_search_stations` | Search the station directory by capability type, name substring, state — paginated |
+| `noaa_find_nearest_stations` | Nearest stations to any lat/lon (great-circle, cached directory), filterable by type |
+| `noaa_get_station_info` | Full station record with expandable sensors, flood levels, benchmarks, bins, deployments... |
+| `noaa_get_station_datums` | Tidal datum elevations (MLLW, MSL, MHHW, NAVD88...), HAT/LAT, historic extremes, current or superseded epoch |
+| `noaa_get_harmonic_constituents` | The M2/S2/K1/... constituents behind a station's predictions (water level or current ellipse form) |
+| `noaa_get_prediction_offsets` | Subordinate-station time/height offsets from their reference stations (tide or current) |
+
+### Climate & Derived Products (DPAPI)
+
+| Tool | What it does |
+|---|---|
+| `noaa_get_sea_level_trends` | Long-term relative sea level trend with error bars and observation period |
+| `noaa_get_sea_level_rise_projections` | 2022 Interagency SLR scenario projections per decade through 2150 |
+| `noaa_get_extreme_water_levels` | Annual exceedance probability levels (e.g. the "100-year" water level) |
+| `noaa_get_top_ten_water_levels` | Highest water levels ever recorded, with causal events (hurricanes, nor'easters) |
+| `noaa_get_high_tide_flooding` | HTF flood-day counts (daily/monthly/seasonal/annual), outlooks, decadal projections, likelihoods |
+
+### Astronomy (computed locally)
+
+| Tool | What it does |
+|---|---|
+| `astro_get_moon_phase` | Phase, illumination, age, distance for a date or range (spring/neap tide context) |
+| `astro_get_next_moon_phase` | Next new/full/quarter moon date(s) |
+| `astro_get_sun_times` | Sunrise/sunset, twilights, golden hour, day length for any location/date |
+| `astro_get_sun_position` | Azimuth/altitude (+ approximate declination/RA) |
+| `astro_get_next_sun_event` | Next occurrence(s) of any sun event |
+
+### Reference
+
+| Tool | What it does |
+|---|---|
+| `noaa_get_reference_guide` | Curated NOAA reference: products, datums, units, time zones, intervals, station types, data limits, quality flags, date formats |
+
+Every tool supports `response_format: "markdown"` (readable tables with units spelled out — the default) or `"json"` (complete structured payload), and attaches structured content for MCP clients that consume it.
+
+## Resources
+
+- `noaa://guide/getting-started` — workflow recipes and common pitfalls
+- `noaa://reference/{topic}` — the nine reference topics above as pinnable resources
+
+## Prompts
 
-Or, you can use the MCP Inspector:
+- `tide_report` — tide report for a place/station and date
+- `boating_conditions` — pre-departure briefing: tides, currents, wind, daylight
+- `station_flood_risk` — flood risk profile: HTF history, extremes, trends, projections
+- `station_overview` — everything a station offers
+
+---
+
+## The Nuances (handled for you)
+
+These are the things that make NOAA's API tricky — this server encodes them:
+
+- **Datums matter.** Heights are meaningless without a vertical reference. MLLW (chart datum) is the default; stations differ in which datums they support (Great Lakes use IGLD/LWD and have **no tide predictions**). `noaa_get_station_datums` gives the conversion table.
+- **Units are asymmetric.** `metric` means m/s for wind but **cm/s for currents**; air pressure is millibars and salinity PSU in *both* systems. Every response labels its units.
+- **Per-product request-span limits** (4 days for 1-minute data, 31 days for 6-minute, 1 year hourly, 10 years for hilo predictions...) are validated client-side with actionable messages before hitting NOAA.
+- **Two station ID schemes.** Water-level/met stations are 7-digit numeric (`9414290`); current stations are alphanumeric (`cb0102`).
+- **Reference vs subordinate stations.** Subordinate (S) prediction stations only support `hilo` predictions, derived by offsets from a reference (R) station.
+- **`daily_mean` requires local standard time** and only exists for Great Lakes stations — enforced automatically.
+- **Quality flags decoded.** Preliminary vs verified data, sigma, flag alphabets (which differ between preliminary and verified!), and HH/H/L/LL tide types are explained inline.
+- **Predictions are astronomical** — storm surge is not included; compare with observed water levels.
+- **Station directory is cached** (6 h) so nearest-station searches don't refetch thousands of records.
+
+---
+
+## Usage Examples
+
+> "When is high tide in Boston tomorrow?"
+
+1. `noaa_find_nearest_stations` (type `tidepredictions`) → `8443970 BOSTON`
+2. `noaa_get_tide_predictions` (interval `hilo`) → high/low times & heights above MLLW
+
+> "How strong will the current be in the Cape Cod Canal this afternoon?"
+
+1. `noaa_find_nearest_stations` (type `currentpredictions`)
+2. `noaa_get_current_predictions` (interval `max_slack`) → max flood/ebb (knots) and slack times
+
+> "How often does Providence flood now vs 20 years ago, and what's projected for 2050?"
+
+1. `noaa_get_high_tide_flooding` (report `annual`, range 25)
+2. `noaa_get_high_tide_flooding` (report `projections`, decade 2050)
+3. `noaa_get_sea_level_trends` + `noaa_get_sea_level_rise_projections`
+
+---
+
+## Development
 
 ```bash
-npx fastmcp inspect dist/index.js
+npm install
+npm run build        # tsc → dist/
+npm test             # vitest unit tests (validation, formatting, astronomy)
+npm run test:live    # end-to-end smoke test against the live NOAA API
+npm run inspector    # MCP Inspector against dist/index.js
+npm run dev          # tsx src/index.ts
 ```
 
-### Available Tools
-
-#### Parameter Definitions
-
-- `get_parameter_definitions` - Get information about valid parameter values for NOAA API requests
-  - Parameters:
-    - `parameter` (string, optional) - Parameter type to get information about (time_zones, datums, units, tide_intervals, current_intervals, velocity_types, products, station_types, date_formats, output_formats). If not provided, returns information about all parameter types.
-
-#### Water Levels
-
-- `get_water_levels` - Get water level data for a station
-  - Parameters:
-    - `station` (string) - Station ID
-    - `date` (string, optional) - Date to retrieve data for ("today", "latest", "recent", or specific date)
-    - `begin_date` (string, optional) - Start date (YYYYMMDD or MM/DD/YYYY)
-    - `end_date` (string, optional) - End date (YYYYMMDD or MM/DD/YYYY)
-    - `range` (number, optional) - Number of hours to retrieve data for
-    - `datum` (string, optional) - Datum to use (MLLW, MSL, etc.)
-    - `units` (string, optional) - Units to use ("english" or "metric")
-    - `time_zone` (string, optional) - Time zone (gmt, lst, lst_ldt)
-    - `format` (string, optional) - Output format (json, xml, csv)
-
-#### Tide Predictions
-
-- `get_tide_predictions` - Get tide prediction data
-  - Parameters:
-    - `station` (string) - Station ID
-    - `begin_date` (string) - Start date (YYYYMMDD or MM/DD/YYYY)
-    - `end_date` (string) - End date (YYYYMMDD or MM/DD/YYYY)
-    - `datum` (string, optional) - Datum to use (MLLW, MSL, etc.)
-    - `units` (string, optional) - Units to use ("english" or "metric")
-    - `time_zone` (string, optional) - Time zone (gmt, lst, lst_ldt)
-    - `interval` (string, optional) - Interval (hilo, hl, h, or a number for minutes)
-    - `format` (string, optional) - Output format (json, xml, csv)
-
-#### Currents
-
-- `get_currents` - Get currents data for a station
-  - Parameters:
-    - `station` (string) - Station ID
-    - `date` (string, optional) - Date to retrieve data for ("today", "latest", "recent", or specific date)
-    - `begin_date` (string, optional) - Start date (YYYYMMDD or MM/DD/YYYY)
-    - `end_date` (string, optional) - End date (YYYYMMDD or MM/DD/YYYY)
-    - `bin` (number, optional) - Bin number
-    - `units` (string, optional) - Units to use ("english" or "metric")
-    - `time_zone` (string, optional) - Time zone (gmt, lst, lst_ldt)
-    - `format` (string, optional) - Output format (json, xml, csv)
-
-#### Current Predictions
-
-- `get_current_predictions` - Get current predictions
-  - Parameters:
-    - `station` (string) - Station ID
-    - `date` (string, optional) - Date to retrieve data for ("today", "latest", "recent", or specific date)
-    - `begin_date` (string, optional) - Start date (YYYYMMDD or MM/DD/YYYY)
-    - `end_date` (string, optional) - End date (YYYYMMDD or MM/DD/YYYY)
-    - `bin` (number, optional) - Bin number
-    - `interval` (string, optional) - Interval (MAX_SLACK or a number for minutes)
-    - `vel_type` (string, optional) - Velocity type (speed_dir or default)
-    - `units` (string, optional) - Units to use ("english" or "metric")
-    - `time_zone` (string, optional) - Time zone (gmt, lst, lst_ldt)
-    - `format` (string, optional) - Output format (json, xml, csv)
-
-#### Meteorological Data
-
-- `get_meteorological_data` - Get meteorological data
-  - Parameters:
-    - `station` (string) - Station ID
-    - `product` (string) - Product (air_temperature, wind, etc.)
-    - `date` (string, optional) - Date to retrieve data for ("today", "latest", "recent", or specific date)
-    - `begin_date` (string, optional) - Start date (YYYYMMDD or MM/DD/YYYY)
-    - `end_date` (string, optional) - End date (YYYYMMDD or MM/DD/YYYY)
-    - `units` (string, optional) - Units to use ("english" or "metric")
-    - `time_zone` (string, optional) - Time zone (gmt, lst, lst_ldt)
-    - `format` (string, optional) - Output format (json, xml, csv)
-
-#### Station Information
-
-- `get_stations` - Get list of stations
-  - Parameters:
-    - `type` (string, optional) - Station type (waterlevels, currents, etc.)
-    - `units` (string, optional) - Units to use ("english" or "metric")
-    - `format` (string, optional) - Output format (json, xml)
-
-- `get_station_details` - Get detailed information about a station
-  - Parameters:
-    - `station` (string) - Station ID
-    - `units` (string, optional) - Units to use ("english" or "metric")
-    - `format` (string, optional) - Output format (json, xml)
-
-#### Moon Phase Information
-
-- `get_moon_phase` - Get moon phase information for a specific date
-  - Parameters:
-    - `date` (string, optional) - Date to get moon phase for (YYYY-MM-DD format). Defaults to current date.
-    - `latitude` (number, optional) - Latitude for location-specific calculations
-    - `longitude` (number, optional) - Longitude for location-specific calculations
-    - `format` (string, optional) - Output format (json or text)
-
-- `get_moon_phases_range` - Get moon phase information for a date range
-  - Parameters:
-    - `start_date` (string) - Start date (YYYY-MM-DD format)
-    - `end_date` (string) - End date (YYYY-MM-DD format)
-    - `latitude` (number, optional) - Latitude for location-specific calculations
-    - `longitude` (number, optional) - Longitude for location-specific calculations
-    - `format` (string, optional) - Output format (json or text)
-
-- `get_next_moon_phase` - Get the next occurrence(s) of a specific moon phase
-  - Parameters:
-    - `phase` (string) - Moon phase to find (New Moon, First Quarter, Full Moon, Last Quarter)
-    - `date` (string, optional) - Starting date (YYYY-MM-DD format). Defaults to current date.
-    - `count` (number, optional) - Number of occurrences to return. Defaults to 1.
-    - `format` (string, optional) - Output format (json or text)
-
-#### Sun Rise/Set Information
-
-- `get_sun_times` - Get sun rise/set and other sun event times for a specific date and location
-  - Parameters:
-    - `date` (string, optional) - Date to get sun times for (YYYY-MM-DD format). Defaults to current date.
-    - `latitude` (number) - Latitude for location-specific calculations
-    - `longitude` (number) - Longitude for location-specific calculations
-    - `format` (string, optional) - Output format (json or text)
-    - `timezone` (string, optional) - Timezone for the results. Defaults to UTC.
-
-- `get_sun_times_range` - Get sun rise/set and other sun event times for a date range and location
-  - Parameters:
-    - `start_date` (string) - Start date (YYYY-MM-DD format)
-    - `end_date` (string) - End date (YYYY-MM-DD format)
-    - `latitude` (number) - Latitude for location-specific calculations
-    - `longitude` (number) - Longitude for location-specific calculations
-    - `format` (string, optional) - Output format (json or text)
-    - `timezone` (string, optional) - Timezone for the results. Defaults to UTC.
-
-- `get_sun_position` - Get sun position information for a specific date, time, and location
-  - Parameters:
-    - `date` (string, optional) - Date to get sun position for (YYYY-MM-DD format). Defaults to current date.
-    - `time` (string, optional) - Time to get sun position for (HH:MM:SS format). Defaults to current time.
-    - `latitude` (number) - Latitude for location-specific calculations
-    - `longitude` (number) - Longitude for location-specific calculations
-    - `format` (string, optional) - Output format (json or text)
-
-- `get_next_sun_event` - Get the next occurrence(s) of a specific sun event
-  - Parameters:
-    - `event` (string) - Sun event to find (sunrise, sunset, dawn, dusk, solarNoon, etc.)
-    - `date` (string, optional) - Starting date (YYYY-MM-DD format). Defaults to current date.
-    - `latitude` (number) - Latitude for location-specific calculations
-    - `longitude` (number) - Longitude for location-specific calculations
-    - `count` (number, optional) - Number of occurrences to return. Defaults to 1.
-    - `format` (string, optional) - Output format (json or text)
-    - `timezone` (string, optional) - Timezone for the results. Defaults to UTC.
-
-## API Documentation
-
-NOAA Tides and Currents API documentation can be found at:
-- CO-OPS Data API: https://api.tidesandcurrents.noaa.gov/api/prod/
-- CO-OPS Metadata API: https://api.tidesandcurrents.noaa.gov/mdapi/prod/
-- CO-OPS Derived Product API: https://api.tidesandcurrents.noaa.gov/dpapi/prod/
+### Architecture
 
-## License
+```
+src/
+├── index.ts            # entry point: stdio (default) or --http streamable HTTP
+├── constants.ts        # API base URLs, timeouts, cache TTLs, response limits
+├── client/             # shared HTTP layer (retry/backoff, error mapping) + TTL cache
+├── validation/         # date normalization + per-product span limit enforcement
+├── format/             # unit labeling, flag legends, markdown/json response shaping
+├── schemas/            # shared Zod field schemas with nuance-carrying descriptions
+├── services/           # Data API, Metadata API, DPAPI, moon & sun services
+├── tools/              # 23 tool registrations grouped by domain
+├── resources/          # noaa:// reference resources
+├── prompts/            # workflow prompt templates
+└── reference/          # curated NOAA reference content
+```
 
-MIT 
+Data sources:
+- **Data API** — `api.tidesandcurrents.noaa.gov/api/prod/datagetter`
+- **Metadata API** — `api.tidesandcurrents.noaa.gov/mdapi/prod/webapi`
+- **Derived Product API** — `api.tidesandcurrents.noaa.gov/dpapi/prod/webapi`
+- **Astronomy** — [suncalc](https://github.com/mourner/suncalc), computed locally
 
+## License
 
-<a href="https://glama.ai/mcp/servers/ro2rz2c734">
-  <img width="380" height="200" src="https://glama.ai/mcp/servers/ro2rz2c734/badge" />
+MIT © Ryan Cardin
 
+NOAA data is provided by the NOAA Center for Operational Oceanographic Products and Services (CO-OPS). This project is not affiliated with or endorsed by NOAA.

package/dist/client/cache.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal in-memory TTL cache used for NOAA metadata responses.
+ * Station directories and per-station metadata change rarely, so caching
+ * them avoids re-fetching multi-thousand-entry lists on every tool call.
+ */
+export declare class TtlCache {
+    private entries;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttlMs: number): void;
+    /** Fetch-through helper: returns cached value or runs `loader` and caches it. */
+    getOrLoad<T>(key: string, ttlMs: number, loader: () => Promise<T>): Promise<T>;
+    clear(): void;
+}
+/** Shared cache instance for the server process. */
+export declare const cache: TtlCache;

package/dist/client/cache.js

@@ -0,0 +1,44 @@
+/**
+ * Minimal in-memory TTL cache used for NOAA metadata responses.
+ * Station directories and per-station metadata change rarely, so caching
+ * them avoids re-fetching multi-thousand-entry lists on every tool call.
+ */
+const MAX_ENTRIES = 200;
+export class TtlCache {
+    entries = new Map();
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, ttlMs) {
+        // Evict the oldest entry when full (insertion order approximates LRU
+        // well enough for this workload).
+        if (this.entries.size >= MAX_ENTRIES && !this.entries.has(key)) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest !== undefined)
+                this.entries.delete(oldest);
+        }
+        this.entries.delete(key);
+        this.entries.set(key, { value, expiresAt: Date.now() + ttlMs });
+    }
+    /** Fetch-through helper: returns cached value or runs `loader` and caches it. */
+    async getOrLoad(key, ttlMs, loader) {
+        const cached = this.get(key);
+        if (cached !== undefined)
+            return cached;
+        const value = await loader();
+        this.set(key, value, ttlMs);
+        return value;
+    }
+    clear() {
+        this.entries.clear();
+    }
+}
+/** Shared cache instance for the server process. */
+export const cache = new TtlCache();

package/dist/client/http.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared HTTP layer for all three NOAA CO-OPS API surfaces.
+ *
+ * Responsibilities:
+ *  - one axios instance with a sane timeout and identifying User-Agent
+ *  - retry with backoff on transient failures (network, 5xx, 429)
+ *  - mapping upstream errors to actionable, agent-friendly messages
+ *    (the Data API returns structured `{error:{message}}` bodies; the
+ *    Metadata API returns bare 404s with no body — they are handled
+ *    differently on purpose)
+ */
+/** Error thrown for any NOAA API failure, with a message safe to show the agent. */
+export declare class NoaaApiError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/** Strip undefined/null/empty-string params so URLs stay clean. */
+export declare function cleanParams(params: Record<string, string | number | boolean | undefined | null>): Record<string, string>;
+/**
+ * Data API GET. Always requests JSON and tags the query with our application
+ * name. The Data API can return HTTP 200 with an error body, so both paths
+ * are checked.
+ */
+export declare function fetchDataApi<T = Record<string, unknown>>(params: Record<string, string | number | boolean | undefined | null>): Promise<T>;
+/** Metadata API GET: path like "/stations.json" or "/stations/8454000/datums.json". */
+export declare function fetchMetadataApi<T = Record<string, unknown>>(path: string, params?: Record<string, string | number | boolean | undefined | null>): Promise<T>;
+/** Derived Product API GET: path like "/htf/htf_annual.json". */
+export declare function fetchDpapi<T = Record<string, unknown>>(path: string, params?: Record<string, string | number | boolean | undefined | null>): Promise<T>;

package/dist/client/http.js

@@ -0,0 +1,178 @@
+/**
+ * Shared HTTP layer for all three NOAA CO-OPS API surfaces.
+ *
+ * Responsibilities:
+ *  - one axios instance with a sane timeout and identifying User-Agent
+ *  - retry with backoff on transient failures (network, 5xx, 429)
+ *  - mapping upstream errors to actionable, agent-friendly messages
+ *    (the Data API returns structured `{error:{message}}` bodies; the
+ *    Metadata API returns bare 404s with no body — they are handled
+ *    differently on purpose)
+ */
+import axios from "axios";
+import { APPLICATION_NAME, DATA_API_BASE_URL, DPAPI_BASE_URL, MAX_RETRIES, METADATA_API_BASE_URL, REQUEST_TIMEOUT_MS, } from "../constants.js";
+/** Error thrown for any NOAA API failure, with a message safe to show the agent. */
+export class NoaaApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "NoaaApiError";
+    }
+}
+const http = axios.create({
+    timeout: REQUEST_TIMEOUT_MS,
+    headers: {
+        Accept: "application/json",
+        "User-Agent": `${APPLICATION_NAME}/2.0`,
+    },
+});
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryable(error) {
+    if (!axios.isAxiosError(error))
+        return false;
+    if (!error.response)
+        return true; // network error / timeout
+    const status = error.response.status;
+    return status === 429 || status >= 500;
+}
+/** Strip undefined/null/empty-string params so URLs stay clean. */
+export function cleanParams(params) {
+    const out = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        out[key] = String(value);
+    }
+    return out;
+}
+async function getWithRetry(url, params) {
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const response = await http.get(url, { params });
+            return response.data;
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < MAX_RETRIES && isRetryable(error)) {
+                await sleep(500 * Math.pow(3, attempt)); // 500ms, 1.5s
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw lastError;
+}
+/** Shape of Data API / DPAPI error bodies: {"error": {"message": "..."}} */
+function extractUpstreamMessage(data) {
+    if (data && typeof data === "object") {
+        const err = data.error;
+        if (err && typeof err.message === "string")
+            return err.message.trim();
+    }
+    if (typeof data === "string" && data.includes("<error>")) {
+        const match = data.match(/<error>([\s\S]*?)<\/error>/);
+        if (match)
+            return match[1].trim();
+    }
+    return undefined;
+}
+/** Add a helpful next step based on common NOAA error message patterns. */
+function adviceFor(message) {
+    const lower = message.toLowerCase();
+    // Check "no data" before "station": NOAA's no-data message mentions the
+    // word "station" too, and the availability hint is the useful one.
+    if (lower.includes("no data")) {
+        return ' The station may not collect this product, or the requested window may pre-date its record (recent current-meter deployments come and go). Check availability with noaa_get_station_info, or try date="recent".';
+    }
+    if (lower.includes("datum")) {
+        return " Use noaa_get_station_datums to see which datums this station supports (Great Lakes stations use IGLD/LWD; coastal stations use MLLW/MSL/etc.).";
+    }
+    if (lower.includes("date") || lower.includes("range")) {
+        return ' Accepted date formats: yyyyMMdd, "yyyyMMdd HH:mm", MM/dd/yyyy, or ISO yyyy-MM-dd. Check the per-product maximum span with noaa_get_reference_guide (topic "data_limits").';
+    }
+    if (lower.includes("station")) {
+        return ' Verify the station ID with noaa_search_stations or noaa_find_nearest_stations (water-level stations use 7-digit numeric IDs; current stations use alphanumeric IDs like "cb0102").';
+    }
+    if (lower.includes("prediction")) {
+        return ' Note: Great Lakes stations have no tide predictions, and subordinate (type "S") stations only support interval=hilo.';
+    }
+    return "";
+}
+function toNoaaError(error, apiLabel) {
+    if (axios.isAxiosError(error)) {
+        const axErr = error;
+        if (axErr.response) {
+            const status = axErr.response.status;
+            const upstream = extractUpstreamMessage(axErr.response.data);
+            if (upstream) {
+                return new NoaaApiError(`NOAA ${apiLabel} error: ${upstream}${adviceFor(upstream)}`, status);
+            }
+            if (status === 404) {
+                return new NoaaApiError(`NOAA ${apiLabel} error: not found (404). The station ID may be wrong or this station does not have the requested resource. Verify with noaa_search_stations.`, status);
+            }
+            if (status === 429) {
+                return new NoaaApiError(`NOAA ${apiLabel} error: rate limited (429). NOAA throttles heavy query volume — wait a moment and retry, and request narrower date ranges.`, status);
+            }
+            return new NoaaApiError(`NOAA ${apiLabel} error: HTTP ${status}.`, status);
+        }
+        if (axErr.code === "ECONNABORTED") {
+            return new NoaaApiError(`NOAA ${apiLabel} error: request timed out after ${REQUEST_TIMEOUT_MS / 1000}s. Try a narrower date range or retry.`);
+        }
+        return new NoaaApiError(`NOAA ${apiLabel} error: network failure (${axErr.code ?? "unknown"}).`);
+    }
+    return new NoaaApiError(`NOAA ${apiLabel} error: ${error instanceof Error ? error.message : String(error)}`);
+}
+/**
+ * Data API GET. Always requests JSON and tags the query with our application
+ * name. The Data API can return HTTP 200 with an error body, so both paths
+ * are checked.
+ */
+export async function fetchDataApi(params) {
+    const query = cleanParams({
+        ...params,
+        application: APPLICATION_NAME,
+        format: "json",
+    });
+    try {
+        const data = await getWithRetry(DATA_API_BASE_URL, query);
+        const upstream = extractUpstreamMessage(data);
+        if (upstream) {
+            throw new NoaaApiError(`NOAA Data API error: ${upstream}${adviceFor(upstream)}`);
+        }
+        return data;
+    }
+    catch (error) {
+        if (error instanceof NoaaApiError)
+            throw error;
+        throw toNoaaError(error, "Data API");
+    }
+}
+/** Metadata API GET: path like "/stations.json" or "/stations/8454000/datums.json". */
+export async function fetchMetadataApi(path, params = {}) {
+    try {
+        return await getWithRetry(`${METADATA_API_BASE_URL}${path}`, cleanParams(params));
+    }
+    catch (error) {
+        throw toNoaaError(error, "Metadata API");
+    }
+}
+/** Derived Product API GET: path like "/htf/htf_annual.json". */
+export async function fetchDpapi(path, params = {}) {
+    try {
+        const data = await getWithRetry(`${DPAPI_BASE_URL}${path}`, cleanParams(params));
+        const upstream = extractUpstreamMessage(data);
+        if (upstream) {
+            throw new NoaaApiError(`NOAA Derived Product API error: ${upstream}${adviceFor(upstream)}`);
+        }
+        return data;
+    }
+    catch (error) {
+        if (error instanceof NoaaApiError)
+            throw error;
+        throw toNoaaError(error, "Derived Product API");
+    }
+}