tides-mcp 1.0.2 → 1.0.3

package/README.md

@@ -18,33 +18,3 @@ node dist/index.js
 ```
 
 The server uses stdio MCP transport and does not write files or contact any service other than NOAA.
-
-## Quick start
-
-```bash
-npm install
-npm run build
-node dist/index.js
-```
-
-The server uses stdio, so it can be connected to Claude Desktop, Cursor, VS Code, MCP Inspector, or another compatible MCP client.
-
-## Tools at a glance
-
-- `get_tide_predictions`: Get NOAA high low or hourly tide predictions for a station and date range.
-- `get_water_levels`: Get observed NOAA water levels for a station and short date range.
-
-## Limits and privacy
-
-This project is intentionally narrow. It should be treated as a practical helper, not a complete certification or security audit. Check the implementation and the returned data before using it with sensitive material. No credentials are required unless the project explicitly says otherwise.
-
-## 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,10 +3,15 @@ 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;
+export declare function stationList(a: {
+    state?: string;
+}): Promise<string>;
+export declare function stationMetadata(a: {
+    station: string;
+}): Promise<string>;
+export declare function tideRange(a: {
+    station: string;
+    begin: string;
+    end: string;
+    units: string;
 }): Promise<string>;

package/dist/api.js

@@ -8,50 +8,58 @@ 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 ?? "?") });
-    }
+const MD = "https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi";
+async function metadata(path) {
+    const res = await fetch(MD + path, { headers: HEADERS, signal: AbortSignal.timeout(20000) });
+    if (!res.ok)
+        throw new TidesError(`NOAA metadata error ${res.status}`);
+    return res.json();
+}
+export async function stationList(a) {
+    const data = await metadata("/stations.json?type=tidepredictions");
+    const all = Array.isArray(data?.stations) ? data.stations : [];
+    const wanted = a.state ? a.state.trim().toUpperCase() : "";
+    const rows = wanted ? all.filter((s) => clean(s?.state).toUpperCase() === wanted) : all;
+    if (!rows.length)
+        return `NOAA lists no tide stations${wanted ? ` in ${wanted}` : ""}.`;
+    return [`${rows.length} tide station(s)${wanted ? ` in ${wanted}` : ""}, showing ${Math.min(rows.length, 40)}:`, "",
+        ...rows.slice(0, 40).map((s, i) => `${i + 1}. ${clean(s?.name)} · ${clean(s?.id)} · ${clean(s?.state)} · ${s?.lat}, ${s?.lng}`)].join("\n");
+}
+export async function stationMetadata(a) {
+    const id = clean(a.station);
+    if (!/^[A-Za-z0-9]{5,10}$/.test(id))
+        throw new TidesError(`"${id}" is not a NOAA station id`);
+    const body = await metadata(`/stations/${encodeURIComponent(id)}.json`);
+    const s = Array.isArray(body?.stations) ? body.stations[0] : undefined;
+    if (!s?.id)
+        throw new TidesError(`No NOAA station ${id}`);
+    return [`${clean(s.name)} (${clean(s.id)})`, "",
+        `State: ${clean(s.state)}`,
+        `Affiliation: ${clean(s.affiliation)}`,
+        `Coordinates: ${s.lat}, ${s.lng}`,
+        `Time zone: ${clean(s.timezone)} ${clean(s.timezonecorr)}`,
+        `Tide predictions: ${s.tideType ? "yes" : "no"}`,
+        `Products: ${Array.isArray(s.products) ? s.products.slice(0, 8).map((p) => clean(p.name)).join(", ") : ""}`,
+        `Station page: https://tidesandcurrents.noaa.gov/stationhome.html?id=${clean(s.id)}`].join("\n");
+}
+export async function tideRange(a) {
+    const id = clean(a.station);
+    if (!/^[A-Za-z0-9]{5,10}$/.test(id))
+        throw new TidesError(`"${id}" is not a NOAA station id`);
+    const data = await predictions(id, a.begin, a.end, "hilo", a.units);
+    const rows = Array.isArray(data?.predictions) ? data.predictions : [];
     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");
+        return `No tide predictions for ${id} between ${a.begin} and ${a.end}.`;
+    const values = rows.map((p) => Number(p.v)).filter((v) => Number.isFinite(v));
+    const highs = rows.filter((p) => clean(p.type).toLowerCase() === "h");
+    const lows = rows.filter((p) => clean(p.type).toLowerCase() === "l");
+    const unit = a.units === "metric" ? "m" : "ft";
+    return [`Tide range for ${id} · ${a.begin} to ${a.end}`, "",
+        `Highest: ${Math.max(...values).toFixed(2)} ${unit}`,
+        `Lowest: ${Math.min(...values).toFixed(2)} ${unit}`,
+        `Range: ${(Math.max(...values) - Math.min(...values)).toFixed(2)} ${unit}`,
+        `High tides: ${highs.length} · low tides: ${lows.length}`,
+        `Next high: ${clean(highs[0]?.t) || "n/a"} ${clean(highs[0]?.v)} ${unit}`,
+        `Next low: ${clean(lows[0]?.t) || "n/a"} ${clean(lows[0]?.v)} ${unit}`].join("\n");
 }
+function clean(value) { return String(value ?? "").replace(/\s+/g, " ").trim(); }

package/dist/index.d.ts

@@ -1 +1,2 @@
+#!/usr/bin/env node
 export {};

package/dist/index.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "./server.js";
 async function main() {

package/dist/server.d.ts

@@ -1,4 +1,2 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { TidesError } from "./api.js";
 export declare function createServer(): McpServer;
-export { TidesError };

package/dist/server.js

@@ -1,115 +1,75 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { format, predictions, tideStatistics, TidesError, waterLevels } from "./api.js";
+import { format, predictions, stationList, stationMetadata, tideRange, 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 };
+const fail = (s) => ({ content: [{ type: "text", text: s }], isError: true });
+function errorMessage(e) {
+    if (e instanceof TidesError || e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}
 export function createServer() {
-    const server = new McpServer({ name: "tides-mcp", version: "1.0.0" });
-    server.registerTool("get_tide_predictions", {
-        title: "Get tide predictions",
-        description: "Get NOAA high low or hourly tide predictions for a station and date range.",
-        inputSchema: z.object({ station: z.string().min(3), begin: z.string().describe("YYYY-MM-DD"), end: z.string().describe("YYYY-MM-DD"), interval: z.enum(["hilo", "h"]).default("hilo"), units: z.enum(["english", "metric"]).default("english") }),
-        annotations: READ_ONLY,
-    }, async ({ station, begin, end, interval, units }) => { try {
-        return text(format(await predictions(station, begin, end, interval, units)));
-    }
-    catch (e) {
-        return textError(`Error: ${e instanceof Error ? e.message : String(e)}`);
-    } });
-    server.registerTool("get_water_levels", {
-        title: "Get water levels",
-        description: "Get observed NOAA water levels for a station and short date range.",
-        inputSchema: z.object({ station: z.string().min(3), begin: z.string(), end: z.string(), interval: z.enum(["6", "h"]).default("6"), units: z.enum(["english", "metric"]).default("english") }),
-        annotations: READ_ONLY,
-    }, async ({ station, begin, end, interval, units }) => { try {
-        return text(format(await waterLevels(station, begin, end, interval, units)));
-    }
-    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)
+    const server = new McpServer({ name: "tides-mcp", version: "1.0.2" });
+    server.tool("get_tide_predictions", "Get NOAA high low or hourly tide predictions for a station and date range.", {
+        station: z.string().min(3).describe("NOAA station id, e.g. 8443970"),
+        begin: z.string().describe("YYYY-MM-DD"),
+        end: z.string().describe("YYYY-MM-DD"),
+        interval: z.enum(["hilo", "h"]).default("hilo"),
+        units: z.enum(["english", "metric"]).default("english")
+    }, async (a) => {
         try {
-            return textError("Not yet implemented: metadata");
+            return text(format(await predictions(a.station, a.begin, a.end, a.interval, a.units)));
         }
         catch (e) {
-            return textError(String(e));
+            return fail(errorMessage(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)
+    server.tool("get_water_levels", "Get observed NOAA water levels for a station and short date range.", {
+        station: z.string().min(3).describe("NOAA station id"),
+        begin: z.string().describe("YYYY-MM-DD"),
+        end: z.string().describe("YYYY-MM-DD"),
+        interval: z.enum(["6", "h"]).default("6"),
+        units: z.enum(["english", "metric"]).default("english")
+    }, async (a) => {
         try {
-            return textError("Not yet implemented: constituents");
+            return text(format(await waterLevels(a.station, a.begin, a.end, a.interval, a.units)));
         }
         catch (e) {
-            return textError(String(e));
+            return fail(errorMessage(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) => {
+    server.tool("list_stations", "List NOAA tide prediction stations, optionally by state.", {
+        state: z.string().length(2).optional().describe("Two-letter state code, e.g. NY")
+    }, async (a) => {
         try {
-            return text(await tideStatistics(args));
+            return text(await stationList(a));
         }
         catch (e) {
-            return textError(`Error: ${e instanceof Error ? e.message : String(e)}`);
+            return fail(errorMessage(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.tool("station_metadata", "Station details for one NOAA tide gauge.", {
+        station: z.string().min(3).describe("NOAA station id, e.g. 8443970")
+    }, async (a) => {
+        try {
+            return text(await stationMetadata(a));
+        }
+        catch (e) {
+            return fail(errorMessage(e));
+        }
     });
-    server.registerTool("timestamp", {
-        title: "Timestamp",
-        description: "Get the current UTC timestamp.",
-        inputSchema: z.object({}),
-        annotations: READ_ONLY,
-    }, async () => {
-        return text(new Date().toISOString());
+    server.tool("tide_range", "Highest, lowest and total tide range for a date window.", {
+        station: z.string().min(3).describe("NOAA station id"),
+        begin: z.string().describe("YYYY-MM-DD"),
+        end: z.string().describe("YYYY-MM-DD"),
+        units: z.enum(["english", "metric"]).default("english")
+    }, async (a) => {
+        try {
+            return text(await tideRange(a));
+        }
+        catch (e) {
+            return fail(errorMessage(e));
+        }
     });
     return server;
 }
-export { TidesError };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "tides-mcp",
-  "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",
+  "version": "1.0.3",
+  "description": "MCP server for NOAA tides and currents predictions and water levels.",
   "type": "module",
   "mcpName": "io.github.mrfentmen/tides-mcp",
   "repository": {
     "type": "git",
-    "url": "https://github.com/mrfentmen/tides-mcp.git"
+    "url": "git+https://github.com/mrfentmen/awesome-servers.git"
   },
   "bin": {
     "tides-mcp": "./dist/index.js"
@@ -35,8 +35,5 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^5.6.0"
-  },
-  "engines": {
-    "node": ">=20"
   }
 }

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.mrfentmen/tides-mcp",
-  "description": "Use this MCP server to NOAA tides and currents predictions and water levels. Tools include get...",
+  "description": "MCP server for NOAA tides and currents predictions and water levels.",
   "repository": {
     "url": "https://github.com/mrfentmen/tides-mcp",
     "source": "github"
   },
-  "version": "1.0.0",
+  "version": "1.0.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "tides-mcp",
-      "version": "1.0.0",
+      "version": "1.0.3",
       "transport": {
         "type": "stdio"
       }