@ryancardin/noaa-tides-currents-mcp-server 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,29 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:tidesandcurrents.noaa.gov)",
+      "WebFetch(domain:api.tidesandcurrents.noaa.gov)",
+      "WebFetch(domain:www.tidesandcurrents.noaa.gov)",
+      "WebFetch(domain:gofastmcp.com)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:deepwiki.com)",
+      "Bash(npm run build:*)",
+      "Bash(npx fastmcp inspect:*)",
+      "Bash(ls:*)",
+      "Bash(node:*)",
+      "Bash(npm test)",
+      "Bash(rm:*)",
+      "Bash(bash -c \"git status\")",
+      "Bash(export:*)",
+      "Bash(/usr/bin/git status)",
+      "Bash(exec /bin/bash -c \"git checkout -b feature/testing-branch\")",
+      "Bash(git checkout:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(npx @modelcontextprotocol/inspector:*)",
+      "Bash(chmod:*)",
+      "Bash(npm pack:*)"
+    ],
+    "deny": []
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,71 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Building and Running
+- `npm run build` - Build TypeScript to JavaScript in `dist/` directory
+- `npm start` - Start the MCP server (requires build first)
+- `npm run dev` - Run in development mode with ts-node-esm
+- `npm run format` - Format code with Prettier
+- `npm test` - Run tests with Vitest
+
+### Testing and Development
+- `npx fastmcp dev dist/index.js` - Test server with fastmcp CLI
+- `npx fastmcp inspect dist/index.js` - Inspect server capabilities
+
+## Architecture Overview
+
+This is a FastMCP server that provides tools for accessing NOAA Tides and Currents data, moon phase information, and sun position calculations.
+
+### Core Structure
+- **Entry Point**: `src/index.ts` - Creates server, registers tools, and starts stdio transport
+- **Server Configuration**: `src/server/config.ts` - FastMCP server setup with fixed stdio transport
+- **Tool Registration**: `src/tools/index.ts` - Centralized tool registration hub
+
+### Service Layer
+The application follows a service-oriented architecture:
+- `NoaaService` - Handles all NOAA API interactions (data and metadata APIs)
+- `MoonPhaseService` - Calculates moon phases and lunar information
+- `SunService` - Calculates sun position, rise/set times using suncalc library
+- `NoaaParametersService` - Provides parameter definitions for NOAA API
+
+### Tool Categories
+Tools are organized by functional area:
+- **Water Tools** (`water-tools.ts`) - Water levels, tide predictions, currents
+- **Station Tools** (`station-tools.ts`) - Station metadata and information
+- **Moon Tools** (`moon-tools.ts`) - Moon phase calculations
+- **Sun Tools** (`sun-tools.ts`) - Sun position and event calculations
+- **Parameter Tools** (`parameter-tools.ts`) - API parameter definitions
+
+### Data Validation
+- Uses Zod schemas for parameter validation in `src/schemas/common.ts`
+- Common validation patterns for dates, stations, units, formats, etc.
+- Refined validation for date parameter combinations
+
+### API Integration
+- **NOAA Data API**: `https://api.tidesandcurrents.noaa.gov/api/prod/datagetter`
+- **NOAA Metadata API**: `https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi`
+- Uses axios for HTTP requests with proper error handling
+
+### Key Dependencies
+- `fastmcp` - MCP server framework
+- `axios` - HTTP client for NOAA API calls
+- `suncalc` - Sun position and timing calculations
+- `zod` - Schema validation
+- TypeScript with ES modules and Node16 module resolution
+
+## Important Implementation Notes
+
+### MCP Server Configuration
+The server uses stdio transport exclusively - do not modify to use other transports as this is designed for MCP client integration.
+
+### Error Handling
+NOAA API errors are caught and re-thrown with structured error messages including status codes and response data.
+
+### Date Handling
+The codebase supports multiple date formats and has specific validation logic for date parameter combinations (date vs begin_date/end_date).
+
+### Tool Organization
+Each tool category has its own registration function that accepts the server instance and relevant service(s). This modular approach makes it easy to add new tools or modify existing ones.

package/Dockerfile

@@ -0,0 +1,14 @@
+# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
+FROM node:lts-alpine
+WORKDIR /app
+
+# Install dependencies
+COPY package*.json ./
+RUN npm install --ignore-scripts
+
+# Copy source code and build the project
+COPY . .
+RUN npm run build
+
+# Start the server in stdio mode
+CMD [ "npm", "start" ]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ryan Cardin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,234 @@
+# LocalTides MCP Server
+
+[![smithery badge](https://smithery.ai/badge/@RyanCardin15/noaa-tidesandcurrents-mcp)](https://smithery.ai/server/@RyanCardin15/noaa-tidesandcurrents-mcp)
+
+This is an MCP (Model Context Protocol) server that provides tools for interacting with the NOAA Tides and Currents API using the FastMCP framework.
+
+## Features
+
+- Water Level data retrieval (real-time and historical)
+- Tide Predictions (high/low or interval-based)
+- Currents data (real-time and historical)
+- Current predictions
+- Station metadata retrieval
+- Wind, air temperature, water temperature, and other meteorological data
+- Moon phase information (past, present, and future)
+- Sun rise/set and position data (past, present, and future)
+
+## Prerequisites
+
+- Node.js (v18 or higher)
+- npm or yarn
+
+## Setup
+
+### Installing via Smithery
+
+To install NOAA Tides and Currents for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@RyanCardin15/tidesandcurrents):
+
+```bash
+npx -y @smithery/cli install @RyanCardin15/tidesandcurrents --client claude
+```
+
+### Manual Installation
+1. Clone this repository
+2. Install dependencies
+
+```bash
+npm install
+```
+
+3. Build the TypeScript code
+
+```bash
+npm run build
+```
+
+4. Start the server
+
+```bash
+npm start
+```
+
+## Usage
+
+This MCP server can be used with any MCP host such as Claude Desktop, which allows you to use the NOAA Tides and Currents API through the MCP protocol.
+
+You can also test it directly using the `fastmcp` command-line tool:
+
+```bash
+npx fastmcp dev dist/index.js
+```
+
+Or, you can use the MCP Inspector:
+
+```bash
+npx fastmcp inspect dist/index.js
+```
+
+### Available Tools
+
+#### Parameter Definitions
+
+- `get_parameter_definitions` - Get information about valid parameter values for NOAA API requests
+  - Parameters:
+    - `parameter` (string, optional) - Parameter type to get information about (time_zones, datums, units, tide_intervals, current_intervals, velocity_types, products, station_types, date_formats, output_formats). If not provided, returns information about all parameter types.
+
+#### Water Levels
+
+- `get_water_levels` - Get water level data for a station
+  - Parameters:
+    - `station` (string) - Station ID
+    - `date` (string, optional) - Date to retrieve data for ("today", "latest", "recent", or specific date)
+    - `begin_date` (string, optional) - Start date (YYYYMMDD or MM/DD/YYYY)
+    - `end_date` (string, optional) - End date (YYYYMMDD or MM/DD/YYYY)
+    - `range` (number, optional) - Number of hours to retrieve data for
+    - `datum` (string, optional) - Datum to use (MLLW, MSL, etc.)
+    - `units` (string, optional) - Units to use ("english" or "metric")
+    - `time_zone` (string, optional) - Time zone (gmt, lst, lst_ldt)
+    - `format` (string, optional) - Output format (json, xml, csv)
+
+#### Tide Predictions
+
+- `get_tide_predictions` - Get tide prediction data
+  - Parameters:
+    - `station` (string) - Station ID
+    - `begin_date` (string) - Start date (YYYYMMDD or MM/DD/YYYY)
+    - `end_date` (string) - End date (YYYYMMDD or MM/DD/YYYY)
+    - `datum` (string, optional) - Datum to use (MLLW, MSL, etc.)
+    - `units` (string, optional) - Units to use ("english" or "metric")
+    - `time_zone` (string, optional) - Time zone (gmt, lst, lst_ldt)
+    - `interval` (string, optional) - Interval (hilo, hl, h, or a number for minutes)
+    - `format` (string, optional) - Output format (json, xml, csv)
+
+#### Currents
+
+- `get_currents` - Get currents data for a station
+  - Parameters:
+    - `station` (string) - Station ID
+    - `date` (string, optional) - Date to retrieve data for ("today", "latest", "recent", or specific date)
+    - `begin_date` (string, optional) - Start date (YYYYMMDD or MM/DD/YYYY)
+    - `end_date` (string, optional) - End date (YYYYMMDD or MM/DD/YYYY)
+    - `bin` (number, optional) - Bin number
+    - `units` (string, optional) - Units to use ("english" or "metric")
+    - `time_zone` (string, optional) - Time zone (gmt, lst, lst_ldt)
+    - `format` (string, optional) - Output format (json, xml, csv)
+
+#### Current Predictions
+
+- `get_current_predictions` - Get current predictions
+  - Parameters:
+    - `station` (string) - Station ID
+    - `date` (string, optional) - Date to retrieve data for ("today", "latest", "recent", or specific date)
+    - `begin_date` (string, optional) - Start date (YYYYMMDD or MM/DD/YYYY)
+    - `end_date` (string, optional) - End date (YYYYMMDD or MM/DD/YYYY)
+    - `bin` (number, optional) - Bin number
+    - `interval` (string, optional) - Interval (MAX_SLACK or a number for minutes)
+    - `vel_type` (string, optional) - Velocity type (speed_dir or default)
+    - `units` (string, optional) - Units to use ("english" or "metric")
+    - `time_zone` (string, optional) - Time zone (gmt, lst, lst_ldt)
+    - `format` (string, optional) - Output format (json, xml, csv)
+
+#### Meteorological Data
+
+- `get_meteorological_data` - Get meteorological data
+  - Parameters:
+    - `station` (string) - Station ID
+    - `product` (string) - Product (air_temperature, wind, etc.)
+    - `date` (string, optional) - Date to retrieve data for ("today", "latest", "recent", or specific date)
+    - `begin_date` (string, optional) - Start date (YYYYMMDD or MM/DD/YYYY)
+    - `end_date` (string, optional) - End date (YYYYMMDD or MM/DD/YYYY)
+    - `units` (string, optional) - Units to use ("english" or "metric")
+    - `time_zone` (string, optional) - Time zone (gmt, lst, lst_ldt)
+    - `format` (string, optional) - Output format (json, xml, csv)
+
+#### Station Information
+
+- `get_stations` - Get list of stations
+  - Parameters:
+    - `type` (string, optional) - Station type (waterlevels, currents, etc.)
+    - `units` (string, optional) - Units to use ("english" or "metric")
+    - `format` (string, optional) - Output format (json, xml)
+
+- `get_station_details` - Get detailed information about a station
+  - Parameters:
+    - `station` (string) - Station ID
+    - `units` (string, optional) - Units to use ("english" or "metric")
+    - `format` (string, optional) - Output format (json, xml)
+
+#### Moon Phase Information
+
+- `get_moon_phase` - Get moon phase information for a specific date
+  - Parameters:
+    - `date` (string, optional) - Date to get moon phase for (YYYY-MM-DD format). Defaults to current date.
+    - `latitude` (number, optional) - Latitude for location-specific calculations
+    - `longitude` (number, optional) - Longitude for location-specific calculations
+    - `format` (string, optional) - Output format (json or text)
+
+- `get_moon_phases_range` - Get moon phase information for a date range
+  - Parameters:
+    - `start_date` (string) - Start date (YYYY-MM-DD format)
+    - `end_date` (string) - End date (YYYY-MM-DD format)
+    - `latitude` (number, optional) - Latitude for location-specific calculations
+    - `longitude` (number, optional) - Longitude for location-specific calculations
+    - `format` (string, optional) - Output format (json or text)
+
+- `get_next_moon_phase` - Get the next occurrence(s) of a specific moon phase
+  - Parameters:
+    - `phase` (string) - Moon phase to find (New Moon, First Quarter, Full Moon, Last Quarter)
+    - `date` (string, optional) - Starting date (YYYY-MM-DD format). Defaults to current date.
+    - `count` (number, optional) - Number of occurrences to return. Defaults to 1.
+    - `format` (string, optional) - Output format (json or text)
+
+#### Sun Rise/Set Information
+
+- `get_sun_times` - Get sun rise/set and other sun event times for a specific date and location
+  - Parameters:
+    - `date` (string, optional) - Date to get sun times for (YYYY-MM-DD format). Defaults to current date.
+    - `latitude` (number) - Latitude for location-specific calculations
+    - `longitude` (number) - Longitude for location-specific calculations
+    - `format` (string, optional) - Output format (json or text)
+    - `timezone` (string, optional) - Timezone for the results. Defaults to UTC.
+
+- `get_sun_times_range` - Get sun rise/set and other sun event times for a date range and location
+  - Parameters:
+    - `start_date` (string) - Start date (YYYY-MM-DD format)
+    - `end_date` (string) - End date (YYYY-MM-DD format)
+    - `latitude` (number) - Latitude for location-specific calculations
+    - `longitude` (number) - Longitude for location-specific calculations
+    - `format` (string, optional) - Output format (json or text)
+    - `timezone` (string, optional) - Timezone for the results. Defaults to UTC.
+
+- `get_sun_position` - Get sun position information for a specific date, time, and location
+  - Parameters:
+    - `date` (string, optional) - Date to get sun position for (YYYY-MM-DD format). Defaults to current date.
+    - `time` (string, optional) - Time to get sun position for (HH:MM:SS format). Defaults to current time.
+    - `latitude` (number) - Latitude for location-specific calculations
+    - `longitude` (number) - Longitude for location-specific calculations
+    - `format` (string, optional) - Output format (json or text)
+
+- `get_next_sun_event` - Get the next occurrence(s) of a specific sun event
+  - Parameters:
+    - `event` (string) - Sun event to find (sunrise, sunset, dawn, dusk, solarNoon, etc.)
+    - `date` (string, optional) - Starting date (YYYY-MM-DD format). Defaults to current date.
+    - `latitude` (number) - Latitude for location-specific calculations
+    - `longitude` (number) - Longitude for location-specific calculations
+    - `count` (number, optional) - Number of occurrences to return. Defaults to 1.
+    - `format` (string, optional) - Output format (json or text)
+    - `timezone` (string, optional) - Timezone for the results. Defaults to UTC.
+
+## API Documentation
+
+NOAA Tides and Currents API documentation can be found at:
+- CO-OPS Data API: https://api.tidesandcurrents.noaa.gov/api/prod/
+- CO-OPS Metadata API: https://api.tidesandcurrents.noaa.gov/mdapi/prod/
+- CO-OPS Derived Product API: https://api.tidesandcurrents.noaa.gov/dpapi/prod/
+
+## License
+
+MIT 
+
+
+<a href="https://glama.ai/mcp/servers/ro2rz2c734">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/ro2rz2c734/badge" />
+

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { createServer, startServer } from './server/config.js';
+import { registerAllTools } from './tools/index.js';
+// Create and configure the MCP server
+const server = createServer();
+// Register all tools
+const services = registerAllTools(server);
+// Start the server
+startServer(server);

package/dist/interfaces/config.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Configuration options for the NOAA service
+ */
+export interface NoaaConfig {
+    applicationName?: string;
+}

package/dist/interfaces/config.js

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

package/dist/interfaces/moon.d.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { MoonPhaseName } from '../types/moon.js';
+/**
+ * Parameters for getting moon phase
+ */
+export declare const MoonPhaseParamsSchema: z.ZodObject<{
+    date: z.ZodOptional<z.ZodString>;
+    latitude: z.ZodOptional<z.ZodNumber>;
+    longitude: z.ZodOptional<z.ZodNumber>;
+    format: z.ZodOptional<z.ZodEnum<["json", "text"]>>;
+}, "strip", z.ZodTypeAny, {
+    date?: string | undefined;
+    format?: "text" | "json" | undefined;
+    latitude?: number | undefined;
+    longitude?: number | undefined;
+}, {
+    date?: string | undefined;
+    format?: "text" | "json" | undefined;
+    latitude?: number | undefined;
+    longitude?: number | undefined;
+}>;
+export type MoonPhaseParams = z.infer<typeof MoonPhaseParamsSchema>;
+/**
+ * Parameters for getting moon phases for a date range
+ */
+export declare const MoonPhasesRangeParamsSchema: z.ZodObject<{
+    start_date: z.ZodString;
+    end_date: z.ZodString;
+    latitude: z.ZodOptional<z.ZodNumber>;
+    longitude: z.ZodOptional<z.ZodNumber>;
+    format: z.ZodOptional<z.ZodEnum<["json", "text"]>>;
+}, "strip", z.ZodTypeAny, {
+    start_date: string;
+    end_date: string;
+    format?: "text" | "json" | undefined;
+    latitude?: number | undefined;
+    longitude?: number | undefined;
+}, {
+    start_date: string;
+    end_date: string;
+    format?: "text" | "json" | undefined;
+    latitude?: number | undefined;
+    longitude?: number | undefined;
+}>;
+export type MoonPhasesRangeParams = z.infer<typeof MoonPhasesRangeParamsSchema>;
+/**
+ * Parameters for getting next moon phase
+ */
+export declare const NextMoonPhaseParamsSchema: z.ZodObject<{
+    phase: z.ZodEnum<[MoonPhaseName.NEW_MOON, MoonPhaseName.FIRST_QUARTER, MoonPhaseName.FULL_MOON, MoonPhaseName.LAST_QUARTER]>;
+    date: z.ZodOptional<z.ZodString>;
+    count: z.ZodOptional<z.ZodNumber>;
+    format: z.ZodOptional<z.ZodEnum<["json", "text"]>>;
+}, "strip", z.ZodTypeAny, {
+    phase: MoonPhaseName.NEW_MOON | MoonPhaseName.FIRST_QUARTER | MoonPhaseName.FULL_MOON | MoonPhaseName.LAST_QUARTER;
+    date?: string | undefined;
+    format?: "text" | "json" | undefined;
+    count?: number | undefined;
+}, {
+    phase: MoonPhaseName.NEW_MOON | MoonPhaseName.FIRST_QUARTER | MoonPhaseName.FULL_MOON | MoonPhaseName.LAST_QUARTER;
+    date?: string | undefined;
+    format?: "text" | "json" | undefined;
+    count?: number | undefined;
+}>;
+export type NextMoonPhaseParams = z.infer<typeof NextMoonPhaseParamsSchema>;

package/dist/interfaces/moon.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { MoonPhaseName } from '../types/moon.js';
+/**
+ * Parameters for getting moon phase
+ */
+export const MoonPhaseParamsSchema = z.object({
+    date: z.string().optional().describe('Date to get moon phase for (YYYY-MM-DD format). Defaults to current date.'),
+    latitude: z.number().min(-90).max(90).optional().describe('Latitude for location-specific calculations'),
+    longitude: z.number().min(-180).max(180).optional().describe('Longitude for location-specific calculations'),
+    format: z.enum(['json', 'text']).optional().describe('Output format (json or text)')
+});
+/**
+ * Parameters for getting moon phases for a date range
+ */
+export const MoonPhasesRangeParamsSchema = z.object({
+    start_date: z.string().describe('Start date (YYYY-MM-DD format)'),
+    end_date: z.string().describe('End date (YYYY-MM-DD format)'),
+    latitude: z.number().min(-90).max(90).optional().describe('Latitude for location-specific calculations'),
+    longitude: z.number().min(-180).max(180).optional().describe('Longitude for location-specific calculations'),
+    format: z.enum(['json', 'text']).optional().describe('Output format (json or text)')
+});
+/**
+ * Parameters for getting next moon phase
+ */
+export const NextMoonPhaseParamsSchema = z.object({
+    phase: z.enum([
+        MoonPhaseName.NEW_MOON,
+        MoonPhaseName.FIRST_QUARTER,
+        MoonPhaseName.FULL_MOON,
+        MoonPhaseName.LAST_QUARTER
+    ]).describe('Moon phase to find'),
+    date: z.string().optional().describe('Starting date (YYYY-MM-DD format). Defaults to current date.'),
+    count: z.number().positive().optional().describe('Number of occurrences to return. Defaults to 1.'),
+    format: z.enum(['json', 'text']).optional().describe('Output format (json or text)')
+});