@dangahagan/weather-mcp 1.3.0 → 1.7.1

package/README.md

@@ -30,6 +30,14 @@ An MCP (Model Context Protocol) server that provides **global weather data** to
   - 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
@@ -91,6 +99,39 @@ An MCP (Model Context Protocol) server that provides **global weather data** to
   - 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
@@ -112,6 +153,10 @@ The cache automatically stores and retrieves weather data with intelligent expir
 
 - **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
@@ -124,18 +169,74 @@ The cache automatically stores and retrieves weather data with intelligent expir
 
 ### Configuration
 
-Caching is **enabled by default** with sensible settings. To customize:
+**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
-# Disable caching (not recommended)
-export CACHE_ENABLED=false
+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)
 
-# Adjust maximum cache size (default: 1000 entries)
-export CACHE_MAX_SIZE=1500
+All settings have sensible defaults and can be omitted entirely.
 
-# Optional: NOAA NCEI API token for official climate normals (US only, NEW in v1.2.0)
-# Falls back to Open-Meteo computed normals if not configured
-export NCEI_API_TOKEN=your_token_here
+#### 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):**
@@ -144,6 +245,25 @@ export NCEI_API_TOKEN=your_token_here
 - 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:
@@ -192,7 +312,7 @@ If you prefer to build from source:
 
 1. Clone the repository:
 ```bash
-git clone https://github.com/dgahagan/weather-mcp.git
+git clone https://github.com/weather-mcp/weather-mcp.git
 cd weather-mcp
 ```
 
@@ -206,6 +326,14 @@ npm install
 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
@@ -257,7 +385,7 @@ npm run build
 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/dgahagan/weather-mcp/releases
+- Latest release: https://github.com/weather-mcp/weather-mcp/releases
 
 ## Usage with AI Assistants
 
@@ -581,6 +709,274 @@ Provides comprehensive marine weather data with intelligent dual-source support:
 - Wave period for planning and safety
 - Optional 5-day forecast with daily summaries
 
+### 9. 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.
+
+### 10. 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.
+
+### 11. 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.
+
+### 12. 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/
+
+### 13. 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
+
+### 14. 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
+
+### 15. 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
+
+### 16. 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")
+
+# 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
@@ -655,7 +1051,7 @@ Use the `check_service_status` tool to proactively verify API availability:
 
 ### Automated Test Suite
 
-This project includes a comprehensive test suite with 722 automated tests:
+This project includes a comprehensive test suite with 1,042 automated tests:
 
 ```bash
 # Run all tests
@@ -672,14 +1068,14 @@ npm run test:ui
 ```
 
 **Test Coverage:**
-- **722 tests** across unit and integration test suites (29 new tests in v1.2.1)
-- **100% coverage** on critical utilities (cache, validation, units, errors, normals, snow, timezone)
-- **54% overall coverage** with focus on reliability and security
-- All tests execute in ~1 second
+- **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** (427 tests) - Cache, validation, units, errors, config, retry logic, normals, snow, timezone
-- **Integration Tests** (19 tests) - Error recovery scenarios, service status checks
+- **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
 
@@ -690,7 +1086,7 @@ npx tsx tests/test_noaa_api.ts
 
 ### Manual Testing with Claude Code
 
-See [TESTING_GUIDE.md](./docs/TESTING_GUIDE.md) for comprehensive manual testing instructions including:
+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
@@ -893,6 +1289,43 @@ To report a security vulnerability, please see our [Security Policy](./SECURITY.
 - 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

package/dist/analytics/anonymizer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Data anonymization utilities for privacy-first analytics
+ * Ensures no PII is collected as per docs/ANALYTICS_MCP_PLAN.md
+ */
+import { AnalyticsEvent, AnalyticsLevel } from './types.js';
+/**
+ * Raw event data before anonymization
+ * Includes all possible fields that might be collected
+ */
+interface RawEventData {
+    version: string;
+    tool: string;
+    status: 'success' | 'error';
+    timestamp_hour: string;
+    analytics_level?: AnalyticsLevel;
+    error_type?: string;
+    response_time_ms?: number;
+    service?: string;
+    cache_hit?: boolean;
+    retry_count?: number;
+    country?: string;
+    parameters?: Record<string, unknown>;
+    session_id?: string;
+    sequence_number?: number;
+}
+/**
+ * Anonymize event data based on analytics level
+ * Strips sensitive information and ensures privacy compliance
+ */
+export declare function anonymizeEvent(rawData: RawEventData, level: AnalyticsLevel, salt?: string): AnalyticsEvent;
+/**
+ * Round timestamp to nearest hour for privacy
+ * Prevents precise user tracking
+ */
+export declare function roundToHour(date: Date): string;
+export {};
+//# sourceMappingURL=anonymizer.d.ts.map

package/dist/analytics/anonymizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anonymizer.d.ts","sourceRoot":"","sources":["../../src/analytics/anonymizer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5D;;;GAGG;AACH,UAAU,YAAY;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,cAAc,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,cAAc,EACrB,IAAI,CAAC,EAAE,MAAM,GACZ,cAAc,CA0ChB;AAiED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAI9C"}