@ryancardin/noaa-tides-currents-mcp-server 2.0.0 → 2.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Ryan Cardin
+Copyright (c) 2025 Cardin LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -9,6 +9,8 @@
 
 **A Model Context Protocol server for NOAA CO-OPS Tides and Currents data**
 
+Built by [Cardin Labs](https://cardinlabs.com) · Hosted at [Perigee](https://perigee-two.vercel.app)
+
 Water levels · tide predictions · currents · marine weather · station metadata ·
 tidal datums · harmonic constituents · sea level trends & projections ·
 high tide flooding · sun & moon calculations
@@ -56,7 +58,7 @@ No API key is required — NOAA's CO-OPS APIs are open.
 
 ---
 
-## Tools (23)
+## Tools (25)
 
 ### Observations & Predictions (Data API)
 
@@ -100,18 +102,25 @@ No API key is required — NOAA's CO-OPS APIs are open.
 | `astro_get_sun_position` | Azimuth/altitude (+ approximate declination/RA) |
 | `astro_get_next_sun_event` | Next occurrence(s) of any sun event |
 
+### Wind & Marine Forecasts (NWS Weather API)
+
+| Tool | What it does |
+|---|---|
+| `nws_get_wind_forecast` | Hourly numeric wind forecast (speed/gust/direction, wave height where gridded) for any US lat/lon, up to ~7 days |
+| `nws_get_marine_forecast` | Official Coastal Waters Forecast narrative for the marine zone covering a lat/lon, incl. Small Craft Advisories |
+
 ### 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 |
+| `noaa_get_reference_guide` | Curated NOAA reference: products, datums, units, time zones, intervals, station types, data limits, quality flags, date formats, marine forecasts |
 
 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
+- `noaa://reference/{topic}` — the ten reference topics above as pinnable resources
 
 ## Prompts
 
@@ -180,7 +189,7 @@ src/
 ├── 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
+├── tools/              # 25 tool registrations grouped by domain
 ├── resources/          # noaa:// reference resources
 ├── prompts/            # workflow prompt templates
 └── reference/          # curated NOAA reference content
@@ -194,6 +203,10 @@ Data sources:
 
 ## License
 
-MIT © Ryan Cardin
+MIT © [Cardin LLC](https://cardinlabs.com) (Cardin Labs)
 
 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.
+
+## 2.1.0 tool delivery contract
+
+Every raw tool advertises an output schema. Successful provider payloads retain their fields and add `_response: { contractVersion: "2026-09-29.1", status: "complete" }`. Reference guides have a separate typed topic/guide result. Both text and structured payloads are bounded: an oversized result returns an explicit `response_too_large` error with narrowing guidance instead of truncated text alongside an unbounded structured response. Error metadata states whether retry may help. Chained provider reads share a 45-second cancellation deadline and each request has an 18-second total retry budget. No fishing, navigation or catch probability is inferred from raw data.

package/dist/client/deadline.d.ts

@@ -0,0 +1,6 @@
+export declare function providerDeadline(): {
+    signal: AbortSignal;
+    endsAt: number;
+} | undefined;
+/** Propagates cancellation through nested provider reads and retry backoff. */
+export declare function withProviderDeadline<T>(load: () => Promise<T>, milliseconds: number): Promise<T>;

package/dist/client/deadline.js

@@ -0,0 +1,23 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const deadlines = new AsyncLocalStorage();
+export function providerDeadline() {
+    return deadlines.getStore();
+}
+/** Propagates cancellation through nested provider reads and retry backoff. */
+export async function withProviderDeadline(load, milliseconds) {
+    const controller = new AbortController();
+    const parent = providerDeadline();
+    const budget = Math.max(1, Math.min(milliseconds, parent ? parent.endsAt - Date.now() : milliseconds));
+    const abort = () => controller.abort();
+    parent?.signal.addEventListener("abort", abort, { once: true });
+    if (parent?.signal.aborted)
+        controller.abort();
+    const timer = setTimeout(abort, budget);
+    try {
+        return await deadlines.run({ signal: controller.signal, endsAt: Date.now() + budget }, load);
+    }
+    finally {
+        clearTimeout(timer);
+        parent?.signal.removeEventListener("abort", abort);
+    }
+}

package/dist/client/http.d.ts

@@ -24,5 +24,7 @@ export declare function cleanParams(params: Record<string, string | number | boo
 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>;
+/** NWS Weather API GET: path like "/points/28.77,-95.62" or "/products/{id}". */
+export declare function fetchNwsApi<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

@@ -9,8 +9,9 @@
  *    Metadata API returns bare 404s with no body — they are handled
  *    differently on purpose)
  */
+import { providerDeadline } from "./deadline.js";
 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";
+import { APPLICATION_NAME, DATA_API_BASE_URL, DPAPI_BASE_URL, MAX_RETRIES, METADATA_API_BASE_URL, NWS_API_BASE_URL, NWS_USER_AGENT, 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;
@@ -27,6 +28,15 @@ const http = axios.create({
         "User-Agent": `${APPLICATION_NAME}/2.0`,
     },
 });
+// Separate instance for the NWS Weather API: NWS mandates a descriptive
+// User-Agent with contact info, and serves GeoJSON rather than plain JSON.
+const nwsHttp = axios.create({
+    timeout: REQUEST_TIMEOUT_MS,
+    headers: {
+        Accept: "application/geo+json, application/ld+json, application/json",
+        "User-Agent": NWS_USER_AGENT,
+    },
+});
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -48,16 +58,29 @@ export function cleanParams(params) {
     }
     return out;
 }
-async function getWithRetry(url, params) {
+async function getWithRetry(url, params, instance = http) {
+    const startedAt = Date.now();
+    const budgetMs = 18_000;
     let lastError;
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
         try {
-            const response = await http.get(url, { params });
+            const deadline = providerDeadline();
+            const remainingMs = Math.min(budgetMs - (Date.now() - startedAt), deadline ? deadline.endsAt - Date.now() : Infinity);
+            if (remainingMs <= 0 || deadline?.signal.aborted)
+                throw new NoaaApiError("Provider request deadline reached.", 504);
+            const response = await instance.get(url, {
+                params,
+                timeout: Math.min(REQUEST_TIMEOUT_MS, remainingMs),
+                signal: deadline?.signal,
+            });
             return response.data;
         }
         catch (error) {
             lastError = error;
-            if (attempt < MAX_RETRIES && isRetryable(error)) {
+            if (attempt < MAX_RETRIES &&
+                !providerDeadline()?.signal.aborted &&
+                isRetryable(error) &&
+                500 * Math.pow(3, attempt) < budgetMs - (Date.now() - startedAt)) {
                 await sleep(500 * Math.pow(3, attempt)); // 500ms, 1.5s
                 continue;
             }
@@ -160,6 +183,54 @@ export async function fetchMetadataApi(path, params = {}) {
         throw toNoaaError(error, "Metadata API");
     }
 }
+/**
+ * Shape of NWS API error bodies: RFC 7807 problem+json —
+ * {"type": "...", "title": "...", "status": 404, "detail": "..."}.
+ */
+function extractNwsProblem(data) {
+    if (data && typeof data === "object") {
+        const body = data;
+        const parts = [body.title, body.detail].filter((s) => typeof s === "string" && s.length > 0);
+        if (parts.length > 0)
+            return parts.join(": ");
+    }
+    return undefined;
+}
+function toNwsError(error) {
+    if (axios.isAxiosError(error)) {
+        const axErr = error;
+        if (axErr.response) {
+            const status = axErr.response.status;
+            const problem = extractNwsProblem(axErr.response.data);
+            if (problem) {
+                return new NoaaApiError(`NWS API error: ${problem}`, status);
+            }
+            if (status === 404) {
+                return new NoaaApiError("NWS API error: not found (404). NWS forecasts cover the US and its territories only — the point may be outside coverage, or too far offshore for a gridpoint.", status);
+            }
+            if (status === 429) {
+                return new NoaaApiError("NWS API error: rate limited (429). Wait a few seconds and retry.", status);
+            }
+            return new NoaaApiError(`NWS API error: HTTP ${status}.`, status);
+        }
+        if (axErr.code === "ECONNABORTED") {
+            return new NoaaApiError(`NWS API error: request timed out after ${REQUEST_TIMEOUT_MS / 1000}s. Retry.`);
+        }
+        return new NoaaApiError(`NWS API error: network failure (${axErr.code ?? "unknown"}).`);
+    }
+    return new NoaaApiError(`NWS API error: ${error instanceof Error ? error.message : String(error)}`);
+}
+/** NWS Weather API GET: path like "/points/28.77,-95.62" or "/products/{id}". */
+export async function fetchNwsApi(path, params = {}) {
+    try {
+        return await getWithRetry(`${NWS_API_BASE_URL}${path}`, cleanParams(params), nwsHttp);
+    }
+    catch (error) {
+        if (error instanceof NoaaApiError)
+            throw error;
+        throw toNwsError(error);
+    }
+}
 /** Derived Product API GET: path like "/htf/htf_annual.json". */
 export async function fetchDpapi(path, params = {}) {
     try {

package/dist/constants.d.ts

@@ -7,6 +7,13 @@ export declare const DATA_API_BASE_URL = "https://api.tidesandcurrents.noaa.gov/
 export declare const METADATA_API_BASE_URL = "https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi";
 /** NOAA CO-OPS Derived Product API (sea level trends, high tide flooding...). */
 export declare const DPAPI_BASE_URL = "https://api.tidesandcurrents.noaa.gov/dpapi/prod";
+/** NWS Weather API (point/gridpoint forecasts, marine zone text products). */
+export declare const NWS_API_BASE_URL = "https://api.weather.gov";
+/**
+ * NWS requires a descriptive User-Agent identifying the application and a
+ * contact point (their abuse-mitigation mechanism; the API has no keys).
+ */
+export declare const NWS_USER_AGENT = "noaa-tides-currents-mcp-server (perigeetides.com, ryandcardin@gmail.com)";
 /**
  * Sent as the `application` parameter on every Data API call so NOAA can
  * attribute traffic in their logs (not an API key; the API is open).
@@ -25,4 +32,8 @@ export declare const CACHE_TTL: {
     readonly stationList: number;
     /** Individual station metadata (datums, sensors, harcon...). */
     readonly stationResource: number;
+    /** Lat/lon → NWS gridpoint resolution (grid assignments drift rarely, but do drift). */
+    readonly nwsPoint: number;
+    /** NWS forecasts and marine text products update roughly hourly. */
+    readonly nwsForecast: number;
 };

package/dist/constants.js

@@ -7,6 +7,13 @@ export const DATA_API_BASE_URL = "https://api.tidesandcurrents.noaa.gov/api/prod
 export const METADATA_API_BASE_URL = "https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi";
 /** NOAA CO-OPS Derived Product API (sea level trends, high tide flooding...). */
 export const DPAPI_BASE_URL = "https://api.tidesandcurrents.noaa.gov/dpapi/prod";
+/** NWS Weather API (point/gridpoint forecasts, marine zone text products). */
+export const NWS_API_BASE_URL = "https://api.weather.gov";
+/**
+ * NWS requires a descriptive User-Agent identifying the application and a
+ * contact point (their abuse-mitigation mechanism; the API has no keys).
+ */
+export const NWS_USER_AGENT = "noaa-tides-currents-mcp-server (perigeetides.com, ryandcardin@gmail.com)";
 /**
  * Sent as the `application` parameter on every Data API call so NOAA can
  * attribute traffic in their logs (not an API key; the API is open).
@@ -25,4 +32,8 @@ export const CACHE_TTL = {
     stationList: 6 * 60 * 60 * 1000,
     /** Individual station metadata (datums, sensors, harcon...). */
     stationResource: 60 * 60 * 1000,
+    /** Lat/lon → NWS gridpoint resolution (grid assignments drift rarely, but do drift). */
+    nwsPoint: 6 * 60 * 60 * 1000,
+    /** NWS forecasts and marine text products update roughly hourly. */
+    nwsForecast: 30 * 60 * 1000,
 };

package/dist/format/respond.d.ts

@@ -5,8 +5,44 @@
  * tables with units spelled out) or "json" (complete structured payload).
  * Structured content is attached in both modes so MCP clients that support
  * it can consume typed output. Responses longer than CHARACTER_LIMIT are
- * truncated with guidance rather than flooding the agent's context.
+ * rejected with narrowing guidance, including their structured payload.
  */
+import { z } from "zod";
+/** Stable delivery contract; provider/domain fields remain additive. */
+export declare const RawToolOutputSchema: z.ZodObject<{
+    _response: z.ZodObject<{
+        contractVersion: z.ZodLiteral<"2026-09-29.1">;
+        status: z.ZodLiteral<"complete">;
+    }, "strict", z.ZodTypeAny, {
+        status: "complete";
+        contractVersion: "2026-09-29.1";
+    }, {
+        status: "complete";
+        contractVersion: "2026-09-29.1";
+    }>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    _response: z.ZodObject<{
+        contractVersion: z.ZodLiteral<"2026-09-29.1">;
+        status: z.ZodLiteral<"complete">;
+    }, "strict", z.ZodTypeAny, {
+        status: "complete";
+        contractVersion: "2026-09-29.1";
+    }, {
+        status: "complete";
+        contractVersion: "2026-09-29.1";
+    }>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    _response: z.ZodObject<{
+        contractVersion: z.ZodLiteral<"2026-09-29.1">;
+        status: z.ZodLiteral<"complete">;
+    }, "strict", z.ZodTypeAny, {
+        status: "complete";
+        contractVersion: "2026-09-29.1";
+    }, {
+        status: "complete";
+        contractVersion: "2026-09-29.1";
+    }>;
+}, z.ZodTypeAny, "passthrough">>;
 export type ResponseFormat = "markdown" | "json";
 export interface ToolResult {
     [key: string]: unknown;

package/dist/format/respond.js

@@ -5,27 +5,62 @@
  * tables with units spelled out) or "json" (complete structured payload).
  * Structured content is attached in both modes so MCP clients that support
  * it can consume typed output. Responses longer than CHARACTER_LIMIT are
- * truncated with guidance rather than flooding the agent's context.
+ * rejected with narrowing guidance, including their structured payload.
  */
+import { z } from "zod";
 import { CHARACTER_LIMIT } from "../constants.js";
+/** Stable delivery contract; provider/domain fields remain additive. */
+export const RawToolOutputSchema = z
+    .object({
+    _response: z
+        .object({
+        contractVersion: z.literal("2026-09-29.1"),
+        status: z.literal("complete"),
+    })
+        .strict(),
+})
+    .passthrough();
 /** Build a successful tool response in the requested format. */
 export function respond(format, structured, markdown) {
-    let text = format === "json" ? JSON.stringify(structured, null, 2) : markdown;
-    if (text.length > CHARACTER_LIMIT) {
-        text =
-            text.slice(0, CHARACTER_LIMIT) +
-                "\n\n…[truncated: response exceeded the size limit. Narrow the date range, lower the limit parameter, or request fewer fields.]";
-    }
-    return {
-        content: [{ type: "text", text }],
-        structuredContent: structured,
+    const payload = {
+        ...structured,
+        _response: { contractVersion: "2026-09-29.1", status: "complete" },
     };
+    const json = JSON.stringify(payload);
+    const text = format === "json" ? json : markdown;
+    if (json.length > CHARACTER_LIMIT || text.length > CHARACTER_LIMIT) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: "The complete response exceeds the delivery limit. Narrow the date range, lower the limit, or request fewer fields; no partial result is presented as complete.",
+                },
+            ],
+            _meta: {
+                error: {
+                    code: "response_too_large",
+                    retryable: false,
+                    limitCharacters: CHARACTER_LIMIT,
+                },
+            },
+        };
+    }
+    return { content: [{ type: "text", text }], structuredContent: payload };
 }
 /** Build an error tool response (kept inside the result per MCP guidance). */
 export function respondError(error) {
     const message = error instanceof Error ? error.message : String(error);
     return {
         isError: true,
+        _meta: {
+            error: {
+                code: "provider_error",
+                retryable: error?.status === undefined ||
+                    error.status === 429 ||
+                    (error.status ?? 0) >= 500,
+            },
+        },
         content: [{ type: "text", text: `Error: ${message}` }],
     };
 }

package/dist/reference/content.d.ts

@@ -3,7 +3,7 @@
  * documentation (api.tidesandcurrents.noaa.gov). Served both by the
  * noaa_get_reference_guide tool and as noaa://reference/{topic} resources.
  */
-export declare const REFERENCE_TOPICS: readonly ["products", "datums", "units", "time_zones", "intervals", "station_types", "data_limits", "quality_flags", "date_formats"];
+export declare const REFERENCE_TOPICS: readonly ["products", "datums", "units", "time_zones", "intervals", "station_types", "data_limits", "quality_flags", "date_formats", "marine_forecast"];
 export type ReferenceTopic = (typeof REFERENCE_TOPICS)[number];
 export declare const REFERENCE_CONTENT: Record<ReferenceTopic, string>;
 /** One-line summaries used in resource listings and the guide index. */

package/dist/reference/content.js

@@ -13,6 +13,7 @@ export const REFERENCE_TOPICS = [
     "data_limits",
     "quality_flags",
     "date_formats",
+    "marine_forecast",
 ];
 export const REFERENCE_CONTENT = {
     products: `# NOAA CO-OPS Data Products
@@ -187,6 +188,28 @@ Exactly ONE of these combinations per request:
 5. range alone — N hours back from now
 
 Timestamps in responses are in the requested time_zone (gmt | lst | lst_ldt).`,
+    marine_forecast: `# Wind & Marine Forecasts (NWS)
+
+Forecasts come from the NWS Weather API (api.weather.gov) — a different NOAA
+service from CO-OPS. CO-OPS observes and predicts tides; NWS forecasts weather.
+
+| Need | Tool |
+|---|---|
+| Hourly wind forecast (numeric speed/gust/direction) at a lat/lon | nws_get_wind_forecast |
+| Official marine narrative (Coastal Waters Forecast, advisories) | nws_get_marine_forecast |
+| OBSERVED wind right now at a NOAA station | noaa_get_meteorological_data (product "wind") |
+
+How it works:
+- A lat/lon resolves to a forecast-office gridpoint (points → gridpoints);
+  values are numeric NDFD series with up to a ~7-day (156 h) horizon.
+- Wave height appears on marine/nearshore gridpoints; swell period/direction
+  are generally only populated for open-ocean grids, not bays.
+- Marine text forecasts are per-ZONE (e.g. GMZ350 "Freeport to Matagorda Ship
+  Channel out 20 NM"); one office bulletin covers many zones and the tool
+  extracts the matching segment. Winds in the narrative are in KNOTS.
+- Coverage: US and territories only. No API key; forecasts update ~hourly.
+- Forecast wind direction is where the wind blows FROM, degrees true — same
+  convention as CO-OPS wind observations.`,
 };
 /** One-line summaries used in resource listings and the guide index. */
 export const REFERENCE_SUMMARIES = {
@@ -199,4 +222,5 @@ export const REFERENCE_SUMMARIES = {
     data_limits: "Maximum date-range span per product",
     quality_flags: "Data quality fields (v/s/f/q), flag letters, HH/H/L/LL",
     date_formats: "Accepted date formats and parameter combinations",
+    marine_forecast: "NWS wind & marine forecast tools vs CO-OPS observations",
 };

package/dist/resources/index.js

@@ -19,6 +19,14 @@ Typical workflows:
 - noaa_get_meteorological_data (product "wind"/"air_temperature", date "latest")
 - noaa_get_currents (date "latest") at a current station (different ID scheme!)
 
+## "What will the wind do tomorrow near <place>?"
+1. Geocode the place to lat/lon (outside this server).
+2. nws_get_wind_forecast (hours 48) → hourly numeric speed/gust/direction.
+3. nws_get_marine_forecast for the official Coastal Waters Forecast narrative
+   (small-craft advisories, sea state) when the point is in US coastal waters.
+Forecast ≠ observation: measured wind right now comes from
+noaa_get_meteorological_data (product "wind") at a station with a met sensor.
+
 ## "How often does <station> flood, and what's projected?"
 - noaa_get_high_tide_flooding (report "annual", range 15)
 - noaa_get_sea_level_trends, noaa_get_sea_level_rise_projections

package/dist/services/nws-api.d.ts

@@ -0,0 +1,115 @@
+/**
+ * NWS Weather API (api.weather.gov) — wind and marine FORECASTS.
+ *
+ * This is a different NOAA service from CO-OPS with different shapes:
+ *  - /points/{lat},{lon} resolves a coordinate to a forecast office gridpoint
+ *    (gridX/gridY assignments drift over re-gridding, so cache with a TTL and
+ *    never hardcode them).
+ *  - /gridpoints/{office}/{x},{y} returns NUMERIC time series (the friendlier
+ *    /forecast/hourly endpoint returns display strings like "10 to 15 mph"
+ *    and is deliberately not used). Each series value carries a validTime of
+ *    the form "2026-07-05T18:00:00+00:00/PT3H" — an ISO instant plus an ISO
+ *    duration the value holds for — which we expand into hourly samples.
+ *  - Marine zone TEXT forecasts are NOT served by /zones/forecast/{id}/forecast
+ *    (that 404s with "Marine Forecast Not Supported"); the working path is the
+ *    Products API: latest CWF product for the issuing office, then extracting
+ *    the segment for the zone from the multi-zone bulletin.
+ */
+export interface NwsPoint {
+    gridId: string;
+    gridX: number;
+    gridY: number;
+    /** Issuing forecast office, e.g. "HGX". */
+    cwa: string;
+    /** IANA time zone for the point, e.g. "America/Chicago". */
+    timeZone: string;
+    /** "land" or "marine" — how NWS classifies the coordinate. */
+    pointType?: string;
+    /** Nearest named place, e.g. "Sargent, TX". */
+    place?: string;
+}
+export declare function resolvePoint(latitude: number, longitude: number): Promise<NwsPoint>;
+export interface GridSeries {
+    uom?: string;
+    values?: Array<{
+        validTime: string;
+        value: number | null;
+    }>;
+}
+/** Parse an ISO 8601 duration like "PT3H", "P1D", "PT1H30M" to milliseconds. */
+export declare function parseIsoDurationMs(duration: string): number;
+/**
+ * Expand a gridpoint series (start-instant + hold-duration values) into a map
+ * of epoch-ms-per-hour → value.
+ */
+export declare function expandGridSeries(series: GridSeries | undefined): Map<number, number>;
+/** Convert a gridpoint speed value to knots based on its declared unit. */
+export declare function speedToKnots(value: number, uom: string | undefined): number;
+export declare function knotsToMs(knots: number): number;
+/** Convert a gridpoint length value to meters based on its declared unit. */
+export declare function lengthToMeters(value: number, uom: string | undefined): number;
+export declare function metersToFeet(meters: number): number;
+export declare function toCompass(degrees: number): string;
+export interface HourlyWindSample {
+    /** UTC instant, ISO 8601. */
+    time: string;
+    /** Wind speed in knots (converted from the gridpoint's declared unit). */
+    speed_knots: number | null;
+    /** Wind gust in knots. */
+    gust_knots: number | null;
+    /** Direction the wind blows FROM, degrees true. */
+    direction_deg: number | null;
+    /** 16-point compass rendering of direction_deg. */
+    compass: string | null;
+    /** Significant wave height in meters (marine gridpoints only, often absent). */
+    wave_height_m: number | null;
+}
+export interface WindForecast {
+    point: NwsPoint;
+    updated?: string;
+    samples: HourlyWindSample[];
+}
+/**
+ * Hourly numeric wind forecast (plus wave height when the grid carries it)
+ * for a coordinate, starting at the current hour.
+ */
+export declare function getWindForecast(latitude: number, longitude: number, hours: number): Promise<WindForecast>;
+export interface MarineZone {
+    id: string;
+    name: string;
+    cwa: string;
+}
+/** Resolve the NWS coastal marine zone covering a coordinate (e.g. GMZ350). */
+export declare function findCoastalZone(latitude: number, longitude: number): Promise<MarineZone>;
+/**
+ * True when a CWF bulletin segment's UGC header covers the given zone.
+ * Headers look like "GMZ330-335-350-061015-" (list) or "GMZ350>355-061015-"
+ * (range), always ending in a 6-digit expiry.
+ */
+export declare function segmentCoversZone(segment: string, zoneId: string): boolean;
+/**
+ * Extract the segment of a multi-zone CWF bulletin covering one zone.
+ * Bulletins are segmented by "$$" terminators; each segment opens with a UGC
+ * zone-list header. Returns undefined when no segment matches.
+ */
+export declare function extractZoneSegment(productText: string, zoneId: string): string | undefined;
+/**
+ * Extract the office-wide synopsis block, when the bulletin carries one.
+ * Offices vary the header casing (".SYNOPSIS...", ".Synopsis For ...").
+ */
+export declare function extractSynopsis(productText: string): string | undefined;
+export interface MarineTextForecast {
+    zone: MarineZone;
+    productId?: string;
+    issuanceTime?: string;
+    /** The bulletin segment for the zone (day-part narrative, winds in knots). */
+    segment?: string;
+    /** The office-wide marine synopsis, when present. */
+    synopsis?: string;
+}
+/**
+ * Latest Coastal Waters Forecast text for the marine zone covering a point.
+ * CWF products are keyed by issuing office (not zone) and cover every zone
+ * that office serves in one bulletin, so the zone's segment is extracted here.
+ */
+export declare function getMarineTextForecast(latitude: number, longitude: number): Promise<MarineTextForecast>;