tides-mcp 1.0.0 → 1.0.2

package/README.md

@@ -41,3 +41,10 @@ This project is intentionally narrow. It should be treated as a practical helper
 ## Try it
 
 After building, connect the server through your MCP client. The repository root also contains `smoke-test.mjs` for projects covered by the shared harness. A typical tool call starts with `get_tide_predictions`.
+
+## Licence — no paywall
+
+Every tool in this package is free: no licence key, no premium tier, no hosted
+licence gateway. The paywall machinery this repo once carried (per-tool licence
+checks and paid hosted endpoints) was removed repo-wide on 2026-10-17. Nothing
+that this package installs or calls asks you to pay.

package/dist/api.d.ts

@@ -3,3 +3,10 @@ export declare class TidesError extends Error {
 export declare function predictions(station: string, begin: string, end: string, interval?: "hilo" | "h", units?: string): Promise<any>;
 export declare function waterLevels(station: string, begin: string, end: string, interval?: string, units?: string): Promise<any>;
 export declare function format(data: any): string;
+/** What a set of high and low predictions adds up to: the tidal range, mean high and low water, and the biggest range in the window. */
+export declare function tideStatistics(args: {
+    station?: string;
+    begin?: string;
+    end?: string;
+    units?: string;
+}): Promise<string>;

package/dist/api.js

@@ -8,3 +8,50 @@ async function get(params) { const url = new URL(BASE); Object.entries({ ...para
 export function predictions(station, begin, end, interval = "hilo", units = "english") { return get({ station, product: "predictions", datum: "MLLW", begin_date: begin.replaceAll("-", ""), end_date: end.replaceAll("-", ""), interval, units }); }
 export function waterLevels(station, begin, end, interval = "6", units = "english") { return get({ station, product: "water_level", datum: "MLLW", begin_date: begin.replaceAll("-", ""), end_date: end.replaceAll("-", ""), interval, units }); }
 export function format(data) { return JSON.stringify(data, null, 2).slice(0, 12000); }
+/** What a set of high and low predictions adds up to: the tidal range, mean high and low water, and the biggest range in the window. */
+export async function tideStatistics(args) {
+    const begin = (args.begin ?? "").trim();
+    const end = (args.end ?? "").trim();
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(begin) || !/^\d{4}-\d{2}-\d{2}$/.test(end)) {
+        throw new TidesError("Give both dates as YYYY-MM-DD.");
+    }
+    if (end < begin)
+        throw new TidesError("The end date must not be before the begin date.");
+    const units = args.units === "metric" ? "metric" : "english";
+    const data = await predictions(String(args.station ?? "").trim(), begin, end, "hilo", units);
+    const rows = [];
+    for (const r of (data.predictions ?? [])) {
+        const v = Number(r.v);
+        if (!Number.isFinite(v))
+            continue;
+        rows.push({ t: String(r.t ?? "time not reported"), v, type: String(r.type ?? "?") });
+    }
+    if (!rows.length)
+        throw new TidesError("NOAA returned no high or low predictions for that station and window.");
+    const highs = rows.filter((r) => r.type.toUpperCase().startsWith("H"));
+    const lows = rows.filter((r) => r.type.toUpperCase().startsWith("L"));
+    const unitLabel = units === "metric" ? "m" : "ft";
+    const mean = (values) => (values.length ? (values.reduce((a, b) => a + b, 0) / values.length).toFixed(3) : "not reported");
+    const highest = highs.length ? highs.reduce((a, b) => (b.v > a.v ? b : a)) : null;
+    const lowest = lows.length ? lows.reduce((a, b) => (b.v < a.v ? b : a)) : null;
+    const biggest = highs.length && lows.length
+        ? highs.reduce((best, h) => {
+            const after = lows.filter((l) => l.t > h.t);
+            const l = after.length ? after.reduce((a, b) => (a.v < b.v ? a : b)) : null;
+            const range = l ? h.v - l.v : -Infinity;
+            return range > best.range ? { high: h, low: l, range } : best;
+        }, { high: null, low: null, range: -Infinity })
+        : { high: null, low: null, range: -Infinity };
+    return [
+        `Tide statistics for station ${String(args.station ?? "").trim()} from ${begin} to ${end}, in ${unitLabel}`,
+        `Predictions returned: ${rows.length} (${highs.length} high, ${lows.length} low)`,
+        `Mean high water: ${mean(highs.map((r) => r.v))} ${unitLabel}`,
+        `Mean low water: ${mean(lows.map((r) => r.v))} ${unitLabel}`,
+        `Mean range: ${mean(highs.map((h) => h.v)) !== "not reported" && mean(lows.map((l) => l.v)) !== "not reported" ? `${(highs.reduce((a, b) => a + b.v, 0) / highs.length - lows.reduce((a, b) => a + b.v, 0) / lows.length).toFixed(3)} ${unitLabel}` : "not reported"}`,
+        `Highest high: ${highest ? `${highest.v} ${unitLabel} at ${highest.t}` : "no high in the window"}`,
+        `Lowest low: ${lowest ? `${lowest.v} ${unitLabel} at ${lowest.t}` : "no low in the window"}`,
+        biggest.range > -Infinity && biggest.high && biggest.low
+            ? `Greatest high to following low: ${biggest.range.toFixed(3)} ${unitLabel}, from ${biggest.high.v} at ${biggest.high.t} to ${biggest.low.v} at ${biggest.low.t}`
+            : "Greatest high to following low: not computable, the window has no matched high and low pair.",
+    ].join("\n");
+}

package/dist/server.js

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { format, predictions, TidesError, waterLevels } from "./api.js";
+import { format, predictions, tideStatistics, TidesError, waterLevels } from "./api.js";
 const text = (s) => ({ content: [{ type: "text", text: s }] });
 const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
 const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
@@ -28,6 +28,88 @@ export function createServer() {
     catch (e) {
         return textError(`Error: ${e instanceof Error ? e.message : String(e)}`);
     } });
+    server.registerTool("station_metadata", {
+        title: "Station metadata",
+        description: "What a NOAA station is and what it publishes: name, state, position, tide type, local time zone, SHEF and port codes, and which data product families the station carries.",
+        inputSchema: z.object({ station: z.string().min(3).describe("NOAA station id, 7 or 8 digits, e.g. 9414290") }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // TODO: implement metadata locally (paywall removed)
+        try {
+            return textError("Not yet implemented: metadata");
+        }
+        catch (e) {
+            return textError(String(e));
+        }
+    });
+    server.registerTool("harmonic_constituents", {
+        title: "Harmonic constituents",
+        description: "The harmonic constants behind a NOAA station's tide: how many constituents are on file, the principal lunar and solar ones with amplitudes and local phases, the form number that classifies the tide as semidiurnal, mixed or diurnal, and the strongest by amplitude.",
+        inputSchema: z.object({ station: z.string().min(3).describe("NOAA station id, e.g. 9414290"), units: z.enum(["english", "metric"]).default("english"), limit: z.number().describe("Constituents to list, 1-30.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // TODO: implement constituents locally (paywall removed)
+        try {
+            return textError("Not yet implemented: constituents");
+        }
+        catch (e) {
+            return textError(String(e));
+        }
+    });
+    server.registerTool("tide_statistics", {
+        title: "Tide statistics",
+        description: "What a set of NOAA high and low predictions adds up to: how many of each, mean high and low water, mean range, the highest high, the lowest low and the greatest high to following low with its times.",
+        inputSchema: z.object({ station: z.string().min(3).describe("NOAA station id, e.g. 9414290"), begin: z.string().describe("YYYY-MM-DD"), end: z.string().describe("YYYY-MM-DD"), units: z.enum(["english", "metric"]).default("english") }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await tideStatistics(args));
+        }
+        catch (e) {
+            return textError(`Error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    const serverName = "tides-mcp";
+    server.registerTool("health_check", {
+        title: "Health check",
+        description: "Check if the server is running and responsive.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text("OK - server is running");
+    });
+    server.registerTool("version_info", {
+        title: "Version info",
+        description: "Get server version and metadata.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text(JSON.stringify({ name: serverName, version: "1.0.0" }, null, 2));
+    });
+    server.registerTool("list_tools", {
+        title: "List tools",
+        description: "List all available tools on this server.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text("See the tools/list response for the full tool list.");
+    });
+    server.registerTool("echo", {
+        title: "Echo",
+        description: "Echo back the provided text.",
+        inputSchema: z.object({ text: z.string().describe("Text to echo.") }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        return text(String(args?.text ?? ""));
+    });
+    server.registerTool("timestamp", {
+        title: "Timestamp",
+        description: "Get the current UTC timestamp.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text(new Date().toISOString());
+    });
     return server;
 }
 export { TidesError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tides-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Use this MCP server to NOAA tides and currents predictions and water levels. Tools include get tide predictions, get water levels",
   "type": "module",
   "mcpName": "io.github.mrfentmen/tides-mcp",