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

package/src/services/dpapi-service.ts

@@ -0,0 +1,187 @@
+import axios from 'axios';
+
+// Base URL for the NOAA Derived Product API
+const DPAPI_BASE_URL = 'https://api.tidesandcurrents.noaa.gov/dpapi/prod';
+
+/**
+ * Service for interacting with NOAA Derived Product API (DPAPI)
+ */
+export class DpapiService {
+
+  /**
+   * Build parameters for the API request
+   * @param params Parameters for the request
+   * @returns URL-encoded parameters string
+   */
+  private buildParams(params: Record<string, any>): string {
+    // Remove undefined and null values
+    const filteredParams = Object.entries(params)
+      .filter(([_, value]) => value !== undefined && value !== null)
+      .reduce((acc, [key, value]) => {
+        acc[key] = value;
+        return acc;
+      }, {} as Record<string, any>);
+
+    // Convert to URL parameters
+    return new URLSearchParams(filteredParams as Record<string, string>).toString();
+  }
+
+  /**
+   * Make a request to the DPAPI
+   * @param endpoint Endpoint path
+   * @param params Parameters for the request
+   * @returns Response data
+   */
+  async fetchDpapi(endpoint: string, params: Record<string, any> = {}): Promise<any> {
+    try {
+      const queryParams = this.buildParams(params);
+      const url = `${DPAPI_BASE_URL}${endpoint}${queryParams ? '?' + queryParams : ''}`;
+      
+      const response = await axios.get(url);
+      return response.data;
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.response) {
+        throw new Error(`NOAA DPAPI Error: ${error.response.status} - ${JSON.stringify(error.response.data)}`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Get sea level trends for a station
+   * @param params Parameters including station ID and affiliation
+   * @returns Sea level trend data
+   */
+  async getSeaLevelTrends(params: Record<string, any>): Promise<any> {
+    const { station, affil = 'Global', format = 'json', ...rest } = params;
+    
+    return this.fetchDpapi('/sltrends', {
+      station,
+      affil,
+      format,
+      ...rest
+    });
+  }
+
+  /**
+   * Get extreme water levels for a station
+   * @param params Parameters including station ID and units
+   * @returns Extreme water level data
+   */
+  async getExtremeWaterLevels(params: Record<string, any>): Promise<any> {
+    const { station, units = 'english', format = 'json', ...rest } = params;
+    
+    return this.fetchDpapi('/ewl', {
+      station,
+      units,
+      format,
+      ...rest
+    });
+  }
+
+  /**
+   * Get high tide flooding daily count data
+   * @param params Parameters including station ID, date range, and thresholds
+   * @returns Daily flood count data
+   */
+  async getHighTideFloodingDaily(params: Record<string, any>): Promise<any> {
+    const { station, format = 'json', ...rest } = params;
+    
+    return this.fetchDpapi('/htf/daily', {
+      station,
+      format,
+      ...rest
+    });
+  }
+
+  /**
+   * Get high tide flooding monthly count data
+   * @param params Parameters including station ID, date range, and thresholds
+   * @returns Monthly flood count data
+   */
+  async getHighTideFloodingMonthly(params: Record<string, any>): Promise<any> {
+    const { station, format = 'json', ...rest } = params;
+    
+    return this.fetchDpapi('/htf/monthly', {
+      station,
+      format,
+      ...rest
+    });
+  }
+
+  /**
+   * Get high tide flooding seasonal count data
+   * @param params Parameters including station ID, seasons, and thresholds
+   * @returns Seasonal flood count data
+   */
+  async getHighTideFloodingSeasonal(params: Record<string, any>): Promise<any> {
+    const { station, format = 'json', ...rest } = params;
+    
+    return this.fetchDpapi('/htf/seasonal', {
+      station,
+      format,
+      ...rest
+    });
+  }
+
+  /**
+   * Get high tide flooding annual count data
+   * @param params Parameters including station ID, year range, and thresholds
+   * @returns Annual flood count data
+   */
+  async getHighTideFloodingAnnual(params: Record<string, any>): Promise<any> {
+    const { station, format = 'json', ...rest } = params;
+    
+    return this.fetchDpapi('/htf/annual', {
+      station,
+      format,
+      ...rest
+    });
+  }
+
+  /**
+   * Get high tide flooding decadal projections
+   * @param params Parameters including station ID, scenario, and decade
+   * @returns Decadal projection data
+   */
+  async getHighTideFloodingProjections(params: Record<string, any>): Promise<any> {
+    const { station, scenario = 'all', format = 'json', ...rest } = params;
+    
+    return this.fetchDpapi('/htf/projections', {
+      station,
+      scenario,
+      format,
+      ...rest
+    });
+  }
+
+  /**
+   * Get high tide flooding daily likelihoods
+   * @param params Parameters including station ID and date
+   * @returns Daily likelihood data
+   */
+  async getHighTideFloodingLikelihoods(params: Record<string, any>): Promise<any> {
+    const { station, format = 'json', ...rest } = params;
+    
+    return this.fetchDpapi('/htf/likelihoods', {
+      station,
+      format,
+      ...rest
+    });
+  }
+
+  /**
+   * Get top ten water levels for a station
+   * @param params Parameters including station ID and analysis type
+   * @returns Top ten water level data
+   */
+  async getTopTenWaterLevels(params: Record<string, any>): Promise<any> {
+    const { station, format = 'json', ...rest } = params;
+    
+    return this.fetchDpapi('/topten', {
+      station,
+      format,
+      ...rest
+    });
+  }
+}

package/src/services/moon-phase-service.ts

@@ -0,0 +1,167 @@
+import SunCalc from 'suncalc';
+import { MoonPhaseParams, MoonPhasesRangeParams, NextMoonPhaseParams } from '../interfaces/moon.js';
+import { MoonPhaseName, MoonPhaseInfo } from '../types/moon.js';
+
+/**
+ * Service for moon phase calculations
+ */
+export class MoonPhaseService {
+  /**
+   * Get the moon phase for a specific date
+   * @param params Parameters for the request
+   * @returns Moon phase information
+   */
+  getMoonPhase(params: MoonPhaseParams): MoonPhaseInfo {
+    const date = params.date ? new Date(params.date) : new Date();
+    
+    // Get moon illumination data
+    const illuminationData = SunCalc.getMoonIllumination(date);
+    
+    // Get moon position data (requires location)
+    const latitude = params.latitude ?? 0;
+    const longitude = params.longitude ?? 0;
+    const positionData = SunCalc.getMoonPosition(date, latitude, longitude);
+    
+    // Calculate moon phase name
+    const phaseName = this.getMoonPhaseName(illuminationData.phase);
+    
+    // Calculate if the moon is waxing (increasing illumination)
+    const isWaxing = illuminationData.phase < 0.5;
+    
+    // Calculate approximate moon age (0-29.53 days)
+    const lunarMonth = 29.53; // days
+    const age = illuminationData.phase * lunarMonth;
+    
+    // Calculate apparent diameter (in degrees)
+    const diameter = 0.5181 * (384400 / positionData.distance);
+    
+    return {
+      date: date.toISOString().split('T')[0],
+      phase: illuminationData.phase,
+      phaseName,
+      illumination: illuminationData.fraction,
+      age,
+      distance: positionData.distance,
+      diameter,
+      isWaxing
+    };
+  }
+
+  /**
+   * Get moon phases for a date range
+   * @param params Parameters for the request
+   * @returns Array of moon phase information
+   */
+  getMoonPhasesRange(params: MoonPhasesRangeParams): MoonPhaseInfo[] {
+    const startDate = new Date(params.start_date);
+    const endDate = new Date(params.end_date);
+    
+    if (isNaN(startDate.getTime()) || isNaN(endDate.getTime())) {
+      throw new Error('Invalid date format. Please use YYYY-MM-DD format.');
+    }
+    
+    if (startDate > endDate) {
+      throw new Error('Start date must be before end date.');
+    }
+    
+    const result: MoonPhaseInfo[] = [];
+    const currentDate = new Date(startDate);
+    
+    while (currentDate <= endDate) {
+      result.push(this.getMoonPhase({
+        date: currentDate.toISOString().split('T')[0],
+        latitude: params.latitude,
+        longitude: params.longitude
+      }));
+      
+      // Move to next day
+      currentDate.setDate(currentDate.getDate() + 1);
+    }
+    
+    return result;
+  }
+
+  /**
+   * Get the next occurrence(s) of a specific moon phase
+   * @param params Parameters for the request
+   * @returns Array of dates for the next occurrences of the specified phase
+   */
+  getNextMoonPhase(params: NextMoonPhaseParams): { date: string, phase: string }[] {
+    const startDate = params.date ? new Date(params.date) : new Date();
+    const count = params.count || 1;
+    const targetPhase = params.phase;
+    
+    // Map phase names to their approximate values
+    const phaseValues: Record<string, number> = {
+      [MoonPhaseName.NEW_MOON]: 0,
+      [MoonPhaseName.FIRST_QUARTER]: 0.25,
+      [MoonPhaseName.FULL_MOON]: 0.5,
+      [MoonPhaseName.LAST_QUARTER]: 0.75
+    };
+    
+    const targetPhaseValue = phaseValues[targetPhase];
+    const results: { date: string, phase: string }[] = [];
+    let currentDate = new Date(startDate);
+    
+    // Find the next occurrences
+    while (results.length < count) {
+      // Check every day (could be optimized with better algorithms)
+      const illuminationData = SunCalc.getMoonIllumination(currentDate);
+      const prevDate = new Date(currentDate);
+      prevDate.setDate(prevDate.getDate() - 1);
+      const prevIlluminationData = SunCalc.getMoonIllumination(prevDate);
+      
+      // Check if we've passed the target phase between yesterday and today
+      const prevDiff = Math.abs(prevIlluminationData.phase - targetPhaseValue);
+      const currentDiff = Math.abs(illuminationData.phase - targetPhaseValue);
+      
+      // If we're getting closer to the target phase and then further away, we've passed it
+      // Or if we're very close to the target phase (within 0.01)
+      if ((prevDiff > currentDiff && currentDiff < 0.01) || currentDiff < 0.005) {
+        results.push({
+          date: currentDate.toISOString().split('T')[0],
+          phase: targetPhase
+        });
+      }
+      
+      // Move to next day
+      currentDate.setDate(currentDate.getDate() + 1);
+      
+      // Safety check to prevent infinite loops
+      if (results.length === 0 && currentDate.getTime() - startDate.getTime() > 366 * 24 * 60 * 60 * 1000) {
+        throw new Error('Could not find the specified moon phase within a year.');
+      }
+    }
+    
+    return results;
+  }
+
+  /**
+   * Get the moon phase name based on the phase value (0-1)
+   * @param phase Phase value (0-1)
+   * @returns Moon phase name
+   */
+  private getMoonPhaseName(phase: number): MoonPhaseName {
+    // Normalize phase to 0-1 range
+    const normalizedPhase = phase < 0 ? phase + 1 : phase > 1 ? phase - 1 : phase;
+    
+    // Determine moon phase based on the value
+    if (normalizedPhase < 0.0625 || normalizedPhase >= 0.9375) {
+      return MoonPhaseName.NEW_MOON;
+    } else if (normalizedPhase < 0.1875) {
+      return MoonPhaseName.WAXING_CRESCENT;
+    } else if (normalizedPhase < 0.3125) {
+      return MoonPhaseName.FIRST_QUARTER;
+    } else if (normalizedPhase < 0.4375) {
+      return MoonPhaseName.WAXING_GIBBOUS;
+    } else if (normalizedPhase < 0.5625) {
+      return MoonPhaseName.FULL_MOON;
+    } else if (normalizedPhase < 0.6875) {
+      return MoonPhaseName.WANING_GIBBOUS;
+    } else if (normalizedPhase < 0.8125) {
+      return MoonPhaseName.LAST_QUARTER;
+    } else {
+      return MoonPhaseName.WANING_CRESCENT;
+    }
+  }
+} 

package/src/services/noaa-parameters-service.ts

@@ -0,0 +1,139 @@
+import axios from 'axios';
+
+/**
+ * Provides information about valid NOAA Tides and Currents API parameters
+ */
+export class NoaaParametersService {
+  /**
+   * Get valid time zone values
+   */
+  getTimeZones(): { id: string, description: string }[] {
+    return [
+      { id: 'gmt', description: 'Greenwich Mean Time' },
+      { id: 'lst', description: 'Local Standard Time' },
+      { id: 'lst_ldt', description: 'Local Standard/Local Daylight Time' }
+    ];
+  }
+
+  /**
+   * Get valid datum values
+   */
+  getDatums(): { id: string, description: string }[] {
+    return [
+      { id: 'MHHW', description: 'Mean Higher High Water' },
+      { id: 'MHW', description: 'Mean High Water' },
+      { id: 'MTL', description: 'Mean Tide Level' },
+      { id: 'MSL', description: 'Mean Sea Level' },
+      { id: 'MLW', description: 'Mean Low Water' },
+      { id: 'MLLW', description: 'Mean Lower Low Water' },
+      { id: 'NAVD', description: 'North American Vertical Datum' },
+      { id: 'STND', description: 'Station Datum' }
+    ];
+  }
+
+  /**
+   * Get valid units
+   */
+  getUnits(): { id: string, description: string }[] {
+    return [
+      { id: 'english', description: 'English units (feet, mph, etc.)' },
+      { id: 'metric', description: 'Metric units (meters, kph, etc.)' }
+    ];
+  }
+
+  /**
+   * Get valid intervals for tide predictions
+   */
+  getTidePredictionIntervals(): { id: string, description: string }[] {
+    return [
+      { id: 'hilo', description: 'High/low tide predictions only' },
+      { id: 'h', description: 'Hourly predictions' },
+      { id: '6', description: '6-minute predictions' },
+      { id: '30', description: '30-minute predictions' },
+      { id: '60', description: '60-minute predictions' }
+    ];
+  }
+
+  /**
+   * Get valid intervals for current predictions
+   */
+  getCurrentPredictionIntervals(): { id: string, description: string }[] {
+    return [
+      { id: 'MAX_SLACK', description: 'Maximum flood/ebb and slack predictions only' },
+      { id: '6', description: '6-minute predictions' },
+      { id: '30', description: '30-minute predictions' },
+      { id: '60', description: '60-minute predictions' }
+    ];
+  }
+
+  /**
+   * Get valid velocity types for current predictions
+   */
+  getVelocityTypes(): { id: string, description: string }[] {
+    return [
+      { id: 'default', description: 'Default velocity reporting (flood/ebb direction)' },
+      { id: 'speed_dir', description: 'Speed and direction format' }
+    ];
+  }
+
+  /**
+   * Get valid meteorological products
+   */
+  getMeteorologicalProducts(): { id: string, description: string }[] {
+    return [
+      { id: 'air_temperature', description: 'Air temperature' },
+      { id: 'water_temperature', description: 'Water temperature' },
+      { id: 'wind', description: 'Wind speed and direction' },
+      { id: 'air_pressure', description: 'Barometric pressure' },
+      { id: 'air_gap', description: 'Air gap (distance between bridge and water surface)' },
+      { id: 'conductivity', description: 'Conductivity' },
+      { id: 'visibility', description: 'Visibility' },
+      { id: 'humidity', description: 'Relative humidity' },
+      { id: 'salinity', description: 'Salinity' },
+      { id: 'hourly_height', description: 'Verified hourly height water level' },
+      { id: 'high_low', description: 'Verified high/low water level' },
+      { id: 'daily_mean', description: 'Verified daily mean water level' },
+      { id: 'monthly_mean', description: 'Verified monthly mean water level' },
+      { id: 'one_minute_water_level', description: 'One-minute water level data' },
+      { id: 'datums', description: 'Datums' }
+    ];
+  }
+
+  /**
+   * Get valid station types
+   */
+  getStationTypes(): { id: string, description: string }[] {
+    return [
+      { id: 'waterlevels', description: 'Water level stations' },
+      { id: 'currentpredictions', description: 'Current prediction stations' },
+      { id: 'currents', description: 'Current observation stations' },
+      { id: 'tidepredictions', description: 'Tide prediction stations' },
+      { id: 'weather', description: 'Weather stations' },
+      { id: 'ports', description: 'Physical Oceanographic Real-Time System (PORTS) stations' }
+    ];
+  }
+
+  /**
+   * Get valid date formats
+   */
+  getDateFormats(): { format: string, description: string, example: string }[] {
+    return [
+      { format: 'YYYYMMDD', description: 'Year, month, day without separators', example: '20230401' },
+      { format: 'MM/DD/YYYY', description: 'Month/day/year with separators', example: '04/01/2023' },
+      { format: 'today', description: 'Current date', example: 'today' },
+      { format: 'latest', description: 'Latest available data', example: 'latest' },
+      { format: 'recent', description: 'Most recent data', example: 'recent' }
+    ];
+  }
+
+  /**
+   * Get valid output formats
+   */
+  getOutputFormats(): { id: string, description: string }[] {
+    return [
+      { id: 'json', description: 'JSON format' },
+      { id: 'xml', description: 'XML format' },
+      { id: 'csv', description: 'CSV format (not available for all endpoints)' }
+    ];
+  }
+} 

package/src/services/noaa-service.ts

@@ -0,0 +1,171 @@
+import axios from 'axios';
+
+// Base URLs for the different NOAA APIs
+const DATA_API_BASE_URL = 'https://api.tidesandcurrents.noaa.gov/api/prod/datagetter';
+const METADATA_API_BASE_URL = 'https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi';
+
+/**
+ * Service for interacting with NOAA Tides and Currents APIs
+ */
+export class NoaaService {
+
+  /**
+   * Build parameters for the API request
+   * @param params Parameters for the request
+   * @returns URL-encoded parameters string
+   */
+  private buildParams(params: Record<string, any>): string {
+    // Remove undefined and null values
+    const filteredParams = Object.entries(params)
+      .filter(([_, value]) => value !== undefined && value !== null)
+      .reduce((acc, [key, value]) => {
+        acc[key] = value;
+        return acc;
+      }, {} as Record<string, any>);
+
+    // Convert to URL parameters
+    return new URLSearchParams(filteredParams as Record<string, string>).toString();
+  }
+
+  /**
+   * Make a request to the Data API
+   * @param params Parameters for the request
+   * @returns Response data
+   */
+  async fetchDataApi(params: Record<string, any>): Promise<any> {
+    try {
+      const queryParams = this.buildParams(params);
+      const url = `${DATA_API_BASE_URL}?${queryParams}`;
+      
+      const response = await axios.get(url);
+      return response.data;
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.response) {
+        throw new Error(`NOAA API Error: ${error.response.status} - ${JSON.stringify(error.response.data)}`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Make a request to the Metadata API
+   * @param endpoint Endpoint path
+   * @param params Parameters for the request
+   * @returns Response data
+   */
+  async fetchMetadataApi(endpoint: string, params: Record<string, any> = {}): Promise<any> {
+    try {
+      const queryParams = this.buildParams(params);
+      const url = `${METADATA_API_BASE_URL}${endpoint}${queryParams ? '?' + queryParams : ''}`;
+      
+      const response = await axios.get(url);
+      return response.data;
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.response) {
+        throw new Error(`NOAA API Error: ${error.response.status} - ${JSON.stringify(error.response.data)}`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Get water level data
+   */
+  async getWaterLevels(params: Record<string, any>): Promise<any> {
+    return this.fetchDataApi({
+      ...params,
+      product: 'water_level'
+    });
+  }
+
+  /**
+   * Get tide predictions
+   */
+  async getTidePredictions(params: Record<string, any>): Promise<any> {
+    return this.fetchDataApi({
+      ...params,
+      product: 'predictions'
+    });
+  }
+
+  /**
+   * Get currents data
+   */
+  async getCurrents(params: Record<string, any>): Promise<any> {
+    return this.fetchDataApi({
+      ...params,
+      product: 'currents'
+    });
+  }
+
+  /**
+   * Get current predictions
+   */
+  async getCurrentPredictions(params: Record<string, any>): Promise<any> {
+    return this.fetchDataApi({
+      ...params,
+      product: 'currents_predictions'
+    });
+  }
+
+  /**
+   * Get meteorological data (air_temperature, wind, etc.)
+   */
+  async getMeteorologicalData(params: Record<string, any>): Promise<any> {
+    const { product, ...rest } = params;
+    return this.fetchDataApi({
+      ...rest,
+      product
+    });
+  }
+
+  /**
+   * Get list of stations
+   */
+  async getStations(params: Record<string, any>): Promise<any> {
+    const { 
+      type, 
+      name, 
+      lat_min, 
+      lat_max, 
+      lon_min, 
+      lon_max, 
+      state, 
+      limit, 
+      offset, 
+      sort_by, 
+      sort_order, 
+      ...rest 
+    } = params;
+    
+    const endpoint = '/stations.' + (rest.format || 'json');
+    
+    // Build query parameters with all the filters
+    const queryParams: Record<string, any> = { ...rest };
+    
+    // Add filters only if they are defined
+    if (type) queryParams.type = type;
+    if (name) queryParams.name = name;
+    if (lat_min !== undefined) queryParams.lat_min = lat_min;
+    if (lat_max !== undefined) queryParams.lat_max = lat_max;
+    if (lon_min !== undefined) queryParams.lon_min = lon_min;
+    if (lon_max !== undefined) queryParams.lon_max = lon_max;
+    if (state) queryParams.state = state;
+    if (limit !== undefined) queryParams.limit = limit;
+    if (offset !== undefined) queryParams.offset = offset;
+    if (sort_by) queryParams.sort_by = sort_by;
+    if (sort_order) queryParams.sort_order = sort_order;
+    
+    return this.fetchMetadataApi(endpoint, queryParams);
+  }
+
+  /**
+   * Get station details
+   */
+  async getStationDetails(params: Record<string, any>): Promise<any> {
+    const { station, ...rest } = params;
+    const endpoint = `/stations/${station}/details.` + (rest.format || 'json');
+    
+    return this.fetchMetadataApi(endpoint, rest);
+  }
+}