@dangahagan/weather-mcp 0.2.0 → 1.0.0

package/README.md

@@ -4,16 +4,71 @@
 [![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.dgahagan/weather-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-An MCP (Model Context Protocol) server that provides weather data to AI systems like Claude Code. Uses NOAA's API for US weather forecasts and current conditions, plus Open-Meteo for global historical weather data.
+An MCP (Model Context Protocol) server that provides **global weather data** to AI systems like Claude Code. Uses NOAA's API for detailed US weather, plus Open-Meteo for international forecasts and historical weather data worldwide.
 
 **📦 Available in the [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.dgahagan/weather-mcp)** as `io.github.dgahagan/weather-mcp`
 
-**No API keys required!** Both NOAA and Open-Meteo APIs are free to use with no authentication needed.
+**No API keys required!** All APIs (NOAA, Open-Meteo) are free to use with no authentication needed.
 
 ## Features
 
-- **Get Forecast**: Retrieve weather forecasts for any US location (7-day forecast)
-- **Current Conditions**: Get real-time weather observations for US locations
+- **Marine Conditions**: Comprehensive marine weather for coastal and ocean areas (NEW in v0.6.0)
+  - Global coverage for waves, swell, and ocean currents
+  - Significant wave height with safety categorization (Calm to Extreme)
+  - Wind waves (locally generated) and swell (distant systems) separation
+  - Wave period and direction for planning
+  - Ocean current velocity and direction
+  - Optional 5-day marine forecast with daily summaries
+  - Safety assessment for maritime activities (sailing, boating, surfing)
+  - Wave interpretation guide based on Douglas Sea Scale
+  - Important: Data has limited coastal accuracy - NOT for navigation
+- **Severe Weather Probabilities**: Probabilistic severe weather forecasting (NEW in v0.6.0)
+  - US locations only (NOAA gridpoint data)
+  - Optional enhancement to forecasts (`include_severe_weather` parameter)
+  - Thunderstorm probability for next 48 hours
+  - Wind gust probabilities (20-60+ mph categories)
+  - Tropical storm and hurricane wind probabilities
+  - Lightning activity levels
+  - Smart display showing only significant threats
+  - Works with both daily and hourly forecasts
+- **Air Quality Monitoring**: Comprehensive air quality data for any location worldwide (v0.5.0)
+  - Air Quality Index (AQI) with automatic region detection (US AQI or European EAQI)
+  - Health recommendations based on AQI levels
+  - Pollutant concentrations (PM2.5, PM10, O₃, NO₂, SO₂, CO, NH₃)
+  - UV Index with sun protection recommendations
+  - Optional hourly air quality forecasts (5-day outlook)
+  - Categorized health risk levels (Good, Moderate, Unhealthy, etc.)
+  - Activity recommendations for sensitive populations
+- **Fire Weather Data**: Fire danger indices for US locations (v0.5.0)
+  - Haines Index (atmospheric fire growth potential)
+  - Grassland Fire Danger Index
+  - Red Flag Threat Index
+  - Mixing Height (smoke dispersion indicator)
+  - Transport Wind Speed (smoke transport)
+  - Optional enhancement to current conditions
+- **Location Search**: Find coordinates for any location worldwide (v0.4.0)
+  - Convert location names to coordinates ("Paris" → 48.8534°, 2.3488°)
+  - Support for cities, airports, landmarks, and regions globally
+  - Detailed metadata: timezone, elevation, population, country
+  - Enables natural language queries: "What's the weather in Tokyo?"
+- **Global Weather Forecasts**: Get forecasts for any location worldwide (ENHANCED in v0.4.0)
+  - Automatic source selection: NOAA (US, more detailed) or Open-Meteo (international)
+  - Extended forecasts up to 16 days (was 7)
+  - Sunrise/sunset times with daylight duration
+  - Daily or hourly granularity
+  - Precipitation probability display
+  - Temperature trends, humidity, wind, and UV index
+- **Weather Alerts**: Get active weather watches, warnings, and advisories for US locations
+  - Severity levels (Extreme, Severe, Moderate, Minor)
+  - Urgency and certainty indicators
+  - Effective and expiration times
+  - Instructions and recommended responses
+- **Current Conditions**: Get enhanced real-time weather observations for US locations
+  - Heat index and wind chill when relevant
+  - 24-hour temperature range
+  - Wind gusts and detailed cloud cover
+  - Recent precipitation history
+  - Optional fire weather indices (see above)
 - **Historical Data**: Access historical weather observations for any location worldwide
   - Recent data (last 7 days): Detailed hourly observations from NOAA real-time API (US only)
   - Archival data (>7 days old): Hourly/daily weather data from 1940-present via Open-Meteo (global coverage)
@@ -36,6 +91,11 @@ The Weather MCP server includes an intelligent in-memory caching system that sig
 
 The cache automatically stores and retrieves weather data with intelligent expiration:
 
+- **Location Searches**: Cached for 30 days (locations don't move)
+- **Marine Conditions**: Cached for 1 hour (marine data updates hourly) - NEW in v0.6.0
+- **Air Quality Data**: Cached for 1 hour (air quality updates hourly) - v0.5.0
+- **Fire Weather Data**: Cached for 2 hours (gridpoint data updates ~hourly) - v0.5.0
+- **Weather Alerts**: Cached for 5 minutes (alerts can change rapidly)
 - **Forecasts**: Cached for 2 hours (updated approximately hourly)
 - **Current Conditions**: Cached for 15 minutes (observations update every 20-60 minutes)
 - **Historical Data (>1 day old)**: Cached indefinitely (finalized data never changes)
@@ -150,60 +210,109 @@ Restart Claude Code and the weather tools will be available.
 
 ## Finding Coordinates
 
-All tools require latitude and longitude coordinates. You can find coordinates for any location by:
-- Asking Claude Code: "What are the coordinates for [city name]?"
+**NEW in v0.4.0**: Use the built-in `search_location` tool to find coordinates automatically!
+
+```
+"What's the weather in Paris?"
+→ Uses search_location to find Paris coordinates (48.8534°, 2.3488°)
+→ Then gets the forecast for those coordinates
+```
+
+You can also find coordinates manually:
 - Using Google Maps: Right-click a location and select the coordinates
 - Using a geocoding service like geocode.maps.co or nominatim.org
 
-### Common US City Coordinates
+### Common City Coordinates (For Reference)
 
 | City | Latitude | Longitude |
 |------|----------|-----------|
-| San Francisco, CA | 37.7749 | -122.4194 |
+| Paris, France | 48.8534 | 2.3488 |
+| Tokyo, Japan | 35.6895 | 139.6917 |
+| London, UK | 51.5085 | -0.1257 |
 | New York, NY | 40.7128 | -74.0060 |
-| Chicago, IL | 41.8781 | -87.6298 |
-| Los Angeles, CA | 34.0522 | -118.2437 |
-| Denver, CO | 39.7392 | -104.9903 |
-| Miami, FL | 25.7617 | -80.1918 |
-| Seattle, WA | 47.6062 | -122.3321 |
-| Austin, TX | 30.2672 | -97.7431 |
+| San Francisco, CA | 37.7749 | -122.4194 |
+| Sydney, Australia | -33.8688 | 151.2093 |
+| Berlin, Germany | 52.5200 | 13.4050 |
+| Dubai, UAE | 25.2048 | 55.2708 |
 
 ## Available Tools
 
-### 1. check_service_status
-Check the operational status of weather APIs and cache performance.
+### 1. search_location (NEW in v0.4.0)
+Find coordinates for any location worldwide by name.
 
-**Parameters:** None
+**Parameters:**
+- `query` (required): Location name to search for (e.g., "Paris", "New York, NY", "Tokyo")
+- `limit` (optional): Maximum number of results to return (1-100, default: 5)
 
 **Description:**
-Performs health checks on both NOAA and Open-Meteo APIs to verify they are operational. Use this tool when experiencing errors or to proactively verify service availability before making weather data requests. Returns current status, helpful messages, links to official status pages, and cache statistics.
+Converts location names to coordinates using the Open-Meteo Geocoding API. Returns multiple matches with detailed metadata including coordinates, timezone, elevation, population, and administrative regions. Enables natural language weather queries by finding coordinates automatically.
 
-**Example:**
+**Examples:**
 ```
-Check if the weather services are operational
+"Find coordinates for Paris"
+"Search for Tokyo, Japan"
+"Where is San Francisco, CA?"
 ```
 
 **Returns:**
-- Operational status for NOAA API (forecasts & current conditions)
-- Operational status for Open-Meteo API (historical data)
-- Cache statistics (hit rate, size, API call reduction)
-- Status page links and recommended actions if issues are detected
-- Overall service availability summary
+- Location name and full administrative hierarchy
+- Latitude and longitude coordinates
+- Timezone and elevation
+- Population (when available)
+- Country and region information
+- Feature type (capital, city, airport, etc.)
 
-### 2. get_forecast
-Get weather forecast for a location.
+### 2. get_forecast (ENHANCED in v0.4.0)
+Get weather forecast for any location worldwide.
 
 **Parameters:**
 - `latitude` (required): Latitude coordinate (-90 to 90)
 - `longitude` (required): Longitude coordinate (-180 to 180)
-- `days` (optional): Number of days in forecast (1-7, default: 7)
+- `days` (optional): Number of days in forecast (1-16, default: 7)
+- `granularity` (optional): "daily" or "hourly" (default: "daily")
+- `include_precipitation_probability` (optional): Include rain chances (default: true)
+- `source` (optional): "auto" (default), "noaa" (US only), or "openmeteo" (global)
+
+**Description:**
+Automatically selects the best data source: NOAA for US locations (more detailed) or Open-Meteo for international locations. Supports extended forecasts up to 16 days. Includes sunrise/sunset times, daylight duration, temperature, precipitation, wind, and UV index.
+
+**Examples:**
+```
+"Get a 7-day forecast for Paris (48.8534, 2.3488)"
+"Hourly forecast for Tokyo for the next 3 days"
+"16-day extended forecast for Sydney, Australia"
+```
+
+**Returns:**
+- Temperature (high/low, feels like)
+- Sunrise and sunset times with daylight duration (NEW in v0.4.0)
+- Precipitation chances and amounts
+- Wind speed, direction, and gusts
+- Weather conditions and descriptions
+- UV index (for international locations)
+- Humidity and atmospheric conditions
+
+### 3. check_service_status
+Check the operational status of weather APIs and cache performance.
+
+**Parameters:** None
+
+**Description:**
+Performs health checks on both NOAA and Open-Meteo APIs to verify they are operational. Use this tool when experiencing errors or to proactively verify service availability before making weather data requests. Returns current status, helpful messages, links to official status pages, and cache statistics.
 
 **Example:**
 ```
-Get the weather forecast for San Francisco (latitude: 37.7749, longitude: -122.4194)
+Check if the weather services are operational
 ```
 
-### 3. get_current_conditions
+**Returns:**
+- Operational status for NOAA API (forecasts & current conditions)
+- Operational status for Open-Meteo API (historical data & forecasts)
+- Cache statistics (hit rate, size, API call reduction)
+- Status page links and recommended actions if issues are detected
+- Overall service availability summary
+
+### 4. get_current_conditions
 Get current weather conditions for a location.
 
 **Parameters:**
@@ -215,7 +324,7 @@ Get current weather conditions for a location.
 What are the current weather conditions in New York? (latitude: 40.7128, longitude: -74.0060)
 ```
 
-### 4. get_historical_weather
+### 5. get_historical_weather
 Get historical weather observations for a location.
 
 **Parameters:**
@@ -274,6 +383,88 @@ If you get "No historical data available":
 - Note: Most recent data has a 5-day delay
 - Very recent dates (last 5 days) may not be available in archival data yet
 
+### 6. get_alerts
+Get active weather alerts, watches, warnings, and advisories for US locations.
+
+**Parameters:**
+- `latitude` (required): Latitude coordinate (-90 to 90)
+- `longitude` (required): Longitude coordinate (-180 to 180)
+- `active_only` (optional): Show only active alerts (default: true)
+
+**Description:**
+Retrieves current weather alerts from the NOAA API for safety-critical weather information. Returns severity levels (Extreme, Severe, Moderate, Minor), urgency indicators, effective/expiration times, and affected areas. Alerts are automatically sorted by severity with the most critical first.
+
+**Examples:**
+```
+"Are there any weather alerts for Miami, Florida?"
+"Check for severe weather warnings in Oklahoma City"
+"What weather watches are active in my area?" (latitude: 40.7128, longitude: -74.0060)
+```
+
+**Returns:**
+- Alert type and severity (Extreme → Severe → Moderate → Minor)
+- Urgency, certainty, and response type
+- Event description and instructions
+- Effective and expiration times
+- Affected geographic areas
+- Recommended actions and safety information
+
+### 7. get_air_quality (NEW in v0.5.0)
+Get comprehensive air quality data for any location worldwide.
+
+**Parameters:**
+- `latitude` (required): Latitude coordinate (-90 to 90)
+- `longitude` (required): Longitude coordinate (-180 to 180)
+- `forecast` (optional): Include hourly forecast for next 5 days (default: false)
+
+**Description:**
+Provides current air quality conditions using the Open-Meteo Air Quality API with automatic AQI scale selection (US AQI for US locations, European EAQI elsewhere). Includes health recommendations, pollutant concentrations, and UV index.
+
+**Examples:**
+```
+"What's the air quality in Los Angeles?"
+"Check pollution levels in Beijing"
+"Get air quality forecast for Paris for the next 5 days"
+```
+
+**Returns:**
+- Air Quality Index (AQI) with appropriate scale (US or European)
+- Health risk category and recommendations
+- Pollutant concentrations (PM2.5, PM10, O₃, NO₂, SO₂, CO, NH₃)
+- UV Index with sun protection guidance
+- Activity recommendations for sensitive groups
+- Optional 5-day hourly forecast
+
+### 8. get_marine_conditions (NEW in v0.6.0)
+Get marine weather conditions including wave height, swell, ocean currents, and sea state.
+
+**Parameters:**
+- `latitude` (required): Latitude coordinate (-90 to 90)
+- `longitude` (required): Longitude coordinate (-180 to 180)
+- `forecast` (optional): Include 5-day marine forecast (default: false)
+
+**Description:**
+Provides comprehensive marine weather data using the Open-Meteo Marine API with global ocean coverage. Includes significant wave height with Douglas Sea Scale categorization, wind waves vs swell separation, wave period/direction, ocean currents, and safety assessment for maritime activities.
+
+**Important:** Data has limited accuracy in coastal areas and is NOT suitable for coastal navigation - always consult official marine forecasts.
+
+**Examples:**
+```
+"What are the ocean conditions off the coast of California?"
+"Get wave height and swell for surfing in Hawaii"
+"Check marine conditions in the Atlantic Ocean" (latitude: 30.0, longitude: -60.0)
+```
+
+**Returns:**
+- Significant wave height (meters/feet) with safety category
+- Wind waves (locally generated) height and direction
+- Swell height, period, and direction (from distant systems)
+- Ocean current velocity and direction
+- Sea state interpretation (Calm → Phenomenal based on Douglas Sea Scale)
+- Safety assessment for maritime activities
+- Wave period for planning and safety
+- Optional 5-day forecast with daily summaries
+
 ## Error Handling & Service Status
 
 ### Enhanced Error Messages
@@ -346,19 +537,45 @@ Use the `check_service_status` tool to proactively verify API availability:
 
 ## Testing
 
-### Quick Test
+### Automated Test Suite
+
+This project includes a comprehensive test suite with 247 automated tests:
 
-Verify NOAA API connectivity:
 ```bash
-npx tsx tests/test_noaa_api.ts
+# Run all tests
+npm test
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Run tests in watch mode (during development)
+npm run test:watch
+
+# Run tests with interactive UI
+npm run test:ui
 ```
 
-This runs 5 tests covering all major functionality with real NOAA API calls.
+**Test Coverage:**
+- **247 tests** across unit and integration test suites
+- **100% coverage** on critical utilities (cache, validation, units, errors)
+- **54% overall coverage** with focus on reliability and security
+- All tests execute in ~1 second
+
+**Test Categories:**
+- **Unit Tests** (228 tests) - Cache, validation, units, errors, config, retry logic
+- **Integration Tests** (19 tests) - Error recovery scenarios, service status checks
+
+### Quick API Connectivity Test
+
+Verify NOAA API connectivity with a quick integration test:
+```bash
+npx tsx tests/test_noaa_api.ts
+```
 
 ### Manual Testing with Claude Code
 
-See [TESTING_GUIDE.md](./docs/TESTING_GUIDE.md) for comprehensive testing instructions including:
-- Setup steps
+See [TESTING_GUIDE.md](./docs/TESTING_GUIDE.md) for comprehensive manual testing instructions including:
+- Setup steps for MCP clients
 - Test cases for all tools
 - Error handling verification
 - Performance testing
@@ -368,43 +585,89 @@ See [TESTING_GUIDE.md](./docs/TESTING_GUIDE.md) for comprehensive testing instru
 
 ### Available Scripts
 
+**Build & Run:**
 - `npm run build` - Compile TypeScript to JavaScript
 - `npm run dev` - Run the server in development mode with tsx
 - `npm start` - Run the compiled server
-- `npx tsx tests/test_noaa_api.ts` - Run API connectivity tests
+
+**Testing:**
+- `npm test` - Run all automated tests
+- `npm run test:coverage` - Run tests with coverage report
+- `npm run test:watch` - Run tests in watch mode
+- `npm run test:ui` - Run tests with interactive UI
+- `npx tsx tests/test_noaa_api.ts` - Quick API connectivity test
+
+**Security & Maintenance:**
+- `npm run audit` - Check for dependency vulnerabilities
+- `npm run audit:fix` - Automatically fix dependency vulnerabilities
 
 ### Project Structure
 
 ```
 weather-mcp/
 ├── src/
-│   ├── index.ts           # Main MCP server
+│   ├── index.ts                 # Main MCP server
+│   ├── config/
+│   │   ├── cache.ts             # Cache configuration and TTL strategies
+│   │   └── displayThresholds.ts # Display thresholds for weather conditions
+│   ├── errors/
+│   │   └── ApiError.ts          # Custom error class hierarchy
+│   ├── handlers/
+│   │   ├── alertsHandler.ts     # Weather alerts tool handler
+│   │   ├── currentConditionsHandler.ts  # Current conditions handler
+│   │   ├── forecastHandler.ts   # Forecast tool handler
+│   │   ├── historicalWeatherHandler.ts  # Historical weather handler
+│   │   └── statusHandler.ts     # Service status handler
 │   ├── services/
-│   │   ├── noaa.ts        # NOAA real-time API service
-│   │   └── openmeteo.ts   # Open-Meteo historical weather API service
+│   │   ├── noaa.ts              # NOAA API service
+│   │   └── openmeteo.ts         # Open-Meteo API service
 │   ├── types/
-│   │   ├── noaa.ts        # NOAA TypeScript type definitions
-│   │   └── openmeteo.ts   # Open-Meteo TypeScript type definitions
+│   │   ├── noaa.ts              # NOAA TypeScript type definitions
+│   │   └── openmeteo.ts         # Open-Meteo TypeScript type definitions
 │   └── utils/
-│       └── units.ts       # Unit conversion utilities
-├── dist/                  # Compiled JavaScript (generated)
-├── tests/                 # Test files
+│       ├── cache.ts             # LRU cache implementation
+│       ├── logger.ts            # Structured logging utilities
+│       ├── temperatureConversion.ts  # Temperature conversion helpers
+│       ├── units.ts             # Unit conversion utilities
+│       └── validation.ts        # Input validation functions
+├── tests/
+│   ├── unit/                    # Unit tests (228 tests)
+│   └── integration/             # Integration tests (19 tests)
+├── dist/                        # Compiled JavaScript (generated)
+├── docs/                        # Documentation
 └── package.json
 ```
 
 ## API Information
 
-This server uses two weather APIs:
+This server uses three weather APIs:
 
-### NOAA Weather API (Real-time)
+### NOAA Weather API (Real-time, US)
 - **Base URL**: https://api.weather.gov
 - **Authentication**: None required (User-Agent header only)
 - **Rate Limits**: Enforced with 5-second retry window
 - **Coverage**: United States locations only
-- **Use cases**: Forecasts, current conditions, recent observations (last 7 days)
+- **Use cases**: US forecasts (detailed), current conditions, recent observations (last 7 days)
 - **Data**: Detailed hourly observations from weather stations
 
-### Open-Meteo Historical Weather API (Archival)
+### Open-Meteo Forecast API (Global) - NEW in v0.4.0
+- **Base URL**: https://api.open-meteo.com/v1
+- **Authentication**: None required (no API token needed)
+- **Rate Limits**: 10,000 requests/day for non-commercial use
+- **Coverage**: Global (worldwide locations)
+- **Use cases**: International forecasts, extended forecasts (up to 16 days)
+- **Data**: Temperature, precipitation, wind, humidity, UV index, sunrise/sunset
+- **Resolution**: 11km global grid resolution
+
+### Open-Meteo Geocoding API (Global) - NEW in v0.4.0
+- **Base URL**: https://geocoding-api.open-meteo.com/v1
+- **Authentication**: None required (no API token needed)
+- **Coverage**: Global (worldwide locations)
+- **Use cases**: Location name to coordinates conversion
+- **Data**: Coordinates, timezone, elevation, population, administrative regions
+- **Cache**: 30-day TTL (locations don't move)
+
+### Open-Meteo Historical Weather API (Global, Archival)
 - **Base URL**: https://archive-api.open-meteo.com/v1
 - **Authentication**: None required (no API token needed)
 - **Rate Limits**: 10,000 requests/day for non-commercial use
@@ -420,9 +683,15 @@ For more details on NOAA APIs, see [NOAA_API_RESEARCH.md](./docs/NOAA_API_RESEAR
 
 ### Geographic Coverage
 
-**Forecasts and Current Conditions:**
-- NOAA APIs only cover **United States locations**
-- International locations are not supported for forecasts and current conditions
+**Forecasts:** (UPDATED in v0.4.0)
+- **Global coverage** via automatic source selection
+- US locations: Uses NOAA API (more detailed, includes narratives)
+- International locations: Uses Open-Meteo API (reliable global forecasts)
+- Extended forecasts (>7 days, up to 16 days): Open-Meteo only
+
+**Current Conditions:**
+- **US locations only** (NOAA API)
+- International real-time conditions not yet supported
 
 **Historical Data:**
 - Recent data (last 7 days): **US locations only** (NOAA API)
@@ -455,6 +724,51 @@ For more details on NOAA APIs, see [NOAA_API_RESEARCH.md](./docs/NOAA_API_RESEAR
 - **For historical analysis**: Open-Meteo provides reliable global coverage back to 1940
 - **For international locations**: Only historical data (>7 days old) is supported
 
+## Security
+
+This project takes security seriously and implements multiple layers of protection:
+
+### Security Features
+
+**Input Validation:**
+- Comprehensive runtime validation for all user inputs
+- NaN and Infinity checks for numeric coordinates
+- Range validation for latitude (-90 to 90) and longitude (-180 to 180)
+- Type checking with TypeScript strict mode
+
+**Error Handling:**
+- Custom error class hierarchy with typed errors
+- Error message sanitization to prevent information leakage
+- Retryable errors clearly identified for graceful recovery
+- Network errors sanitized before display
+
+**Dependency Security:**
+- Automated dependency scanning via `npm audit`
+- GitHub Dependabot configured for weekly security updates
+- Minimal dependency footprint (3 runtime dependencies)
+- Zero known vulnerabilities in current dependencies
+
+**Reliability:**
+- Exponential backoff with jitter prevents thundering herd problems
+- Comprehensive test suite (247 tests) with 100% coverage on critical utilities
+- Memory-safe cache with automatic cleanup
+- Graceful shutdown handling
+
+### Security Audit
+
+The project has undergone a comprehensive security audit:
+- **Overall Security Posture:** B+ (Good)
+- **Risk Level:** LOW
+- **Vulnerabilities:** Zero critical or high-severity issues
+- See [SECURITY_AUDIT.md](./docs/development/SECURITY_AUDIT.md) for full audit report
+
+### Reporting Security Issues
+
+To report a security vulnerability, please see our [Security Policy](./SECURITY.md) which includes:
+- Vulnerability reporting procedures
+- Response timeline commitments (48hr acknowledgment, 7-day assessment)
+- Security best practices for users and developers
+
 ## License
 
 MIT
@@ -462,3 +776,8 @@ MIT
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
+
+For information about code quality, security considerations, and development best practices, see:
+- [CODE_REVIEW.md](./docs/development/CODE_REVIEW.md) - Comprehensive code quality analysis
+- [CONTRIBUTING.md](./CONTRIBUTING.md) - Contribution guidelines
+- [SECURITY.md](./SECURITY.md) - Security policy and vulnerability reporting

package/dist/config/cache.d.ts

@@ -10,11 +10,13 @@
 export declare const CacheConfig: {
     readonly enabled: boolean;
     readonly maxSize: number;
+    readonly apiTimeoutMs: number;
     readonly ttl: {
         readonly gridCoordinates: number;
         readonly stations: number;
         readonly forecast: number;
         readonly currentConditions: number;
+        readonly alerts: number;
         readonly recentHistorical: number;
         readonly historicalData: number;
         readonly serviceStatus: number;

package/dist/config/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/config/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,eAAO,MAAM,WAAW;;;;;;;;;;;;CAqCd,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAYrE"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/config/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkDH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;CA8Cd,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAYrE"}

package/dist/config/cache.js

@@ -11,11 +11,54 @@
 const MINUTE = 60 * 1000;
 const HOUR = 60 * MINUTE;
 const DAY = 24 * HOUR;
+/**
+ * Parse a boolean environment variable
+ * @param key Environment variable key
+ * @param defaultValue Default value if not set
+ * @returns Boolean value
+ */
+function getEnvBoolean(key, defaultValue) {
+    const value = process.env[key];
+    if (value === undefined)
+        return defaultValue;
+    return value !== 'false' && value !== '0';
+}
+/**
+ * Parse a number environment variable with validation
+ * @param key Environment variable key
+ * @param defaultValue Default value if not set or invalid
+ * @param min Minimum allowed value (optional)
+ * @param max Maximum allowed value (optional)
+ * @returns Validated number value
+ */
+function getEnvNumber(key, defaultValue, min, max) {
+    const value = process.env[key];
+    if (value === undefined)
+        return defaultValue;
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed)) {
+        console.warn(`Invalid ${key}: "${value}". Using default: ${defaultValue}`);
+        return defaultValue;
+    }
+    if (min !== undefined && parsed < min) {
+        console.warn(`${key} too low: ${parsed}. Using minimum: ${min}`);
+        return min;
+    }
+    if (max !== undefined && parsed > max) {
+        console.warn(`${key} too high: ${parsed}. Using maximum: ${max}`);
+        return max;
+    }
+    return parsed;
+}
 export const CacheConfig = {
     // Enable/disable caching globally
-    enabled: process.env.CACHE_ENABLED !== 'false', // Default: enabled
+    enabled: getEnvBoolean('CACHE_ENABLED', true),
     // Maximum number of entries in cache before LRU eviction
-    maxSize: parseInt(process.env.CACHE_MAX_SIZE || '1000', 10),
+    // Min: 100, Max: 10000, Default: 1000
+    maxSize: getEnvNumber('CACHE_MAX_SIZE', 1000, 100, 10000),
+    // API timeout configuration
+    // Min: 5000ms (5 seconds), Max: 120000ms (2 minutes), Default: 30000ms (30 seconds)
+    apiTimeoutMs: getEnvNumber('API_TIMEOUT_MS', 30000, 5000, 120000),
     // TTL values for different data types
     ttl: {
         // Grid coordinate lookups (lat/lon -> grid mapping)
@@ -30,6 +73,9 @@ export const CacheConfig = {
         // Current weather conditions
         // Observations typically update every 20-60 minutes
         currentConditions: 15 * MINUTE,
+        // Weather alerts
+        // Alerts can change rapidly, cache for shorter period
+        alerts: 5 * MINUTE,
         // Recent historical data (< 7 days old)
         // Recent data may still be updated/corrected
         recentHistorical: 1 * HOUR,

package/dist/config/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/config/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,iCAAiC;AACjC,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC;AACzB,MAAM,IAAI,GAAG,EAAE,GAAG,MAAM,CAAC;AACzB,MAAM,GAAG,GAAG,EAAE,GAAG,IAAI,CAAC;AAEtB,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,OAAO,EAAE,mBAAmB;IAEnE,yDAAyD;IACzD,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,MAAM,EAAE,EAAE,CAAC;IAE3D,sCAAsC;IACtC,GAAG,EAAE;QACH,oDAAoD;QACpD,wCAAwC;QACxC,eAAe,EAAE,QAAQ;QAEzB,wBAAwB;QACxB,yBAAyB;QACzB,QAAQ,EAAE,EAAE,GAAG,IAAI;QAEnB,kBAAkB;QAClB,8CAA8C;QAC9C,QAAQ,EAAE,CAAC,GAAG,IAAI;QAElB,6BAA6B;QAC7B,oDAAoD;QACpD,iBAAiB,EAAE,EAAE,GAAG,MAAM;QAE9B,wCAAwC;QACxC,6CAA6C;QAC7C,gBAAgB,EAAE,CAAC,GAAG,IAAI;QAE1B,kDAAkD;QAClD,6DAA6D;QAC7D,cAAc,EAAE,QAAQ;QAExB,8BAA8B;QAC9B,+BAA+B;QAC/B,aAAa,EAAE,CAAC,GAAG,MAAM;KAC1B;CACO,CAAC;AAEX;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAwB;IAC3D,MAAM,KAAK,GAAG,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9E,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,GAAG,CAAC;IAEzD,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,gEAAgE;QAChE,OAAO,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC;IACxC,CAAC;SAAM,CAAC;QACN,mCAAmC;QACnC,OAAO,WAAW,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAC1C,CAAC;AACH,CAAC"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/config/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,iCAAiC;AACjC,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC;AACzB,MAAM,IAAI,GAAG,EAAE,GAAG,MAAM,CAAC;AACzB,MAAM,GAAG,GAAG,EAAE,GAAG,IAAI,CAAC;AAEtB;;;;;GAKG;AACH,SAAS,aAAa,CAAC,GAAW,EAAE,YAAqB;IACvD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC;IAC7C,OAAO,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,GAAG,CAAC;AAC5C,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,GAAW,EAAE,YAAoB,EAAE,GAAY,EAAE,GAAY;IACjF,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC;IAE7C,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACnC,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAClB,OAAO,CAAC,IAAI,CAAC,WAAW,GAAG,MAAM,KAAK,qBAAqB,YAAY,EAAE,CAAC,CAAC;QAC3E,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,GAAG,KAAK,SAAS,IAAI,MAAM,GAAG,GAAG,EAAE,CAAC;QACtC,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,aAAa,MAAM,oBAAoB,GAAG,EAAE,CAAC,CAAC;QACjE,OAAO,GAAG,CAAC;IACb,CAAC;IAED,IAAI,GAAG,KAAK,SAAS,IAAI,MAAM,GAAG,GAAG,EAAE,CAAC;QACtC,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,cAAc,MAAM,oBAAoB,GAAG,EAAE,CAAC,CAAC;QAClE,OAAO,GAAG,CAAC;IACb,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,kCAAkC;IAClC,OAAO,EAAE,aAAa,CAAC,eAAe,EAAE,IAAI,CAAC;IAE7C,yDAAyD;IACzD,sCAAsC;IACtC,OAAO,EAAE,YAAY,CAAC,gBAAgB,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC;IAEzD,4BAA4B;IAC5B,oFAAoF;IACpF,YAAY,EAAE,YAAY,CAAC,gBAAgB,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC;IAEjE,sCAAsC;IACtC,GAAG,EAAE;QACH,oDAAoD;QACpD,wCAAwC;QACxC,eAAe,EAAE,QAAQ;QAEzB,wBAAwB;QACxB,yBAAyB;QACzB,QAAQ,EAAE,EAAE,GAAG,IAAI;QAEnB,kBAAkB;QAClB,8CAA8C;QAC9C,QAAQ,EAAE,CAAC,GAAG,IAAI;QAElB,6BAA6B;QAC7B,oDAAoD;QACpD,iBAAiB,EAAE,EAAE,GAAG,MAAM;QAE9B,iBAAiB;QACjB,sDAAsD;QACtD,MAAM,EAAE,CAAC,GAAG,MAAM;QAElB,wCAAwC;QACxC,6CAA6C;QAC7C,gBAAgB,EAAE,CAAC,GAAG,IAAI;QAE1B,kDAAkD;QAClD,6DAA6D;QAC7D,cAAc,EAAE,QAAQ;QAExB,8BAA8B;QAC9B,+BAA+B;QAC/B,aAAa,EAAE,CAAC,GAAG,MAAM;KAC1B;CACO,CAAC;AAEX;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAwB;IAC3D,MAAM,KAAK,GAAG,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9E,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,GAAG,CAAC;IAEzD,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,gEAAgE;QAChE,OAAO,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC;IACxC,CAAC;SAAM,CAAC;QACN,mCAAmC;QACnC,OAAO,WAAW,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAC1C,CAAC;AACH,CAAC"}