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

package/dist/prompts/index.js

@@ -0,0 +1,89 @@
+/**
+ * MCP prompts: reusable workflow templates that orchestrate the server's
+ * tools for the most common NOAA questions.
+ */
+import { z } from "zod";
+function userPrompt(text) {
+    return {
+        messages: [
+            {
+                role: "user",
+                content: { type: "text", text },
+            },
+        ],
+    };
+}
+export function registerPrompts(server) {
+    server.registerPrompt("tide_report", {
+        title: "Tide Report",
+        description: "Produce a tide report (high/low times, current level, context) for a place or station and date.",
+        argsSchema: {
+            location: z
+                .string()
+                .describe("Place name, coordinates, or a 7-digit NOAA station ID."),
+            date: z
+                .string()
+                .optional()
+                .describe("Date (YYYY-MM-DD). Defaults to today."),
+        },
+    }, ({ location, date }) => userPrompt(`Create a tide report for ${location}${date ? ` on ${date}` : " for today"}.
+
+Steps:
+1. If "${location}" is not already a NOAA station ID, resolve it to coordinates and use noaa_find_nearest_stations (type "tidepredictions") to pick the closest station; state which station you chose and how far away it is.
+2. Get high/low tide times with noaa_get_tide_predictions (interval "hilo"${date ? `, begin_date "${date}", end_date "${date}"` : ', date "today"'}).
+3. If the station observes water levels, compare the current observed level (noaa_get_water_levels, date "latest") against the predictions and note any surge (observed minus predicted).
+4. Report: station used, each high/low with time and height (state the datum — MLLW — and units), current conditions if available, and the moon phase (astro_get_moon_phase) with a note on spring/neap tides.`));
+    server.registerPrompt("boating_conditions", {
+        title: "Boating & On-the-Water Conditions",
+        description: "Assemble tides, currents, wind, weather, and daylight for a location and date — a pre-departure briefing.",
+        argsSchema: {
+            location: z
+                .string()
+                .describe("Place name or coordinates of the launch/operating area."),
+            date: z
+                .string()
+                .optional()
+                .describe("Date (YYYY-MM-DD). Defaults to today."),
+        },
+    }, ({ location, date }) => userPrompt(`Prepare an on-the-water conditions briefing for ${location}${date ? ` on ${date}` : " today"}.
+
+Gather (resolve ${location} to coordinates first):
+1. Tides: nearest tide-prediction station (noaa_find_nearest_stations type "tidepredictions") → noaa_get_tide_predictions interval "hilo".
+2. Currents: nearest current-prediction station (type "currentpredictions") → noaa_get_current_predictions interval "max_slack" — report max flood/ebb speeds (note units!) and slack times, best transit windows.
+3. Weather: nearest met station (type "met") → noaa_get_meteorological_data for wind (latest and/or recent trend) and air/water temperature.
+4. Daylight: astro_get_sun_times for sunrise/sunset/twilight.
+
+Present as a briefing: daylight window, tide events, slack-water windows, current strength warnings, wind conditions, and water temperature. Flag any station that is far (>25 km) from the requested location.`));
+    server.registerPrompt("station_flood_risk", {
+        title: "Station Flood Risk Profile",
+        description: "Synthesize high-tide-flooding history, extremes, sea level trend, and projections into a flood risk profile for a station.",
+        argsSchema: {
+            station: z
+                .string()
+                .describe('7-digit NOAA water-level station ID (e.g. "8454000").'),
+        },
+    }, ({ station }) => userPrompt(`Build a flood risk profile for NOAA station ${station}.
+
+Gather:
+1. noaa_get_station_info (expand ["floodlevels"]) — station identity and NOS/NWS flood thresholds.
+2. noaa_get_high_tide_flooding report "annual" with range 20 — historical flood-day trend.
+3. noaa_get_high_tide_flooding report "annual_outlook" — next-year outlook, and report "projections" — decadal projections.
+4. noaa_get_sea_level_trends — long-term relative sea level trend.
+5. noaa_get_top_ten_water_levels — worst historical events.
+6. noaa_get_extreme_water_levels — exceedance probability levels.
+
+Synthesize: how often the station floods now vs 20 years ago, the driving sea-level trend, projected flooding by 2050, historical worst cases, and the water levels associated with 1%-annual-chance events. State datums and units explicitly.`));
+    server.registerPrompt("station_overview", {
+        title: "Station Capabilities Overview",
+        description: "Summarize everything a NOAA station offers: sensors, datums, products, data availability.",
+        argsSchema: {
+            station: z
+                .string()
+                .describe("NOAA station ID (7-digit or alphanumeric current station)."),
+        },
+    }, ({ station }) => userPrompt(`Summarize NOAA station ${station}: what it is, where it is, and what data it offers.
+
+Use noaa_get_station_info (expand ["details", "sensors", "products"]), noaa_get_station_datums, and if it is a prediction station check whether it is reference (R) or subordinate (S) via noaa_search_stations / noaa_get_prediction_offsets.
+
+Report: location/state/established date, tide type, installed sensors, supported datums (with MLLW–MSL offset), available data products and the right tool for each, and any caveats (Great Lakes, subordinate hilo-only predictions, historic-only status).`));
+}

package/dist/reference/content.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Curated NOAA CO-OPS reference content, compiled from the official API
+ * 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 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. */
+export declare const REFERENCE_SUMMARIES: Record<ReferenceTopic, string>;

package/dist/reference/content.js

@@ -0,0 +1,202 @@
+/**
+ * Curated NOAA CO-OPS reference content, compiled from the official API
+ * documentation (api.tidesandcurrents.noaa.gov). Served both by the
+ * noaa_get_reference_guide tool and as noaa://reference/{topic} resources.
+ */
+export const REFERENCE_TOPICS = [
+    "products",
+    "datums",
+    "units",
+    "time_zones",
+    "intervals",
+    "station_types",
+    "data_limits",
+    "quality_flags",
+    "date_formats",
+];
+export const REFERENCE_CONTENT = {
+    products: `# NOAA CO-OPS Data Products
+
+## Water level / tide products (all require a datum)
+| Product | Description | Tool |
+|---|---|---|
+| water_level | 6-minute preliminary or verified observations | noaa_get_water_levels (interval "6") |
+| one_minute_water_level | 1-minute preliminary observations | noaa_get_water_levels (interval "1") |
+| hourly_height | Verified hourly heights | noaa_get_water_levels (interval "hourly") |
+| high_low | Verified daily highs/lows (HH/H/L/LL) | noaa_get_water_level_summaries |
+| daily_mean | Verified daily means — GREAT LAKES ONLY, requires lst time zone | noaa_get_water_level_summaries |
+| daily_max_min | Daily maxima/minima with completeness % | noaa_get_water_level_summaries |
+| monthly_mean | Verified monthly datum means (MHHW, MSL, ... columns) | noaa_get_water_level_summaries |
+| predictions | Harmonic tide predictions (heights or high/low events) | noaa_get_tide_predictions |
+| air_gap | Bridge clearance (structure to water surface) | noaa_get_meteorological_data |
+
+## Meteorological products (no datum)
+air_temperature, water_temperature, wind (speed/gust/direction), air_pressure,
+conductivity, visibility, humidity, salinity — via noaa_get_meteorological_data.
+
+## Currents
+| Product | Description | Tool |
+|---|---|---|
+| currents | Observed current speed/direction by depth bin | noaa_get_currents |
+| currents_predictions | Predicted currents incl. max flood/ebb and slack | noaa_get_current_predictions |
+
+## Derived products (DPAPI)
+Sea level trends, sea level rise projections, extreme water levels,
+top-ten/peak water levels, high tide flooding — via noaa_get_sea_level_trends,
+noaa_get_extreme_water_levels, noaa_get_top_ten_water_levels, noaa_get_high_tide_flooding.
+
+Notes:
+- Great Lakes stations have NO tide predictions.
+- Subordinate ("S" type) prediction stations only support interval=hilo.`,
+    datums: `# Vertical Datums
+
+A datum is the zero reference for water heights. The same water level reads
+differently against different datums — always report which datum was used.
+
+| Datum | Meaning | Applies to |
+|---|---|---|
+| MLLW | Mean Lower Low Water — standard US nautical chart datum | Coastal/tidal stations (default choice) |
+| MLW | Mean Low Water | Coastal |
+| MSL | Mean Sea Level | Coastal |
+| MTL | Mean Tide Level | Coastal |
+| MHW | Mean High Water | Coastal |
+| MHHW | Mean Higher High Water (flood analyses often use this) | Coastal |
+| STND | Station datum (arbitrary fixed zero, always available) | All stations |
+| NAVD | North American Vertical Datum 1988 | Only stations where computed |
+| CRD | Columbia River Datum | Columbia River stations only |
+| IGLD | International Great Lakes Datum 1985 | Great Lakes ONLY |
+| LWD | Low Water Datum (Great Lakes chart datum) | Great Lakes ONLY |
+
+- Datum values come from the current National Tidal Datum Epoch (1983–2001).
+- Requesting a datum a station does not support returns an error; check
+  supported datums first with noaa_get_station_datums.
+- Datum applies to water-level products and tide predictions; it does not
+  apply to meteorological or current data.`,
+    units: `# Unit Systems
+
+The \`units\` parameter is english (default) or metric. Units differ per
+measurement — note the two asymmetric cases (wind vs currents in metric):
+
+| Measurement | english | metric |
+|---|---|---|
+| Water level / air gap | feet | meters |
+| Air & water temperature | °F | °C |
+| Wind speed & gust | knots | m/s |
+| **Current speed** | **knots** | **cm/s (NOT m/s)** |
+| Visibility | nautical miles | kilometers |
+| Air pressure | millibars | millibars (unchanged) |
+| Salinity | PSU | PSU (unchanged) |
+| Conductivity | mS/cm | mS/cm (unchanged) |`,
+    time_zones: `# Time Zones
+
+| Value | Meaning |
+|---|---|
+| gmt | Greenwich Mean Time (UTC) |
+| lst | Station's Local Standard Time — never shifts for DST |
+| lst_ldt | Station's local time honoring daylight saving |
+
+- daily_mean data REQUIRES lst (the server enforces this automatically).
+- Predictions and observations may be requested in any of the three.
+- When comparing NOAA timestamps with other data sources, prefer gmt.`,
+    intervals: `# Interval Parameter
+
+| Tool / product | Valid intervals |
+|---|---|
+| Tide predictions | hilo (high/low events), h (hourly), 1, 5, 6, 10, 15, 30, 60 (minutes) |
+| Water levels | chosen via interval param: "1" (1-min), "6" (6-min, standard), "hourly" |
+| Meteorological | 6 (default) or h (hourly) |
+| Observed currents | 6-minute (default) or h |
+| Current predictions | max_slack (max flood/ebb + slack events), h, 1, 6, 10, 30, 60 |
+
+- interval=hilo returns the four daily tide events instead of a time series —
+  this is what you want for "when is high tide?".
+- interval=max_slack is the currents analog: max flood, max ebb, slack times.`,
+    station_types: `# Station Types (noaa_search_stations \`type\` values)
+
+| Type | Stations that... |
+|---|---|
+| waterlevels | actively observe water levels |
+| historicwl | historically observed water levels |
+| met | have meteorological sensors |
+| waterlevelsandmet | have both |
+| tidepredictions | have tide predictions (R=reference, S=subordinate) |
+| currents | actively observe currents (alphanumeric IDs like cb0102) |
+| historiccurrents / surveycurrents | historical/survey current observations |
+| currentpredictions | have current predictions |
+| harcon | have harmonic constituents |
+| datums / supersededdatums | have (superseded) tidal datums |
+| benchmarks / supersededbenchmarks | have leveling benchmarks |
+| cond / watertemp / airgap / visibility | conductivity / water temp / air gap / visibility sensors |
+| physocean | physical oceanography (PORTS) |
+| tcoon | Texas Coastal Ocean Observation Network |
+| 1minute | report 1-minute water levels |
+| highwater / lowwater | high/low water marks |
+
+Station ID formats: 7-digit numeric for water-level/met (e.g. 9414290);
+alphanumeric for current stations (e.g. cb0102). Tide-prediction subordinate
+(S) stations derive predictions from a reference (R) station via offsets.`,
+    data_limits: `# Maximum Request Spans (enforced before calling NOAA)
+
+| Product | Max span per request |
+|---|---|
+| 1-minute water levels | 4 days |
+| 6-minute water levels | 31 days |
+| Hourly heights | 1 year |
+| High/low observations | 1 year |
+| Daily means / daily max-min | 10 years |
+| Monthly means | 200 years |
+| Tide predictions, interval=hilo | 10 years |
+| Tide predictions, other intervals | 1 year |
+| Observed currents (any bin, incl. bin=0) | 7 days |
+| Current predictions, interval=max_slack | 1 year |
+| Current predictions, other intervals | 31 days |
+| Meteorological products | 31 days |
+
+For longer periods, make multiple chunked requests. NOAA throttles heavy
+query volume (no published numeric limit) — request only what you need.`,
+    quality_flags: `# Data Quality Fields & Flags
+
+Water level responses include:
+- v — value; s — sigma (standard deviation of the 1-second samples)
+- q — quality: p = preliminary (recent, unverified), v = verified
+- f — comma-separated flag counts/indicators:
+  - Preliminary water levels: O=outliers beyond 3-sigma, F=flat tolerance
+    exceeded, R=rate-of-change exceeded, L=max/min limit exceeded
+  - Verified water levels: I=inferred, F=flat, R=rate-of-change, T=max/min
+  - Hourly heights & high_low: I=inferred, L=limit exceeded
+  - Met products: X=max exceeded, N=min exceeded, R=rate-of-change
+  - Wind: X=max speed exceeded, R=rate-of-change
+  - Air gap: O, F, R, A=max/min limit
+
+high_low \`ty\` values: HH=higher high, H=high, L=low, LL=lower low
+(mixed-tide coasts have two unequal highs and lows per day).
+
+Verified data replaces preliminary data after NOAA QC (typically days to
+weeks later); recent observations are almost always preliminary.`,
+    date_formats: `# Date Parameters
+
+Formats accepted: yyyyMMdd, "yyyyMMdd HH:mm", MM/dd/yyyy, "MM/dd/yyyy HH:mm",
+and ISO yyyy-MM-dd or yyyy-MM-ddTHH:mm (normalized automatically).
+
+Exactly ONE of these combinations per request:
+1. begin_date + end_date — explicit window
+2. begin_date + range — N hours forward from begin
+3. end_date + range — N hours back from end
+4. date=today | latest | recent — today (midnight→now), latest (single most
+   recent reading, ~18 min window), recent (last 72 hours)
+5. range alone — N hours back from now
+
+Timestamps in responses are in the requested time_zone (gmt | lst | lst_ldt).`,
+};
+/** One-line summaries used in resource listings and the guide index. */
+export const REFERENCE_SUMMARIES = {
+    products: "Every NOAA CO-OPS data product and which tool serves it",
+    datums: "Vertical datums (MLLW, MSL, IGLD...) and station applicability",
+    units: "What english vs metric means per measurement (incl. cm/s currents)",
+    time_zones: "gmt / lst / lst_ldt semantics and restrictions",
+    intervals: "Valid interval values per product family",
+    station_types: "Station type filters and station ID formats",
+    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",
+};

package/dist/resources/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * MCP resources: the reference guide topics exposed as noaa://reference/{topic}
+ * plus a getting-started guide. Clients that support resources can pin these
+ * into context without a tool round-trip.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerResources(server: McpServer): void;

package/dist/resources/index.js

@@ -0,0 +1,73 @@
+/**
+ * MCP resources: the reference guide topics exposed as noaa://reference/{topic}
+ * plus a getting-started guide. Clients that support resources can pin these
+ * into context without a tool round-trip.
+ */
+import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { REFERENCE_CONTENT, REFERENCE_SUMMARIES, REFERENCE_TOPICS, } from "../reference/content.js";
+const GETTING_STARTED = `# NOAA Tides & Currents MCP Server — Getting Started
+
+Typical workflows:
+
+## "When is high tide near <place>?"
+1. Geocode the place to lat/lon (outside this server).
+2. noaa_find_nearest_stations (type "tidepredictions") → pick a station ID.
+3. noaa_get_tide_predictions with interval "hilo" and a date window.
+
+## "What are conditions right now at <station>?"
+- noaa_get_water_levels (date "latest") for water level
+- noaa_get_meteorological_data (product "wind"/"air_temperature", date "latest")
+- noaa_get_currents (date "latest") at a current station (different ID scheme!)
+
+## "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
+- noaa_get_extreme_water_levels for exceedance probabilities
+
+## Things that trip people up
+- Datum matters: heights above MLLW differ from MSL by several feet at many
+  stations. MLLW is the chart default. See noaa://reference/datums.
+- Units: metric current speed is cm/s, not m/s. See noaa://reference/units.
+- Water-level and current stations have DIFFERENT ID schemes (7-digit vs
+  alphanumeric like "cb0102").
+- Predictions are astronomical — storms are not included.
+- Per-product maximum date spans apply. See noaa://reference/data_limits.
+- Great Lakes stations: no tide predictions; datums IGLD/LWD; daily_mean.
+`;
+export function registerResources(server) {
+    server.registerResource("getting-started", "noaa://guide/getting-started", {
+        title: "Getting Started with NOAA Tides & Currents",
+        description: "Workflow recipes and common pitfalls for this server.",
+        mimeType: "text/markdown",
+    }, async (uri) => ({
+        contents: [
+            { uri: uri.href, mimeType: "text/markdown", text: GETTING_STARTED },
+        ],
+    }));
+    server.registerResource("reference", new ResourceTemplate("noaa://reference/{topic}", {
+        list: async () => ({
+            resources: REFERENCE_TOPICS.map((topic) => ({
+                uri: `noaa://reference/${topic}`,
+                name: `NOAA reference: ${topic}`,
+                description: REFERENCE_SUMMARIES[topic],
+                mimeType: "text/markdown",
+            })),
+        }),
+        complete: {
+            topic: async (value) => REFERENCE_TOPICS.filter((t) => t.startsWith(value ?? "")).map(String),
+        },
+    }), {
+        title: "NOAA CO-OPS Reference",
+        description: "Curated NOAA API reference topics (datums, units, limits, flags...).",
+        mimeType: "text/markdown",
+    }, async (uri, variables) => {
+        const topic = String(variables.topic);
+        const content = REFERENCE_CONTENT[topic];
+        if (!content) {
+            throw new Error(`Unknown reference topic "${topic}". Valid topics: ${REFERENCE_TOPICS.join(", ")}.`);
+        }
+        return {
+            contents: [{ uri: uri.href, mimeType: "text/markdown", text: content }],
+        };
+    });
+}

package/dist/schemas/common.d.ts

@@ -1,14 +1,38 @@
-import { z } from 'zod';
-export declare const StationSchema: z.ZodString;
-export declare const DateSchema: z.ZodOptional<z.ZodString>;
-export declare const BeginDateSchema: z.ZodOptional<z.ZodString>;
-export declare const EndDateSchema: z.ZodOptional<z.ZodString>;
-export declare const RangeSchema: z.ZodOptional<z.ZodNumber>;
-export declare const DatumSchema: z.ZodOptional<z.ZodString>;
-export declare const UnitsSchema: z.ZodOptional<z.ZodEnum<["english", "metric"]>>;
-export declare const TimeZoneSchema: z.ZodOptional<z.ZodEnum<["gmt", "lst", "lst_ldt"]>>;
-export declare const FormatSchema: z.ZodOptional<z.ZodEnum<["json", "xml", "csv"]>>;
-export declare const BinSchema: z.ZodOptional<z.ZodNumber>;
-export declare const IntervalSchema: z.ZodOptional<z.ZodString>;
-export declare const refineDateParams: (data: any) => any;
-export declare const dateRefinementMessage = "You must provide either 'date', 'begin_date' and 'end_date', 'begin_date' and 'range', 'end_date' and 'range', or just 'range'";
+/**
+ * Shared Zod field schemas used across tool input schemas.
+ * Field descriptions matter: MCP clients show them to the model, so they
+ * carry the load-bearing NOAA nuances (units, datums, limits).
+ */
+import { z } from "zod";
+/** 7-digit numeric (water level/met) or alphanumeric current-station IDs like "cb0102". */
+export declare const StationIdSchema: z.ZodString;
+export declare const DateAliasSchema: z.ZodEnum<["today", "latest", "recent"]>;
+export declare const BeginDateSchema: z.ZodString;
+export declare const EndDateSchema: z.ZodString;
+export declare const RangeSchema: z.ZodNumber;
+export declare const DatumSchema: z.ZodEnum<["MHHW", "MHW", "MTL", "MSL", "MLW", "MLLW", "NAVD", "STND", "IGLD", "LWD", "CRD"]>;
+export declare const UnitsSchema: z.ZodDefault<z.ZodEnum<["english", "metric"]>>;
+export declare const TimeZoneSchema: z.ZodDefault<z.ZodEnum<["gmt", "lst", "lst_ldt"]>>;
+export declare const ResponseFormatSchema: z.ZodDefault<z.ZodEnum<["markdown", "json"]>>;
+/** Base date-selection fields shared by all Data API tools. */
+export declare const dateFields: {
+    date: z.ZodOptional<z.ZodEnum<["today", "latest", "recent"]>>;
+    begin_date: z.ZodOptional<z.ZodString>;
+    end_date: z.ZodOptional<z.ZodString>;
+    range: z.ZodOptional<z.ZodNumber>;
+};
+export declare const READ_ONLY_ANNOTATIONS: {
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+    readonly idempotentHint: true;
+    readonly openWorldHint: true;
+};
+/** Astronomy tools compute locally — no external world interaction. */
+export declare const LOCAL_COMPUTE_ANNOTATIONS: {
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+};
+export declare const LatitudeSchema: z.ZodNumber;
+export declare const LongitudeSchema: z.ZodNumber;

package/dist/schemas/common.js

@@ -1,18 +1,82 @@
-import { z } from 'zod';
-// Common parameter schemas
-export const StationSchema = z.string().min(1).describe('Station ID');
-export const DateSchema = z.string().optional().describe('Date to retrieve data for ("today", "latest", "recent", or specific date)');
-export const BeginDateSchema = z.string().optional().describe('Start date (YYYYMMDD or MM/DD/YYYY)');
-export const EndDateSchema = z.string().optional().describe('End date (YYYYMMDD or MM/DD/YYYY)');
-export const RangeSchema = z.number().optional().describe('Number of hours to retrieve data for');
-export const DatumSchema = z.string().optional().describe('Datum to use (MLLW, MSL, etc.)');
-export const UnitsSchema = z.enum(['english', 'metric']).optional().describe('Units to use ("english" or "metric")');
-export const TimeZoneSchema = z.enum(['gmt', 'lst', 'lst_ldt']).optional().describe('Time zone (gmt, lst, lst_ldt)');
-export const FormatSchema = z.enum(['json', 'xml', 'csv']).optional().describe('Output format (json, xml, csv)');
-export const BinSchema = z.number().optional().describe('Bin number');
-export const IntervalSchema = z.string().optional().describe('Interval (hilo, hl, h, or a number for minutes)');
-// Schema refinement function for date parameters
-export const refineDateParams = (data) => (data.date || (data.begin_date && data.end_date) ||
-    (data.begin_date && data.range) || (data.end_date && data.range) ||
-    data.range);
-export const dateRefinementMessage = "You must provide either 'date', 'begin_date' and 'end_date', 'begin_date' and 'range', 'end_date' and 'range', or just 'range'";
+/**
+ * Shared Zod field schemas used across tool input schemas.
+ * Field descriptions matter: MCP clients show them to the model, so they
+ * carry the load-bearing NOAA nuances (units, datums, limits).
+ */
+import { z } from "zod";
+/** 7-digit numeric (water level/met) or alphanumeric current-station IDs like "cb0102". */
+export const StationIdSchema = z
+    .string()
+    .regex(/^[A-Za-z0-9_]{4,10}$/, 'Station IDs are 7-digit numbers for water-level/met stations (e.g. "9414290") or alphanumeric codes for current stations (e.g. "cb0102").')
+    .describe('Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations.');
+export const DateAliasSchema = z
+    .enum(["today", "latest", "recent"])
+    .describe('Shortcut window: "today" = midnight to now, "latest" = single most recent reading, "recent" = last 72 hours. Mutually exclusive with begin_date/end_date/range.');
+export const BeginDateSchema = z
+    .string()
+    .describe('Start date/time. Formats: yyyyMMdd, "yyyyMMdd HH:mm", MM/dd/yyyy, or ISO yyyy-MM-dd[THH:mm].');
+export const EndDateSchema = z
+    .string()
+    .describe("End date/time. Same formats as begin_date.");
+export const RangeSchema = z
+    .number()
+    .int()
+    .positive()
+    .describe("Number of hours. With begin_date: hours forward. With end_date: hours back. Alone: hours back from now.");
+export const DatumSchema = z
+    .enum([
+    "MHHW",
+    "MHW",
+    "MTL",
+    "MSL",
+    "MLW",
+    "MLLW",
+    "NAVD",
+    "STND",
+    "IGLD",
+    "LWD",
+    "CRD",
+])
+    .describe("Vertical reference datum for heights. MLLW is the standard chart datum for coastal stations. IGLD and LWD apply to Great Lakes stations ONLY; NAVD/CRD exist only at stations where computed. Check a station's supported datums with noaa_get_station_datums.");
+export const UnitsSchema = z
+    .enum(["english", "metric"])
+    .default("english")
+    .describe("Unit system. english: feet, °F, knots (wind AND currents), nautical miles. metric: meters, °C, m/s for wind but cm/s for currents, kilometers. Air pressure is millibars and salinity is PSU in BOTH systems.");
+export const TimeZoneSchema = z
+    .enum(["gmt", "lst", "lst_ldt"])
+    .default("lst_ldt")
+    .describe("Time zone for timestamps: gmt = UTC, lst = station local standard time (no DST), lst_ldt = station local time with DST. Note: daily_mean data requires lst.");
+export const ResponseFormatSchema = z
+    .enum(["markdown", "json"])
+    .default("markdown")
+    .describe('Output format: "markdown" for a readable summary table, "json" for the complete structured payload.');
+/** Base date-selection fields shared by all Data API tools. */
+export const dateFields = {
+    date: DateAliasSchema.optional(),
+    begin_date: BeginDateSchema.optional(),
+    end_date: EndDateSchema.optional(),
+    range: RangeSchema.optional(),
+};
+export const READ_ONLY_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+/** Astronomy tools compute locally — no external world interaction. */
+export const LOCAL_COMPUTE_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+export const LatitudeSchema = z
+    .number()
+    .min(-90)
+    .max(90)
+    .describe("Latitude in decimal degrees (-90 to 90).");
+export const LongitudeSchema = z
+    .number()
+    .min(-180)
+    .max(180)
+    .describe("Longitude in decimal degrees (-180 to 180).");

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

@@ -0,0 +1,81 @@
+/**
+ * NOAA CO-OPS Data Retrieval API service.
+ *
+ * Encodes the per-product rules discovered from the official docs:
+ *  - which products need a datum
+ *  - per-product/interval maximum request spans (validated before calling)
+ *  - product-specific restrictions (daily_mean is Great Lakes-only and
+ *    requires time_zone=lst; bin=0 caps currents at 7 days; etc.)
+ */
+import { DateParams } from "../validation/dates.js";
+import type { UnitSystem } from "../format/units.js";
+export type NoaaTimeZone = "gmt" | "lst" | "lst_ldt";
+export interface DataApiBaseParams extends DateParams {
+    station: string;
+    units: UnitSystem;
+    time_zone: NoaaTimeZone;
+}
+interface DataObservation {
+    t: string;
+    v?: string;
+    s?: string;
+    f?: string;
+    q?: string;
+    ty?: string;
+    d?: string;
+    dr?: string;
+    g?: string;
+    b?: string;
+    [key: string]: string | undefined;
+}
+export interface DataApiResponse {
+    metadata?: {
+        id: string;
+        name: string;
+        lat: string;
+        lon: string;
+    };
+    data?: DataObservation[];
+    predictions?: DataObservation[];
+    current_predictions?: {
+        cp: DataObservation[];
+    } | DataObservation[];
+    [key: string]: unknown;
+}
+export type WaterLevelInterval = "1" | "6" | "hourly";
+export declare function getWaterLevels(params: DataApiBaseParams & {
+    interval: WaterLevelInterval;
+    datum: string;
+}): Promise<{
+    product: string;
+    response: DataApiResponse;
+}>;
+export type SummaryProduct = "high_low" | "daily_mean" | "daily_max_min" | "monthly_mean";
+export declare function getWaterLevelSummaries(params: DataApiBaseParams & {
+    product: SummaryProduct;
+    datum: string;
+}): Promise<{
+    response: DataApiResponse;
+    timeZoneForced: boolean;
+}>;
+export type PredictionInterval = "hilo" | "h" | "1" | "5" | "6" | "10" | "15" | "30" | "60";
+export declare function getTidePredictions(params: DataApiBaseParams & {
+    interval: PredictionInterval;
+    datum: string;
+}): Promise<DataApiResponse>;
+export declare function getCurrents(params: DataApiBaseParams & {
+    bin?: number;
+    expand_detailed?: boolean;
+}): Promise<DataApiResponse>;
+export type CurrentPredictionInterval = "max_slack" | "h" | "1" | "6" | "10" | "30" | "60";
+export declare function getCurrentPredictions(params: DataApiBaseParams & {
+    bin?: number;
+    interval: CurrentPredictionInterval;
+    vel_type?: "default" | "speed_dir";
+}): Promise<DataApiResponse>;
+export type MetProduct = "air_temperature" | "water_temperature" | "wind" | "air_pressure" | "air_gap" | "conductivity" | "visibility" | "humidity" | "salinity";
+export declare function getMeteorologicalData(params: DataApiBaseParams & {
+    product: MetProduct;
+    interval?: "6" | "h";
+}): Promise<DataApiResponse>;
+export {};