@dangahagan/weather-mcp 0.2.0 → 1.0.0

package/dist/index.js

@@ -11,16 +11,33 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 import { NOAAService } from './services/noaa.js';
 import { OpenMeteoService } from './services/openmeteo.js';
 import { CacheConfig } from './config/cache.js';
+import { logger } from './utils/logger.js';
+import { formatErrorForUser } from './errors/ApiError.js';
+import { handleGetForecast } from './handlers/forecastHandler.js';
+import { handleGetCurrentConditions } from './handlers/currentConditionsHandler.js';
+import { handleGetAlerts } from './handlers/alertsHandler.js';
+import { handleGetHistoricalWeather } from './handlers/historicalWeatherHandler.js';
+import { handleCheckServiceStatus } from './handlers/statusHandler.js';
+import { handleSearchLocation } from './handlers/locationHandler.js';
+import { handleGetAirQuality } from './handlers/airQualityHandler.js';
+import { handleGetMarineConditions } from './handlers/marineConditionsHandler.js';
 /**
  * Server information
  */
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+// Read version from package.json to ensure single source of truth
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJson = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
 const SERVER_NAME = 'weather-mcp';
-const SERVER_VERSION = '0.1.0';
+const SERVER_VERSION = packageJson.version;
 /**
  * Initialize the NOAA service
  */
 const noaaService = new NOAAService({
-    userAgent: '(weather-mcp, github.com/weather-mcp)'
+    userAgent: `weather-mcp/${SERVER_VERSION} (https://github.com/dgahagan/weather-mcp)`
 });
 /**
  * Initialize the Open-Meteo service for historical data
@@ -46,7 +63,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         tools: [
             {
                 name: 'get_forecast',
-                description: 'Get future weather forecast for a location (US only). Use this for upcoming weather predictions (e.g., "tomorrow", "this week", "next 7 days"). Returns forecast data including temperature, precipitation, wind, and conditions. For current weather, use get_current_conditions. For past weather, use get_historical_weather. If this tool returns an error, check the error message for status page links and consider using check_service_status to verify API availability.',
+                description: 'Get future weather forecast for a location (global coverage). Use this for upcoming weather predictions (e.g., "tomorrow", "this week", "next 7 days", "hourly forecast"). Returns forecast data including temperature, precipitation, wind, conditions, and sunrise/sunset times. Supports both daily and hourly granularity. Automatically selects best data source: NOAA for US locations (more detailed), Open-Meteo for international locations. For current weather, use get_current_conditions. For past weather, use get_historical_weather. If this tool returns an error, check the error message for status page links and consider using check_service_status to verify API availability.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -64,10 +81,32 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         },
                         days: {
                             type: 'number',
-                            description: 'Number of days to include in forecast (1-7, default: 7)',
+                            description: 'Number of days to include in forecast (1-16 for global, 1-7 for US NOAA, default: 7)',
                             minimum: 1,
-                            maximum: 7,
+                            maximum: 16,
                             default: 7
+                        },
+                        granularity: {
+                            type: 'string',
+                            description: 'Forecast granularity: "daily" for day/night periods or "hourly" for hour-by-hour detail (default: "daily")',
+                            enum: ['daily', 'hourly'],
+                            default: 'daily'
+                        },
+                        include_precipitation_probability: {
+                            type: 'boolean',
+                            description: 'Include precipitation probability in the forecast output (default: true)',
+                            default: true
+                        },
+                        include_severe_weather: {
+                            type: 'boolean',
+                            description: 'Include severe weather probabilities such as thunderstorm chance, wind gust probabilities, and tropical storm/hurricane risks (default: false, US/NOAA only)',
+                            default: false
+                        },
+                        source: {
+                            type: 'string',
+                            description: 'Data source: "auto" (default, selects NOAA for US or Open-Meteo for international), "noaa" (US only), or "openmeteo" (global)',
+                            enum: ['auto', 'noaa', 'openmeteo'],
+                            default: 'auto'
                         }
                     },
                     required: ['latitude', 'longitude']
@@ -75,7 +114,34 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'get_current_conditions',
-                description: 'Get the most recent weather observation for a location (US only). Use this for current weather or when asking about "today\'s weather", "right now", or recent conditions without a specific historical date range. Returns the latest observation from the nearest weather station. For specific past dates or date ranges, use get_historical_weather instead. If this tool returns an error, check the error message for status page links and consider using check_service_status to verify API availability.',
+                description: 'Get the most recent weather observation for a location (US only). Use this for current weather or when asking about "today\'s weather", "right now", or recent conditions without a specific historical date range. Returns the latest observation from the nearest weather station. Optionally includes fire weather indices (Haines Index, Grassland Fire Danger, Red Flag Threat) when requested. For specific past dates or date ranges, use get_historical_weather instead. If this tool returns an error, check the error message for status page links and consider using check_service_status to verify API availability.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        latitude: {
+                            type: 'number',
+                            description: 'Latitude of the location (-90 to 90)',
+                            minimum: -90,
+                            maximum: 90
+                        },
+                        longitude: {
+                            type: 'number',
+                            description: 'Longitude of the location (-180 to 180)',
+                            minimum: -180,
+                            maximum: 180
+                        },
+                        include_fire_weather: {
+                            type: 'boolean',
+                            description: 'Include fire weather indices (Haines Index, Grassland Fire Danger, Red Flag Threat) in the response (default: false, US only)',
+                            default: false
+                        }
+                    },
+                    required: ['latitude', 'longitude']
+                }
+            },
+            {
+                name: 'get_alerts',
+                description: 'Get active weather alerts, watches, warnings, and advisories for a location (US only). Use this for safety-critical weather information when asked about "any alerts?", "weather warnings?", "is it safe?", "dangerous weather?", or "weather watches?". Returns severity, urgency, certainty, effective/expiration times, and affected areas. For forecast data, use get_forecast instead. If this tool returns an error, check the error message for status page links and consider using check_service_status to verify API availability.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -90,6 +156,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: 'Longitude of the location (-180 to 180)',
                             minimum: -180,
                             maximum: 180
+                        },
+                        active_only: {
+                            type: 'boolean',
+                            description: 'Whether to show only active alerts (default: true)',
+                            default: true
                         }
                     },
                     required: ['latitude', 'longitude']
@@ -140,6 +211,81 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     properties: {},
                     required: []
                 }
+            },
+            {
+                name: 'search_location',
+                description: 'Search for locations by name to get coordinates for weather queries. Use this when the user provides a location name instead of coordinates (e.g., "Paris", "New York", "Tokyo", "San Francisco, CA"). Returns location matches with coordinates, timezone, elevation, and other metadata. Enables natural language location queries like "What\'s the weather in Paris?" by converting location names to coordinates.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        query: {
+                            type: 'string',
+                            description: 'Location name to search for (e.g., "Paris", "New York, NY", "Tokyo")'
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Maximum number of results to return (1-100, default: 5)',
+                            minimum: 1,
+                            maximum: 100,
+                            default: 5
+                        }
+                    },
+                    required: ['query']
+                }
+            },
+            {
+                name: 'get_air_quality',
+                description: 'Get air quality data including AQI (Air Quality Index), pollutant concentrations, and UV index for a location (global coverage). Use this when asked about "air quality", "pollution", "AQI", "UV index", "safe to exercise outside", or health-related environmental conditions. Returns current conditions and optional hourly forecast. Shows appropriate AQI scale (US AQI for US locations, European EAQI elsewhere) with health recommendations. Pollutants include PM2.5, PM10, ozone, NO2, SO2, and CO.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        latitude: {
+                            type: 'number',
+                            description: 'Latitude of the location (-90 to 90)',
+                            minimum: -90,
+                            maximum: 90
+                        },
+                        longitude: {
+                            type: 'number',
+                            description: 'Longitude of the location (-180 to 180)',
+                            minimum: -180,
+                            maximum: 180
+                        },
+                        forecast: {
+                            type: 'boolean',
+                            description: 'Include hourly air quality forecast for next 5 days (default: false, shows current only)',
+                            default: false
+                        }
+                    },
+                    required: ['latitude', 'longitude']
+                }
+            },
+            {
+                name: 'get_marine_conditions',
+                description: 'Get marine conditions including wave height, swell, ocean currents, and sea state for a location (global coverage). Use this when asked about "ocean conditions", "wave height", "surf conditions", "safe to boat", "marine forecast", "swell", or "sea state". Returns current conditions and optional daily/hourly forecast. Includes significant wave height, wind waves, swell, wave period, and ocean currents. Shows safety assessment for maritime activities. NOTE: Data has limited accuracy in coastal areas and is NOT suitable for coastal navigation - always consult official marine forecasts.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        latitude: {
+                            type: 'number',
+                            description: 'Latitude of the location (-90 to 90)',
+                            minimum: -90,
+                            maximum: 90
+                        },
+                        longitude: {
+                            type: 'number',
+                            description: 'Longitude of the location (-180 to 180)',
+                            minimum: -180,
+                            maximum: 180
+                        },
+                        forecast: {
+                            type: 'boolean',
+                            description: 'Include marine forecast for next 5 days (default: false, shows current only)',
+                            default: false
+                        }
+                    },
+                    required: ['latitude', 'longitude']
+                }
             }
         ]
     };
@@ -151,382 +297,39 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
         switch (name) {
-            case 'get_forecast': {
-                const { latitude, longitude, days = 7 } = args;
-                // Get forecast data
-                const forecast = await noaaService.getForecastByCoordinates(latitude, longitude);
-                const periods = forecast.properties.periods.slice(0, days * 2); // Each day typically has 2 periods (day/night)
-                // Format the forecast for display
-                let output = `# Weather Forecast\n\n`;
-                output += `**Location:** ${forecast.properties.elevation.value}m elevation\n`;
-                output += `**Updated:** ${new Date(forecast.properties.updated).toLocaleString()}\n\n`;
-                for (const period of periods) {
-                    output += `## ${period.name}\n`;
-                    output += `**Temperature:** ${period.temperature}°${period.temperatureUnit}\n`;
-                    output += `**Wind:** ${period.windSpeed} ${period.windDirection}\n`;
-                    output += `**Forecast:** ${period.shortForecast}\n\n`;
-                    if (period.detailedForecast) {
-                        output += `${period.detailedForecast}\n\n`;
-                    }
-                }
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: output
-                        }
-                    ]
-                };
-            }
-            case 'get_current_conditions': {
-                const { latitude, longitude } = args;
-                // Get current observation
-                const observation = await noaaService.getCurrentConditions(latitude, longitude);
-                const props = observation.properties;
-                // Format current conditions
-                let output = `# Current Weather Conditions\n\n`;
-                output += `**Station:** ${props.station}\n`;
-                output += `**Time:** ${new Date(props.timestamp).toLocaleString()}\n\n`;
-                if (props.textDescription) {
-                    output += `**Conditions:** ${props.textDescription}\n`;
-                }
-                if (props.temperature.value !== null) {
-                    const tempF = props.temperature.unitCode.includes('degC')
-                        ? (props.temperature.value * 9 / 5) + 32
-                        : props.temperature.value;
-                    output += `**Temperature:** ${Math.round(tempF)}°F\n`;
-                }
-                if (props.dewpoint.value !== null) {
-                    const dewF = props.dewpoint.unitCode.includes('degC')
-                        ? (props.dewpoint.value * 9 / 5) + 32
-                        : props.dewpoint.value;
-                    output += `**Dewpoint:** ${Math.round(dewF)}°F\n`;
-                }
-                if (props.relativeHumidity.value !== null) {
-                    output += `**Humidity:** ${Math.round(props.relativeHumidity.value)}%\n`;
-                }
-                if (props.windSpeed.value !== null) {
-                    const windMph = props.windSpeed.unitCode.includes('km_h')
-                        ? props.windSpeed.value * 0.621371
-                        : props.windSpeed.value * 2.23694; // m/s to mph
-                    const windDir = props.windDirection.value;
-                    output += `**Wind:** ${Math.round(windMph)} mph`;
-                    if (windDir !== null) {
-                        output += ` from ${Math.round(windDir)}°`;
-                    }
-                    output += `\n`;
-                }
-                if (props.barometricPressure.value !== null) {
-                    const pressureInHg = props.barometricPressure.value * 0.0002953;
-                    output += `**Pressure:** ${pressureInHg.toFixed(2)} inHg\n`;
-                }
-                if (props.visibility.value !== null) {
-                    const visibilityMiles = props.visibility.value * 0.000621371;
-                    output += `**Visibility:** ${visibilityMiles.toFixed(1)} miles\n`;
-                }
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: output
-                        }
-                    ]
-                };
-            }
-            case 'get_historical_weather': {
-                const { latitude, longitude, start_date, end_date, limit = 168 } = args;
-                // Parse dates
-                const startTime = new Date(start_date);
-                const endTime = new Date(end_date);
-                // Validate date parsing
-                if (isNaN(startTime.getTime()) || isNaN(endTime.getTime())) {
-                    throw new Error('Invalid date format. Please use ISO format (YYYY-MM-DD or full ISO 8601 datetime).');
-                }
-                // Validate date range
-                if (startTime > endTime) {
-                    throw new Error(`Invalid date range: start date (${start_date}) must be before end date (${end_date}).`);
-                }
-                // Validate dates are not in the future
-                const now = new Date();
-                if (startTime > now) {
-                    throw new Error(`Start date (${start_date}) cannot be in the future. Current date is ${now.toISOString().split('T')[0]}.`);
-                }
-                if (endTime > now) {
-                    throw new Error(`End date (${end_date}) cannot be in the future. Current date is ${now.toISOString().split('T')[0]}.`);
-                }
-                // Determine which API to use based on date range
-                // If start date is more than 7 days old, use CDO API for archival data
-                const sevenDaysAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
-                const useArchivalData = startTime < sevenDaysAgo;
-                if (useArchivalData) {
-                    // Use Open-Meteo API for historical/archival data
-                    try {
-                        // Determine whether to use hourly or daily data based on date range
-                        const daysDiff = Math.ceil((endTime.getTime() - startTime.getTime()) / (1000 * 60 * 60 * 24));
-                        const useHourly = daysDiff <= 31; // Use hourly for up to 31 days
-                        const weatherData = await openMeteoService.getHistoricalWeather(latitude, longitude, start_date.split('T')[0], // Ensure YYYY-MM-DD format
-                        end_date.split('T')[0], useHourly);
-                        // Format the response based on data granularity
-                        if (useHourly && weatherData.hourly) {
-                            // Format hourly observations
-                            let output = `# Historical Weather Observations (Hourly)\n\n`;
-                            output += `**Period:** ${startTime.toLocaleDateString()} to ${endTime.toLocaleDateString()}\n`;
-                            output += `**Location:** ${weatherData.latitude.toFixed(4)}°N, ${Math.abs(weatherData.longitude).toFixed(4)}°${weatherData.longitude >= 0 ? 'E' : 'W'} (${weatherData.elevation}m elevation)\n`;
-                            output += `**Number of observations:** ${weatherData.hourly.time.length}\n`;
-                            output += `**Data source:** Open-Meteo Historical Weather API (Reanalysis)\n\n`;
-                            const maxObservations = Math.min(limit, weatherData.hourly.time.length);
-                            for (let i = 0; i < maxObservations; i++) {
-                                const time = new Date(weatherData.hourly.time[i]);
-                                output += `## ${time.toLocaleString()}\n`;
-                                if (weatherData.hourly.temperature_2m?.[i] !== null && weatherData.hourly.temperature_2m?.[i] !== undefined) {
-                                    output += `- **Temperature:** ${Math.round(weatherData.hourly.temperature_2m[i])}°F\n`;
-                                }
-                                if (weatherData.hourly.apparent_temperature?.[i] !== null && weatherData.hourly.apparent_temperature?.[i] !== undefined) {
-                                    output += `- **Feels Like:** ${Math.round(weatherData.hourly.apparent_temperature[i])}°F\n`;
-                                }
-                                if (weatherData.hourly.weather_code?.[i] !== null && weatherData.hourly.weather_code?.[i] !== undefined) {
-                                    output += `- **Conditions:** ${openMeteoService.getWeatherDescription(weatherData.hourly.weather_code[i])}\n`;
-                                }
-                                if (weatherData.hourly.precipitation?.[i] !== null && weatherData.hourly.precipitation?.[i] !== undefined && weatherData.hourly.precipitation[i] > 0) {
-                                    output += `- **Precipitation:** ${weatherData.hourly.precipitation[i].toFixed(2)} in\n`;
-                                }
-                                if (weatherData.hourly.snowfall?.[i] !== null && weatherData.hourly.snowfall?.[i] !== undefined && weatherData.hourly.snowfall[i] > 0) {
-                                    output += `- **Snowfall:** ${weatherData.hourly.snowfall[i].toFixed(1)} in\n`;
-                                }
-                                if (weatherData.hourly.wind_speed_10m?.[i] !== null && weatherData.hourly.wind_speed_10m?.[i] !== undefined) {
-                                    output += `- **Wind:** ${Math.round(weatherData.hourly.wind_speed_10m[i])} mph`;
-                                    if (weatherData.hourly.wind_direction_10m?.[i] !== null && weatherData.hourly.wind_direction_10m?.[i] !== undefined) {
-                                        output += ` from ${Math.round(weatherData.hourly.wind_direction_10m[i])}°`;
-                                    }
-                                    output += `\n`;
-                                }
-                                if (weatherData.hourly.relative_humidity_2m?.[i] !== null && weatherData.hourly.relative_humidity_2m?.[i] !== undefined) {
-                                    output += `- **Humidity:** ${Math.round(weatherData.hourly.relative_humidity_2m[i])}%\n`;
-                                }
-                                if (weatherData.hourly.pressure_msl?.[i] !== null && weatherData.hourly.pressure_msl?.[i] !== undefined) {
-                                    const pressureInHg = weatherData.hourly.pressure_msl[i] * 0.02953;
-                                    output += `- **Pressure:** ${pressureInHg.toFixed(2)} inHg\n`;
-                                }
-                                if (weatherData.hourly.cloud_cover?.[i] !== null && weatherData.hourly.cloud_cover?.[i] !== undefined) {
-                                    output += `- **Cloud Cover:** ${weatherData.hourly.cloud_cover[i]}%\n`;
-                                }
-                                output += `\n`;
-                            }
-                            return {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: output
-                                    }
-                                ]
-                            };
-                        }
-                        else if (weatherData.daily) {
-                            // Format daily summaries
-                            let output = `# Historical Weather Data (Daily Summaries)\n\n`;
-                            output += `**Period:** ${startTime.toLocaleDateString()} to ${endTime.toLocaleDateString()}\n`;
-                            output += `**Location:** ${weatherData.latitude.toFixed(4)}°N, ${Math.abs(weatherData.longitude).toFixed(4)}°${weatherData.longitude >= 0 ? 'E' : 'W'} (${weatherData.elevation}m elevation)\n`;
-                            output += `**Number of days:** ${weatherData.daily.time.length}\n`;
-                            output += `**Data source:** Open-Meteo Historical Weather API (Reanalysis)\n\n`;
-                            for (let i = 0; i < weatherData.daily.time.length; i++) {
-                                const date = new Date(weatherData.daily.time[i]);
-                                output += `## ${date.toLocaleDateString()}\n`;
-                                if (weatherData.daily.temperature_2m_max?.[i] !== null && weatherData.daily.temperature_2m_max?.[i] !== undefined) {
-                                    output += `- **High Temperature:** ${Math.round(weatherData.daily.temperature_2m_max[i])}°F\n`;
-                                }
-                                if (weatherData.daily.temperature_2m_min?.[i] !== null && weatherData.daily.temperature_2m_min?.[i] !== undefined) {
-                                    output += `- **Low Temperature:** ${Math.round(weatherData.daily.temperature_2m_min[i])}°F\n`;
-                                }
-                                if (weatherData.daily.temperature_2m_mean?.[i] !== null && weatherData.daily.temperature_2m_mean?.[i] !== undefined) {
-                                    output += `- **Average Temperature:** ${Math.round(weatherData.daily.temperature_2m_mean[i])}°F\n`;
-                                }
-                                if (weatherData.daily.weather_code?.[i] !== null && weatherData.daily.weather_code?.[i] !== undefined) {
-                                    output += `- **Conditions:** ${openMeteoService.getWeatherDescription(weatherData.daily.weather_code[i])}\n`;
-                                }
-                                if (weatherData.daily.precipitation_sum?.[i] !== null && weatherData.daily.precipitation_sum?.[i] !== undefined) {
-                                    output += `- **Precipitation:** ${weatherData.daily.precipitation_sum[i].toFixed(2)} in\n`;
-                                }
-                                if (weatherData.daily.snowfall_sum?.[i] !== null && weatherData.daily.snowfall_sum?.[i] !== undefined && weatherData.daily.snowfall_sum[i] > 0) {
-                                    output += `- **Snowfall:** ${weatherData.daily.snowfall_sum[i].toFixed(1)} in\n`;
-                                }
-                                if (weatherData.daily.wind_speed_10m_max?.[i] !== null && weatherData.daily.wind_speed_10m_max?.[i] !== undefined) {
-                                    output += `- **Max Wind Speed:** ${Math.round(weatherData.daily.wind_speed_10m_max[i])} mph\n`;
-                                }
-                                output += `\n`;
-                            }
-                            return {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: output
-                                    }
-                                ]
-                            };
-                        }
-                        else {
-                            throw new Error('No weather data available in response');
-                        }
-                    }
-                    catch (error) {
-                        // If Open-Meteo API fails, provide helpful error message
-                        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-                        throw new Error(`Unable to retrieve historical data: ${errorMessage}`);
-                    }
-                }
-                else {
-                    // Use real-time NOAA API for recent data (last 7 days)
-                    const observations = await noaaService.getHistoricalObservations(latitude, longitude, startTime, endTime, limit);
-                    if (!observations.features || observations.features.length === 0) {
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: `No historical observations found for the specified date range (${start_date} to ${end_date}).\n\nThis may occur because:\n- The dates are outside the station's available data range\n- There are gaps in the observation records for this location\n- The weather station near this location may not have archived data for these dates\n\nNote: Historical weather data availability varies by location and weather station. Some stations have limited historical records.`
-                                }
-                            ]
-                        };
-                    }
-                    // Format the observations
-                    let output = `# Historical Weather Observations\n\n`;
-                    output += `**Period:** ${startTime.toLocaleDateString()} to ${endTime.toLocaleDateString()}\n`;
-                    output += `**Number of observations:** ${observations.features.length}\n`;
-                    output += `**Data source:** NOAA Real-time API\n\n`;
-                    for (const obs of observations.features) {
-                        const props = obs.properties;
-                        output += `## ${new Date(props.timestamp).toLocaleString()}\n`;
-                        if (props.temperature.value !== null) {
-                            const tempF = props.temperature.unitCode.includes('degC')
-                                ? (props.temperature.value * 9 / 5) + 32
-                                : props.temperature.value;
-                            output += `- **Temperature:** ${Math.round(tempF)}°F\n`;
-                        }
-                        if (props.textDescription) {
-                            output += `- **Conditions:** ${props.textDescription}\n`;
-                        }
-                        if (props.windSpeed.value !== null) {
-                            const windMph = props.windSpeed.unitCode.includes('km_h')
-                                ? props.windSpeed.value * 0.621371
-                                : props.windSpeed.value * 2.23694;
-                            output += `- **Wind:** ${Math.round(windMph)} mph\n`;
-                        }
-                        output += `\n`;
-                    }
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: output
-                            }
-                        ]
-                    };
-                }
-            }
-            case 'check_service_status': {
-                // Check status of both services
-                const noaaStatus = await noaaService.checkServiceStatus();
-                const openMeteoStatus = await openMeteoService.checkServiceStatus();
-                // Format the status report
-                let output = `# Weather API Service Status\n\n`;
-                output += `**Check Time:** ${new Date().toLocaleString()}\n\n`;
-                // NOAA Status
-                output += `## NOAA Weather API (Forecasts & Current Conditions)\n\n`;
-                output += `**Status:** ${noaaStatus.operational ? '✅ Operational' : '❌ Issues Detected'}\n`;
-                output += `**Message:** ${noaaStatus.message}\n`;
-                output += `**Status Page:** ${noaaStatus.statusPage}\n`;
-                output += `**Coverage:** United States locations only\n\n`;
-                if (!noaaStatus.operational) {
-                    output += `**Recommended Actions:**\n`;
-                    output += `- Check planned outages: https://weather-gov.github.io/api/planned-outages\n`;
-                    output += `- View service notices: https://www.weather.gov/notification\n`;
-                    output += `- Report issues: nco.ops@noaa.gov or (301) 683-1518\n\n`;
-                }
-                // Open-Meteo Status
-                output += `## Open-Meteo API (Historical Weather Data)\n\n`;
-                output += `**Status:** ${openMeteoStatus.operational ? '✅ Operational' : '❌ Issues Detected'}\n`;
-                output += `**Message:** ${openMeteoStatus.message}\n`;
-                output += `**Status Page:** ${openMeteoStatus.statusPage}\n`;
-                output += `**Coverage:** Global (worldwide locations)\n\n`;
-                if (!openMeteoStatus.operational) {
-                    output += `**Recommended Actions:**\n`;
-                    output += `- Check production status: https://open-meteo.com/en/docs/model-updates\n`;
-                    output += `- View GitHub issues: https://github.com/open-meteo/open-meteo/issues\n`;
-                    output += `- Review documentation: https://open-meteo.com/en/docs\n\n`;
-                }
-                // Cache Statistics
-                if (CacheConfig.enabled) {
-                    output += `## Cache Statistics\n\n`;
-                    const noaaStats = noaaService.getCacheStats();
-                    const openMeteoStats = openMeteoService.getCacheStats();
-                    const totalHits = noaaStats.hits + openMeteoStats.hits;
-                    const totalMisses = noaaStats.misses + openMeteoStats.misses;
-                    const totalRequests = totalHits + totalMisses;
-                    const overallHitRate = totalRequests > 0 ? ((totalHits / totalRequests) * 100).toFixed(1) : '0.0';
-                    output += `**Cache Status:** ✅ Enabled\n`;
-                    output += `**Overall Hit Rate:** ${overallHitRate}%\n`;
-                    output += `**Total Cache Hits:** ${totalHits}\n`;
-                    output += `**Total Cache Misses:** ${totalMisses}\n`;
-                    output += `**Total Requests:** ${totalRequests}\n\n`;
-                    output += `### NOAA Service Cache\n`;
-                    output += `- Entries: ${noaaStats.size} / ${noaaStats.maxSize}\n`;
-                    output += `- Hit Rate: ${noaaService.cache.getHitRate().toFixed(1)}%\n`;
-                    output += `- Hits: ${noaaStats.hits}\n`;
-                    output += `- Misses: ${noaaStats.misses}\n`;
-                    output += `- Evictions: ${noaaStats.evictions}\n\n`;
-                    output += `### Open-Meteo Service Cache\n`;
-                    output += `- Entries: ${openMeteoStats.size} / ${openMeteoStats.maxSize}\n`;
-                    output += `- Hit Rate: ${openMeteoService.cache.getHitRate().toFixed(1)}%\n`;
-                    output += `- Hits: ${openMeteoStats.hits}\n`;
-                    output += `- Misses: ${openMeteoStats.misses}\n`;
-                    output += `- Evictions: ${openMeteoStats.evictions}\n\n`;
-                    output += `*Cache reduces API calls and improves performance for repeated queries.*\n\n`;
-                }
-                else {
-                    output += `## Cache Statistics\n\n`;
-                    output += `**Cache Status:** ❌ Disabled\n`;
-                    output += `*Set CACHE_ENABLED=true in environment to enable caching.*\n\n`;
-                }
-                // Overall status summary
-                const bothOperational = noaaStatus.operational && openMeteoStatus.operational;
-                const neitherOperational = !noaaStatus.operational && !openMeteoStatus.operational;
-                if (bothOperational) {
-                    output += `## Overall Status: ✅ All Services Operational\n\n`;
-                    output += `Both NOAA and Open-Meteo APIs are functioning normally. Weather data requests should succeed.\n`;
-                }
-                else if (neitherOperational) {
-                    output += `## Overall Status: ❌ Multiple Service Issues\n\n`;
-                    output += `Both weather APIs are experiencing issues. Please check the status pages above for updates.\n`;
-                }
-                else {
-                    output += `## Overall Status: ⚠️ Partial Service Availability\n\n`;
-                    if (noaaStatus.operational) {
-                        output += `NOAA API is operational: Forecasts and current conditions for US locations are available.\n`;
-                        output += `Open-Meteo API has issues: Historical weather data may be unavailable.\n`;
-                    }
-                    else {
-                        output += `Open-Meteo API is operational: Historical weather data is available globally.\n`;
-                        output += `NOAA API has issues: Forecasts and current conditions for US locations may be unavailable.\n`;
-                    }
-                }
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: output
-                        }
-                    ]
-                };
-            }
+            case 'get_forecast':
+                return await handleGetForecast(args, noaaService, openMeteoService);
+            case 'get_current_conditions':
+                return await handleGetCurrentConditions(args, noaaService);
+            case 'get_alerts':
+                return await handleGetAlerts(args, noaaService);
+            case 'get_historical_weather':
+                return await handleGetHistoricalWeather(args, noaaService, openMeteoService);
+            case 'check_service_status':
+                return await handleCheckServiceStatus(noaaService, openMeteoService);
+            case 'search_location':
+                return await handleSearchLocation(args, openMeteoService);
+            case 'get_air_quality':
+                return await handleGetAirQuality(args, openMeteoService);
+            case 'get_marine_conditions':
+                return await handleGetMarineConditions(args, openMeteoService);
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
     }
     catch (error) {
-        const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+        // Log the error with full details
+        logger.error('Tool execution error', error, {
+            tool: name,
+            args: args ? JSON.stringify(args) : undefined,
+        });
+        // Format error for user display (sanitized)
+        const userMessage = formatErrorForUser(error);
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Error: ${errorMessage}`
+                    text: userMessage
                 }
             ],
             isError: true
@@ -538,12 +341,51 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
  */
 async function main() {
     const transport = new StdioServerTransport();
-    await server.connect(transport);
-    // Log to stderr so it doesn't interfere with MCP communication
-    console.error('Weather MCP Server running on stdio');
+    // Set up graceful shutdown handlers
+    const shutdown = async (signal) => {
+        logger.info(`Received ${signal}, shutting down gracefully...`);
+        try {
+            // Clean up resources
+            noaaService.clearCache();
+            openMeteoService.clearCache();
+            logger.info('Cache cleared');
+            // Close server connection
+            await server.close();
+            logger.info('Server closed');
+            process.exit(0);
+        }
+        catch (error) {
+            logger.error('Error during shutdown', error);
+            process.exit(1);
+        }
+    };
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    try {
+        await server.connect(transport);
+        logger.info('Weather MCP Server started', {
+            version: SERVER_VERSION,
+            cacheEnabled: CacheConfig.enabled,
+            logLevel: process.env.LOG_LEVEL || 'INFO',
+        });
+    }
+    catch (error) {
+        logger.error('Failed to start server', error);
+        throw error;
+    }
 }
 main().catch((error) => {
-    console.error('Fatal error in main():', error);
+    logger.error('Fatal error in main()', error);
+    // Log structured error for monitoring
+    console.error(JSON.stringify({
+        timestamp: new Date().toISOString(),
+        level: 'FATAL',
+        message: 'Application failed to start',
+        error: {
+            message: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+        }
+    }));
     process.exit(1);
 });
 //# sourceMappingURL=index.js.map