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

package/dist/services/dpapi-service.js

@@ -0,0 +1,164 @@
+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
+     */
+    buildParams(params) {
+        // 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;
+        }, {});
+        // Convert to URL parameters
+        return new URLSearchParams(filteredParams).toString();
+    }
+    /**
+     * Make a request to the DPAPI
+     * @param endpoint Endpoint path
+     * @param params Parameters for the request
+     * @returns Response data
+     */
+    async fetchDpapi(endpoint, params = {}) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        const { station, format = 'json', ...rest } = params;
+        return this.fetchDpapi('/topten', {
+            station,
+            format,
+            ...rest
+        });
+    }
+}

package/dist/services/moon-phase-service.d.ts

@@ -0,0 +1,34 @@
+import { MoonPhaseParams, MoonPhasesRangeParams, NextMoonPhaseParams } from '../interfaces/moon.js';
+import { MoonPhaseInfo } from '../types/moon.js';
+/**
+ * Service for moon phase calculations
+ */
+export declare class MoonPhaseService {
+    /**
+     * Get the moon phase for a specific date
+     * @param params Parameters for the request
+     * @returns Moon phase information
+     */
+    getMoonPhase(params: MoonPhaseParams): MoonPhaseInfo;
+    /**
+     * Get moon phases for a date range
+     * @param params Parameters for the request
+     * @returns Array of moon phase information
+     */
+    getMoonPhasesRange(params: MoonPhasesRangeParams): MoonPhaseInfo[];
+    /**
+     * 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;
+    }[];
+    /**
+     * Get the moon phase name based on the phase value (0-1)
+     * @param phase Phase value (0-1)
+     * @returns Moon phase name
+     */
+    private getMoonPhaseName;
+}

package/dist/services/moon-phase-service.js

@@ -0,0 +1,147 @@
+import SunCalc from 'suncalc';
+import { MoonPhaseName } 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) {
+        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) {
+        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 = [];
+        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) {
+        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 = {
+            [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 = [];
+        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
+     */
+    getMoonPhaseName(phase) {
+        // 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/dist/services/noaa-parameters-service.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Provides information about valid NOAA Tides and Currents API parameters
+ */
+export declare class NoaaParametersService {
+    /**
+     * Get valid time zone values
+     */
+    getTimeZones(): {
+        id: string;
+        description: string;
+    }[];
+    /**
+     * Get valid datum values
+     */
+    getDatums(): {
+        id: string;
+        description: string;
+    }[];
+    /**
+     * Get valid units
+     */
+    getUnits(): {
+        id: string;
+        description: string;
+    }[];
+    /**
+     * Get valid intervals for tide predictions
+     */
+    getTidePredictionIntervals(): {
+        id: string;
+        description: string;
+    }[];
+    /**
+     * Get valid intervals for current predictions
+     */
+    getCurrentPredictionIntervals(): {
+        id: string;
+        description: string;
+    }[];
+    /**
+     * Get valid velocity types for current predictions
+     */
+    getVelocityTypes(): {
+        id: string;
+        description: string;
+    }[];
+    /**
+     * Get valid meteorological products
+     */
+    getMeteorologicalProducts(): {
+        id: string;
+        description: string;
+    }[];
+    /**
+     * Get valid station types
+     */
+    getStationTypes(): {
+        id: string;
+        description: string;
+    }[];
+    /**
+     * Get valid date formats
+     */
+    getDateFormats(): {
+        format: string;
+        description: string;
+        example: string;
+    }[];
+    /**
+     * Get valid output formats
+     */
+    getOutputFormats(): {
+        id: string;
+        description: string;
+    }[];
+}

package/dist/services/noaa-parameters-service.js

@@ -0,0 +1,128 @@
+/**
+ * Provides information about valid NOAA Tides and Currents API parameters
+ */
+export class NoaaParametersService {
+    /**
+     * Get valid time zone values
+     */
+    getTimeZones() {
+        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() {
+        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() {
+        return [
+            { id: 'english', description: 'English units (feet, mph, etc.)' },
+            { id: 'metric', description: 'Metric units (meters, kph, etc.)' }
+        ];
+    }
+    /**
+     * Get valid intervals for tide predictions
+     */
+    getTidePredictionIntervals() {
+        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() {
+        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() {
+        return [
+            { id: 'default', description: 'Default velocity reporting (flood/ebb direction)' },
+            { id: 'speed_dir', description: 'Speed and direction format' }
+        ];
+    }
+    /**
+     * Get valid meteorological products
+     */
+    getMeteorologicalProducts() {
+        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() {
+        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() {
+        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() {
+        return [
+            { id: 'json', description: 'JSON format' },
+            { id: 'xml', description: 'XML format' },
+            { id: 'csv', description: 'CSV format (not available for all endpoints)' }
+        ];
+    }
+}

package/dist/services/noaa-service.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Service for interacting with NOAA Tides and Currents APIs
+ */
+export declare class NoaaService {
+    /**
+     * Build parameters for the API request
+     * @param params Parameters for the request
+     * @returns URL-encoded parameters string
+     */
+    private buildParams;
+    /**
+     * Make a request to the Data API
+     * @param params Parameters for the request
+     * @returns Response data
+     */
+    fetchDataApi(params: Record<string, any>): Promise<any>;
+    /**
+     * Make a request to the Metadata API
+     * @param endpoint Endpoint path
+     * @param params Parameters for the request
+     * @returns Response data
+     */
+    fetchMetadataApi(endpoint: string, params?: Record<string, any>): Promise<any>;
+    /**
+     * Get water level data
+     */
+    getWaterLevels(params: Record<string, any>): Promise<any>;
+    /**
+     * Get tide predictions
+     */
+    getTidePredictions(params: Record<string, any>): Promise<any>;
+    /**
+     * Get currents data
+     */
+    getCurrents(params: Record<string, any>): Promise<any>;
+    /**
+     * Get current predictions
+     */
+    getCurrentPredictions(params: Record<string, any>): Promise<any>;
+    /**
+     * Get meteorological data (air_temperature, wind, etc.)
+     */
+    getMeteorologicalData(params: Record<string, any>): Promise<any>;
+    /**
+     * Get list of stations
+     */
+    getStations(params: Record<string, any>): Promise<any>;
+    /**
+     * Get station details
+     */
+    getStationDetails(params: Record<string, any>): Promise<any>;
+}