@jablum/weather-mcp 1.7.0

package/README.md

@@ -0,0 +1,1319 @@
+# Weather MCP Server
+
+[![npm version](https://badge.fury.io/js/@dangahagan%2Fweather-mcp.svg)](https://www.npmjs.com/package/@dangahagan/weather-mcp)
+[![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 **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!** All APIs (NOAA, Open-Meteo) are free to use with no authentication needed.
+
+## Features
+
+- **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
+- **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 below)
+- **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?"
+- **Saved Locations**: Save and reuse favorite locations (NEW in v1.7.0)
+  - Save frequently used locations with simple aliases ("home", "work", "cabin")
+  - Use saved locations by name instead of coordinates in all weather tools
+  - Tag locations with activities ("boating", "hiking", "skiing") for contextual weather info
+  - Automatic geocoding when saving (just provide location name)
+  - Persistent storage in `~/.weather-mcp/locations.json`
+  - Manage locations: save, list, view details, remove
+  - Makes queries natural: "What's the weather at home?" instead of providing coordinates
+- **Climate Normals - Historical Context**: Compare weather to 30-year averages (NEW in v1.2.0)
+  - **Optional enhancement** for current conditions and forecasts (`include_normals=true`)
+  - Shows normal high/low temperatures and precipitation for comparison
+  - Displays departure from normal ("10°F warmer than normal")
+  - **Hybrid data strategy**: Open-Meteo computed normals (global, free) or optional NOAA NCEI official normals (US only, requires free API token)
+  - Based on 1991-2020 climate normals period
+  - Helps understand if weather is unusual for the time of year
+- **Snow and Ice Data**: Enhanced winter weather information (NEW in v1.2.0)
+  - Snow depth on ground (current conditions, US only)
+  - Snowfall accumulation forecasts with time periods
+  - Ice accumulation forecasts for freezing rain events
+  - Smart threshold-based display (filters trace amounts)
+  - Unit conversions from metric to imperial
+- **Timezone-Aware Display**: All timestamps in local time (NEW in v1.2.0)
+  - Automatic timezone detection from coordinates
+  - All times displayed in location's local timezone
+  - Includes timezone abbreviations (EST, PDT, etc.)
+  - Handles daylight saving time transitions
+  - Formatted time ranges for forecast periods
+- **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
+- **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)
+- **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
+- **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
+- **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
+- **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
+- **Weather Imagery**: Visual weather radar and precipitation maps (NEW in v1.5.0)
+  - Global precipitation radar from RainViewer API
+  - Static radar images showing current precipitation
+  - Animated radar loops (up to 2 hours of history)
+  - Tile URLs for efficient rendering
+  - Automatic coordinate-to-tile calculation
+  - Visual confirmation of approaching weather
+  - Free, no API key required
+- **Lightning Activity**: Real-time lightning strike detection and safety monitoring (NEW in v1.5.0)
+  - Real-time strike detection from Blitzortung.org network
+  - Strikes within customizable radius (default: 100km)
+  - 4-level safety assessment (Safe, Elevated, High, Extreme)
+  - Distance to nearest strike with comprehensive statistics
+  - Strike polarity and amplitude information
+  - Safety recommendations based on proximity
+  - Critical for outdoor activity safety planning
+  - Free, no API key required
+- **River Conditions**: Monitor river levels and flood status for safety and recreation (NEW in v1.6.0)
+  - Current water levels from NOAA and USGS gauges
+  - Flood stage thresholds (action, minor, moderate, major)
+  - Streamflow data in cubic feet per second
+  - Distance-based gauge filtering within customizable radius
+  - Safety assessment for boating and recreation
+  - Historical flood crest data when available
+  - US coverage via NOAA NWPS and USGS Water Services
+- **Wildfire Information**: Track active wildfires and fire perimeters (NEW in v1.6.0)
+  - Active wildfire locations and prescribed burns
+  - Fire size, containment status, and discovery date
+  - Distance-based proximity filtering
+  - 4-level safety assessment (Extreme Danger, High Alert, Caution, Awareness)
+  - Evacuation recommendations based on proximity
+  - Detailed fire attributes (type, location, status)
+  - Data from NIFC WFIGS (National Interagency Fire Center)
+- **Service Status Checking**: Proactively verify API availability with health checks
+- **Enhanced Error Handling**: Detailed, actionable error messages with status page links
+- **Intelligent Caching**: Built-in in-memory cache reduces API calls and improves performance
+
+## Caching
+
+The Weather MCP server includes an intelligent in-memory caching system that significantly improves performance for AI-driven weather queries.
+
+### Benefits
+
+- **Faster Responses**: Cached queries return in <10ms vs 200-1000ms for API calls
+- **Reduced API Load**: 50-80% fewer API calls for typical AI conversation patterns
+- **Rate Limit Protection**: Prevents hitting API rate limits during heavy usage
+- **Automatic Management**: Smart TTL-based expiration with LRU eviction
+
+### How It Works
+
+The cache automatically stores and retrieves weather data with intelligent expiration:
+
+- **Location Searches**: Cached for 30 days (locations don't move)
+- **Climate Normals**: Cached indefinitely (30-year averages are static) - NEW in v1.2.0
+- **Weather Imagery**: Cached for 15 minutes (radar updates frequently) - NEW in v1.5.0
+- **Lightning Strikes**: Cached for 5 minutes (real-time safety data) - NEW in v1.5.0
+- **River Conditions**: Cached for 1 hour (gauge data updates frequently) - NEW in v1.6.0
+- **Wildfire Information**: Cached for 30 minutes (fire data changes rapidly) - NEW in v1.6.0
+- **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)
+- **Recent Historical (<1 day)**: Cached for 1 hour (may still be updated)
+- **Grid Coordinates**: Cached indefinitely (geographic mappings are static)
+
+### Configuration
+
+**For most users: No configuration needed!** The server works out of the box with sensible defaults and requires no API keys.
+
+#### Optional: Environment Variables
+
+To customize server behavior, copy the example configuration file:
+
+```bash
+cp .env.example .env
+```
+
+Then edit `.env` to adjust settings as needed. See [`.env.example`](./.env.example) for comprehensive documentation on all available options.
+
+**What you can configure:**
+- **Tool Selection** - Choose which MCP tools to expose (basic/standard/full/all presets)
+- **Cache Settings** - Adjust cache size and enable/disable caching
+- **API Configuration** - Set request timeouts
+- **Logging** - Control log verbosity levels
+- **Optional API Tokens** - Add NCEI token for official US climate normals (falls back to free Open-Meteo data)
+- **Lightning Detection** - Configure alternative MQTT broker (optional)
+
+All settings have sensible defaults and can be omitted entirely.
+
+#### Tool Selection (NEW in v1.4.0)
+
+Control which MCP tools are exposed to reduce context overhead and customize functionality. By default, only **basic** tools are enabled.
+
+**Available Presets:**
+- `basic` (default): Essential weather tools (5 tools) - forecast, current_conditions, alerts, search_location, check_service_status
+- `standard`: Basic + historical_weather (6 tools)
+- `full`: Standard + air_quality (7 tools)
+- `all`: All available tools (16 tools) - includes marine_conditions, weather_imagery, lightning_activity, river_conditions, wildfire_info, save_location, list_saved_locations, get_saved_location, remove_saved_location
+
+**Configuration Examples:**
+
+```bash
+# In .env file or MCP client config
+ENABLED_TOOLS=full                              # Use a preset
+ENABLED_TOOLS=forecast,current,alerts,air_quality  # Specific tools only
+ENABLED_TOOLS=basic,+historical,+air_quality   # Add to preset
+ENABLED_TOOLS=all,-marine                       # Remove from preset
+```
+
+**Tool Aliases:**
+Short names are supported: `forecast`, `current`, `conditions`, `alerts`, `warnings`, `historical`, `history`, `status`, `location`, `search`, `air_quality`, `aqi`, `marine`, `ocean`, `waves`, `imagery`, `radar`, `satellite`, `lightning`, `strikes`, `thunderstorm`
+
+**Benefits:**
+- **Reduced Context**: Load only needed tools to reduce initial MCP context
+- **Better Security**: Only expose necessary functionality
+- **Customization**: Tailor the server to your specific use case
+
+#### MCP Client Configuration
+
+You can also set environment variables directly in your MCP client configuration file instead of using a `.env` file:
+
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "command": "npx",
+      "args": ["-y", "@dangahagan/weather-mcp@latest"],
+      "env": {
+        "ENABLED_TOOLS": "full",
+        "CACHE_MAX_SIZE": "2000",
+        "LOG_LEVEL": "1"
+      }
+    }
+  }
+}
+```
+
+**Note on Climate Normals (v1.2.0):**
+- By default, climate normals use Open-Meteo's computed 30-year averages (completely free, global coverage, zero setup)
+- Optionally, you can configure a free NCEI API token to use official NOAA climate normals for US locations
+- Get a free token at: https://www.ncdc.noaa.gov/cdo-web/token
+- If NCEI token is configured but unavailable, the system automatically falls back to Open-Meteo
+
+#### Saved Locations (NEW in v1.7.0)
+
+The saved locations feature stores your favorite places (like "home", "work", "cabin") for easy reuse in weather queries. No configuration needed - it works automatically!
+
+**Storage Location:**
+- Data stored in: `~/.weather-mcp/locations.json`
+- Directory created automatically on first save
+- File is human-readable JSON (can be backed up or edited manually)
+
+**Features:**
+- No limit on number of saved locations
+- Tag locations with activities (e.g., "boating", "hiking") to help AI provide relevant weather info
+- Persistent across MCP server restarts
+- Portable - copy the file to migrate locations to another machine
+
+**Learn More:**
+- See [save_location](#13-save_location-new-in-v170) for usage instructions
+- See [Using Saved Locations](#using-saved-locations-with-weather-tools) for examples
+
+### Monitoring
+
+Use the `check_service_status` tool to view cache statistics including:
+- Hit rate percentage
+- Cache size and utilization
+- API call reduction metrics
+
+For detailed information about caching architecture and configuration, see [.github/CACHING.md](./.github/CACHING.md).
+
+## Installation
+
+### Quick Install (Recommended)
+
+**Via npm:**
+```bash
+npm install -g @dangahagan/weather-mcp
+```
+
+**Via npx (no installation, always uses latest):**
+```bash
+npx -y @dangahagan/weather-mcp@latest
+```
+
+Then configure in your MCP client using:
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "command": "npx",
+      "args": ["-y", "@dangahagan/weather-mcp@latest"]
+    }
+  }
+}
+```
+
+### From Source
+
+If you prefer to build from source:
+
+**Prerequisites:**
+- Node.js 18 or higher
+- npm or yarn
+- **No API keys or tokens required**
+
+**Setup:**
+
+1. Clone the repository:
+```bash
+git clone https://github.com/weather-mcp/weather-mcp.git
+cd weather-mcp
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Build the project:
+```bash
+npm run build
+```
+
+4. (Optional) Configure environment variables:
+```bash
+cp .env.example .env
+# Edit .env to customize settings (all optional)
+```
+
+See the [Configuration](#configuration) section for details.
+
+## Upgrading to Latest Version
+
+### Upgrading npm Installation
+
+If you installed via npm globally:
+
+```bash
+# Check your current version
+npm list -g @dangahagan/weather-mcp
+
+# Update to latest version
+npm update -g @dangahagan/weather-mcp
+
+# Or reinstall to ensure latest version
+npm install -g @dangahagan/weather-mcp@latest
+```
+
+**For npx users:** If you're using `@latest` (recommended), no upgrade needed! The `npx -y @dangahagan/weather-mcp@latest` command always fetches the newest version.
+
+### Upgrading from Source
+
+If you cloned the repository:
+
+```bash
+# Navigate to your installation directory
+cd /path/to/weather-mcp
+
+# Fetch latest changes
+git fetch origin
+
+# Check current version
+git describe --tags
+
+# Update to latest release
+git checkout main
+git pull origin main
+
+# Reinstall dependencies and rebuild
+npm install
+npm run build
+```
+
+**After upgrading:**
+- Restart your MCP client (Claude Desktop, Claude Code, etc.)
+- Check the changelog at [CHANGELOG.md](./CHANGELOG.md) for breaking changes
+- Verify the new version with the latest features
+
+**Version Check:**
+You can verify your installed version by checking:
+- npm: `npm list -g @dangahagan/weather-mcp`
+- Source: `git describe --tags` or check `package.json`
+- Latest release: https://github.com/weather-mcp/weather-mcp/releases
+
+## Usage with AI Assistants
+
+This MCP server works with any client that supports the Model Context Protocol, including:
+
+- **Claude Desktop** - Official Claude desktop application
+- **Claude Code** - Official Claude CLI tool
+- **Cline** - VS Code extension for AI-assisted coding
+- **Cursor** - AI-powered code editor
+- **Zed** - High-performance code editor with AI features
+- **VS Code (GitHub Copilot)** - With MCP support enabled
+- **LM Studio** - Local AI model interface
+- **Postman** - API platform with MCP integration
+
+For detailed setup instructions for each client, see **[CLIENT_SETUP.md](./docs/CLIENT_SETUP.md)**.
+
+### Quick Start: Claude Code
+
+Edit `~/.config/claude-code/mcp_settings.json` (macOS/Linux) or `%APPDATA%\claude-code\mcp_settings.json` (Windows):
+
+**Recommended (npx, always latest):**
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "command": "npx",
+      "args": ["-y", "@dangahagan/weather-mcp@latest"]
+    }
+  }
+}
+```
+
+**Alternative (from source):**
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "command": "node",
+      "args": ["/absolute/path/to/weather-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Restart Claude Code and the weather tools will be available.
+
+## Finding Coordinates
+
+**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 City Coordinates (For Reference)
+
+| City | Latitude | Longitude |
+|------|----------|-----------|
+| 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 |
+| 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. get_forecast (ENHANCED in v0.4.0, v1.2.0)
+Get weather forecast for any location worldwide.
+
+**Parameters:**
+- `latitude` (optional): Latitude coordinate (-90 to 90). Not required if `location_name` or `city_name` is provided.
+- `longitude` (optional): Longitude coordinate (-180 to 180). Not required if `location_name` or `city_name` is provided.
+- `location_name` (optional): Saved location alias (e.g., `"home"`). See saved locations below.
+- `city_name` (optional): City or place name to geocode (e.g., `"Paris, France"`). For cities in China, use pinyin only (e.g., `"Beijing"`, not `"北京"`). Uses the same geocoding as `search_location`.
+- `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)
+- `include_normals` (optional): Include climate normals for comparison (default: false, NEW in v1.2.0)
+- `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
+- Climate normals comparison (when `include_normals=true`, NEW in v1.2.0)
+- Snow and ice accumulation forecasts (when available, NEW in v1.2.0)
+- All timestamps in local timezone (NEW in v1.2.0)
+
+### 2. search_location (NEW in v0.4.0)
+Find coordinates for any location worldwide by name.
+
+**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:**
+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.
+
+**Examples:**
+```
+"Find coordinates for Paris"
+"Search for Tokyo, Japan"
+"Where is San Francisco, CA?"
+```
+
+**Returns:**
+- 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.)
+
+### 3. 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
+
+### 4. get_historical_weather
+Get historical weather observations for a location.
+
+**Parameters:**
+- `latitude` (required): Latitude coordinate (-90 to 90)
+- `longitude` (required): Longitude coordinate (-180 to 180)
+- `start_date` (required): Start date in ISO format (YYYY-MM-DD)
+- `end_date` (required): End date in ISO format (YYYY-MM-DD)
+- `limit` (optional): Max observations to return (1-500, default: 168)
+
+**Data Source Selection:**
+The server automatically chooses the best data source based on your date range:
+
+- **Last 7 days**: Uses NOAA real-time API
+  - ✓ Detailed hourly observations from weather stations
+  - ✓ Includes: temperature, conditions, wind speed, humidity, pressure
+  - ✓ High reliability and availability
+  - ⚠️ US locations only
+
+- **Older than 7 days**: Uses Open-Meteo Historical Weather API
+  - ✓ No API token required
+  - ✓ Global coverage (worldwide)
+  - ✓ Historical data from 1940 to present
+  - ✓ Hourly data for ranges up to 31 days
+  - ✓ Daily summaries for longer periods
+  - ✓ Includes: temperature, precipitation, wind, humidity, pressure, cloud cover
+  - ✓ High resolution reanalysis data (9-25km grid)
+  - ⚠️ 5-day delay for most recent data
+
+**Examples:**
+
+Recent data (US locations, detailed observations):
+```
+"What was the weather like in Chicago 3 days ago?"
+Coordinates: latitude: 41.8781, longitude: -87.6298
+Date range: 3 days ago to 2 days ago
+```
+
+Historical data (global coverage):
+```
+"What was the weather in Paris on January 15, 2024?"
+Coordinates: latitude: 48.8566, longitude: 2.3522
+Date range: 2024-01-15 to 2024-01-15
+```
+
+Long-term historical analysis:
+```
+"Show me weather data for Tokyo from January 1, 2020 to December 31, 2020"
+Coordinates: latitude: 35.6762, longitude: 139.6503
+Date range: 2020-01-01 to 2020-12-31
+```
+
+**Troubleshooting:**
+If you get "No historical data available":
+- For recent dates (last 7 days): Ensure you're using US coordinates
+- For older dates: Data should be available globally back to 1940
+- Note: Most recent data has a 5-day delay
+- Very recent dates (last 5 days) may not be available in archival data yet
+
+### 5. 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
+
+### 6. 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:**
+```
+Check if the weather services are operational
+```
+
+**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
+
+### 7. get_marine_conditions (NEW in v0.6.0, Enhanced in v1.1.0)
+Get marine weather conditions including wave height, swell, ocean currents, and sea state with automatic source selection for Great Lakes and coastal bays.
+
+**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 with intelligent dual-source support:
+- **Great Lakes & Coastal Bays (NEW in v1.1.0)**: Automatically uses NOAA gridpoint data for all 5 Great Lakes (Superior, Michigan, Huron, Erie, Ontario) and major US coastal bays (Chesapeake Bay, San Francisco Bay, Tampa Bay, Puget Sound, Lake Okeechobee). Provides wave height, wave period, wave direction, and wind conditions.
+- **Ocean Coverage**: Uses Open-Meteo Marine API for global ocean coverage, including significant wave height with Douglas Sea Scale categorization, wind waves vs swell separation, wave period/direction, ocean currents, and safety assessment for maritime activities.
+- **Automatic Selection**: Intelligent geographic detection automatically selects the best data source with zero configuration required.
+
+**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
+
+### 8. get_weather_imagery (NEW in v1.5.0)
+Get weather radar and precipitation imagery for visual weather analysis.
+
+**Parameters:**
+- `latitude` (required): Latitude coordinate (-90 to 90)
+- `longitude` (required): Longitude coordinate (-180 to 180)
+- `type` (required): Imagery type - "precipitation", "radar", or "satellite" (Note: satellite not yet implemented)
+- `animated` (optional): Return animated loop vs static image (default: false)
+- `layers` (optional): Additional map layers (reserved for future use)
+
+**Description:**
+Provides access to weather radar and precipitation imagery from RainViewer API with global coverage. Returns tile URLs for efficient rendering of current precipitation or animated radar loops showing up to 2 hours of history. Perfect for visual confirmation of approaching weather systems.
+
+**Examples:**
+```
+"Show me the current radar for New York"
+"Get animated precipitation radar for London for the last 2 hours"
+"Is there any precipitation showing on radar near me?"
+```
+
+**Returns:**
+- Precipitation radar imagery (static or animated)
+- Tile URLs for efficient rendering
+- Frame timestamps for animated sequences
+- Coverage area and resolution information
+- Automatic coordinate-to-tile calculation
+- Up to 2 hours of historical radar frames when animated
+
+**Note:** Satellite imagery is planned for a future release. Precipitation radar provides global coverage via the free RainViewer API.
+
+### 9. get_lightning_activity (NEW in v1.5.0)
+Get real-time lightning strike detection and safety assessment for outdoor activity planning.
+
+**Parameters:**
+- `latitude` (required): Latitude coordinate (-90 to 90)
+- `longitude` (required): Longitude coordinate (-180 to 180)
+- `radius` (optional): Search radius in kilometers (1-500, default: 100)
+- `timeWindow` (optional): Historical time window in minutes (1-180, default: 60)
+
+**Description:**
+Provides real-time lightning strike detection from the Blitzortung.org global lightning detection network. Includes comprehensive safety assessment with 4 risk levels based on strike proximity. Critical for outdoor safety planning including boating, hiking, golfing, and other outdoor activities.
+
+**Examples:**
+```
+"Are there any lightning strikes near Miami?"
+"Check for lightning activity within 50km"
+"Is it safe to be outside based on lightning?"
+"Show me recent lightning strikes in the last hour"
+```
+
+**Returns:**
+- Real-time lightning strikes within specified radius
+- 4-level safety assessment:
+  - **Safe** (>50km): No immediate lightning threat
+  - **Elevated** (16-50km): Monitor conditions, plan indoor access
+  - **High** (8-16km): Seek shelter immediately
+  - **Extreme** (<8km): Active thunderstorm, dangerous conditions
+- Comprehensive statistics:
+  - Total strikes and strike density (per sq km)
+  - Strikes per minute rate
+  - Distance to nearest strike
+  - Average distance of all strikes
+- Strike details:
+  - Polarity (cloud-to-ground vs intra-cloud)
+  - Amplitude in kiloamperes (kA)
+  - Precise timestamp and location
+- Safety recommendations based on proximity
+- Geographic region-optimized data retrieval
+
+**Note:** Data provided by Blitzortung.org, a free community-operated lightning detection network. May have regional coverage variations.
+
+### 10. get_river_conditions (NEW in v1.6.0)
+Monitor river levels and flood status using NOAA and USGS data sources.
+
+**Parameters:**
+- `latitude` (required): Latitude coordinate (-90 to 90)
+- `longitude` (required): Longitude coordinate (-180 to 180)
+- `radius` (optional): Search radius in kilometers (1-500, default: 50)
+
+**Description:**
+Provides comprehensive river and streamflow monitoring for flood safety and recreation planning. Automatically finds the nearest river gauges within the specified radius and reports current water levels, flood stages, and flow rates. Uses NOAA National Water Prediction Service (NWPS) for gauge locations and USGS Water Services for real-time streamflow data.
+
+**Examples:**
+```
+"What are the river conditions near St. Louis?" (latitude: 38.6270, longitude: -90.1994)
+"Check for flooding on the Mississippi River"
+"Is the river level safe for kayaking?"
+"Show me nearby river gauge readings"
+```
+
+**Returns:**
+- Nearest river gauges with current water levels
+- Flood stage thresholds (action, minor, moderate, major)
+- Current flood status and forecast
+- Streamflow data (cubic feet per second)
+- Distance to each gauge from query location
+- River and location names
+- Safety assessment for recreation
+- Historical context (flood crests if available)
+
+**Note:** US coverage only. Data provided by NOAA National Water Prediction Service and USGS Water Services.
+
+### 11. get_wildfire_info (NEW in v1.6.0)
+Monitor active wildfires and fire perimeters for safety and evacuation planning.
+
+**Parameters:**
+- `latitude` (required): Latitude coordinate (-90 to 90)
+- `longitude` (required): Longitude coordinate (-180 to 180)
+- `radius` (optional): Search radius in kilometers (1-500, default: 100)
+
+**Description:**
+Provides critical wildfire monitoring and safety information using NIFC (National Interagency Fire Center) data. Reports active wildfires and prescribed burns within the specified radius, including fire size, containment status, and proximity-based safety assessments. Essential for residents in fire-prone regions and outdoor activity planning.
+
+**Examples:**
+```
+"Are there any wildfires near Los Angeles?" (latitude: 34.0522, longitude: -118.2437)
+"Check for active fires in Colorado"
+"How close is the nearest wildfire?"
+"Show me fire perimeters and containment status"
+```
+
+**Returns:**
+- Active wildfire locations within search radius
+- Fire size in acres and hectares
+- Containment percentage with visual indicator
+- Distance from query location to each fire
+- Discovery date and days active
+- Fire type (Wildfire vs Prescribed Fire)
+- Location details (state, county, city)
+- 4-level safety assessment:
+  - **EXTREME DANGER** (<5km): Evacuate if advised
+  - **HIGH ALERT** (5-25km): Prepare for evacuation
+  - **CAUTION** (25-50km): Monitor conditions
+  - **AWARENESS** (>50km): Stay informed
+- Evacuation recommendations and safety guidance
+
+**Note:** Data from NIFC WFIGS (Wildland Fire Interagency Geospatial Services). Always consult official sources for evacuation orders at https://inciweb.nwcg.gov/
+
+### 12. save_location (NEW in v1.7.0)
+Save a location with an alias for easy reuse in weather queries.
+
+**Parameters:**
+- `alias` (required): Short name for the location (e.g., "home", "work", "cabin"). Max 50 characters.
+- `location_query` (optional): Location to geocode and save (e.g., "Seattle, WA", "Paris, France"). Not required if latitude/longitude provided.
+- `latitude` (optional): Latitude if providing coordinates directly. Not required if location_query provided.
+- `longitude` (optional): Longitude if providing coordinates directly. Not required if location_query provided.
+- `name` (optional): Display name (required when using latitude/longitude directly)
+- `activities` (optional): Activities you do at this location (e.g., ["boating", "fishing"]). Helps AI provide relevant weather information. Each activity max 50 characters.
+
+**Description:**
+Saves a location to persistent storage (`~/.weather-mcp/locations.json`) for easy reuse. Accepts either a location query (which will be automatically geocoded using Nominatim/OpenStreetMap) or direct coordinates. Once saved, the location can be used in any weather tool by providing `location_name` instead of coordinates.
+
+**Smart Updates:** If the alias already exists and you only provide `name` and/or `activities` (without location details), it will update just those fields while preserving all coordinates and metadata. This makes it easy to add activities or rename locations without re-specifying the full address.
+
+**Examples:**
+```
+"Save my home location in Seattle, WA"
+  → save_location(alias="home", location_query="Seattle, WA")
+
+"Save the cabin at Lake Tahoe"
+  → save_location(alias="cabin", location_query="Lake Tahoe, CA")
+
+"Save coordinates 47.6062, -122.3321 as my office"
+  → save_location(alias="office", latitude=47.6062, longitude=-122.3321, name="Seattle Office")
+
+"Save the lake house where we go boating and fishing"
+  → save_location(alias="lake_house", location_query="Lake Tahoe, CA", activities=["boating", "fishing"])
+
+"Save my favorite hiking spot"
+  → save_location(alias="trail", location_query="Mt. Rainier, WA", activities=["hiking", "camping", "photography"])
+
+"Add more activities to the cabin" (smart update - no location needed)
+  → save_location(alias="cabin", activities=["boating", "fishing", "hiking", "swimming"])
+
+"Rename my campsite" (smart update - no location needed)
+  → save_location(alias="campsite", name="Yosemite Valley Campground")
+```
+
+**Returns:**
+- Confirmation of save with location details
+- Coordinates, timezone, and administrative region
+- Usage examples showing how to use with weather tools
+
+### 13. list_saved_locations (NEW in v1.7.0)
+View all saved locations.
+
+**Parameters:** None
+
+**Description:**
+Lists all locations saved in your persistent storage with their aliases, names, coordinates, and save dates. Helpful for seeing what location names are available for use with weather tools.
+
+**Examples:**
+```
+"Show my saved locations"
+"What locations do I have saved?"
+"List all my saved places"
+```
+
+**Returns:**
+- List of all saved locations with full details
+- Usage examples for each location
+- Total count of saved locations
+
+### 14. get_saved_location (NEW in v1.7.0)
+Get details for a specific saved location.
+
+**Parameters:**
+- `alias` (required): The name of the saved location to retrieve (e.g., "home", "work")
+
+**Description:**
+Retrieves detailed information about a specific saved location, including coordinates, timezone, region information, and save/update timestamps.
+
+**Examples:**
+```
+"Show details for my home location"
+"What are the coordinates for my cabin?"
+"Get info about my work location"
+```
+
+**Returns:**
+- Location name and coordinates
+- Timezone and administrative regions
+- Save and update timestamps
+- Usage examples
+
+### 15. remove_saved_location (NEW in v1.7.0)
+Remove a saved location.
+
+**Parameters:**
+- `alias` (required): The name of the saved location to remove (e.g., "home", "work")
+
+**Description:**
+Permanently removes a saved location from storage. The location data is deleted and can no longer be used with weather tools unless saved again.
+
+**Examples:**
+```
+"Remove my work location"
+"Delete the cabin from saved locations"
+"Remove home"
+```
+
+**Returns:**
+- Confirmation of removal
+- Count of remaining saved locations
+
+## Using Saved Locations with Weather Tools
+
+Once you've saved locations, you can use them with any weather tool by providing `location_name` instead of coordinates:
+
+**Examples:**
+```
+# Instead of:
+get_forecast(latitude=47.6062, longitude=-122.3321)
+
+# You can use:
+get_forecast(location_name="home")
+
+# Or geocode a city/place name directly:
+get_forecast(city_name="Paris, France")
+
+# Natural language queries work too:
+"What's the weather forecast at home?"
+"How's the air quality at my cabin?"
+"Are there any weather alerts for my work location?"
+```
+
+**Currently Supported Tools:**
+- `get_forecast` - Weather forecasts using saved locations
+
+**Coming Soon:** Support for saved locations in all weather tools (current conditions, alerts, air quality, marine conditions, etc.)
+
+## Error Handling & Service Status
+
+### Enhanced Error Messages
+
+This MCP server provides detailed, actionable error messages when issues occur. All error messages include:
+
+- **Clear problem description** - What went wrong and why
+- **Contextual help** - Specific guidance based on the error type
+- **Status page links** - Direct links to official service status pages
+- **Recommended actions** - Concrete steps to resolve or investigate the issue
+
+**Example Error Messages:**
+
+When a service is down:
+```
+NOAA API server error: Service temporarily unavailable
+
+The NOAA Weather API may be experiencing an outage.
+
+Check service status:
+- Planned outages: https://weather-gov.github.io/api/planned-outages
+- Service notices: https://www.weather.gov/notification
+- Report issues: nco.ops@noaa.gov or (301) 683-1518
+```
+
+When rate limited:
+```
+Open-Meteo API rate limit exceeded (10,000 requests/day for non-commercial use).
+
+Please retry later or consider:
+- Reducing request frequency
+- Using daily instead of hourly data for longer periods
+- Upgrading to a commercial plan for higher limits
+
+More info: https://open-meteo.com/en/pricing
+```
+
+### Service Status Checking
+
+Use the `check_service_status` tool to proactively verify API availability:
+
+```
+# Query example
+"Check if the weather services are working"
+
+# Returns:
+- ✅/❌ Status for NOAA API (US forecasts & current conditions)
+- ✅/❌ Status for Open-Meteo API (global historical data)
+- Links to official status pages
+- Recommended actions if issues detected
+- Overall service availability summary
+```
+
+**When to use:**
+- Before making multiple weather requests
+- When experiencing errors or timeouts
+- To verify service availability after an outage
+- For monitoring and alerting purposes
+
+**Status Page Links:**
+- **NOAA API:**
+  - Planned outages: https://weather-gov.github.io/api/planned-outages
+  - Service notices: https://www.weather.gov/notification
+  - Report issues: https://weather-gov.github.io/api/reporting-issues
+
+- **Open-Meteo API:**
+  - Production status: https://open-meteo.com/en/docs/model-updates
+  - GitHub issues: https://github.com/open-meteo/open-meteo/issues
+  - Documentation: https://open-meteo.com/en/docs
+
+## Testing
+
+### Automated Test Suite
+
+This project includes a comprehensive test suite with 1,042 automated tests:
+
+```bash
+# 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
+```
+
+**Test Coverage:**
+- **1,042 tests** across unit and integration test suites (111 new tests in v1.6.0)
+- **100% coverage** on critical utilities (cache, validation, units, errors, normals, snow, timezone, distance, geohash, security)
+- **100% pass rate** with comprehensive security and boundary validation
+- All tests execute in ~2 seconds
+
+**Test Categories:**
+- **Unit Tests** (965 tests) - Cache, validation, units, errors, config, retry logic, normals, snow, timezone, distance, security, geohash
+- **Integration Tests** (77 tests) - Error recovery, service status checks, safety & hazards features
+
+### 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/TESTING_GUIDE.md) for comprehensive manual testing instructions including:
+- Setup steps for MCP clients
+- Test cases for all tools
+- Error handling verification
+- Performance testing
+- Debugging tips
+
+## Development
+
+### 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
+
+**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
+│   ├── config/
+│   │   ├── api.ts               # API configuration (NCEI token) - NEW in v1.2.0
+│   │   ├── 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
+│   │   ├── forecastHandler.ts   # Forecast tool handler
+│   │   ├── historicalWeatherHandler.ts  # Historical weather handler
+│   │   ├── airQualityHandler.ts # Air quality handler
+│   │   ├── marineConditionsHandler.ts   # Marine conditions handler
+│   │   ├── locationHandler.ts   # Location search handler
+│   │   └── statusHandler.ts     # Service status handler
+│   ├── services/
+│   │   ├── noaa.ts              # NOAA API service
+│   │   ├── openmeteo.ts         # Open-Meteo API service
+│   │   └── ncei.ts              # NCEI climate normals service - NEW in v1.2.0
+│   ├── types/
+│   │   ├── noaa.ts              # NOAA TypeScript type definitions
+│   │   └── openmeteo.ts         # Open-Meteo TypeScript type definitions
+│   └── utils/
+│       ├── 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
+│       ├── normals.ts           # Climate normals utilities - NEW in v1.2.0
+│       ├── snow.ts              # Snow and ice data utilities - NEW in v1.2.0
+│       └── timezone.ts          # Timezone-aware formatting - NEW in v1.2.0
+├── tests/
+│   ├── unit/                    # Unit tests (427 tests) - 93 new tests in v1.2.0
+│   └── integration/             # Integration tests (19 tests)
+├── dist/                        # Compiled JavaScript (generated)
+├── docs/                        # Documentation
+└── package.json
+```
+
+## API Information
+
+This server uses three weather APIs:
+
+### 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**: US forecasts (detailed), current conditions, recent observations (last 7 days)
+- **Data**: Detailed hourly observations from weather stations
+
+### 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
+- **Coverage**: Global (worldwide locations)
+- **Use cases**: Historical weather data from 1940 to present
+- **Data**: Hourly or daily temperature, precipitation, wind, humidity, pressure, cloud cover
+- **Resolution**: 9-25km grid resolution from reanalysis models
+- **Delay**: 5-day delay for most recent data
+
+For more details on NOAA APIs, see [NOAA_API_RESEARCH.md](./docs/NOAA_API_RESEARCH.md).
+
+## Limitations
+
+### Geographic Coverage
+
+**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)
+- Archival data (>7 days old): **Global coverage** (Open-Meteo API)
+
+### Historical Data (get_historical_weather)
+
+**Recent Data (Last 7 Days)** - US Only, High Detail:
+- ✓ Detailed hourly observations from weather stations
+- ✓ No API token required
+- ⚠️ US locations only
+- ⚠️ May have occasional gaps depending on weather station
+- ⚠️ Observations may be delayed up to 20 minutes
+
+**Archival Data (Older than 7 Days)** - Global, Reanalysis-Based:
+- ✓ Global coverage (any location worldwide)
+- ✓ No API token required
+- ✓ Reliable data from 1940 to present
+- ✓ Hourly data for date ranges up to 31 days
+- ✓ Daily summaries for longer periods
+- ⚠️ Most recent data has a 5-day delay
+- ⚠️ Reanalysis-based (grid model, not direct station observations)
+
+### Rate Limits
+- **NOAA Weather API**: Automatic retry with exponential backoff on rate limit errors
+- **Open-Meteo API**: 10,000 requests/day for non-commercial use
+
+### Recommendations
+- **For recent US weather**: Use dates within the last 7 days for detailed station observations
+- **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
+
+## Documentation
+
+📚 **[Complete Documentation Index](./docs/README.md)** - Comprehensive navigation guide to all project documentation
+
+### Quick Links
+
+**For Users:**
+- [Client Setup Guide](./docs/CLIENT_SETUP.md) - Setup instructions for 8 different MCP clients
+- [Testing Guide](./docs/testing/TESTING_GUIDE.md) - Manual testing procedures
+- [Error Handling](./docs/ERROR_HANDLING.md) - Enhanced error handling features
+
+**For Developers:**
+- [Contributing Guidelines](./CONTRIBUTING.md) - How to contribute
+- [Development Guide](./CLAUDE.md) - AI assistant development guide
+- [Code Review](./docs/development/CODE_REVIEW.md) - Code quality analysis
+- [Security Audit](./docs/development/SECURITY_AUDIT_V1.6.md) - Security assessment
+
+**Planning & Roadmap:**
+- [Implementation Plan](./docs/planning/IMPLEMENTATION_PLAN.md) - Project roadmap
+- [Future Enhancements](./docs/planning/FUTURE_ENHANCEMENTS.md) - Planned features
+- [Roadmap](./docs/planning/ROADMAP.md) - Long-term plans
+
+**Testing & Quality:**
+- [Test Suite](./docs/testing/TEST_SUITE_README.md) - Test overview
+- [Test Coverage](./docs/testing/TEST_COVERAGE_ANALYSIS_2025.md) - Latest coverage analysis
+- [Test Recommendations](./docs/testing/TEST_RECOMMENDATIONS.md) - Improvement suggestions
+
+**Analytics (Optional):**
+- [Analytics Plan](./docs/analytics/ANALYTICS_MCP_PLAN.md) - Privacy-first analytics
+- [Analytics Security](./docs/analytics/MCP_ANALYTICS_SECURITY_GUIDE.md) - Security implementation guide
+- [Local Analytics](./docs/analytics/LOCAL_ANALYTICS_GUIDE.md) - Setup guide
+
+**Technical Documentation:**
+- [NOAA API Research](./docs/NOAA_API_RESEARCH.md) - NOAA API integration details
+- [Historical Data Plan](./docs/HISTORICAL_DATA_PLAN.md) - Historical weather implementation
+- [MCP Best Practices](./docs/MCP_BEST_PRACTICES.md) - MCP protocol guidelines
+
+## License
+
+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