tides-mcp 1.0.0 → 1.0.1

package/README.md

@@ -41,3 +41,22 @@ 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`.
+
+<!-- paywall -->
+## Premium tools
+
+These tools need a license key:
+
+* `station_metadata`
+* `harmonic_constituents`
+
+Buy a key at https://mcp-marketplace.io/server/io-github-mrfentmen-tides-mcp and set it in your MCP client config:
+
+```json
+"env": { "MCP_LICENSE_KEY": "mcp_live_..." }
+```
+
+The key is checked against MCP Marketplace, cached for 24 hours, and keeps
+working offline once one check has succeeded. Every other tool on this server
+stays free.
+<!-- /paywall -->

package/dist/api.d.ts

@@ -3,3 +3,20 @@ 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 NOAA station is and what it publishes: identity, position, tide type, and the product families it carries. */
+export declare function stationMetadata(args: {
+    station?: string;
+}): Promise<string>;
+/** The harmonic constants behind a station's tide: which constituents dominate, and whether the tide is semidiurnal, mixed or diurnal. */
+export declare function harmonicConstituents(args: {
+    station?: string;
+    units?: string;
+    limit?: number;
+}): Promise<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,137 @@ 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); }
+// ---- muxF tools:
+const METADATA = "https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi/stations";
+async function metaGet(url) {
+    const res = await fetch(url, { headers: HEADERS, signal: AbortSignal.timeout(20000) });
+    if (res.status === 404)
+        throw new TidesError("NOAA has no record at that address.");
+    if (!res.ok)
+        throw new TidesError(`NOAA error ${res.status}`);
+    const data = (await res.json());
+    if (data?.error)
+        throw new TidesError(data.error.message ?? "NOAA returned an error");
+    return data;
+}
+function clean(station) {
+    const value = (station ?? "").trim();
+    if (!/^[A-Za-z0-9]{7,12}$/.test(value))
+        throw new TidesError(`Not a NOAA station id: "${station}". Use the 7 or 8 digit station number.`);
+    return value;
+}
+function yesNo(value) {
+    if (value === undefined)
+        return "not reported";
+    return value ? "yes" : "no";
+}
+/** What a NOAA station is and what it publishes: identity, position, tide type, and the product families it carries. */
+export async function stationMetadata(args) {
+    const id = clean(args.station ?? "");
+    const data = await metaGet(`${METADATA}/${encodeURIComponent(id)}.json`);
+    const s = data.stations?.[0];
+    if (!s)
+        throw new TidesError(`NOAA has no station with id ${id}.`);
+    const products = [
+        ["Tide predictions", yesNo(s.forecast)],
+        ["Observed water levels", yesNo(s.observedst)],
+        ["Flood levels", yesNo(s.floodlevels)],
+        ["Inundation database", yesNo(s.inundationdb)],
+        ["Storm surge outlooks", yesNo(s.outlook)],
+        ["Storm surge products", yesNo(s.stormsurge)],
+        ["Historical tide factors", yesNo(s.HTFhistorical)],
+        ["Monthly mean tides", yesNo(s.HTFmonthly)],
+    ];
+    const available = products.filter(([, v]) => v === "yes").map(([k]) => k);
+    return [
+        `NOAA station ${s.id ?? id}: ${s.name ?? "name not reported"}${s.state ? `, ${s.state}` : ""}`,
+        `Position: ${s.lat === undefined ? "not reported" : s.lat}, ${s.lng === undefined ? "not reported" : s.lng}`,
+        `Tidal station: ${yesNo(s.tidal)}${s.greatlakes ? " (Great Lakes station)" : ""}`,
+        `Tide type: ${s.tideType ?? "not reported"}`,
+        `Local time zone: ${s.timezone ?? "not reported"}${s.timezonecorr === undefined ? "" : ` (offset ${s.timezonecorr} hours from GMT)`}`,
+        `SHEF code: ${s.shefcode ?? "not reported"}`,
+        `Port code: ${s.portscode ? s.portscode : "none reported"}`,
+        `Affiliations: ${s.affiliations ? s.affiliations : "none reported"}`,
+        `Marked non-navigational: ${yesNo(s.nonNavigational)}`,
+        `Data product families published (${available.length} of ${products.length}): ${available.join(", ") || "none reported"}`,
+    ].join("\n");
+}
+/** The harmonic constants behind a station's tide: which constituents dominate, and whether the tide is semidiurnal, mixed or diurnal. */
+export async function harmonicConstituents(args) {
+    const id = clean(args.station ?? "");
+    const units = args.units === "metric" ? "metric" : "english";
+    const limit = Math.max(1, Math.min(Math.floor(args.limit ?? 10), 30));
+    const data = await metaGet(`${METADATA}/${encodeURIComponent(id)}/harcon.json?units=${units}`);
+    const rows = data.HarmonicConstituents ?? [];
+    if (!rows.length)
+        throw new TidesError(`NOAA publishes no harmonic constituents for station ${id}.`);
+    const unitLabel = data.units === "metric" ? "metres" : "feet";
+    const byName = new Map(rows.map((r) => [String(r.name ?? ""), r]));
+    const amplitude = (name) => Number(byName.get(name)?.amplitude ?? 0);
+    const m2 = amplitude("M2");
+    const s2 = amplitude("S2");
+    const k1 = amplitude("K1");
+    const o1 = amplitude("O1");
+    const form = m2 + s2 > 0 ? (k1 + o1) / (m2 + s2) : NaN;
+    const kind = !Number.isFinite(form) ? "not classifiable, no semidiurnal energy reported" : form < 0.5 ? "predominantly semidiurnal" : form <= 2 ? "mixed mainly semidiurnal" : "predominantly diurnal";
+    const ranked = [...rows].sort((a, b) => (Number(b.amplitude) || 0) - (Number(a.amplitude) || 0));
+    const principal = ["M2", "S2", "K1", "O1"].filter((n) => byName.has(n));
+    return [
+        `Harmonic constituents at NOAA station ${id}, amplitudes in ${unitLabel}`,
+        `Constituents on file: ${rows.length}`,
+        `Form number F = (K1+O1)/(M2+S2) = ${Number.isFinite(form) ? form.toFixed(3) : "not reported"}, so the tide is ${kind}`,
+        principal.length
+            ? `Principal constituents: ${principal.map((n) => `${n} ${amplitude(n)} ${unitLabel} at local phase ${byName.get(n)?.phase_local ?? "not reported"} degrees`).join("; ")}`
+            : "Principal constituents: none of M2, S2, K1 or O1 are on file for this station.",
+        `Strongest ${Math.min(limit, ranked.length)} by amplitude:`,
+        ...ranked.slice(0, limit).map((c) => `- ${c.name ?? "unnamed"}: ${c.amplitude === undefined ? "amplitude not reported" : c.amplitude} ${unitLabel}, local phase ${c.phase_local ?? "not reported"} degrees, speed ${c.speed ?? "not reported"} deg/h, ${c.description ?? "no description"}`),
+        ranked.length > limit ? `... and ${ranked.length - limit} more constituent(s).` : "",
+    ].filter(Boolean).join("\n");
+}
+/** 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/license.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export declare function premiumRequired(tool: string): Promise<string | null>;

package/dist/license.js

@@ -0,0 +1,79 @@
+// Premium tools on this server need a license key bought from MCP Marketplace.
+// Buyers put the key in their MCP client config as MCP_LICENSE_KEY. Every tool
+// that is not listed in PREMIUM keeps working without a key.
+const SLUG = "tides-mcp";
+// Tools that need a key. Everything else is free.
+const PREMIUM = new Set([
+    "station_metadata",
+    "harmonic_constituents",
+]);
+const BUY_URL = `https://mcp-marketplace.io/server/io-github-mrfentmen-${SLUG}`;
+// The license check calls the marketplace's verify endpoint directly instead of
+// using @mcp_marketplace/license. That SDK sends no `apikey` header, so every
+// check it makes is rejected by Supabase before it reaches the function. The
+// publishable key below is public by design - it ships in mcp-marketplace.io's
+// own JavaScript and only ever reaches their licence check.
+const DEFAULT_VERIFY_URL = "https://virupvwhtkpkjsiskckg.supabase.co/functions/v1/verify-key";
+const PUBLISHABLE_KEY = "sb_publishable_BuqlW96Ke8C_zzJG-LQv1Q_YHi_r_4h";
+const OK_CACHE_MS = 60 * 60 * 1000;
+const BAD_CACHE_MS = 60 * 1000;
+const seen = new Map();
+const REASONS = {
+    missing_key: "no key is set",
+    invalid_format: "that key is not a valid MCP Marketplace key",
+    not_found: "that key was not found",
+    revoked: "that key has been revoked",
+    rotated: "that key was rotated, use your new one",
+    expired: "that key has expired, renew it",
+    rate_limited: "there were too many checks just now, try again shortly",
+    network_error: "the license server could not be reached",
+};
+function blocked(tool, reason) {
+    const why = REASONS[reason] ?? `the license server answered "${reason}"`;
+    return `"${tool}" needs a license key, but ${why}. ` +
+        `Set MCP_LICENSE_KEY in your MCP client config. Get a key: ${BUY_URL}`;
+}
+async function verify(key) {
+    const res = await fetch(process.env.MCP_LICENSE_VERIFY_URL || DEFAULT_VERIFY_URL, {
+        method: "POST",
+        headers: {
+            apikey: PUBLISHABLE_KEY,
+            Authorization: `Bearer ${PUBLISHABLE_KEY}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ key, slug: SLUG }),
+        // an unusable key answers 400 with a JSON body, so read the body either way
+        signal: AbortSignal.timeout(15000),
+    });
+    const data = (await res.json());
+    if (typeof data?.valid !== "boolean")
+        return { valid: false, reason: "unexpected_response" };
+    return data;
+}
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export async function premiumRequired(tool) {
+    if (!PREMIUM.has(tool))
+        return null;
+    const key = process.env.MCP_LICENSE_KEY;
+    if (!key)
+        return blocked(tool, "missing_key");
+    const hit = seen.get(key);
+    if (hit && Date.now() - hit.at < (hit.valid ? OK_CACHE_MS : BAD_CACHE_MS)) {
+        return hit.valid ? null : blocked(tool, hit.reason ?? "invalid");
+    }
+    let result;
+    try {
+        result = await verify(key);
+    }
+    catch {
+        result = { valid: false, reason: "network_error" };
+    }
+    seen.set(key, { ...result, at: Date.now() });
+    return result.valid ? null : blocked(tool, result.reason ?? "invalid");
+}

package/dist/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { format, predictions, TidesError, waterLevels } from "./api.js";
+import { format, harmonicConstituents, predictions, stationMetadata, tideStatistics, TidesError, waterLevels } from "./api.js";
+import { premiumRequired } from "./license.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 +29,55 @@ 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) => {
+        // ---- paywall: station_metadata ----
+        const paywallMessage = await premiumRequired("station_metadata");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await stationMetadata(args));
+        }
+        catch (e) {
+            return textError(`Error: ${e instanceof Error ? e.message : 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) => {
+        // ---- paywall: harmonic_constituents ----
+        const paywallMessage = await premiumRequired("harmonic_constituents");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await harmonicConstituents(args));
+        }
+        catch (e) {
+            return textError(`Error: ${e instanceof Error ? e.message : 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)}`);
+        }
+    });
     return server;
 }
 export { TidesError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tides-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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",