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

package/src/interfaces/noaa.ts

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+
+// Common parameter schemas
+const StationSchema = z.string().min(1).describe('Station ID');
+const DateSchema = z.string().optional().describe('Date to retrieve data for ("today", "latest", "recent", or specific date)');
+const BeginDateSchema = z.string().optional().describe('Start date (YYYYMMDD or MM/DD/YYYY)');
+const EndDateSchema = z.string().optional().describe('End date (YYYYMMDD or MM/DD/YYYY)');
+const RangeSchema = z.number().optional().describe('Number of hours to retrieve data for');
+const DatumSchema = z.string().optional().describe('Datum to use (MLLW, MSL, etc.)');
+const UnitsSchema = z.enum(['english', 'metric']).optional().describe('Units to use ("english" or "metric")');
+const TimeZoneSchema = z.enum(['gmt', 'lst', 'lst_ldt']).optional().describe('Time zone (gmt, lst, lst_ldt)');
+const FormatSchema = z.enum(['json', 'xml', 'csv']).optional().describe('Output format (json, xml, csv)');
+const BinSchema = z.number().optional().describe('Bin number');
+const IntervalSchema = z.string().optional().describe('Interval (hilo, hl, h, or a number for minutes)');
+
+// Water Level Schema
+export const GetWaterLevelsSchema = z.object({
+  station: StationSchema,
+  date: DateSchema,
+  begin_date: BeginDateSchema,
+  end_date: EndDateSchema,
+  range: RangeSchema,
+  datum: DatumSchema,
+  units: UnitsSchema,
+  time_zone: TimeZoneSchema,
+  format: FormatSchema,
+}).refine(
+  data => (data.date || (data.begin_date && data.end_date) || (data.begin_date && data.range) || (data.end_date && data.range) || data.range),
+  { message: "You must provide either 'date', 'begin_date' and 'end_date', 'begin_date' and 'range', 'end_date' and 'range', or just 'range'" }
+);
+
+// Tide Predictions Schema
+export const GetTidePredictionsSchema = z.object({
+  station: StationSchema,
+  begin_date: BeginDateSchema,
+  end_date: EndDateSchema,
+  date: DateSchema,
+  range: RangeSchema,
+  datum: DatumSchema,
+  units: UnitsSchema,
+  time_zone: TimeZoneSchema,
+  interval: IntervalSchema,
+  format: FormatSchema,
+}).refine(
+  data => (data.date || (data.begin_date && data.end_date) || (data.begin_date && data.range) || (data.end_date && data.range) || data.range),
+  { message: "You must provide either 'date', 'begin_date' and 'end_date', 'begin_date' and 'range', 'end_date' and 'range', or just 'range'" }
+);
+
+// Currents Schema
+export const GetCurrentsSchema = z.object({
+  station: StationSchema,
+  date: DateSchema,
+  begin_date: BeginDateSchema,
+  end_date: EndDateSchema,
+  range: RangeSchema,
+  bin: BinSchema,
+  units: UnitsSchema,
+  time_zone: TimeZoneSchema,
+  format: FormatSchema,
+}).refine(
+  data => (data.date || (data.begin_date && data.end_date) || (data.begin_date && data.range) || (data.end_date && data.range) || data.range),
+  { message: "You must provide either 'date', 'begin_date' and 'end_date', 'begin_date' and 'range', 'end_date' and 'range', or just 'range'" }
+);
+
+// Current Predictions Schema
+export const GetCurrentPredictionsSchema = z.object({
+  station: StationSchema,
+  date: DateSchema,
+  begin_date: BeginDateSchema,
+  end_date: EndDateSchema,
+  range: RangeSchema,
+  bin: BinSchema,
+  interval: z.string().optional().describe('Interval (MAX_SLACK or a number for minutes)'),
+  vel_type: z.enum(['speed_dir', 'default']).optional().describe('Velocity type (speed_dir or default)'),
+  units: UnitsSchema,
+  time_zone: TimeZoneSchema,
+  format: FormatSchema,
+}).refine(
+  data => (data.date || (data.begin_date && data.end_date) || (data.begin_date && data.range) || (data.end_date && data.range) || data.range),
+  { message: "You must provide either 'date', 'begin_date' and 'end_date', 'begin_date' and 'range', 'end_date' and 'range', or just 'range'" }
+);
+
+// Meteorological Data Schema
+export const GetMeteorologicalDataSchema = z.object({
+  station: StationSchema,
+  product: z.string().min(1).describe('Product (air_temperature, wind, etc.)'),
+  date: DateSchema,
+  begin_date: BeginDateSchema,
+  end_date: EndDateSchema,
+  range: RangeSchema,
+  units: UnitsSchema,
+  time_zone: TimeZoneSchema,
+  format: FormatSchema,
+}).refine(
+  data => (data.date || (data.begin_date && data.end_date) || (data.begin_date && data.range) || (data.end_date && data.range) || data.range),
+  { message: "You must provide either 'date', 'begin_date' and 'end_date', 'begin_date' and 'range', 'end_date' and 'range', or just 'range'" }
+);
+
+// Station List Schema
+export const GetStationsSchema = z.object({
+  type: z.string().optional().describe('Station type (waterlevels, currents, etc.)'),
+  units: UnitsSchema,
+  format: z.enum(['json', 'xml']).optional().describe('Output format (json, xml)'),
+  name: z.string().optional().describe('Filter stations by name (partial match)'),
+  lat_min: z.number().optional().describe('Minimum latitude boundary'),
+  lat_max: z.number().optional().describe('Maximum latitude boundary'),
+  lon_min: z.number().optional().describe('Minimum longitude boundary'),
+  lon_max: z.number().optional().describe('Maximum longitude boundary'),
+  state: z.string().optional().describe('Filter stations by state code (e.g., CA, NY)'),
+  limit: z.number().optional().describe('Maximum number of stations to return'),
+  offset: z.number().optional().describe('Number of stations to skip for pagination'),
+  sort_by: z.enum(['name', 'id', 'state']).optional().describe('Field to sort results by'),
+  sort_order: z.enum(['asc', 'desc']).optional().describe('Sort order (ascending or descending)'),
+});
+
+// Station Details Schema
+export const GetStationDetailsSchema = z.object({
+  station: StationSchema,
+  units: UnitsSchema,
+  format: z.enum(['json', 'xml']).optional().describe('Output format (json, xml)'),
+});
+
+// Define exported types
+export type GetWaterLevelsParams = z.infer<typeof GetWaterLevelsSchema>;
+export type GetTidePredictionsParams = z.infer<typeof GetTidePredictionsSchema>;
+export type GetCurrentsParams = z.infer<typeof GetCurrentsSchema>;
+export type GetCurrentPredictionsParams = z.infer<typeof GetCurrentPredictionsSchema>;
+export type GetMeteorologicalDataParams = z.infer<typeof GetMeteorologicalDataSchema>;
+export type GetStationsParams = z.infer<typeof GetStationsSchema>;
+export type GetStationDetailsParams = z.infer<typeof GetStationDetailsSchema>; 

package/src/interfaces/parameters.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+
+// Parameter type schema
+export const ParameterSchema = z.object({
+  parameter: z.string().optional().describe('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.')
+});
+
+export type GetParametersParams = z.infer<typeof ParameterSchema>;
+
+// Interface for parameter info responses
+export interface ParameterInfo {
+  id: string;
+  description: string;
+}
+
+export interface DateFormatInfo {
+  format: string;
+  description: string;
+  example: string;
+} 

package/src/interfaces/sun.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { SunEventType } from '../types/sun.js';
+
+/**
+ * Parameters for getting sun times
+ */
+export const SunTimesParamsSchema = z.object({
+  date: z.string().optional().describe('Date to get sun times for (YYYY-MM-DD format). Defaults to current date.'),
+  latitude: z.number().min(-90).max(90).describe('Latitude for location-specific calculations'),
+  longitude: z.number().min(-180).max(180).describe('Longitude for location-specific calculations'),
+  format: z.enum(['json', 'text']).optional().describe('Output format (json or text)'),
+  timezone: z.string().optional().describe('Timezone for the results. Defaults to UTC.')
+});
+
+export type SunTimesParams = z.infer<typeof SunTimesParamsSchema>;
+
+/**
+ * Parameters for getting sun times for a date range
+ */
+export const SunTimesRangeParamsSchema = 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).describe('Latitude for location-specific calculations'),
+  longitude: z.number().min(-180).max(180).describe('Longitude for location-specific calculations'),
+  format: z.enum(['json', 'text']).optional().describe('Output format (json or text)'),
+  timezone: z.string().optional().describe('Timezone for the results. Defaults to UTC.')
+});
+
+export type SunTimesRangeParams = z.infer<typeof SunTimesRangeParamsSchema>;
+
+/**
+ * Parameters for getting sun position
+ */
+export const SunPositionParamsSchema = z.object({
+  date: z.string().optional().describe('Date to get sun position for (YYYY-MM-DD format). Defaults to current date.'),
+  time: z.string().optional().describe('Time to get sun position for (HH:MM:SS format). Defaults to current time.'),
+  latitude: z.number().min(-90).max(90).describe('Latitude for location-specific calculations'),
+  longitude: z.number().min(-180).max(180).describe('Longitude for location-specific calculations'),
+  format: z.enum(['json', 'text']).optional().describe('Output format (json or text)')
+});
+
+export type SunPositionParams = z.infer<typeof SunPositionParamsSchema>;
+
+/**
+ * Parameters for finding the next sun event
+ */
+export const NextSunEventParamsSchema = z.object({
+  event: z.nativeEnum(SunEventType).describe('Sun event to find'),
+  date: z.string().optional().describe('Starting date (YYYY-MM-DD format). Defaults to current date.'),
+  latitude: z.number().min(-90).max(90).describe('Latitude for location-specific calculations'),
+  longitude: z.number().min(-180).max(180).describe('Longitude for location-specific calculations'),
+  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)'),
+  timezone: z.string().optional().describe('Timezone for the results. Defaults to UTC.')
+});
+
+export type NextSunEventParams = z.infer<typeof NextSunEventParamsSchema>; 

package/src/schemas/common.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+// Common parameter schemas
+export const StationSchema = z.string().min(1).describe('Station ID');
+export const DateSchema = z.string().optional().describe('Date to retrieve data for ("today", "latest", "recent", or specific date)');
+export const BeginDateSchema = z.string().optional().describe('Start date (YYYYMMDD or MM/DD/YYYY)');
+export const EndDateSchema = z.string().optional().describe('End date (YYYYMMDD or MM/DD/YYYY)');
+export const RangeSchema = z.number().optional().describe('Number of hours to retrieve data for');
+export const DatumSchema = z.string().optional().describe('Datum to use (MLLW, MSL, etc.)');
+export const UnitsSchema = z.enum(['english', 'metric']).optional().describe('Units to use ("english" or "metric")');
+export const TimeZoneSchema = z.enum(['gmt', 'lst', 'lst_ldt']).optional().describe('Time zone (gmt, lst, lst_ldt)');
+export const FormatSchema = z.enum(['json', 'xml', 'csv']).optional().describe('Output format (json, xml, csv)');
+export const BinSchema = z.number().optional().describe('Bin number');
+export const IntervalSchema = z.string().optional().describe('Interval (hilo, hl, h, or a number for minutes)');
+
+// Schema refinement function for date parameters
+export const refineDateParams = (data: any) => 
+  (data.date || (data.begin_date && data.end_date) || 
+   (data.begin_date && data.range) || (data.end_date && data.range) || 
+   data.range);
+
+export const dateRefinementMessage = 
+  "You must provide either 'date', 'begin_date' and 'end_date', 'begin_date' and 'range', 'end_date' and 'range', or just 'range'"; 

package/src/schemas/dpapi.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+import { StationSchema, UnitsSchema, FormatSchema } from './common.js';
+
+// DPAPI-specific parameter schemas
+export const AffiliationSchema = z.enum(['Global', 'US']).optional().describe('Station affiliation (Global or US)');
+export const ScenarioSchema = z.enum(['all', 'low', 'intermediate-low', 'intermediate', 'intermediate-high', 'high', 'extreme']).optional().describe('Sea level rise scenario');
+export const SeasonSchema = z.enum(['DJF', 'MAM', 'JJA', 'SON']).optional().describe('Season months (DJF-Winter, MAM-Spring, JJA-Summer, SON-Fall)');
+export const DpapiDatumSchema = z.enum(['STND', 'MLLW', 'MHHW', 'GT', 'MSL', 'MLW', 'MHW']).optional().describe('Datum reference for DPAPI');
+export const ThresholdSchema = z.enum(['minor', 'moderate', 'major']).optional().describe('Flood threshold level');
+export const DecadeSchema = z.string().optional().describe('Decade for projections (e.g., "2050")');
+export const YearSchema = z.string().optional().describe('Year for analysis (YYYY format)');
+export const YearRangeSchema = z.string().optional().describe('Year range (YYYY-YYYY format)');
+
+// Sea Level Trends schema
+export const SeaLevelTrendsSchema = z.object({
+  station: StationSchema,
+  affil: AffiliationSchema,
+  format: FormatSchema
+}).describe('Get sea level trends for a station');
+
+// Extreme Water Levels schema
+export const ExtremeWaterLevelsSchema = z.object({
+  station: StationSchema,
+  units: UnitsSchema,
+  format: FormatSchema
+}).describe('Get extreme water levels for a station');
+
+// High Tide Flooding Daily schema
+export const HighTideFloodingDailySchema = z.object({
+  station: StationSchema,
+  format: FormatSchema,
+  datum: DpapiDatumSchema,
+  threshold: ThresholdSchema,
+  begin_date: z.string().optional().describe('Start date (YYYYMMDD format)'),
+  end_date: z.string().optional().describe('End date (YYYYMMDD format)'),
+  year: YearSchema
+}).describe('Get high tide flooding daily count data');
+
+// High Tide Flooding Monthly schema
+export const HighTideFloodingMonthlySchema = z.object({
+  station: StationSchema,
+  format: FormatSchema,
+  datum: DpapiDatumSchema,
+  threshold: ThresholdSchema,
+  begin_date: z.string().optional().describe('Start date (YYYYMMDD format)'),
+  end_date: z.string().optional().describe('End date (YYYYMMDD format)'),
+  year: YearSchema
+}).describe('Get high tide flooding monthly count data');
+
+// High Tide Flooding Seasonal schema
+export const HighTideFloodingSeasonalSchema = z.object({
+  station: StationSchema,
+  format: FormatSchema,
+  datum: DpapiDatumSchema,
+  threshold: ThresholdSchema,
+  season_months: SeasonSchema,
+  begin_date: z.string().optional().describe('Start date (YYYYMMDD format)'),
+  end_date: z.string().optional().describe('End date (YYYYMMDD format)'),
+  year: YearSchema
+}).describe('Get high tide flooding seasonal count data');
+
+// High Tide Flooding Annual schema
+export const HighTideFloodingAnnualSchema = z.object({
+  station: StationSchema,
+  format: FormatSchema,
+  datum: DpapiDatumSchema,
+  threshold: ThresholdSchema,
+  begin_date: z.string().optional().describe('Start date (YYYYMMDD format)'),
+  end_date: z.string().optional().describe('End date (YYYYMMDD format)'),
+  year_range: YearRangeSchema
+}).describe('Get high tide flooding annual count data');
+
+// High Tide Flooding Projections schema
+export const HighTideFloodingProjectionsSchema = z.object({
+  station: StationSchema,
+  format: FormatSchema,
+  scenario: ScenarioSchema,
+  datum: DpapiDatumSchema,
+  threshold: ThresholdSchema,
+  decade: DecadeSchema
+}).describe('Get high tide flooding decadal projections');
+
+// High Tide Flooding Likelihoods schema
+export const HighTideFloodingLikelihoodsSchema = z.object({
+  station: StationSchema,
+  format: FormatSchema,
+  datum: DpapiDatumSchema,
+  threshold: ThresholdSchema,
+  date: z.string().optional().describe('Specific date (YYYYMMDD format)')
+}).describe('Get high tide flooding daily likelihoods');
+
+// Top Ten Water Levels schema
+export const TopTenWaterLevelsSchema = z.object({
+  station: StationSchema,
+  format: FormatSchema,
+  datum: DpapiDatumSchema,
+  units: UnitsSchema,
+  analysis_type: z.enum(['highest', 'lowest']).optional().describe('Analysis type (highest or lowest)')
+}).describe('Get top ten water levels for a station');

package/src/server/config.ts

@@ -0,0 +1,43 @@
+import { FastMCP } from 'fastmcp';
+
+/**
+ * Create and configure the FastMCP server
+ */
+export function createServer() {
+  // Create the MCP server with fixed configuration
+  const server = new FastMCP({
+    name: 'LocalTides',
+    version: '1.0.0'
+  });
+
+  return server;
+}
+
+/**
+ * Start the FastMCP server with configurable transport
+ */
+export function startServer(server: FastMCP) {
+  // Check command line arguments for transport type
+  const args = process.argv.slice(2);
+  const httpIndex = args.indexOf('--http');
+  const portIndex = args.indexOf('--port');
+  
+  if (httpIndex !== -1) {
+    // HTTP transport mode
+    const port = portIndex !== -1 && args[portIndex + 1] ? parseInt(args[portIndex + 1]) : 3000;
+    console.log(`Starting NOAA MCP server on HTTP port ${port}`);
+    server.start({ 
+      transportType: 'httpStream',
+      httpStream: {
+        endpoint: '/sse',
+        port: port
+      }
+    });
+  } else {
+    // Default stdio transport
+    console.log('Starting NOAA MCP server with stdio transport');
+    server.start({ 
+      transportType: 'stdio'
+    });
+  }
+} 

package/src/server/mcp-server.ts

@@ -0,0 +1,135 @@
+import { NoaaService } from '../services/noaa-service.js';
+import { ZodSchema } from 'zod';
+import {
+  GetWaterLevelsSchema,
+  GetTidePredictionsSchema,
+  GetCurrentsSchema,
+  GetCurrentPredictionsSchema,
+  GetMeteorologicalDataSchema,
+  GetStationsSchema,
+  GetStationDetailsSchema
+} from '../interfaces/noaa.js';
+
+// MCP Tool type
+interface MCPTool<TParams = any, TResult = any> {
+  name: string;
+  description: string;
+  inputSchema: ZodSchema<TParams>;
+  handler: (params: TParams) => Promise<TResult>;
+}
+
+// Class for the MCP server
+export class McpServer {
+  private tools: MCPTool[];
+  private noaaService: NoaaService;
+
+  constructor(noaaService: NoaaService) {
+    this.noaaService = noaaService;
+    this.tools = this.initializeTools();
+  }
+
+  // Initialize the tools
+  private initializeTools(): MCPTool[] {
+    // Water Levels tool
+    const getWaterLevels: MCPTool = {
+      name: "get_water_levels",
+      description: "Get water level data for a station",
+      inputSchema: GetWaterLevelsSchema,
+      handler: async (params) => {
+        return this.noaaService.getWaterLevels(params);
+      }
+    };
+
+    // Tide Predictions tool
+    const getTidePredictions: MCPTool = {
+      name: "get_tide_predictions",
+      description: "Get tide prediction data",
+      inputSchema: GetTidePredictionsSchema,
+      handler: async (params) => {
+        return this.noaaService.getTidePredictions(params);
+      }
+    };
+
+    // Currents tool
+    const getCurrents: MCPTool = {
+      name: "get_currents",
+      description: "Get currents data for a station",
+      inputSchema: GetCurrentsSchema,
+      handler: async (params) => {
+        return this.noaaService.getCurrents(params);
+      }
+    };
+
+    // Current Predictions tool
+    const getCurrentPredictions: MCPTool = {
+      name: "get_current_predictions",
+      description: "Get current predictions",
+      inputSchema: GetCurrentPredictionsSchema,
+      handler: async (params) => {
+        return this.noaaService.getCurrentPredictions(params);
+      }
+    };
+
+    // Meteorological Data tool
+    const getMeteorologicalData: MCPTool = {
+      name: "get_meteorological_data",
+      description: "Get meteorological data",
+      inputSchema: GetMeteorologicalDataSchema,
+      handler: async (params) => {
+        return this.noaaService.getMeteorologicalData(params);
+      }
+    };
+
+    // Stations tool
+    const getStations: MCPTool = {
+      name: "get_stations",
+      description: "Get list of stations",
+      inputSchema: GetStationsSchema,
+      handler: async (params) => {
+        return this.noaaService.getStations(params);
+      }
+    };
+
+    // Station Details tool
+    const getStationDetails: MCPTool = {
+      name: "get_station_details",
+      description: "Get detailed information about a station",
+      inputSchema: GetStationDetailsSchema,
+      handler: async (params) => {
+        return this.noaaService.getStationDetails(params);
+      }
+    };
+
+    return [
+      getWaterLevels,
+      getTidePredictions,
+      getCurrents,
+      getCurrentPredictions,
+      getMeteorologicalData,
+      getStations,
+      getStationDetails
+    ];
+  }
+
+  // Method to get all tools
+  getTools(): { name: string, description: string }[] {
+    return this.tools.map(tool => ({
+      name: tool.name,
+      description: tool.description
+    }));
+  }
+
+  // Method to handle tool execution
+  async executeTool(toolName: string, params: any): Promise<any> {
+    const tool = this.tools.find(t => t.name === toolName);
+    if (!tool) {
+      throw new Error(`Tool '${toolName}' not found`);
+    }
+
+    // Validate the parameters against the schema
+    const validatedParams = tool.inputSchema.parse(params);
+    
+    // Execute the tool handler
+    return tool.handler(validatedParams);
+  }
+}