tides-mcp 1.0.0

package/README.md

@@ -0,0 +1,43 @@
+# tides-mcp
+
+A small MCP server for coastal planning with NOAA CO-OPS tide data. It is useful for fishing, kayaking, tidepool trips, photography, flood awareness, and checking whether a tide window is worth investigating.
+
+## Tools
+
+- `get_tide_predictions`: high and low predictions or hourly predictions for a station and date range.
+- `get_water_levels`: observed water levels for a station and date range.
+
+The server uses the public NOAA CO-OPS API and needs no key. Dates use `YYYY-MM-DD`; station ids are NOAA station identifiers such as `9414290`. Requests time out after 20 seconds.
+
+## Run
+
+```bash
+npm install
+npm run build
+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`.

package/dist/api.d.ts

@@ -0,0 +1,5 @@
+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;

package/dist/api.js

@@ -0,0 +1,10 @@
+const BASE = "https://api.tidesandcurrents.noaa.gov/api/prod/datagetter";
+const HEADERS = { "User-Agent": "mrfentmen-tides-mcp/1.0" };
+export class TidesError extends Error {
+}
+async function get(params) { const url = new URL(BASE); Object.entries({ ...params, format: "json", units: params.units ?? "english", time_zone: params.time_zone ?? "gmt" }).forEach(([k, v]) => url.searchParams.set(k, v)); const res = await fetch(url, { headers: HEADERS, signal: AbortSignal.timeout(20000) }); if (!res.ok)
+    throw new TidesError(`NOAA tides error ${res.status}`); const data = await res.json(); if (data.error)
+    throw new TidesError(data.error.message ?? "NOAA returned an error"); return data; }
+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); }

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

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

package/dist/server.js

@@ -0,0 +1,33 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { format, predictions, 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 };
+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)}`);
+    } });
+    return server;
+}
+export { TidesError };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "tides-mcp",
+  "version": "1.0.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/tides-mcp.git"
+  },
+  "bin": {
+    "tides-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "server.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "npm run build && node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "public-data",
+    "tides"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/server.json

@@ -0,0 +1,20 @@
+{
+  "$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...",
+  "repository": {
+    "url": "https://github.com/mrfentmen/tides-mcp",
+    "source": "github"
+  },
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "tides-mcp",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}