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

package/dist/services/nws-api.js

@@ -0,0 +1,267 @@
+/**
+ * NWS Weather API (api.weather.gov) — wind and marine FORECASTS.
+ *
+ * This is a different NOAA service from CO-OPS with different shapes:
+ *  - /points/{lat},{lon} resolves a coordinate to a forecast office gridpoint
+ *    (gridX/gridY assignments drift over re-gridding, so cache with a TTL and
+ *    never hardcode them).
+ *  - /gridpoints/{office}/{x},{y} returns NUMERIC time series (the friendlier
+ *    /forecast/hourly endpoint returns display strings like "10 to 15 mph"
+ *    and is deliberately not used). Each series value carries a validTime of
+ *    the form "2026-07-05T18:00:00+00:00/PT3H" — an ISO instant plus an ISO
+ *    duration the value holds for — which we expand into hourly samples.
+ *  - Marine zone TEXT forecasts are NOT served by /zones/forecast/{id}/forecast
+ *    (that 404s with "Marine Forecast Not Supported"); the working path is the
+ *    Products API: latest CWF product for the issuing office, then extracting
+ *    the segment for the zone from the multi-zone bulletin.
+ */
+import { cache } from "../client/cache.js";
+import { fetchNwsApi } from "../client/http.js";
+import { NoaaApiError } from "../client/http.js";
+import { CACHE_TTL } from "../constants.js";
+function pointKey(latitude, longitude) {
+    return `${latitude.toFixed(4)},${longitude.toFixed(4)}`;
+}
+export async function resolvePoint(latitude, longitude) {
+    const key = pointKey(latitude, longitude);
+    return cache.getOrLoad(`nws:point:${key}`, CACHE_TTL.nwsPoint, async () => {
+        const data = await fetchNwsApi(`/points/${key}`);
+        const p = data.properties;
+        if (!p?.gridId || p.gridX === undefined || p.gridY === undefined) {
+            throw new NoaaApiError("NWS API error: the point resolved to no forecast gridpoint. NWS forecasts cover the US and its territories only.");
+        }
+        const loc = p.relativeLocation?.properties;
+        return {
+            gridId: p.gridId,
+            gridX: p.gridX,
+            gridY: p.gridY,
+            cwa: p.cwa ?? p.gridId,
+            timeZone: p.timeZone ?? "UTC",
+            pointType: p.type,
+            place: loc?.city && loc?.state ? `${loc.city}, ${loc.state}` : undefined,
+        };
+    });
+}
+const HOUR_MS = 3_600_000;
+/** Parse an ISO 8601 duration like "PT3H", "P1D", "PT1H30M" to milliseconds. */
+export function parseIsoDurationMs(duration) {
+    const match = duration.match(/^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/);
+    if (!match)
+        return HOUR_MS;
+    const [, days, hours, minutes, seconds] = match;
+    return ((Number(days ?? 0) * 24 + Number(hours ?? 0)) * HOUR_MS +
+        Number(minutes ?? 0) * 60_000 +
+        Number(seconds ?? 0) * 1_000);
+}
+/**
+ * Expand a gridpoint series (start-instant + hold-duration values) into a map
+ * of epoch-ms-per-hour → value.
+ */
+export function expandGridSeries(series) {
+    const out = new Map();
+    for (const entry of series?.values ?? []) {
+        if (entry.value === null || entry.value === undefined)
+            continue;
+        const [startStr, durationStr] = entry.validTime.split("/");
+        const start = Date.parse(startStr);
+        if (Number.isNaN(start))
+            continue;
+        const startHour = Math.floor(start / HOUR_MS) * HOUR_MS;
+        const hours = Math.max(1, Math.round(parseIsoDurationMs(durationStr ?? "PT1H") / HOUR_MS));
+        for (let i = 0; i < hours; i++) {
+            const key = startHour + i * HOUR_MS;
+            if (!out.has(key))
+                out.set(key, entry.value);
+        }
+    }
+    return out;
+}
+/** Convert a gridpoint speed value to knots based on its declared unit. */
+export function speedToKnots(value, uom) {
+    if (uom?.includes("km_h"))
+        return value / 1.852;
+    if (uom?.includes("m_s"))
+        return value * 1.9438444924;
+    if (uom?.includes("kn"))
+        return value;
+    if (uom?.includes("mi_h"))
+        return value * 0.8689762419;
+    // NWS gridpoint wind defaults to km/h; assume that when the unit is missing.
+    return value / 1.852;
+}
+export function knotsToMs(knots) {
+    return knots * 0.5144444444;
+}
+/** Convert a gridpoint length value to meters based on its declared unit. */
+export function lengthToMeters(value, uom) {
+    if (uom?.includes("ft"))
+        return value * 0.3048;
+    return value; // wmoUnit:m
+}
+export function metersToFeet(meters) {
+    return meters / 0.3048;
+}
+const COMPASS_POINTS = [
+    "N",
+    "NNE",
+    "NE",
+    "ENE",
+    "E",
+    "ESE",
+    "SE",
+    "SSE",
+    "S",
+    "SSW",
+    "SW",
+    "WSW",
+    "W",
+    "WNW",
+    "NW",
+    "NNW",
+];
+export function toCompass(degrees) {
+    const normalized = ((degrees % 360) + 360) % 360;
+    return COMPASS_POINTS[Math.round(normalized / 22.5) % 16];
+}
+/**
+ * Hourly numeric wind forecast (plus wave height when the grid carries it)
+ * for a coordinate, starting at the current hour.
+ */
+export async function getWindForecast(latitude, longitude, hours) {
+    const point = await resolvePoint(latitude, longitude);
+    const gridPath = `/gridpoints/${point.gridId}/${point.gridX},${point.gridY}`;
+    const grid = await cache.getOrLoad(`nws:grid:${gridPath}`, CACHE_TTL.nwsForecast, () => fetchNwsApi(gridPath));
+    const p = grid.properties ?? {};
+    const speeds = expandGridSeries(p.windSpeed);
+    const gusts = expandGridSeries(p.windGust);
+    const directions = expandGridSeries(p.windDirection);
+    const waves = expandGridSeries(p.waveHeight);
+    const startHour = Math.floor(Date.now() / HOUR_MS) * HOUR_MS;
+    const samples = [];
+    for (let i = 0; i < hours; i++) {
+        const t = startHour + i * HOUR_MS;
+        const speed = speeds.get(t);
+        const gust = gusts.get(t);
+        const direction = directions.get(t);
+        const wave = waves.get(t);
+        if (speed === undefined &&
+            gust === undefined &&
+            direction === undefined &&
+            wave === undefined) {
+            continue; // past the end of the forecast grid
+        }
+        samples.push({
+            time: new Date(t).toISOString(),
+            speed_knots: speed === undefined
+                ? null
+                : round1(speedToKnots(speed, p.windSpeed?.uom)),
+            gust_knots: gust === undefined ? null : round1(speedToKnots(gust, p.windGust?.uom)),
+            direction_deg: direction === undefined ? null : Math.round(direction),
+            compass: direction === undefined ? null : toCompass(direction),
+            wave_height_m: wave === undefined
+                ? null
+                : round1(lengthToMeters(wave, p.waveHeight?.uom)),
+        });
+    }
+    return { point, updated: p.updateTime, samples };
+}
+function round1(value) {
+    return Math.round(value * 10) / 10;
+}
+/** Resolve the NWS coastal marine zone covering a coordinate (e.g. GMZ350). */
+export async function findCoastalZone(latitude, longitude) {
+    const key = pointKey(latitude, longitude);
+    return cache.getOrLoad(`nws:zone:${key}`, CACHE_TTL.nwsPoint, async () => {
+        const data = await fetchNwsApi("/zones", {
+            type: "coastal",
+            point: key,
+            include_geometry: false,
+        });
+        const zone = data.features?.[0]?.properties;
+        if (!zone?.id) {
+            throw new NoaaApiError("NWS API error: no coastal marine zone covers this point. Coastal Waters Forecasts exist only for US coastal waters (roughly out to 20-60 NM); for a land point, use nws_get_wind_forecast instead.");
+        }
+        return {
+            id: zone.id,
+            name: zone.name ?? zone.id,
+            cwa: zone.cwa?.[0] ?? "",
+        };
+    });
+}
+/**
+ * True when a CWF bulletin segment's UGC header covers the given zone.
+ * Headers look like "GMZ330-335-350-061015-" (list) or "GMZ350>355-061015-"
+ * (range), always ending in a 6-digit expiry.
+ */
+export function segmentCoversZone(segment, zoneId) {
+    const prefix = zoneId.slice(0, 3);
+    const target = Number(zoneId.slice(3));
+    const ugcLines = segment.match(/^[A-Z]{2}Z[0-9>-]+/gm) ?? [];
+    for (const line of ugcLines) {
+        if (!line.startsWith(prefix))
+            continue;
+        const body = line.slice(3).replace(/-\d{6}-?$/, "");
+        for (const part of body.split("-")) {
+            if (!part)
+                continue;
+            if (part.includes(">")) {
+                const [lo, hi] = part.split(">").map(Number);
+                if (target >= lo && target <= hi)
+                    return true;
+            }
+            else if (Number(part) === target) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Extract the segment of a multi-zone CWF bulletin covering one zone.
+ * Bulletins are segmented by "$$" terminators; each segment opens with a UGC
+ * zone-list header. Returns undefined when no segment matches.
+ */
+export function extractZoneSegment(productText, zoneId) {
+    const segments = productText.split(/^\s*\$\$\s*$/m);
+    const match = segments.find((s) => segmentCoversZone(s, zoneId));
+    return match?.trim();
+}
+/**
+ * Extract the office-wide synopsis block, when the bulletin carries one.
+ * Offices vary the header casing (".SYNOPSIS...", ".Synopsis For ...").
+ */
+export function extractSynopsis(productText) {
+    const match = productText.match(/^\.synopsis[\s\S]*?(?=^\s*\$\$\s*$|^\.\w)/im);
+    return match?.[0]?.trim();
+}
+/**
+ * Latest Coastal Waters Forecast text for the marine zone covering a point.
+ * CWF products are keyed by issuing office (not zone) and cover every zone
+ * that office serves in one bulletin, so the zone's segment is extracted here.
+ */
+export async function getMarineTextForecast(latitude, longitude) {
+    const zone = await findCoastalZone(latitude, longitude);
+    if (!zone.cwa) {
+        throw new NoaaApiError(`NWS API error: marine zone ${zone.id} has no issuing office on record; cannot locate its Coastal Waters Forecast.`);
+    }
+    const result = await cache.getOrLoad(`nws:cwf:${zone.cwa}`, CACHE_TTL.nwsForecast, async () => {
+        const list = await fetchNwsApi(`/products/types/CWF/locations/${zone.cwa}`);
+        const latest = list["@graph"]?.[0];
+        if (!latest?.id) {
+            throw new NoaaApiError(`NWS API error: no recent Coastal Waters Forecast found for office ${zone.cwa}.`);
+        }
+        const product = await fetchNwsApi(`/products/${latest.id}`);
+        return {
+            productId: latest.id,
+            issuanceTime: product.issuanceTime ?? latest.issuanceTime,
+            text: product.productText ?? "",
+        };
+    });
+    return {
+        zone,
+        productId: result.productId,
+        issuanceTime: result.issuanceTime,
+        segment: extractZoneSegment(result.text, zone.id),
+        synopsis: extractSynopsis(result.text),
+    };
+}

package/dist/tools/astronomy.js

@@ -9,7 +9,7 @@ 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";
+import { markdownTable, respond, respondError, RawToolOutputSchema, } from "../format/respond.js";
 const IsoDateSchema = z
     .string()
     .regex(/^\d{4}-\d{2}-\d{2}$/, "Use YYYY-MM-DD format.")
@@ -34,6 +34,7 @@ Tide context: spring tides (largest range) occur just after new and full moons;
             response_format: ResponseFormatSchema,
         },
         annotations: LOCAL_COMPUTE_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const phases = params.end_date
@@ -103,6 +104,7 @@ Use for: "when is the next full moon?", planning around spring tides (which foll
             response_format: ResponseFormatSchema,
         },
         annotations: LOCAL_COMPUTE_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const occurrences = moonService.getNextMoonPhase({
@@ -136,6 +138,7 @@ Times are ISO UTC unless an IANA timezone is provided. At high latitudes some ev
             response_format: ResponseFormatSchema,
         },
         annotations: LOCAL_COMPUTE_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const times = params.end_date
@@ -201,6 +204,7 @@ Use for: shadow/lighting analysis, solar exposure. Computed locally with suncalc
             response_format: ResponseFormatSchema,
         },
         annotations: LOCAL_COMPUTE_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const position = sunService.getSunPosition({
@@ -245,6 +249,7 @@ Use for: "when is sunset today?", planning golden-hour photography or dawn fishi
             response_format: ResponseFormatSchema,
         },
         annotations: LOCAL_COMPUTE_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const occurrences = sunService.getNextSunEvent({

package/dist/tools/currents.js

@@ -4,7 +4,7 @@
 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 { respond, respondError, RawToolOutputSchema, } from "../format/respond.js";
 import { seriesMarkdown, timeZoneLabel } from "../format/series.js";
 import { unitLabel } from "../format/units.js";
 const BinSchema = z
@@ -35,6 +35,7 @@ Returns per record: t (time), s (speed), d (direction, degrees true), b (bin num
             response_format: ResponseFormatSchema,
         },
         annotations: READ_ONLY_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const response = await getCurrents(params);
@@ -89,6 +90,7 @@ vel_type="speed_dir" returns Speed/Direction pairs; "default" returns velocities
             response_format: ResponseFormatSchema,
         },
         annotations: READ_ONLY_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const response = await getCurrentPredictions(params);

package/dist/tools/derived.js

@@ -5,7 +5,7 @@
 import { z } from "zod";
 import { getExtremeWaterLevels, getHighTideFlooding, getSeaLevelRiseProjections, getSeaLevelTrends, getTopTenWaterLevels, } from "../services/dpapi.js";
 import { READ_ONLY_ANNOTATIONS, ResponseFormatSchema, StationIdSchema, UnitsSchema, } from "../schemas/common.js";
-import { markdownTable, respond, respondError } from "../format/respond.js";
+import { markdownTable, respond, respondError, RawToolOutputSchema, } from "../format/respond.js";
 function firstArray(payload) {
     for (const [key, value] of Object.entries(payload)) {
         if (Array.isArray(value) &&
@@ -53,6 +53,7 @@ Relative sea level combines ocean rise AND local land movement (subsidence/uplif
             response_format: ResponseFormatSchema,
         },
         annotations: READ_ONLY_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const payload = await getSeaLevelTrends({
@@ -98,6 +99,7 @@ Scenarios: low, intermediate-low, intermediate, intermediate-high, high, extreme
             response_format: ResponseFormatSchema,
         },
         annotations: READ_ONLY_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const payload = await getSeaLevelRiseProjections({
@@ -134,6 +136,7 @@ Use for flood risk questions ("what water level has a 1% chance per year at X?")
             response_format: ResponseFormatSchema,
         },
         annotations: READ_ONLY_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const payload = await getExtremeWaterLevels({
@@ -183,6 +186,7 @@ Heights are relative to the requested datum (MHHW is typical for flood compariso
             response_format: ResponseFormatSchema,
         },
         annotations: READ_ONLY_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const payload = await getTopTenWaterLevels({
@@ -283,6 +287,7 @@ Use for: "how often does X flood?", trends in nuisance flooding, future flooding
             response_format: ResponseFormatSchema,
         },
         annotations: READ_ONLY_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const { report, response_format, ...rest } = params;

package/dist/tools/index.js

@@ -1,6 +1,7 @@
 /**
  * Central registration for all tools.
  */
+import { withProviderDeadline } from "../client/deadline.js";
 import { registerWaterTools } from "./water.js";
 import { registerCurrentTools } from "./currents.js";
 import { registerMetTools } from "./met.js";
@@ -8,8 +9,18 @@ import { registerStationTools } from "./stations.js";
 import { registerStationMetadataTools } from "./station-metadata.js";
 import { registerDerivedProductTools } from "./derived.js";
 import { registerAstronomyTools } from "./astronomy.js";
+import { registerMarineForecastTools } from "./marine-forecast.js";
 import { registerReferenceTools } from "./reference.js";
 export function registerAllTools(server) {
+    // Keep a provider deadline across chained reads within one tool invocation.
+    // The facade preserves registration state on the real SDK server.
+    server = new Proxy(server, {
+        get(target, key, receiver) {
+            if (key !== "registerTool")
+                return Reflect.get(target, key, receiver);
+            return (name, config, callback) => target.registerTool(name, config, ((...args) => withProviderDeadline(() => callback(...args), 45_000)));
+        },
+    });
     registerWaterTools(server);
     registerCurrentTools(server);
     registerMetTools(server);
@@ -17,5 +28,6 @@ export function registerAllTools(server) {
     registerStationMetadataTools(server);
     registerDerivedProductTools(server);
     registerAstronomyTools(server);
+    registerMarineForecastTools(server);
     registerReferenceTools(server);
 }

package/dist/tools/marine-forecast.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Wind & marine FORECAST tools backed by the NWS Weather API
+ * (api.weather.gov) — a different NOAA service from CO-OPS, hence the
+ * nws_* prefix (mirroring how astro_* marks non-CO-OPS tools).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerMarineForecastTools(server: McpServer): void;

package/dist/tools/marine-forecast.js

@@ -0,0 +1,177 @@
+/**
+ * Wind & marine FORECAST tools backed by the NWS Weather API
+ * (api.weather.gov) — a different NOAA service from CO-OPS, hence the
+ * nws_* prefix (mirroring how astro_* marks non-CO-OPS tools).
+ */
+import { z } from "zod";
+import { getMarineTextForecast, getWindForecast, knotsToMs, metersToFeet, } from "../services/nws-api.js";
+import { LatitudeSchema, LongitudeSchema, READ_ONLY_ANNOTATIONS, ResponseFormatSchema, UnitsSchema, } from "../schemas/common.js";
+import { respond, respondError, RawToolOutputSchema, } from "../format/respond.js";
+import { seriesMarkdown } from "../format/series.js";
+/** "2026-07-06 09:00" in the gridpoint's IANA time zone. */
+function formatLocal(isoUtc, timeZone) {
+    try {
+        return new Intl.DateTimeFormat("sv-SE", {
+            timeZone,
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            hour12: false,
+        }).format(new Date(isoUtc));
+    }
+    catch {
+        return isoUtc;
+    }
+}
+export function registerMarineForecastTools(server) {
+    server.registerTool("nws_get_wind_forecast", {
+        title: "Get Wind Forecast (NWS)",
+        description: `Get the NWS hourly wind FORECAST (speed, gust, direction — plus wave height where the grid carries it) for a latitude/longitude.
+
+Data comes from the NWS forecast grid (api.weather.gov gridpoints — numeric NDFD values, not display strings). Horizon is up to ~7 days (156 hours), starting at the current hour. US and territories only. Wave height appears for marine/nearshore gridpoints; swell/period fields are typically only populated for open-ocean points.
+
+Units: english = knots and feet (default), metric = m/s and meters. Direction is degrees true, the direction the wind blows FROM.
+
+This is FORECAST data. For observed (measured) wind at a NOAA station right now, use noaa_get_meteorological_data (product "wind"). For the official marine text forecast (Coastal Waters Forecast narrative with small-craft advisories), use nws_get_marine_forecast.`,
+        inputSchema: {
+            latitude: LatitudeSchema,
+            longitude: LongitudeSchema,
+            hours: z
+                .number()
+                .int()
+                .min(1)
+                .max(156)
+                .default(24)
+                .describe("Forecast hours to return, starting at the current hour (max 156 ≈ 7 days; the grid may end sooner)."),
+            units: UnitsSchema,
+            response_format: ResponseFormatSchema,
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
+    }, async (params) => {
+        try {
+            const forecast = await getWindForecast(params.latitude, params.longitude, params.hours);
+            const metric = params.units === "metric";
+            const speedLabel = metric ? "m/s" : "knots";
+            const waveLabel = metric ? "meters" : "feet";
+            const convertSpeed = (knots) => knots === null ? null : metric ? round1(knotsToMs(knots)) : knots;
+            const convertWave = (meters) => meters === null
+                ? null
+                : metric
+                    ? meters
+                    : round1(metersToFeet(meters));
+            const data = forecast.samples.map((s) => ({
+                time_utc: s.time,
+                time_local: formatLocal(s.time, forecast.point.timeZone),
+                speed: convertSpeed(s.speed_knots),
+                gust: convertSpeed(s.gust_knots),
+                direction_deg: s.direction_deg,
+                compass: s.compass,
+                wave_height: convertWave(s.wave_height_m),
+            }));
+            const hasWaves = data.some((d) => d.wave_height !== null);
+            const structured = {
+                latitude: params.latitude,
+                longitude: params.longitude,
+                place: forecast.point.place,
+                grid: {
+                    office: forecast.point.gridId,
+                    grid_x: forecast.point.gridX,
+                    grid_y: forecast.point.gridY,
+                    point_type: forecast.point.pointType,
+                },
+                time_zone: forecast.point.timeZone,
+                units: params.units,
+                speed_units_label: speedLabel,
+                wave_units_label: waveLabel,
+                forecast_updated: forecast.updated,
+                count: data.length,
+                data,
+            };
+            const headers = [
+                `Time (${forecast.point.timeZone})`,
+                `Speed (${speedLabel})`,
+                `Gust (${speedLabel})`,
+                "Direction (°T)",
+                "Compass",
+                ...(hasWaves ? [`Waves (${waveLabel})`] : []),
+            ];
+            const rows = data.map((d) => [
+                d.time_local,
+                d.speed,
+                d.gust,
+                d.direction_deg,
+                d.compass,
+                ...(hasWaves ? [d.wave_height] : []),
+            ]);
+            const markdown = seriesMarkdown({
+                title: "Wind Forecast (NWS)",
+                station: `${params.latitude.toFixed(4)},${params.longitude.toFixed(4)}`,
+                stationName: forecast.point.place,
+                unitsLabel: speedLabel,
+                timeZone: forecast.point.timeZone,
+                extra: [
+                    `NWS grid ${forecast.point.gridId} ${forecast.point.gridX},${forecast.point.gridY}${forecast.updated ? ` · updated ${forecast.updated}` : ""}. Direction = where the wind blows FROM.`,
+                ],
+            }, headers, rows);
+            return respond(params.response_format, structured, markdown);
+        }
+        catch (error) {
+            return respondError(error);
+        }
+    });
+    server.registerTool("nws_get_marine_forecast", {
+        title: "Get Marine Text Forecast (NWS)",
+        description: `Get the official NWS Coastal Waters Forecast (CWF) narrative for the marine zone covering a latitude/longitude — day-part wind/seas text ("SE winds 10 to 15 kt... Bay waters choppy"), including Small Craft Advisories.
+
+The point must lie in (or very near) US coastal waters; CWF zones extend roughly 20-60 NM offshore. Returns the zone's segment from the latest bulletin plus the office-wide synopsis.
+
+For numeric hourly wind values use nws_get_wind_forecast; for observed wind at a NOAA station use noaa_get_meteorological_data (product "wind").`,
+        inputSchema: {
+            latitude: LatitudeSchema,
+            longitude: LongitudeSchema,
+            response_format: ResponseFormatSchema,
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
+    }, async (params) => {
+        try {
+            const forecast = await getMarineTextForecast(params.latitude, params.longitude);
+            const structured = {
+                latitude: params.latitude,
+                longitude: params.longitude,
+                zone_id: forecast.zone.id,
+                zone_name: forecast.zone.name,
+                issuing_office: forecast.zone.cwa,
+                product_id: forecast.productId,
+                issuance_time: forecast.issuanceTime,
+                synopsis: forecast.synopsis ?? null,
+                forecast: forecast.segment ?? null,
+            };
+            const lines = [
+                `# Coastal Waters Forecast — ${forecast.zone.name}`,
+                "",
+                `**Zone**: ${forecast.zone.id} · **Office**: ${forecast.zone.cwa}${forecast.issuanceTime ? ` · **Issued**: ${forecast.issuanceTime}` : ""}`,
+                "",
+            ];
+            if (forecast.synopsis) {
+                lines.push("```", forecast.synopsis, "```", "");
+            }
+            if (forecast.segment) {
+                lines.push("```", forecast.segment, "```");
+            }
+            else {
+                lines.push(`_The latest ${forecast.zone.cwa} bulletin contains no segment for ${forecast.zone.id} — the zone may be covered under a combined header this parser missed, or the bulletin may be mid-update. Retry, or request response_format "json"._`);
+            }
+            return respond(params.response_format, structured, lines.join("\n"));
+        }
+        catch (error) {
+            return respondError(error);
+        }
+    });
+}
+function round1(value) {
+    return Math.round(value * 10) / 10;
+}

package/dist/tools/met.js

@@ -4,7 +4,7 @@
 import { z } from "zod";
 import { getMeteorologicalData, } 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 { respond, respondError, RawToolOutputSchema, } from "../format/respond.js";
 import { seriesMarkdown, timeZoneLabel } from "../format/series.js";
 import { FLAG_LEGENDS, unitLabel } from "../format/units.js";
 const MET_KIND = {
@@ -53,6 +53,7 @@ Not every station has every sensor — check with noaa_get_station_info (expand
             response_format: ResponseFormatSchema,
         },
         annotations: READ_ONLY_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const response = await getMeteorologicalData(params);

package/dist/tools/reference.js

@@ -20,9 +20,13 @@ Consult this before constructing unusual requests — especially "datums" (which
                 .describe("Reference topic to retrieve."),
         },
         annotations: LOCAL_COMPUTE_ANNOTATIONS,
+        outputSchema: z
+            .object({ topic: z.enum(REFERENCE_TOPICS), guide: z.string() })
+            .strict(),
     }, async ({ topic }) => {
         try {
             return {
+                structuredContent: { topic, guide: REFERENCE_CONTENT[topic] },
                 content: [{ type: "text", text: REFERENCE_CONTENT[topic] }],
             };
         }

package/dist/tools/station-metadata.js

@@ -5,7 +5,7 @@
 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 { markdownTable, respond, respondError, RawToolOutputSchema, } from "../format/respond.js";
 import { unitLabel } from "../format/units.js";
 export function registerStationMetadataTools(server) {
     server.registerTool("noaa_get_station_datums", {
@@ -25,6 +25,7 @@ All values share one reference zero (the station datum), so datum-to-datum conve
             response_format: ResponseFormatSchema,
         },
         annotations: READ_ONLY_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const resource = params.epoch === "superseded" ? "supersededdatums" : "datums";
@@ -84,6 +85,7 @@ Use for: building custom tide computations, checking a station's dominant consti
             response_format: ResponseFormatSchema,
         },
         annotations: READ_ONLY_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const payload = await getStationResource(params.station, "harcon", {
@@ -172,6 +174,7 @@ Reference (R) stations return empty/null offsets — they don't need any.`,
             response_format: ResponseFormatSchema,
         },
         annotations: READ_ONLY_ANNOTATIONS,
+        outputSchema: RawToolOutputSchema,
     }, async (params) => {
         try {
             const resource = params.kind === "tide"