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

package/dist/services/data-api.js

@@ -0,0 +1,117 @@
+/**
+ * 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 { fetchDataApi } from "../client/http.js";
+import { assertSpanWithinLimit, resolveDateParams, } from "../validation/dates.js";
+function dateQuery(resolved) {
+    return {
+        date: resolved.date,
+        begin_date: resolved.begin_date,
+        end_date: resolved.end_date,
+        range: resolved.range,
+    };
+}
+const WATER_LEVEL_PRODUCTS = {
+    "1": "one_minute_water_level",
+    "6": "water_level",
+    hourly: "hourly_height",
+};
+export async function getWaterLevels(params) {
+    const product = WATER_LEVEL_PRODUCTS[params.interval];
+    const resolved = resolveDateParams(params);
+    assertSpanWithinLimit(resolved.spanDays, product, `${params.interval}-minute-interval water levels`);
+    const response = await fetchDataApi({
+        product,
+        station: params.station,
+        datum: params.datum,
+        units: params.units,
+        time_zone: params.time_zone,
+        ...dateQuery(resolved),
+    });
+    return { product, response };
+}
+export async function getWaterLevelSummaries(params) {
+    const resolved = resolveDateParams(params);
+    assertSpanWithinLimit(resolved.spanDays, params.product, params.product);
+    // daily_mean is only computed for Great Lakes stations and NOAA requires
+    // time_zone=lst for it — force it rather than surface a cryptic upstream error.
+    let timeZone = params.time_zone;
+    let timeZoneForced = false;
+    if (params.product === "daily_mean" && timeZone !== "lst") {
+        timeZone = "lst";
+        timeZoneForced = true;
+    }
+    const response = await fetchDataApi({
+        product: params.product,
+        station: params.station,
+        datum: params.datum,
+        units: params.units,
+        time_zone: timeZone,
+        ...dateQuery(resolved),
+    });
+    return { response, timeZoneForced };
+}
+export async function getTidePredictions(params) {
+    const resolved = resolveDateParams(params);
+    const limitKey = params.interval === "hilo" ? "predictions:hilo" : "predictions";
+    assertSpanWithinLimit(resolved.spanDays, limitKey, params.interval === "hilo"
+        ? "high/low tide predictions"
+        : "interval tide predictions");
+    return fetchDataApi({
+        product: "predictions",
+        station: params.station,
+        datum: params.datum,
+        units: params.units,
+        time_zone: params.time_zone,
+        interval: params.interval,
+        ...dateQuery(resolved),
+    });
+}
+export async function getCurrents(params) {
+    const resolved = resolveDateParams(params);
+    assertSpanWithinLimit(resolved.spanDays, "currents", "observed currents");
+    return fetchDataApi({
+        product: "currents",
+        station: params.station,
+        units: params.units,
+        time_zone: params.time_zone,
+        bin: params.bin,
+        expand: params.expand_detailed ? "detailed" : undefined,
+        ...dateQuery(resolved),
+    });
+}
+export async function getCurrentPredictions(params) {
+    const resolved = resolveDateParams(params);
+    const limitKey = params.interval === "max_slack"
+        ? "currents_predictions:max_slack"
+        : "currents_predictions";
+    assertSpanWithinLimit(resolved.spanDays, limitKey, "current predictions");
+    return fetchDataApi({
+        product: "currents_predictions",
+        station: params.station,
+        units: params.units,
+        time_zone: params.time_zone,
+        bin: params.bin,
+        interval: params.interval,
+        vel_type: params.vel_type === "speed_dir" ? "speed_dir" : undefined,
+        ...dateQuery(resolved),
+    });
+}
+export async function getMeteorologicalData(params) {
+    const resolved = resolveDateParams(params);
+    assertSpanWithinLimit(resolved.spanDays, params.product === "air_gap" ? "air_gap" : "met", params.product);
+    return fetchDataApi({
+        product: params.product,
+        station: params.station,
+        units: params.units,
+        time_zone: params.time_zone,
+        interval: params.interval === "h" ? "h" : undefined,
+        ...dateQuery(resolved),
+    });
+}

package/dist/services/dpapi.d.ts

@@ -0,0 +1,55 @@
+/**
+ * NOAA CO-OPS Derived Product API (DPAPI) service.
+ *
+ * Endpoint paths verified live (2026-07):
+ *   /webapi/product/sealvltrends.json          — relative sea level trends
+ *   /webapi/product.json?name=extremewaterlevels
+ *   /webapi/product.json?name=toptenwaterlevels|peakwaterlevels
+ *   /webapi/product/slr_projections.json       — sea level rise projections
+ *   /webapi/htf/htf_daily|htf_monthly|htf_seasonal|htf_annual|
+ *          htf_met_year_annual|htf_met_year_annual_outlook|
+ *          htf_projection_decadal|htf_record|htf_likely_decadal_scenarios .json
+ *   /webapi/htb.json                           — HTF daily likelihoods
+ */
+import type { UnitSystem } from "../format/units.js";
+export declare function getSeaLevelTrends(params: {
+    station?: string;
+    affil?: "Global" | "US";
+}): Promise<Record<string, unknown>>;
+export declare function getExtremeWaterLevels(params: {
+    station: string;
+    units: UnitSystem;
+    extremeType?: "annuals" | "monthlies";
+    levelType?: "high" | "low";
+    datum?: string;
+}): Promise<Record<string, unknown>>;
+export declare function getTopTenWaterLevels(params: {
+    station: string;
+    analysis: "toptenwaterlevels" | "peakwaterlevels";
+    units: UnitSystem;
+    datum?: string;
+    year?: number;
+}): Promise<Record<string, unknown>>;
+export declare function getSeaLevelRiseProjections(params: {
+    station?: string;
+    scenario?: string;
+    projection_year?: number;
+    report_year?: number;
+    units?: UnitSystem;
+}): Promise<Record<string, unknown>>;
+export type HtfReport = "daily" | "monthly" | "seasonal" | "annual" | "met_year_annual" | "annual_outlook" | "projections" | "record_days" | "likely_scenarios" | "daily_likelihoods";
+export interface HtfParams {
+    station: string;
+    start_date?: string;
+    end_date?: string;
+    year?: number;
+    month?: number;
+    range?: number;
+    season_months?: "DJF" | "MAM" | "JJA" | "SON";
+    met_year?: number;
+    decade?: number;
+    flood_threshold?: "minor" | "moderate" | "major";
+    units?: UnitSystem;
+    datum?: string;
+}
+export declare function getHighTideFlooding(report: HtfReport, params: HtfParams): Promise<Record<string, unknown>>;

package/dist/services/dpapi.js

@@ -0,0 +1,60 @@
+/**
+ * NOAA CO-OPS Derived Product API (DPAPI) service.
+ *
+ * Endpoint paths verified live (2026-07):
+ *   /webapi/product/sealvltrends.json          — relative sea level trends
+ *   /webapi/product.json?name=extremewaterlevels
+ *   /webapi/product.json?name=toptenwaterlevels|peakwaterlevels
+ *   /webapi/product/slr_projections.json       — sea level rise projections
+ *   /webapi/htf/htf_daily|htf_monthly|htf_seasonal|htf_annual|
+ *          htf_met_year_annual|htf_met_year_annual_outlook|
+ *          htf_projection_decadal|htf_record|htf_likely_decadal_scenarios .json
+ *   /webapi/htb.json                           — HTF daily likelihoods
+ */
+import { fetchDpapi } from "../client/http.js";
+export async function getSeaLevelTrends(params) {
+    return fetchDpapi("/webapi/product/sealvltrends.json", params);
+}
+export async function getExtremeWaterLevels(params) {
+    return fetchDpapi("/webapi/product.json", {
+        name: "extremewaterlevels",
+        ...params,
+    });
+}
+export async function getTopTenWaterLevels(params) {
+    const { analysis, ...rest } = params;
+    return fetchDpapi("/webapi/product.json", { name: analysis, ...rest });
+}
+export async function getSeaLevelRiseProjections(params) {
+    return fetchDpapi("/webapi/product/slr_projections.json", params);
+}
+const HTF_PATHS = {
+    daily: "/webapi/htf/htf_daily.json",
+    monthly: "/webapi/htf/htf_monthly.json",
+    seasonal: "/webapi/htf/htf_seasonal.json",
+    annual: "/webapi/htf/htf_annual.json",
+    met_year_annual: "/webapi/htf/htf_met_year_annual.json",
+    annual_outlook: "/webapi/htf/htf_met_year_annual_outlook.json",
+    projections: "/webapi/htf/htf_projection_decadal.json",
+    record_days: "/webapi/htf/htf_record.json",
+    likely_scenarios: "/webapi/htf/htf_likely_decadal_scenarios.json",
+    daily_likelihoods: "/webapi/htb.json",
+};
+export async function getHighTideFlooding(report, params) {
+    if (report === "daily" && (!params.start_date || !params.end_date)) {
+        throw new Error("The daily high-tide-flooding report requires both start_date and end_date (YYYYMMDD).");
+    }
+    const query = { ...params };
+    // NOAA's `range` only takes effect alongside a starting year (year..year+range).
+    // A bare range reads most naturally as "the last N years" — translate it.
+    if (query.range !== undefined) {
+        const startYear = new Date().getUTCFullYear() - query.range;
+        if (report === "met_year_annual" || report === "annual_outlook") {
+            query.met_year = query.met_year ?? startYear;
+        }
+        else if (query.year === undefined) {
+            query.year = startYear;
+        }
+    }
+    return fetchDpapi(HTF_PATHS[report], { ...query });
+}

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

@@ -0,0 +1,62 @@
+/**
+ * NOAA CO-OPS Metadata API (MDAPI) service.
+ *
+ * Notes from live verification of the API (2026-07):
+ *  - The stations list endpoint IGNORES lat/lon/radius query params, so
+ *    "find stations near a point" is implemented client-side with a cached
+ *    station directory and Haversine distance.
+ *  - Response array keys differ from NOAA's own docs prose (e.g. datums not
+ *    datumList, HarmonicConstituents not harconList) — parse defensively.
+ *  - 404s are bare (no JSON body), unlike the Data API's structured errors.
+ */
+import type { UnitSystem } from "../format/units.js";
+export declare const STATION_TYPES: readonly ["waterlevels", "historicwl", "met", "waterlevelsandmet", "tidepredictions", "harcon", "datums", "supersededdatums", "benchmarks", "supersededbenchmarks", "currents", "historiccurrents", "surveycurrents", "currentpredictions", "cond", "watertemp", "physocean", "tcoon", "1minute", "airgap", "visibility", "highwater", "lowwater"];
+export type StationType = (typeof STATION_TYPES)[number];
+export interface StationSummary {
+    id: string;
+    name: string;
+    lat: number;
+    lng: number;
+    state?: string;
+    affiliations?: string;
+    portscode?: string | null;
+    tideType?: string;
+    tidal?: boolean;
+    greatlakes?: boolean;
+    type?: string;
+    reference_id?: string;
+    [key: string]: unknown;
+}
+interface StationListResponse {
+    count: number;
+    units: string | null;
+    stations: StationSummary[];
+}
+/** Cached fetch of the full station directory for one station type. */
+export declare function listStations(type: StationType | undefined, units: UnitSystem): Promise<StationListResponse>;
+export interface StationSearchFilters {
+    type?: StationType;
+    name?: string;
+    state?: string;
+    units: UnitSystem;
+}
+/** Client-side filtered station search over the cached directory. */
+export declare function searchStations(filters: StationSearchFilters): Promise<StationSummary[]>;
+export declare function haversineKm(lat1: number, lon1: number, lat2: number, lon2: number): number;
+export interface NearbyStation extends StationSummary {
+    distance_km: number;
+    distance_mi: number;
+}
+/** Nearest stations to an arbitrary point (MDAPI has no native lat/lon search). */
+export declare function findNearestStations(lat: number, lon: number, type: StationType | undefined, limit: number, maxDistanceKm?: number): Promise<NearbyStation[]>;
+/** Single-station overview, optionally expanding sub-resources inline. */
+export declare function getStationInfo(stationId: string, expand: string[] | undefined, units: UnitSystem): Promise<Record<string, unknown>>;
+/** Generic station sub-resource fetch (datums, harcon, tidepredoffsets, ...). */
+export declare function getStationResource<T = Record<string, unknown>>(stationId: string, resource: string, params?: Record<string, string | number | undefined>): Promise<T>;
+/**
+ * Defensive array extraction: MDAPI's real key names differ from its docs
+ * (observed live: `datums`, `HarmonicConstituents`, `sensors`, `bins`,
+ * `notices`, `products` — docs claim `datumList`, `harconList`, ...).
+ */
+export declare function extractList<T = Record<string, unknown>>(payload: Record<string, unknown>, ...candidateKeys: string[]): T[];
+export {};

package/dist/services/metadata-api.js

@@ -0,0 +1,105 @@
+/**
+ * NOAA CO-OPS Metadata API (MDAPI) service.
+ *
+ * Notes from live verification of the API (2026-07):
+ *  - The stations list endpoint IGNORES lat/lon/radius query params, so
+ *    "find stations near a point" is implemented client-side with a cached
+ *    station directory and Haversine distance.
+ *  - Response array keys differ from NOAA's own docs prose (e.g. datums not
+ *    datumList, HarmonicConstituents not harconList) — parse defensively.
+ *  - 404s are bare (no JSON body), unlike the Data API's structured errors.
+ */
+import { fetchMetadataApi } from "../client/http.js";
+import { cache } from "../client/cache.js";
+import { CACHE_TTL } from "../constants.js";
+export const STATION_TYPES = [
+    "waterlevels",
+    "historicwl",
+    "met",
+    "waterlevelsandmet",
+    "tidepredictions",
+    "harcon",
+    "datums",
+    "supersededdatums",
+    "benchmarks",
+    "supersededbenchmarks",
+    "currents",
+    "historiccurrents",
+    "surveycurrents",
+    "currentpredictions",
+    "cond",
+    "watertemp",
+    "physocean",
+    "tcoon",
+    "1minute",
+    "airgap",
+    "visibility",
+    "highwater",
+    "lowwater",
+];
+/** Cached fetch of the full station directory for one station type. */
+export async function listStations(type, units) {
+    const key = `stations:${type ?? "all"}:${units}`;
+    return cache.getOrLoad(key, CACHE_TTL.stationList, () => fetchMetadataApi("/stations.json", { type, units }));
+}
+/** Client-side filtered station search over the cached directory. */
+export async function searchStations(filters) {
+    const { stations } = await listStations(filters.type, filters.units);
+    const nameNeedle = filters.name?.toLowerCase();
+    const stateNeedle = filters.state?.toLowerCase();
+    return stations.filter((s) => {
+        if (nameNeedle && !s.name?.toLowerCase().includes(nameNeedle))
+            return false;
+        if (stateNeedle && (s.state ?? "").toLowerCase() !== stateNeedle)
+            return false;
+        return true;
+    });
+}
+const EARTH_RADIUS_KM = 6371;
+export function haversineKm(lat1, lon1, lat2, lon2) {
+    const toRad = (deg) => (deg * Math.PI) / 180;
+    const dLat = toRad(lat2 - lat1);
+    const dLon = toRad(lon2 - lon1);
+    const a = Math.sin(dLat / 2) ** 2 +
+        Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) ** 2;
+    return 2 * EARTH_RADIUS_KM * Math.asin(Math.sqrt(a));
+}
+/** Nearest stations to an arbitrary point (MDAPI has no native lat/lon search). */
+export async function findNearestStations(lat, lon, type, limit, maxDistanceKm) {
+    const { stations } = await listStations(type, "english");
+    const ranked = stations
+        .filter((s) => typeof s.lat === "number" && typeof s.lng === "number")
+        .map((s) => {
+        const distance_km = haversineKm(lat, lon, s.lat, s.lng);
+        return { ...s, distance_km, distance_mi: distance_km * 0.621371 };
+    })
+        .filter((s) => maxDistanceKm === undefined || s.distance_km <= maxDistanceKm)
+        .sort((a, b) => a.distance_km - b.distance_km);
+    return ranked.slice(0, limit);
+}
+/** Single-station overview, optionally expanding sub-resources inline. */
+export async function getStationInfo(stationId, expand, units) {
+    const key = `station:${stationId}:${units}:${expand?.slice().sort().join(",") ?? ""}`;
+    return cache.getOrLoad(key, CACHE_TTL.stationResource, () => fetchMetadataApi(`/stations/${encodeURIComponent(stationId)}.json`, {
+        units,
+        expand: expand?.length ? expand.join(",") : undefined,
+    }));
+}
+/** Generic station sub-resource fetch (datums, harcon, tidepredoffsets, ...). */
+export async function getStationResource(stationId, resource, params = {}) {
+    const key = `resource:${stationId}:${resource}:${JSON.stringify(params)}`;
+    return cache.getOrLoad(key, CACHE_TTL.stationResource, () => fetchMetadataApi(`/stations/${encodeURIComponent(stationId)}/${resource}.json`, params));
+}
+/**
+ * Defensive array extraction: MDAPI's real key names differ from its docs
+ * (observed live: `datums`, `HarmonicConstituents`, `sensors`, `bins`,
+ * `notices`, `products` — docs claim `datumList`, `harconList`, ...).
+ */
+export function extractList(payload, ...candidateKeys) {
+    for (const key of candidateKeys) {
+        const value = payload[key];
+        if (Array.isArray(value))
+            return value;
+    }
+    return [];
+}

package/dist/services/moon-phase-service.d.ts

@@ -1,5 +1,5 @@
-import { MoonPhaseParams, MoonPhasesRangeParams, NextMoonPhaseParams } from '../interfaces/moon.js';
-import { MoonPhaseInfo } from '../types/moon.js';
+import { MoonPhaseParams, MoonPhasesRangeParams, NextMoonPhaseParams } from "../interfaces/moon.js";
+import { MoonPhaseInfo } from "../types/moon.js";
 /**
  * Service for moon phase calculations
  */

package/dist/services/moon-phase-service.js

@@ -1,5 +1,5 @@
-import SunCalc from 'suncalc';
-import { MoonPhaseName } from '../types/moon.js';
+import SunCalc from "suncalc";
+import { MoonPhaseName } from "../types/moon.js";
 /**
  * Service for moon phase calculations
  */
@@ -27,14 +27,14 @@ export class MoonPhaseService {
         // Calculate apparent diameter (in degrees)
         const diameter = 0.5181 * (384400 / positionData.distance);
         return {
-            date: date.toISOString().split('T')[0],
+            date: date.toISOString().split("T")[0],
             phase: illuminationData.phase,
             phaseName,
             illumination: illuminationData.fraction,
             age,
             distance: positionData.distance,
             diameter,
-            isWaxing
+            isWaxing,
         };
     }
     /**
@@ -46,18 +46,18 @@ export class MoonPhaseService {
         const startDate = new Date(params.start_date);
         const endDate = new Date(params.end_date);
         if (isNaN(startDate.getTime()) || isNaN(endDate.getTime())) {
-            throw new Error('Invalid date format. Please use YYYY-MM-DD format.');
+            throw new Error("Invalid date format. Please use YYYY-MM-DD format.");
         }
         if (startDate > endDate) {
-            throw new Error('Start date must be before end date.');
+            throw new Error("Start date must be before end date.");
         }
         const result = [];
         const currentDate = new Date(startDate);
         while (currentDate <= endDate) {
             result.push(this.getMoonPhase({
-                date: currentDate.toISOString().split('T')[0],
+                date: currentDate.toISOString().split("T")[0],
                 latitude: params.latitude,
-                longitude: params.longitude
+                longitude: params.longitude,
             }));
             // Move to next day
             currentDate.setDate(currentDate.getDate() + 1);
@@ -78,34 +78,32 @@ export class MoonPhaseService {
             [MoonPhaseName.NEW_MOON]: 0,
             [MoonPhaseName.FIRST_QUARTER]: 0.25,
             [MoonPhaseName.FULL_MOON]: 0.5,
-            [MoonPhaseName.LAST_QUARTER]: 0.75
+            [MoonPhaseName.LAST_QUARTER]: 0.75,
         };
         const targetPhaseValue = phaseValues[targetPhase];
         const results = [];
         let currentDate = new Date(startDate);
-        // Find the next occurrences
+        // Signed circular offset of a phase from the target, in [-0.5, 0.5).
+        // The lunar phase is cyclic (0 and 1 are both new moon), so plain
+        // |phase - target| breaks at the wraparound.
+        const signedDelta = (phase) => ((phase - targetPhaseValue + 1.5) % 1) - 0.5;
+        // The phase advances ~0.034/day, so the target is hit on the day where
+        // the signed offset crosses from negative to non-negative.
         while (results.length < count) {
-            // Check every day (could be optimized with better algorithms)
-            const illuminationData = SunCalc.getMoonIllumination(currentDate);
             const prevDate = new Date(currentDate);
             prevDate.setDate(prevDate.getDate() - 1);
-            const prevIlluminationData = SunCalc.getMoonIllumination(prevDate);
-            // Check if we've passed the target phase between yesterday and today
-            const prevDiff = Math.abs(prevIlluminationData.phase - targetPhaseValue);
-            const currentDiff = Math.abs(illuminationData.phase - targetPhaseValue);
-            // If we're getting closer to the target phase and then further away, we've passed it
-            // Or if we're very close to the target phase (within 0.01)
-            if ((prevDiff > currentDiff && currentDiff < 0.01) || currentDiff < 0.005) {
+            const prev = signedDelta(SunCalc.getMoonIllumination(prevDate).phase);
+            const curr = signedDelta(SunCalc.getMoonIllumination(currentDate).phase);
+            if (prev < 0 && curr >= 0) {
                 results.push({
-                    date: currentDate.toISOString().split('T')[0],
-                    phase: targetPhase
+                    date: currentDate.toISOString().split("T")[0],
+                    phase: targetPhase,
                 });
             }
-            // Move to next day
             currentDate.setDate(currentDate.getDate() + 1);
-            // Safety check to prevent infinite loops
-            if (results.length === 0 && currentDate.getTime() - startDate.getTime() > 366 * 24 * 60 * 60 * 1000) {
-                throw new Error('Could not find the specified moon phase within a year.');
+            if (currentDate.getTime() - startDate.getTime() >
+                (count + 1) * 31 * 24 * 60 * 60 * 1000) {
+                throw new Error("Could not find the specified moon phase within the expected window.");
             }
         }
         return results;

package/dist/services/sun-service.d.ts

@@ -1,5 +1,5 @@
-import { SunTimesParams, SunTimesRangeParams, SunPositionParams, NextSunEventParams } from '../interfaces/sun.js';
-import { SunTimesInfo, SunPositionInfo } from '../types/sun.js';
+import { SunTimesParams, SunTimesRangeParams, SunPositionParams, NextSunEventParams } from "../interfaces/sun.js";
+import { SunTimesInfo, SunPositionInfo } from "../types/sun.js";
 /**
  * Service for sun calculations
  */