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

package/dist/tools/station-metadata.js

@@ -0,0 +1,208 @@
+/**
+ * Station scientific metadata tools: datums, harmonic constituents,
+ * prediction offsets.
+ */
+import { z } from "zod";
+import { extractList, getStationResource } from "../services/metadata-api.js";
+import { READ_ONLY_ANNOTATIONS, ResponseFormatSchema, StationIdSchema, UnitsSchema, } from "../schemas/common.js";
+import { markdownTable, respond, respondError } from "../format/respond.js";
+import { unitLabel } from "../format/units.js";
+export function registerStationMetadataTools(server) {
+    server.registerTool("noaa_get_station_datums", {
+        title: "Get Station Datums",
+        description: `Get the accepted tidal datum values for a station: the elevations of MHHW, MHW, MTL, MSL, DTL, MLW, MLLW, STND, NAVD88 (where computed), plus GT (great diurnal range), MN (mean range), LAT/HAT (lowest/highest astronomical tide), and the station's historical extreme min/max water levels with dates.
+
+epoch "current" returns the present National Tidal Datum Epoch (1983–2001) values; "superseded" returns the prior epoch's values (useful for historical comparisons — not all stations have one).
+
+All values share one reference zero (the station datum), so datum-to-datum conversion is subtraction: height_above_MLLW = height_above_MSL + (MSL − MLLW). Use this tool to (1) check which datums a station supports before requesting data, and (2) convert heights between datums.`,
+        inputSchema: {
+            station: StationIdSchema,
+            epoch: z
+                .enum(["current", "superseded"])
+                .default("current")
+                .describe('"current" = present NTDE (1983–2001); "superseded" = prior epoch values.'),
+            units: UnitsSchema,
+            response_format: ResponseFormatSchema,
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        try {
+            const resource = params.epoch === "superseded" ? "supersededdatums" : "datums";
+            const payload = await getStationResource(params.station, resource, {
+                units: params.units,
+            });
+            const datums = extractList(payload, "datums", "datumList");
+            const heightUnits = unitLabel("water_level", params.units);
+            const structured = {
+                station: params.station,
+                epoch_requested: params.epoch,
+                epoch: payload.epoch,
+                units_label: heightUnits,
+                orthometric_datum: payload.OrthometricDatum,
+                datums,
+                LAT: payload.LAT,
+                HAT: payload.HAT,
+                historic_min: payload.min,
+                historic_min_date: payload.mindate,
+                historic_max: payload.max,
+                historic_max_date: payload.maxdate,
+            };
+            const lines = [
+                `# Tidal Datums — Station ${params.station}`,
+                "",
+                `**Epoch**: ${String(payload.epoch ?? "n/a")} (${params.epoch}) · **Units**: ${heightUnits} above station datum`,
+                "",
+                datums.length === 0
+                    ? "_No datums published for this station and epoch._"
+                    : markdownTable(["Datum", "Description", `Value (${heightUnits})`], datums.map((d) => [d.name, d.description, d.value])),
+                "",
+                `- **HAT** (highest astronomical tide): ${String(payload.HAT ?? "—")} · **LAT**: ${String(payload.LAT ?? "—")}`,
+                `- **Historic max**: ${String(payload.max ?? "—")} on ${String(payload.maxdate ?? "—")} · **Historic min**: ${String(payload.min ?? "—")} on ${String(payload.mindate ?? "—")}`,
+            ];
+            return respond(params.response_format, structured, lines.join("\n"));
+        }
+        catch (error) {
+            return respondError(error);
+        }
+    });
+    server.registerTool("noaa_get_harmonic_constituents", {
+        title: "Get Harmonic Constituents",
+        description: `Get the harmonic constituents NOAA uses to compute tide or current predictions at a station — the amplitude, phase, and angular speed of each tidal constituent (M2, S2, N2, K1, O1, ...).
+
+For water-level stations: amplitude (feet/meters), phase_GMT and phase_local (degrees), speed (degrees/hour). For current stations (alphanumeric IDs) constituents are current ellipses (major/minor amplitudes and phases per depth bin — pass bin to filter).
+
+Use for: building custom tide computations, checking a station's dominant constituents (M2 amplitude indicates semidiurnal range), verifying whether a station is harmonically predicted at all. Only reference (R) stations have constituents — subordinate stations use offsets (noaa_get_prediction_offsets).`,
+        inputSchema: {
+            station: StationIdSchema,
+            bin: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe("For current stations: restrict to one depth bin."),
+            units: UnitsSchema,
+            response_format: ResponseFormatSchema,
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        try {
+            const payload = await getStationResource(params.station, "harcon", {
+                units: params.units,
+                bin: params.bin,
+            });
+            const constituents = extractList(payload, "HarmonicConstituents", "harmonicConstituents", "harconList");
+            const isCurrentStation = constituents[0]?.majorAmplitude !== undefined;
+            // Water-level harcon amplitudes are heights (feet/meters). Current
+            // harcon reports a compound units string like "meters, centimeters/second"
+            // (bin depth, amplitude) — prefer NOAA's own label when present.
+            const amplitudeUnits = typeof payload.units === "string" && payload.units
+                ? payload.units
+                : unitLabel(isCurrentStation ? "currents" : "water_level", params.units);
+            const structured = {
+                station: params.station,
+                bin: params.bin,
+                amplitude_units: amplitudeUnits,
+                count: constituents.length,
+                constituents,
+            };
+            const markdown = [
+                `# Harmonic Constituents — Station ${params.station}${params.bin ? ` (bin ${params.bin})` : ""}`,
+                "",
+                `**Count**: ${constituents.length} · **Amplitude units**: ${amplitudeUnits} · phases in degrees, speed in degrees/hour`,
+                "",
+                constituents.length === 0
+                    ? "_No harmonic constituents published — this may be a subordinate station (see noaa_get_prediction_offsets)._"
+                    : isCurrentStation
+                        ? markdownTable([
+                            "#",
+                            "Name",
+                            "Major amp",
+                            "Major phase (GMT)",
+                            "Minor amp",
+                            "Speed",
+                            "Bin",
+                        ], constituents.map((c) => [
+                            String(c.constNum ?? c.number ?? ""),
+                            String(c.constituentName ?? c.name ?? ""),
+                            String(c.majorAmplitude ?? ""),
+                            String(c.majorPhaseGMT ?? ""),
+                            String(c.minorAmplitude ?? ""),
+                            String(c.majorMeanSpeed ?? ""),
+                            String(c.binNbr ?? ""),
+                        ]))
+                        : markdownTable([
+                            "#",
+                            "Name",
+                            "Description",
+                            `Amplitude (${amplitudeUnits})`,
+                            "Phase GMT (°)",
+                            "Phase local (°)",
+                            "Speed (°/hr)",
+                        ], constituents.map((c) => [
+                            String(c.number ?? ""),
+                            String(c.name ?? ""),
+                            String(c.description ?? ""),
+                            String(c.amplitude ?? ""),
+                            String(c.phase_GMT ?? ""),
+                            String(c.phase_local ?? ""),
+                            String(c.speed ?? ""),
+                        ])),
+            ].join("\n");
+            return respond(params.response_format, structured, markdown);
+        }
+        catch (error) {
+            return respondError(error);
+        }
+    });
+    server.registerTool("noaa_get_prediction_offsets", {
+        title: "Get Prediction Offsets (Subordinate Stations)",
+        description: `Get the offsets a subordinate (type "S") prediction station applies to its reference station's predictions.
+
+kind "tide": returns refStationId, time offsets for high/low tide (minutes), height offsets for high/low tide, and whether the height adjustment is a ratio (multiplied) or fixed value — this is how NOAA derives subordinate-station tide times from the reference harmonic station.
+
+kind "current": returns refStationId/bin, mean flood/ebb directions, and time adjustments (minutes) for max flood, slack-before-ebb, max ebb, slack-before-flood plus amplitude ratios. Note: current prediction offsets are indexed per bin — pass the station_bin_suffix ID form (e.g. "ACT0091_1") if the plain ID returns nothing.
+
+Reference (R) stations return empty/null offsets — they don't need any.`,
+        inputSchema: {
+            station: StationIdSchema,
+            kind: z
+                .enum(["tide", "current"])
+                .default("tide")
+                .describe('"tide" = tidepredoffsets; "current" = currentpredictionoffsets.'),
+            response_format: ResponseFormatSchema,
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        try {
+            const resource = params.kind === "tide"
+                ? "tidepredoffsets"
+                : "currentpredictionoffsets";
+            const payload = await getStationResource(params.station, resource);
+            const structured = {
+                station: params.station,
+                kind: params.kind,
+                offsets: payload,
+            };
+            const lines = [
+                `# Prediction Offsets (${params.kind}) — Station ${params.station}`,
+                "",
+            ];
+            if (params.kind === "tide") {
+                const p = payload;
+                if (!p.refStationId) {
+                    lines.push("_No offsets — this is likely a reference (R) station with its own harmonic constituents, or has no published offsets._");
+                }
+                else {
+                    lines.push(`- **Reference station**: ${String(p.refStationId)}`, `- **High tide**: time offset ${String(p.timeOffsetHighTide ?? "—")} min, height offset ${String(p.heightOffsetHighTide ?? "—")}`, `- **Low tide**: time offset ${String(p.timeOffsetLowTide ?? "—")} min, height offset ${String(p.heightOffsetLowTide ?? "—")}`, `- **Height adjustment type**: ${String(p.heightAdjustedType ?? "—")} (R = ratio/multiplier, F = fixed additive)`);
+                }
+            }
+            else {
+                lines.push("```json", JSON.stringify(payload, null, 2), "```");
+            }
+            return respond(params.response_format, structured, lines.join("\n"));
+        }
+        catch (error) {
+            return respondError(error);
+        }
+    });
+}

package/dist/tools/stations.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Station discovery and overview tools (Metadata API).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerStationTools(server: McpServer): void;

package/dist/tools/stations.js

@@ -0,0 +1,265 @@
+/**
+ * Station discovery and overview tools (Metadata API).
+ */
+import { z } from "zod";
+import { findNearestStations, getStationInfo, searchStations, STATION_TYPES, } from "../services/metadata-api.js";
+import { LatitudeSchema, LongitudeSchema, READ_ONLY_ANNOTATIONS, ResponseFormatSchema, StationIdSchema, UnitsSchema, } from "../schemas/common.js";
+import { markdownTable, respond, respondError } from "../format/respond.js";
+const StationTypeSchema = z
+    .enum(STATION_TYPES)
+    .describe('Station capability filter. Common: "waterlevels" (active water level), "tidepredictions", "currents" (observed currents), "currentpredictions", "met" (weather sensors). Full list via noaa_get_reference_guide topic "station_types".');
+function summarize(s) {
+    return {
+        id: s.id,
+        name: s.name,
+        state: s.state ?? undefined,
+        lat: s.lat,
+        lng: s.lng,
+        tide_type: s.tideType || undefined,
+        great_lakes: s.greatlakes || undefined,
+        prediction_type: s.type === "R"
+            ? "reference (harmonic)"
+            : s.type === "S"
+                ? "subordinate (offsets)"
+                : undefined,
+        reference_id: s.reference_id || undefined,
+        ports_code: s.portscode || undefined,
+    };
+}
+export function registerStationTools(server) {
+    server.registerTool("noaa_search_stations", {
+        title: "Search NOAA Stations",
+        description: `Search the NOAA CO-OPS station directory by capability type, name, and/or state.
+
+Filter with:
+- type: what the station does (waterlevels, tidepredictions, currents, currentpredictions, met, ...) — pick the type matching the data you plan to request.
+- name: case-insensitive substring ("San Francisco", "Boston").
+- state: two-letter code ("CA", "MA").
+
+Returns id, name, location, tide type, Great Lakes flag, and for prediction stations whether they are reference (R, harmonic) or subordinate (S, offset-based — hilo predictions only). Results are paginated (limit/offset). For proximity search by coordinates use noaa_find_nearest_stations instead.`,
+        inputSchema: {
+            type: StationTypeSchema.optional(),
+            name: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Case-insensitive substring of the station name."),
+            state: z
+                .string()
+                .length(2)
+                .optional()
+                .describe('Two-letter US state/territory code, e.g. "CA".'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(25)
+                .describe("Maximum stations to return."),
+            offset: z
+                .number()
+                .int()
+                .min(0)
+                .default(0)
+                .describe("Pagination offset."),
+            response_format: ResponseFormatSchema,
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        try {
+            const matches = await searchStations({
+                type: params.type,
+                name: params.name,
+                state: params.state,
+                units: "english",
+            });
+            const page = matches.slice(params.offset, params.offset + params.limit);
+            const hasMore = params.offset + page.length < matches.length;
+            const structured = {
+                total: matches.length,
+                count: page.length,
+                offset: params.offset,
+                has_more: hasMore,
+                ...(hasMore ? { next_offset: params.offset + page.length } : {}),
+                stations: page.map(summarize),
+            };
+            const filterDesc = [
+                params.type && `type=${params.type}`,
+                params.name && `name~"${params.name}"`,
+                params.state && `state=${params.state}`,
+            ]
+                .filter(Boolean)
+                .join(", ");
+            const markdown = [
+                `# Station Search${filterDesc ? ` (${filterDesc})` : ""}`,
+                "",
+                `${matches.length} match(es); showing ${page.length} from offset ${params.offset}.${hasMore ? ` More available — call again with offset=${params.offset + page.length}.` : ""}`,
+                "",
+                markdownTable(["ID", "Name", "State", "Lat", "Lon", "Tide type", "Notes"], page.map((s) => [
+                    s.id,
+                    s.name,
+                    s.state,
+                    s.lat,
+                    s.lng,
+                    s.tideType,
+                    [
+                        s.greatlakes ? "Great Lakes" : null,
+                        s.type === "S"
+                            ? `subordinate of ${s.reference_id ?? "?"}`
+                            : null,
+                        s.type === "R" ? "reference" : null,
+                    ]
+                        .filter(Boolean)
+                        .join("; "),
+                ])),
+            ].join("\n");
+            return respond(params.response_format, structured, markdown);
+        }
+        catch (error) {
+            return respondError(error);
+        }
+    });
+    server.registerTool("noaa_find_nearest_stations", {
+        title: "Find Nearest NOAA Stations",
+        description: `Find the NOAA stations closest to a latitude/longitude point, sorted by distance.
+
+Use this to answer "what's the tide station near <place>?" — geocode the place to coordinates first, then call this. Filter by type to match the data you need (e.g. type "tidepredictions" before calling noaa_get_tide_predictions, "currents" before noaa_get_currents — current stations have different IDs than water-level stations).
+
+Distance is computed great-circle (Haversine) and reported in both km and miles. (NOAA's API has no native coordinate search; this tool maintains a cached station directory.)`,
+        inputSchema: {
+            latitude: LatitudeSchema,
+            longitude: LongitudeSchema,
+            type: StationTypeSchema.optional(),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .default(10)
+                .describe("Number of stations to return."),
+            max_distance_km: z
+                .number()
+                .positive()
+                .optional()
+                .describe("Optional cutoff radius in kilometers."),
+            response_format: ResponseFormatSchema,
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        try {
+            const nearest = await findNearestStations(params.latitude, params.longitude, params.type, params.limit, params.max_distance_km);
+            const structured = {
+                origin: { latitude: params.latitude, longitude: params.longitude },
+                type: params.type,
+                count: nearest.length,
+                stations: nearest.map((s) => ({
+                    ...summarize(s),
+                    distance_km: Number(s.distance_km.toFixed(2)),
+                    distance_mi: Number(s.distance_mi.toFixed(2)),
+                })),
+            };
+            const markdown = [
+                `# Nearest Stations to (${params.latitude}, ${params.longitude})${params.type ? ` — type ${params.type}` : ""}`,
+                "",
+                nearest.length === 0
+                    ? "_No stations found within the given constraints. Try removing max_distance_km or the type filter._"
+                    : markdownTable([
+                        "ID",
+                        "Name",
+                        "State",
+                        "Distance (km)",
+                        "Distance (mi)",
+                        "Tide type",
+                        "Notes",
+                    ], nearest.map((s) => [
+                        s.id,
+                        s.name,
+                        s.state,
+                        s.distance_km.toFixed(1),
+                        s.distance_mi.toFixed(1),
+                        s.tideType,
+                        s.type === "S"
+                            ? `subordinate of ${s.reference_id ?? "?"}`
+                            : s.greatlakes
+                                ? "Great Lakes"
+                                : "",
+                    ])),
+            ].join("\n");
+            return respond(params.response_format, structured, markdown);
+        }
+        catch (error) {
+            return respondError(error);
+        }
+    });
+    server.registerTool("noaa_get_station_info", {
+        title: "Get Station Info",
+        description: `Get a NOAA station's full metadata record: location, state, time zone, tide type, Great Lakes flag, capability flags, and links to available sub-resources.
+
+Optionally expand sub-resources inline via the "expand" list:
+- details (established/removed dates), sensors (installed instruments + elevations), floodlevels (NOS/NWS minor/moderate/major flood thresholds), benchmarks, products (available data page links), notices, disclaimers — for water-level stations
+- bins (ADCP depth bins), deployments — for current stations (alphanumeric IDs)
+
+Use this before requesting data to confirm what the station actually collects. For datum values use noaa_get_station_datums; for harmonic constituents use noaa_get_harmonic_constituents.`,
+        inputSchema: {
+            station: StationIdSchema,
+            expand: z
+                .array(z.enum([
+                "details",
+                "sensors",
+                "floodlevels",
+                "benchmarks",
+                "products",
+                "notices",
+                "disclaimers",
+                "bins",
+                "deployments",
+            ]))
+                .optional()
+                .describe("Sub-resources to embed inline (availability varies by station type)."),
+            units: UnitsSchema,
+            response_format: ResponseFormatSchema,
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        try {
+            const payload = await getStationInfo(params.station, params.expand, params.units);
+            const stations = payload.stations;
+            const info = stations?.[0] ?? payload;
+            const structured = {
+                station: params.station,
+                units: params.units,
+                info,
+            };
+            const lines = [
+                `# Station ${params.station} — ${String(info.name ?? "")}`,
+                "",
+            ];
+            const fact = (label, value) => {
+                if (value !== undefined && value !== null && value !== "") {
+                    lines.push(`- **${label}**: ${String(value)}`);
+                }
+            };
+            fact("Location", `${info.lat}, ${info.lng}`);
+            fact("State", info.state);
+            fact("Time zone", info.timezone);
+            fact("Tide type", info.tideType);
+            fact("Tidal", info.tidal);
+            fact("Great Lakes", info.greatlakes);
+            fact("Affiliations", info.affiliations);
+            fact("PORTS code", info.portscode);
+            fact("Storm surge station", info.stormsurge);
+            fact("High-tide-flooding history available", info.HTFhistorical);
+            if (typeof info.expand === "string" && info.expand) {
+                fact("Expandable sub-resources", info.expand);
+            }
+            if (params.expand?.length) {
+                lines.push("", `Expanded sub-resources (${params.expand.join(", ")}) are included in the JSON payload.`);
+            }
+            lines.push("", '_Use response_format "json" for the complete record._');
+            return respond(params.response_format, structured, lines.join("\n"));
+        }
+        catch (error) {
+            return respondError(error);
+        }
+    });
+}

package/dist/tools/water.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Water level observation and tide prediction tools.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerWaterTools(server: McpServer): void;