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

package/src/tools/station-tools.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { FastMCP } from 'fastmcp';
+import { NoaaService } from '../services/noaa-service.js';
+import { 
+  StationSchema, 
+  UnitsSchema, 
+  FormatSchema
+} from '../schemas/common.js';
+
+/**
+ * Register station-related tools with the MCP server
+ */
+export function registerStationTools(server: FastMCP, noaaService: NoaaService) {
+  // Add stations tool
+  server.addTool({
+    name: 'get_stations',
+    description: 'Get list of stations',
+    parameters: z.object({
+      type: z.string().optional().describe('Station type (waterlevels, currents, etc.)'),
+      format: z.enum(['json', 'xml']).optional().describe('Output format (json, xml)'),
+      units: UnitsSchema,
+    }),
+    execute: async (params) => {
+      try {
+        const result = await noaaService.getStations(params);
+        return JSON.stringify(result);
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new Error(`Failed to get stations: ${error.message}`);
+        }
+        throw new Error('Failed to get stations');
+      }
+    }
+  });
+
+  // Add station details tool
+  server.addTool({
+    name: 'get_station_details',
+    description: 'Get detailed information about a station',
+    parameters: z.object({
+      station: StationSchema,
+      format: z.enum(['json', 'xml']).optional().describe('Output format (json, xml)'),
+      units: UnitsSchema,
+    }),
+    execute: async (params) => {
+      try {
+        const result = await noaaService.getStationDetails(params);
+        return JSON.stringify(result);
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new Error(`Failed to get station details: ${error.message}`);
+        }
+        throw new Error('Failed to get station details');
+      }
+    }
+  });
+} 

package/src/tools/sun-tools.ts

@@ -0,0 +1,120 @@
+import { FastMCP } from 'fastmcp';
+import { SunService } from '../services/sun-service.js';
+import { 
+  SunTimesParamsSchema, 
+  SunTimesRangeParamsSchema, 
+  SunPositionParamsSchema, 
+  NextSunEventParamsSchema 
+} from '../interfaces/sun.js';
+
+/**
+ * Register sun-related tools with the MCP server
+ */
+export function registerSunTools(server: FastMCP, sunService: SunService) {
+  // Add sun times tool
+  server.addTool({
+    name: 'get_sun_times',
+    description: 'Get sun rise/set and other sun event times for a specific date and location',
+    parameters: SunTimesParamsSchema,
+    execute: async (params) => {
+      try {
+        const result = sunService.getSunTimes(params);
+        if (params.format === 'text') {
+          let text = `Sun times for ${result.date} at latitude ${params.latitude}, longitude ${params.longitude}:\n`;
+          text += `Sunrise: ${result.sunrise || 'N/A'}\n`;
+          text += `Sunset: ${result.sunset || 'N/A'}\n`;
+          text += `Day length: ${Math.floor(result.dayLength / 60)}h ${Math.round(result.dayLength % 60)}m\n`;
+          text += `Solar noon: ${result.solarNoon || 'N/A'}\n`;
+          text += `Dawn: ${result.dawn || 'N/A'}\n`;
+          text += `Dusk: ${result.dusk || 'N/A'}\n`;
+          return text;
+        }
+        return JSON.stringify(result);
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new Error(`Failed to get sun times: ${error.message}`);
+        }
+        throw new Error('Failed to get sun times');
+      }
+    }
+  });
+
+  // Add sun times range tool
+  server.addTool({
+    name: 'get_sun_times_range',
+    description: 'Get sun rise/set and other sun event times for a date range and location',
+    parameters: SunTimesRangeParamsSchema,
+    execute: async (params) => {
+      try {
+        const results = sunService.getSunTimesRange(params);
+        if (params.format === 'text') {
+          let text = `Sun times from ${params.start_date} to ${params.end_date} at latitude ${params.latitude}, longitude ${params.longitude}:\n\n`;
+          
+          results.forEach(result => {
+            text += `Date: ${result.date}\n`;
+            text += `Sunrise: ${result.sunrise || 'N/A'}\n`;
+            text += `Sunset: ${result.sunset || 'N/A'}\n`;
+            text += `Day length: ${Math.floor(result.dayLength / 60)}h ${Math.round(result.dayLength % 60)}m\n\n`;
+          });
+          
+          return text;
+        }
+        return JSON.stringify(results);
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new Error(`Failed to get sun times range: ${error.message}`);
+        }
+        throw new Error('Failed to get sun times range');
+      }
+    }
+  });
+
+  // Add sun position tool
+  server.addTool({
+    name: 'get_sun_position',
+    description: 'Get sun position information for a specific date, time, and location',
+    parameters: SunPositionParamsSchema,
+    execute: async (params) => {
+      try {
+        const result = sunService.getSunPosition(params);
+        if (params.format === 'text') {
+          let text = `Sun position for ${result.date} ${result.time} at latitude ${params.latitude}, longitude ${params.longitude}:\n`;
+          text += `Azimuth: ${result.azimuth.toFixed(2)}°\n`;
+          text += `Altitude: ${result.altitude.toFixed(2)}°\n`;
+          text += `Declination: ${result.declination.toFixed(2)}°\n`;
+          text += `Right Ascension: ${result.rightAscension.toFixed(2)}h\n`;
+          return text;
+        }
+        return JSON.stringify(result);
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new Error(`Failed to get sun position: ${error.message}`);
+        }
+        throw new Error('Failed to get sun position');
+      }
+    }
+  });
+
+  // Add next sun event tool
+  server.addTool({
+    name: 'get_next_sun_event',
+    description: 'Get the next occurrence(s) of a specific sun event',
+    parameters: NextSunEventParamsSchema,
+    execute: async (params) => {
+      try {
+        const results = sunService.getNextSunEvent(params);
+        if (params.format === 'text') {
+          return results.map(result => 
+            `Next ${result.event}: ${result.date} at ${result.time}`
+          ).join('\n');
+        }
+        return JSON.stringify(results);
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new Error(`Failed to get next sun event: ${error.message}`);
+        }
+        throw new Error('Failed to get next sun event');
+      }
+    }
+  });
+} 

package/src/tools/water-tools.ts

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+import { FastMCP } from 'fastmcp';
+import { NoaaService } from '../services/noaa-service.js';
+import { 
+  StationSchema, 
+  DateSchema, 
+  BeginDateSchema, 
+  EndDateSchema, 
+  RangeSchema,
+  DatumSchema, 
+  UnitsSchema, 
+  TimeZoneSchema, 
+  FormatSchema,
+  BinSchema,
+  IntervalSchema,
+  refineDateParams,
+  dateRefinementMessage
+} from '../schemas/common.js';
+
+/**
+ * Register water-related tools with the MCP server
+ */
+export function registerWaterTools(server: FastMCP, noaaService: NoaaService) {
+  // Add water levels tool
+  server.addTool({
+    name: 'get_water_levels',
+    description: 'Get water level data for a station',
+    parameters: z.object({
+      station: StationSchema,
+      date: DateSchema,
+      begin_date: BeginDateSchema,
+      end_date: EndDateSchema,
+      range: RangeSchema,
+      datum: DatumSchema,
+      units: UnitsSchema,
+      time_zone: TimeZoneSchema,
+      format: FormatSchema,
+    }).refine(refineDateParams, { message: dateRefinementMessage }),
+    execute: async (params) => {
+      try {
+        const result = await noaaService.getWaterLevels(params);
+        return JSON.stringify(result);
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new Error(`Failed to get water levels: ${error.message}`);
+        }
+        throw new Error('Failed to get water levels');
+      }
+    }
+  });
+
+  // Add tide predictions tool
+  server.addTool({
+    name: 'get_tide_predictions',
+    description: 'Get tide prediction data',
+    parameters: 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(refineDateParams, { message: dateRefinementMessage }),
+    execute: async (params) => {
+      try {
+        const result = await noaaService.getTidePredictions(params);
+        return JSON.stringify(result);
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new Error(`Failed to get tide predictions: ${error.message}`);
+        }
+        throw new Error('Failed to get tide predictions');
+      }
+    }
+  });
+
+  // Add currents tool
+  server.addTool({
+    name: 'get_currents',
+    description: 'Get currents data for a station',
+    parameters: z.object({
+      station: StationSchema,
+      date: DateSchema,
+      begin_date: BeginDateSchema,
+      end_date: EndDateSchema,
+      range: RangeSchema,
+      bin: BinSchema,
+      units: UnitsSchema,
+      time_zone: TimeZoneSchema,
+      format: FormatSchema,
+    }).refine(refineDateParams, { message: dateRefinementMessage }),
+    execute: async (params) => {
+      try {
+        const result = await noaaService.getCurrents(params);
+        return JSON.stringify(result);
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new Error(`Failed to get currents: ${error.message}`);
+        }
+        throw new Error('Failed to get currents');
+      }
+    }
+  });
+
+  // Add current predictions tool
+  server.addTool({
+    name: 'get_current_predictions',
+    description: 'Get current predictions',
+    parameters: 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(refineDateParams, { message: dateRefinementMessage }),
+    execute: async (params) => {
+      try {
+        const result = await noaaService.getCurrentPredictions(params);
+        return JSON.stringify(result);
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new Error(`Failed to get current predictions: ${error.message}`);
+        }
+        throw new Error('Failed to get current predictions');
+      }
+    }
+  });
+
+  // Add meteorological data tool
+  server.addTool({
+    name: 'get_meteorological_data',
+    description: 'Get meteorological data',
+    parameters: 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(refineDateParams, { message: dateRefinementMessage }),
+    execute: async (params) => {
+      try {
+        const result = await noaaService.getMeteorologicalData(params);
+        return JSON.stringify(result);
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new Error(`Failed to get meteorological data: ${error.message}`);
+        }
+        throw new Error('Failed to get meteorological data');
+      }
+    }
+  });
+} 

package/src/types/moon.ts

@@ -0,0 +1,27 @@
+/**
+ * Moon phase names and their approximate ranges
+ */
+export enum MoonPhaseName {
+  NEW_MOON = 'New Moon',
+  WAXING_CRESCENT = 'Waxing Crescent',
+  FIRST_QUARTER = 'First Quarter',
+  WAXING_GIBBOUS = 'Waxing Gibbous',
+  FULL_MOON = 'Full Moon',
+  WANING_GIBBOUS = 'Waning Gibbous',
+  LAST_QUARTER = 'Last Quarter',
+  WANING_CRESCENT = 'Waning Crescent'
+}
+
+/**
+ * Moon phase information
+ */
+export interface MoonPhaseInfo {
+  date: string;
+  phase: number;
+  phaseName: MoonPhaseName;
+  illumination: number;
+  age: number;
+  distance: number;
+  diameter: number;
+  isWaxing: boolean;
+} 

package/src/types/sun.ts

@@ -0,0 +1,51 @@
+/**
+ * Sun event types
+ */
+export enum SunEventType {
+  SUNRISE = 'sunrise',
+  SUNSET = 'sunset',
+  DAWN = 'dawn',
+  DUSK = 'dusk',
+  SOLAR_NOON = 'solarNoon',
+  NIGHT_START = 'night',
+  NIGHT_END = 'nightEnd',
+  GOLDEN_HOUR_START = 'goldenHourStart',
+  GOLDEN_HOUR_END = 'goldenHourEnd',
+  NAUTICAL_DAWN = 'nauticalDawn',
+  NAUTICAL_DUSK = 'nauticalDusk',
+  ASTRONOMICAL_DAWN = 'astronomicalDawn',
+  ASTRONOMICAL_DUSK = 'astronomicalDusk'
+}
+
+/**
+ * Sun times information
+ */
+export interface SunTimesInfo {
+  date: string;
+  sunrise: string | null;
+  sunset: string | null;
+  solarNoon: string | null;
+  dawn: string | null;
+  dusk: string | null;
+  nightStart: string | null;
+  nightEnd: string | null;
+  goldenHourStart: string | null;
+  goldenHourEnd: string | null;
+  nauticalDawn: string | null;
+  nauticalDusk: string | null;
+  astronomicalDawn: string | null;
+  astronomicalDusk: string | null;
+  dayLength: number; // in minutes
+}
+
+/**
+ * Sun position information
+ */
+export interface SunPositionInfo {
+  date: string;
+  time: string;
+  azimuth: number;
+  altitude: number;
+  declination: number;
+  rightAscension: number;
+} 

package/src/types/suncalc.d.ts

@@ -0,0 +1,110 @@
+declare module 'suncalc' {
+  export interface MoonIllumination {
+    /** fraction of moon's visible disk that is illuminated */
+    fraction: number;
+    /** moon phase (0.0-1.0) */
+    phase: number;
+    /** midpoint angle in radians of the illuminated limb of the moon reckoned eastward from the north point of the disk */
+    angle: number;
+  }
+
+  export interface MoonPosition {
+    /** moon azimuth in radians */
+    azimuth: number;
+    /** moon altitude above the horizon in radians */
+    altitude: number;
+    /** distance to moon in kilometers */
+    distance: number;
+    /** parallactic angle of the moon in radians */
+    parallacticAngle: number;
+  }
+
+  export interface SunPosition {
+    /** sun azimuth in radians (direction along the horizon, measured from south to west) */
+    azimuth: number;
+    /** sun altitude above the horizon in radians */
+    altitude: number;
+  }
+
+  export interface SunTimes {
+    /** sunrise (top edge of the sun appears on the horizon) */
+    sunrise: Date;
+    /** sunrise ends (bottom edge of the sun touches the horizon) */
+    sunriseEnd: Date;
+    /** morning golden hour (soft light, best time for photography) starts */
+    goldenHourEnd: Date;
+    /** solar noon (sun is in the highest position) */
+    solarNoon: Date;
+    /** evening golden hour starts */
+    goldenHour: Date;
+    /** sunset starts (bottom edge of the sun touches the horizon) */
+    sunsetStart: Date;
+    /** sunset (sun disappears below the horizon, evening civil twilight starts) */
+    sunset: Date;
+    /** dusk (evening nautical twilight starts) */
+    dusk: Date;
+    /** nautical dusk (evening astronomical twilight starts) */
+    nauticalDusk: Date;
+    /** astronomical dusk (evening astronomical twilight starts) */
+    astronomicalDusk: Date;
+    /** night starts (dark enough for astronomical observations) */
+    night: Date;
+    /** nadir (darkest moment of the night, sun is in the lowest position) */
+    nadir: Date;
+    /** night ends (morning astronomical twilight starts) */
+    nightEnd: Date;
+    /** astronomical dawn (morning astronomical twilight starts) */
+    astronomicalDawn: Date;
+    /** nautical dawn (morning nautical twilight starts) */
+    nauticalDawn: Date;
+    /** dawn (morning nautical twilight ends, morning civil twilight starts) */
+    dawn: Date;
+  }
+
+  export interface MoonTimes {
+    /** moonrise time as Date */
+    rise: Date | null;
+    /** moonset time as Date */
+    set: Date | null;
+    /** true if the moon never rises/sets and is always above the horizon during the day */
+    alwaysUp: boolean;
+    /** true if the moon is always below the horizon */
+    alwaysDown: boolean;
+  }
+
+  /**
+   * Calculates sun position for a given date and latitude/longitude
+   */
+  export function getPosition(date: Date | number, lat: number, lng: number): SunPosition;
+
+  /**
+   * Calculates sun times for a given date, latitude/longitude, and, optionally, the observer height (in meters) relative to the horizon
+   */
+  export function getTimes(date: Date | number, lat: number, lng: number, height?: number): SunTimes;
+
+  /**
+   * Returns an object with the following properties:
+   * altitude: moon altitude above the horizon in radians
+   * azimuth: moon azimuth in radians
+   * distance: distance to moon in kilometers
+   * parallacticAngle: parallactic angle of the moon in radians
+   */
+  export function getMoonPosition(date: Date | number, lat: number, lng: number): MoonPosition;
+
+  /**
+   * Returns an object with the following properties:
+   * fraction: illuminated fraction of the moon; varies from 0.0 (new moon) to 1.0 (full moon)
+   * phase: moon phase; varies from 0.0 to 1.0, described below
+   * angle: midpoint angle in radians of the illuminated limb of the moon reckoned eastward from the north point of the disk
+   */
+  export function getMoonIllumination(date: Date | number): MoonIllumination;
+
+  /**
+   * Returns an object with the following properties:
+   * rise: moonrise time as Date
+   * set: moonset time as Date
+   * alwaysUp: true if the moon never rises/sets and is always above the horizon during the day
+   * alwaysDown: true if the moon is always below the horizon
+   */
+  export function getMoonTimes(date: Date | number, lat: number, lng: number, inUTC?: boolean): MoonTimes;
+} 

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "esModuleInterop": true,
+    "strict": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "**/*.test.ts"]
+}