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

package/dist/services/sun-service.js

@@ -1,4 +1,4 @@
-import SunCalc from 'suncalc';
+import SunCalc from "suncalc";
 /**
  * Service for sun calculations
  */
@@ -19,7 +19,9 @@ export class SunService {
                 return null;
             if (params.timezone) {
                 try {
-                    return time.toLocaleTimeString('en-US', { timeZone: params.timezone });
+                    return time.toLocaleTimeString("en-US", {
+                        timeZone: params.timezone,
+                    });
                 }
                 catch (error) {
                     // If timezone is invalid, fall back to ISO string
@@ -32,11 +34,14 @@ export class SunService {
         const sunrise = sunTimes.sunrise;
         const sunset = sunTimes.sunset;
         let dayLength = 0;
-        if (sunrise && sunset && !isNaN(sunrise.getTime()) && !isNaN(sunset.getTime())) {
+        if (sunrise &&
+            sunset &&
+            !isNaN(sunrise.getTime()) &&
+            !isNaN(sunset.getTime())) {
             dayLength = (sunset.getTime() - sunrise.getTime()) / (60 * 1000);
         }
         return {
-            date: date.toISOString().split('T')[0],
+            date: date.toISOString().split("T")[0],
             sunrise: formatTime(sunTimes.sunrise),
             sunset: formatTime(sunTimes.sunset),
             solarNoon: formatTime(sunTimes.solarNoon),
@@ -48,9 +53,11 @@ export class SunService {
             goldenHourEnd: formatTime(sunTimes.goldenHourEnd),
             nauticalDawn: formatTime(sunTimes.nauticalDawn),
             nauticalDusk: formatTime(sunTimes.nauticalDusk),
-            astronomicalDawn: formatTime(sunTimes.astronomicalDawn),
-            astronomicalDusk: formatTime(sunTimes.astronomicalDusk),
-            dayLength
+            // suncalc has no astronomicalDawn/Dusk keys: astronomical dawn is
+            // nightEnd and astronomical dusk is night (start of astronomical night)
+            astronomicalDawn: formatTime(sunTimes.nightEnd),
+            astronomicalDusk: formatTime(sunTimes.night),
+            dayLength,
         };
     }
     /**
@@ -62,19 +69,19 @@ export class SunService {
         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.getSunTimes({
-                date: currentDate.toISOString().split('T')[0],
+                date: currentDate.toISOString().split("T")[0],
                 latitude: params.latitude,
                 longitude: params.longitude,
-                timezone: params.timezone
+                timezone: params.timezone,
             }));
             // Move to next day
             currentDate.setDate(currentDate.getDate() + 1);
@@ -92,12 +99,12 @@ export class SunService {
         const { latitude, longitude } = params;
         // Set the time if provided
         if (time) {
-            const [hours, minutes, seconds] = time.split(':').map(Number);
+            const [hours, minutes, seconds] = time.split(":").map(Number);
             if (!isNaN(hours) && !isNaN(minutes) && (!seconds || !isNaN(seconds))) {
                 date.setHours(hours, minutes, seconds || 0, 0);
             }
             else {
-                throw new Error('Invalid time format. Please use HH:MM:SS format.');
+                throw new Error("Invalid time format. Please use HH:MM:SS format.");
             }
         }
         // Get sun position data
@@ -106,12 +113,12 @@ export class SunService {
         // Note: These are approximate calculations and may not be precise
         const equatorialCoords = this.calculateEquatorialCoordinates(date, position.azimuth, position.altitude, latitude, longitude);
         return {
-            date: date.toISOString().split('T')[0],
-            time: date.toISOString().split('T')[1].split('.')[0],
+            date: date.toISOString().split("T")[0],
+            time: date.toISOString().split("T")[1].split(".")[0],
             azimuth: position.azimuth * (180 / Math.PI),
             altitude: position.altitude * (180 / Math.PI),
             declination: equatorialCoords.declination,
-            rightAscension: equatorialCoords.rightAscension
+            rightAscension: equatorialCoords.rightAscension,
         };
     }
     /**
@@ -123,27 +130,36 @@ export class SunService {
         const startDate = params.date ? new Date(params.date) : new Date();
         const count = params.count !== undefined ? params.count : 1;
         const { latitude, longitude } = params;
-        const timezone = params.timezone !== undefined ? params.timezone : 'UTC';
+        const timezone = params.timezone !== undefined ? params.timezone : "UTC";
         const results = [];
         let currentDate = new Date(startDate);
+        // Map our event names to suncalc's keys where they differ.
+        const suncalcKeyOverrides = {
+            goldenHourStart: "goldenHour",
+            astronomicalDawn: "nightEnd",
+            astronomicalDusk: "night",
+        };
+        const eventKey = suncalcKeyOverrides[params.event] ?? params.event;
         // Find the next occurrences
         while (results.length < count) {
             const sunTimes = SunCalc.getTimes(currentDate, latitude, longitude);
-            const eventTime = sunTimes[params.event];
+            const eventTime = sunTimes[eventKey];
             if (eventTime && !isNaN(eventTime.getTime()) && eventTime > startDate) {
                 let formattedTime;
                 try {
-                    formattedTime = eventTime.toLocaleTimeString('en-US', { timeZone: timezone });
+                    formattedTime = eventTime.toLocaleTimeString("en-US", {
+                        timeZone: timezone,
+                    });
                 }
                 catch (error) {
                     // If timezone is invalid, fall back to ISO string
                     console.warn(`Invalid timezone: ${timezone}. Using UTC.`);
-                    formattedTime = eventTime.toISOString().split('T')[1].split('.')[0];
+                    formattedTime = eventTime.toISOString().split("T")[1].split(".")[0];
                 }
                 results.push({
-                    date: eventTime.toISOString().split('T')[0],
+                    date: eventTime.toISOString().split("T")[0],
                     time: formattedTime,
-                    event: params.event
+                    event: params.event,
                 });
                 // Move to next day to find the next occurrence
                 currentDate.setDate(currentDate.getDate() + 1);
@@ -153,8 +169,9 @@ export class SunService {
                 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 sun event within a year.');
+            if (results.length === 0 &&
+                currentDate.getTime() - startDate.getTime() > 366 * 24 * 60 * 60 * 1000) {
+                throw new Error("Could not find the specified sun event within a year.");
             }
         }
         return results;
@@ -174,12 +191,14 @@ export class SunService {
         // Convert degrees to radians
         const lat = latitude * (Math.PI / 180);
         // Calculate hour angle and declination
-        const sinDec = Math.sin(altitude) * Math.sin(lat) + Math.cos(altitude) * Math.cos(lat) * Math.cos(azimuth);
+        const sinDec = Math.sin(altitude) * Math.sin(lat) +
+            Math.cos(altitude) * Math.cos(lat) * Math.cos(azimuth);
         const declination = Math.asin(sinDec) * (180 / Math.PI);
-        const cosH = (Math.sin(altitude) - Math.sin(lat) * sinDec) / (Math.cos(lat) * Math.cos(declination * (Math.PI / 180)));
+        const cosH = (Math.sin(altitude) - Math.sin(lat) * sinDec) /
+            (Math.cos(lat) * Math.cos(declination * (Math.PI / 180)));
         const hourAngle = Math.acos(Math.max(-1, Math.min(1, cosH)));
         // Adjust hour angle based on azimuth
-        const adjustedHourAngle = (azimuth > 0 && azimuth < Math.PI) ? (2 * Math.PI - hourAngle) : hourAngle;
+        const adjustedHourAngle = azimuth > 0 && azimuth < Math.PI ? 2 * Math.PI - hourAngle : hourAngle;
         // Calculate right ascension
         const localSiderealTime = this.calculateLocalSiderealTime(date, longitude);
         let rightAscension = (localSiderealTime - adjustedHourAngle) * (12 / Math.PI);
@@ -221,14 +240,17 @@ export class SunService {
         const m = date.getMonth() + 1;
         const d = date.getDate();
         // Calculate Julian day
-        const jd = 367 * y - Math.floor(7 * (y + Math.floor((m + 9) / 12)) / 4) -
-            Math.floor(3 * (Math.floor((y + (m - 9) / 7) / 100) + 1) / 4) +
-            Math.floor(275 * m / 9) + d + 1721028.5;
+        const jd = 367 * y -
+            Math.floor((7 * (y + Math.floor((m + 9) / 12))) / 4) -
+            Math.floor((3 * (Math.floor((y + (m - 9) / 7) / 100) + 1)) / 4) +
+            Math.floor((275 * m) / 9) +
+            d +
+            1721028.5;
         // Add time of day
         const hours = date.getUTCHours();
         const minutes = date.getUTCMinutes();
         const seconds = date.getUTCSeconds();
         const milliseconds = date.getUTCMilliseconds();
-        return jd + (hours + minutes / 60 + seconds / 3600 + milliseconds / 3600000) / 24;
+        return (jd + (hours + minutes / 60 + seconds / 3600 + milliseconds / 3600000) / 24);
     }
 }

package/dist/tools/astronomy.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Sun and moon calculation tools (computed locally with suncalc — no network).
+ * Useful companions to tide data for boating, fishing, and photography:
+ * spring tides follow new/full moons, and slack/golden-hour timing matters.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAstronomyTools(server: McpServer): void;

package/dist/tools/astronomy.js

@@ -0,0 +1,270 @@
+/**
+ * Sun and moon calculation tools (computed locally with suncalc — no network).
+ * Useful companions to tide data for boating, fishing, and photography:
+ * spring tides follow new/full moons, and slack/golden-hour timing matters.
+ */
+import { z } from "zod";
+import { MoonPhaseService } from "../services/moon-phase-service.js";
+import { SunService } from "../services/sun-service.js";
+import { MoonPhaseName } from "../types/moon.js";
+import { SunEventType } from "../types/sun.js";
+import { LatitudeSchema, LOCAL_COMPUTE_ANNOTATIONS, LongitudeSchema, ResponseFormatSchema, } from "../schemas/common.js";
+import { markdownTable, respond, respondError } from "../format/respond.js";
+const IsoDateSchema = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, "Use YYYY-MM-DD format.")
+    .describe("Date in YYYY-MM-DD format. Defaults to today.");
+const TimezoneSchema = z
+    .string()
+    .optional()
+    .describe('IANA timezone for output times (e.g. "America/New_York"). Defaults to UTC ISO timestamps.');
+export function registerAstronomyTools(server) {
+    const moonService = new MoonPhaseService();
+    const sunService = new SunService();
+    server.registerTool("astro_get_moon_phase", {
+        title: "Get Moon Phase",
+        description: `Get the moon phase for a date (or each day of a date range if end_date is given): phase name (New Moon, Waxing Crescent, ...), illuminated fraction, age in days within the 29.53-day cycle, distance (km), apparent diameter (degrees), and waxing/waning.
+
+Tide context: spring tides (largest range) occur just after new and full moons; neap tides after quarter moons. Computed locally — no NOAA data involved.`,
+        inputSchema: {
+            date: IsoDateSchema.optional(),
+            end_date: IsoDateSchema.optional().describe("Optional range end (YYYY-MM-DD): returns one entry per day from date through end_date."),
+            latitude: LatitudeSchema.optional().describe("Optional latitude for distance/diameter precision."),
+            longitude: LongitudeSchema.optional(),
+            response_format: ResponseFormatSchema,
+        },
+        annotations: LOCAL_COMPUTE_ANNOTATIONS,
+    }, async (params) => {
+        try {
+            const phases = params.end_date
+                ? moonService.getMoonPhasesRange({
+                    start_date: params.date ?? new Date().toISOString().split("T")[0],
+                    end_date: params.end_date,
+                    latitude: params.latitude,
+                    longitude: params.longitude,
+                })
+                : [
+                    moonService.getMoonPhase({
+                        date: params.date,
+                        latitude: params.latitude,
+                        longitude: params.longitude,
+                    }),
+                ];
+            const structured = { count: phases.length, phases };
+            const markdown = [
+                "# Moon Phase",
+                "",
+                markdownTable([
+                    "Date",
+                    "Phase",
+                    "Illumination",
+                    "Age (days)",
+                    "Distance (km)",
+                    "Waxing?",
+                ], phases.map((p) => [
+                    p.date,
+                    p.phaseName,
+                    `${(p.illumination * 100).toFixed(1)}%`,
+                    p.age.toFixed(1),
+                    Math.round(p.distance).toLocaleString(),
+                    p.isWaxing ? "yes" : "no",
+                ])),
+                "",
+                "_Spring tides (largest range) follow new/full moons; neap tides follow quarters._",
+            ].join("\n");
+            return respond(params.response_format, structured, markdown);
+        }
+        catch (error) {
+            return respondError(error);
+        }
+    });
+    server.registerTool("astro_get_next_moon_phase", {
+        title: "Get Next Moon Phase Occurrence",
+        description: `Find the date(s) of the next occurrence(s) of a principal moon phase (New Moon, First Quarter, Full Moon, Last Quarter) from a starting date.
+
+Use for: "when is the next full moon?", planning around spring tides (which follow new/full moons by 1–2 days).`,
+        inputSchema: {
+            phase: z
+                .enum([
+                MoonPhaseName.NEW_MOON,
+                MoonPhaseName.FIRST_QUARTER,
+                MoonPhaseName.FULL_MOON,
+                MoonPhaseName.LAST_QUARTER,
+            ])
+                .describe("Which principal phase to find."),
+            date: IsoDateSchema.optional().describe("Search start date (YYYY-MM-DD). Defaults to today."),
+            count: z
+                .number()
+                .int()
+                .min(1)
+                .max(24)
+                .default(1)
+                .describe("How many occurrences to return."),
+            response_format: ResponseFormatSchema,
+        },
+        annotations: LOCAL_COMPUTE_ANNOTATIONS,
+    }, async (params) => {
+        try {
+            const occurrences = moonService.getNextMoonPhase({
+                phase: params.phase,
+                date: params.date,
+                count: params.count,
+            });
+            const structured = { phase: params.phase, occurrences };
+            const markdown = [
+                `# Next ${params.phase}`,
+                "",
+                ...occurrences.map((o, i) => `${i + 1}. ${o.date}`),
+            ].join("\n");
+            return respond(params.response_format, structured, markdown);
+        }
+        catch (error) {
+            return respondError(error);
+        }
+    });
+    server.registerTool("astro_get_sun_times", {
+        title: "Get Sun Times",
+        description: `Get sunrise, sunset, solar noon, dawn/dusk (civil), nautical dawn/dusk, astronomical dawn/dusk, golden hour, and day length for a location and date (or each day of a range if end_date is given).
+
+Times are ISO UTC unless an IANA timezone is provided. At high latitudes some events may be null (e.g. no astronomical night in summer). Computed locally.`,
+        inputSchema: {
+            latitude: LatitudeSchema,
+            longitude: LongitudeSchema,
+            date: IsoDateSchema.optional(),
+            end_date: IsoDateSchema.optional().describe("Optional range end: one entry per day."),
+            timezone: TimezoneSchema,
+            response_format: ResponseFormatSchema,
+        },
+        annotations: LOCAL_COMPUTE_ANNOTATIONS,
+    }, async (params) => {
+        try {
+            const times = params.end_date
+                ? sunService.getSunTimesRange({
+                    start_date: params.date ?? new Date().toISOString().split("T")[0],
+                    end_date: params.end_date,
+                    latitude: params.latitude,
+                    longitude: params.longitude,
+                    timezone: params.timezone,
+                })
+                : [
+                    sunService.getSunTimes({
+                        date: params.date,
+                        latitude: params.latitude,
+                        longitude: params.longitude,
+                        timezone: params.timezone,
+                    }),
+                ];
+            const structured = { count: times.length, sun_times: times };
+            const markdown = [
+                `# Sun Times (${params.latitude}, ${params.longitude})${params.timezone ? ` — ${params.timezone}` : " — UTC"}`,
+                "",
+                markdownTable([
+                    "Date",
+                    "Dawn",
+                    "Sunrise",
+                    "Solar noon",
+                    "Sunset",
+                    "Dusk",
+                    "Day length",
+                ], times.map((t) => [
+                    t.date,
+                    t.dawn,
+                    t.sunrise,
+                    t.solarNoon,
+                    t.sunset,
+                    t.dusk,
+                    `${Math.floor(t.dayLength / 60)}h ${Math.round(t.dayLength % 60)}m`,
+                ])),
+                "",
+                "_Golden hour, nautical and astronomical twilight times are in the JSON payload._",
+            ].join("\n");
+            return respond(params.response_format, structured, markdown);
+        }
+        catch (error) {
+            return respondError(error);
+        }
+    });
+    server.registerTool("astro_get_sun_position", {
+        title: "Get Sun Position",
+        description: `Get the sun's position for a date, time, and location: azimuth (degrees clockwise from north as rendered here), altitude above the horizon (degrees), plus approximate declination and right ascension.
+
+Use for: shadow/lighting analysis, solar exposure. Computed locally with suncalc; declination/RA are approximate.`,
+        inputSchema: {
+            latitude: LatitudeSchema,
+            longitude: LongitudeSchema,
+            date: IsoDateSchema.optional(),
+            time: z
+                .string()
+                .regex(/^\d{2}:\d{2}(:\d{2})?$/, "Use HH:MM or HH:MM:SS.")
+                .optional()
+                .describe("Time of day (HH:MM[:SS], interpreted in the local runtime timezone). Defaults to now."),
+            response_format: ResponseFormatSchema,
+        },
+        annotations: LOCAL_COMPUTE_ANNOTATIONS,
+    }, async (params) => {
+        try {
+            const position = sunService.getSunPosition({
+                date: params.date,
+                time: params.time,
+                latitude: params.latitude,
+                longitude: params.longitude,
+            });
+            const structured = { position };
+            const markdown = [
+                `# Sun Position (${params.latitude}, ${params.longitude}) at ${position.date} ${position.time} UTC`,
+                "",
+                `- **Azimuth**: ${position.azimuth.toFixed(2)}°`,
+                `- **Altitude**: ${position.altitude.toFixed(2)}° ${position.altitude > 0 ? "(above horizon)" : "(below horizon)"}`,
+                `- **Declination**: ${position.declination.toFixed(2)}° (approx.)`,
+                `- **Right ascension**: ${position.rightAscension.toFixed(2)}h (approx.)`,
+            ].join("\n");
+            return respond(params.response_format, structured, markdown);
+        }
+        catch (error) {
+            return respondError(error);
+        }
+    });
+    server.registerTool("astro_get_next_sun_event", {
+        title: "Get Next Sun Event",
+        description: `Find the next occurrence(s) of a sun event (sunrise, sunset, dawn, dusk, solarNoon, night, nightEnd, goldenHourStart, goldenHourEnd, nauticalDawn, nauticalDusk, astronomicalDawn, astronomicalDusk) at a location from a starting date.
+
+Use for: "when is sunset today?", planning golden-hour photography or dawn fishing around tide windows.`,
+        inputSchema: {
+            event: z.nativeEnum(SunEventType).describe("Sun event to find."),
+            latitude: LatitudeSchema,
+            longitude: LongitudeSchema,
+            date: IsoDateSchema.optional().describe("Search start date. Defaults to today."),
+            count: z
+                .number()
+                .int()
+                .min(1)
+                .max(30)
+                .default(1)
+                .describe("How many occurrences to return."),
+            timezone: TimezoneSchema,
+            response_format: ResponseFormatSchema,
+        },
+        annotations: LOCAL_COMPUTE_ANNOTATIONS,
+    }, async (params) => {
+        try {
+            const occurrences = sunService.getNextSunEvent({
+                event: params.event,
+                latitude: params.latitude,
+                longitude: params.longitude,
+                date: params.date,
+                count: params.count,
+                timezone: params.timezone,
+            });
+            const structured = { event: params.event, occurrences };
+            const markdown = [
+                `# Next ${params.event} at (${params.latitude}, ${params.longitude})`,
+                "",
+                ...occurrences.map((o, i) => `${i + 1}. ${o.date} at ${o.time}${params.timezone ? ` (${params.timezone})` : ""}`),
+            ].join("\n");
+            return respond(params.response_format, structured, markdown);
+        }
+        catch (error) {
+            return respondError(error);
+        }
+    });
+}

package/dist/tools/currents.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Observed and predicted current tools.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCurrentTools(server: McpServer): void;

package/dist/tools/currents.js

@@ -0,0 +1,168 @@
+/**
+ * Observed and predicted current tools.
+ */
+import { z } from "zod";
+import { getCurrents, getCurrentPredictions } from "../services/data-api.js";
+import { dateFields, READ_ONLY_ANNOTATIONS, ResponseFormatSchema, StationIdSchema, TimeZoneSchema, UnitsSchema, } from "../schemas/common.js";
+import { respond, respondError } from "../format/respond.js";
+import { seriesMarkdown, timeZoneLabel } from "../format/series.js";
+import { unitLabel } from "../format/units.js";
+const BinSchema = z
+    .number()
+    .int()
+    .min(0)
+    .describe('Depth bin number (current meters measure at multiple depths). Find valid bins with noaa_get_station_info (expand ["bins"]). bin=0 returns ALL bins but caps the request at 7 days. Omit at single-bin stations.');
+export function registerCurrentTools(server) {
+    server.registerTool("noaa_get_currents", {
+        title: "Get Observed Currents",
+        description: `Get observed current speed and direction from a NOAA current meter station.
+
+Current stations use alphanumeric IDs (e.g. "cb0102" Chesapeake, "bh0101" Boston Harbor) — NOT the 7-digit water-level station IDs. Find them with noaa_search_stations (type "currents") or noaa_find_nearest_stations.
+
+UNITS WARNING: english = knots, but metric = cm/s (centimeters/second, not m/s).
+
+Returns per record: t (time), s (speed), d (direction, degrees true), b (bin number). Max 7 days per request. Set expand_detailed=true to include per-beam echo intensity and correlation diagnostics.`,
+        inputSchema: {
+            station: StationIdSchema,
+            bin: BinSchema.optional(),
+            expand_detailed: z
+                .boolean()
+                .default(false)
+                .describe("Include ADCP beam diagnostics (echo1-4, corr1-4) per record."),
+            units: UnitsSchema,
+            time_zone: TimeZoneSchema,
+            ...dateFields,
+            response_format: ResponseFormatSchema,
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        try {
+            const response = await getCurrents(params);
+            const data = response.data ?? [];
+            const speedLabel = unitLabel("currents", params.units);
+            const structured = {
+                station: params.station,
+                product: "currents",
+                bin: params.bin,
+                units: params.units,
+                speed_units: speedLabel,
+                direction_units: "degrees true",
+                time_zone: params.time_zone,
+                count: data.length,
+                data,
+            };
+            const markdown = seriesMarkdown({
+                title: "Observed Currents",
+                station: params.station,
+                unitsLabel: `speed in ${speedLabel}, direction in degrees true`,
+                timeZone: timeZoneLabel(params.time_zone),
+            }, ["Time", `Speed (${speedLabel})`, "Direction (°T)", "Bin"], data.map((d) => [d.t, d.s, d.d, d.b]));
+            return respond(params.response_format, structured, markdown);
+        }
+        catch (error) {
+            return respondError(error);
+        }
+    });
+    server.registerTool("noaa_get_current_predictions", {
+        title: "Get Current Predictions",
+        description: `Get predicted tidal currents for a NOAA current prediction station.
+
+interval="max_slack" (recommended for navigation) returns the tidal-current events — maximum flood, maximum ebb, and slack water times — up to 1 year per request. Other intervals (h, 1, 6, 10, 30, 60 minutes) return a velocity time series — up to 31 days.
+
+UNITS WARNING: english = knots; metric = cm/s.
+
+vel_type="speed_dir" returns Speed/Direction pairs; "default" returns velocities projected on the flood/ebb axis (Velocity_Major: positive = flood direction, negative = ebb) with meanFloodDir/meanEbbDir. Subordinate (type "S") prediction stations derive from a reference station — see noaa_get_prediction_offsets.`,
+        inputSchema: {
+            station: StationIdSchema,
+            bin: BinSchema.optional(),
+            interval: z
+                .enum(["max_slack", "h", "1", "6", "10", "30", "60"])
+                .default("max_slack")
+                .describe('"max_slack" = max flood/ebb + slack events (1-year max span); h/1/6/10/30/60 = time series (31-day max span).'),
+            vel_type: z
+                .enum(["default", "speed_dir"])
+                .default("default")
+                .describe('"default" = flood/ebb-axis velocity (Velocity_Major signed: + flood, - ebb); "speed_dir" = speed and compass direction.'),
+            units: UnitsSchema,
+            time_zone: TimeZoneSchema,
+            ...dateFields,
+            response_format: ResponseFormatSchema,
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        try {
+            const response = await getCurrentPredictions(params);
+            const raw = response.current_predictions;
+            const data = Array.isArray(raw) ? raw : (raw?.cp ?? []);
+            const speedLabel = unitLabel("currents", params.units);
+            const structured = {
+                station: params.station,
+                product: "currents_predictions",
+                interval: params.interval,
+                vel_type: params.vel_type,
+                bin: params.bin,
+                units: params.units,
+                speed_units: speedLabel,
+                time_zone: params.time_zone,
+                count: data.length,
+                predictions: data,
+            };
+            let headers;
+            let rows;
+            if (params.vel_type === "speed_dir") {
+                headers = [
+                    "Time",
+                    `Speed (${speedLabel})`,
+                    "Direction (°T)",
+                    "Depth",
+                    "Bin",
+                ];
+                rows = data.map((d) => [
+                    d.Time,
+                    d.Speed,
+                    d.Direction,
+                    d.Depth,
+                    d.Bin,
+                ]);
+            }
+            else {
+                headers = [
+                    "Time",
+                    `Velocity along flood/ebb axis (${speedLabel})`,
+                    "Type",
+                    "Depth",
+                    "Bin",
+                ];
+                rows = data.map((d) => {
+                    const velocity = Number(d.Velocity_Major);
+                    const type = d.Type ??
+                        (isNaN(velocity)
+                            ? ""
+                            : Math.abs(velocity) < 0.05
+                                ? "slack"
+                                : velocity > 0
+                                    ? "flood"
+                                    : "ebb");
+                    return [d.Time, d.Velocity_Major, String(type), d.Depth, d.Bin];
+                });
+            }
+            const markdown = seriesMarkdown({
+                title: params.interval === "max_slack"
+                    ? "Current Predictions — Max Flood/Ebb & Slack"
+                    : "Current Predictions",
+                station: params.station,
+                unitsLabel: `speed in ${speedLabel}`,
+                timeZone: timeZoneLabel(params.time_zone),
+                extra: params.vel_type === "default"
+                    ? [
+                        "_Velocity sign: positive = flood direction, negative = ebb direction._",
+                    ]
+                    : undefined,
+            }, headers, rows);
+            return respond(params.response_format, structured, markdown);
+        }
+        catch (error) {
+            return respondError(error);
+        }
+    });
+}

package/dist/tools/derived.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Derived Product API tools: sea level trends & rise projections, extreme
+ * water levels, top-ten/peak water levels, high tide flooding.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDerivedProductTools(server: McpServer): void;