@dangahagan/weather-mcp 1.22.0 → 1.23.0

package/README.md

@@ -3,7 +3,7 @@
 [![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)
-[![Tests](https://img.shields.io/badge/tests-2%2C204%20passing-brightgreen)](./docs/testing/TEST_SUITE_README.md)
+[![Tests](https://img.shields.io/badge/tests-2%2C274%20passing-brightgreen)](./docs/testing/TEST_SUITE_README.md)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org)
 
 **Give your AI assistant real weather data — 17 tools, zero API keys, zero signup, zero cost.**
@@ -50,7 +50,7 @@ Choose this one if you want:
 
 - **Genuinely free** — every data source is a free public API. No trial that expires, no credit card, no rate-limited "free tier" bait.
 - **No API keys** — install to first forecast in under a minute. Nothing to configure, nothing to leak into a repo. ([Three optional keys](#optional-api-keys) add extras if you want them; the default configuration needs none.)
-- **Fully open source** — MIT licensed, readable TypeScript, 2,204 tests. Audit it, fork it, fix it.
+- **Fully open source** — MIT licensed, readable TypeScript, 2,274 tests. Audit it, fork it, fix it.
 - **Privacy-respecting** — your queries go directly from your machine to public weather APIs. No middleman server, no telemetry.
 - **Breadth** — 17 tools covering weather, safety hazards (lightning, floods, wildfires), marine conditions, air quality, and historical data back to 1940. Most weather MCPs stop at forecasts.
 
@@ -256,6 +256,7 @@ Supported on `get_forecast`, `get_current_conditions`, and `get_historical_weath
 | `NCEI_API_TOKEN` | — | Optional [free NCEI token](https://www.ncdc.noaa.gov/cdo-web/token) for official NOAA climate normals (US); falls back to Open-Meteo automatically. See [Optional API keys](#optional-api-keys) |
 | `FIRMS_MAP_KEY` | — | Optional [free FIRMS key](https://firms.modaps.eosdis.nasa.gov/api/map_key/) for targeted wildfire queries and up to 5 days of detection history. See [Optional API keys](#optional-api-keys) |
 | `GOOGLE_POLLEN_API_KEY` | — | Optional key for pollen outside Europe (incl. the US). **Requires a Google Cloud billing account** — free tier is 5,000 lookups/month. See [Optional API keys](#optional-api-keys) and [the setup guide](./docs/GOOGLE_POLLEN_KEY_SETUP.md) |
+| `GOOGLE_WEATHER_API_KEY` | — | Optional key for official weather alerts beyond the US, Canada, and Europe (~45+ more territories). **Requires a Google Cloud billing account.** See [Optional API keys](#optional-api-keys) and [the setup guide](./docs/GOOGLE_WEATHER_KEY_SETUP.md) |
 
 For caching architecture details, see [.github/CACHING.md](./.github/CACHING.md).
 
@@ -266,7 +267,7 @@ zero signup, and zero cost — that is the configuration this project is built
 around and the one most people should use. If that's you, you can skip this
 section entirely.
 
-Three optional keys each unlock one extra. Without them the corresponding tool
+Four optional keys each unlock one extra. Without them the corresponding tool
 still works; it just returns the keyless answer.
 
 | Variable | What it costs | What it adds | Without it |
@@ -274,11 +275,15 @@ still works; it just returns the keyless answer.
 | [`NCEI_API_TOKEN`](https://www.ncdc.noaa.gov/cdo-web/token) | Free registration (email) | Official NOAA station climate normals for US locations | Normals are computed from the Open-Meteo reanalysis archive — global, and the path virtually every user is already on |
 | [`FIRMS_MAP_KEY`](https://firms.modaps.eosdis.nasa.gov/api/map_key/) | Free registration (email) | Targeted wildfire bbox queries with 1–5 days of detection history | Keyless 24-hour regional detection files — `get_wildfire_info` still works globally |
 | `GOOGLE_POLLEN_API_KEY` | **Free tier, but requires a Google Cloud billing account (credit card on file)** — 5,000 lookups/month free, ~$10/1,000 after. [Setup guide](./docs/GOOGLE_POLLEN_KEY_SETUP.md) | Grass/tree/weed Universal Pollen Index outside Europe, including the US (65+ countries) | European pollen via CAMS still works keyless; elsewhere no pollen section renders |
+| `GOOGLE_WEATHER_API_KEY` | **Free tier, but requires a Google Cloud billing account (credit card on file)** — the Weather API bills under a Maps Platform Essentials SKU; check Google's current allowance. [Setup guide](./docs/GOOGLE_WEATHER_KEY_SETUP.md) | Official weather alerts for ~45+ more territories — Australia, Japan, Brazil, Mexico and others ([Google's coverage list](https://developers.google.com/maps/documentation/weather/coverage) is authoritative) | US, Canadian, and European alerts still work keyless; elsewhere `get_alerts` returns today's not-covered message |
 
-The NCEI and FIRMS keys are true free registrations. **The Google Pollen key is
-not** — it has a free usage tier, but Google requires a billing account with a
-payment method to issue it at all. That's why it isn't described as simply
-"free" anywhere in these docs, and why it stays strictly optional.
+The NCEI and FIRMS keys are true free registrations. **The two Google keys are
+not** — each has a free usage tier, but Google requires a billing account with
+a payment method to issue them at all. That's why they aren't described as
+simply "free" anywhere in these docs, and why they stay strictly optional. They
+are separate variables on purpose: the recommended console restriction ties a
+key to one specific API, so a Pollen-restricted key cannot serve alerts and
+vice versa. If you prefer one unrestricted key, put the same string in both.
 
 ### Standing key policy
 
@@ -302,13 +307,14 @@ Being honest about what free public data can and can't do:
 | Historical weather (1940+) | ✅ (>7 days old) | Station-level detail for last 7 days |
 | Air quality, marine, radar, lightning | ✅ | — |
 | Current conditions | ✅ (model data, or real station observations via `source="metar"`) | Station observations via NOAA (richer detail) |
-| Weather alerts | ✅ US, Canada, and 38 European countries | NWS zone-level precision; Europe is matched at country level |
+| Weather alerts | ✅ US, Canada, and 38 European countries keyless; ~45+ more territories with an optional key | NWS zone-level precision; Europe is matched at country level |
 | River conditions | ✅ (GloFAS modeled discharge) | Gauge observations + official flood stages via NWPS |
 | Wildfires | ✅ (FIRMS satellite detections) | Named incidents with acreage + containment via NIFC |
 | Fire weather | ✅ (computed Fosberg index + dryness context) | NOAA-published Haines, grassland, red-flag indices |
 | Pollen | 🇪🇺 Europe keyless (CAMS, grains/m³); elsewhere needs an optional key | Universal Pollen Index with `GOOGLE_POLLEN_API_KEY` |
 
 - European alerts are matched at **country level** — the keyless MeteoAlarm feeds carry no region polygons, so warnings for a large country may not affect the requested point; the output says so. Canadian alerts use a real bbox query with polygon-backed features.
+- Outside the US, Canada, and Europe, alerts need an optional [`GOOGLE_WEATHER_API_KEY`](#optional-api-keys); without one `get_alerts` says plainly that the region isn't covered rather than guessing. With a key, Google aggregates official national feeds for roughly 45 more territories — Australia, Japan, Brazil and Mexico among them, with [Google's coverage page](https://developers.google.com/maps/documentation/weather/coverage) as the authoritative list. Matching is by **provider polygon**, so coverage alignment may not be exact and an empty answer means "no alerts found", not a guarantee of coverage; the output says so both ways. Alert text appears in the publisher's source language. **The US, Canada, and Europe never contact Google** — those authorities stay first choice, key or no key — and a key failure surfaces loudly rather than degrading to a possibly-false all-clear.
 - International current conditions default to **model-interpolated** values at the exact coordinates. `source="metar"` returns a **real instrument reading** instead — but from the nearest airport, which may be tens of km away and up to an hour old. The output always names the station, its distance and bearing, and the observation age, so the tradeoff is visible rather than assumed. METAR coverage follows airports, so remote land and open ocean have real gaps.
 - Historical data older than 7 days comes from reanalysis models (9–25km grid), not direct station observations, and trails real time by ~5 days.
 - Non-US wildfire results are **satellite heat detections, not managed incidents** — no fire names, sizes, or containment percentages exist in the data, detections can include industrial heat sources or agricultural burns, and a clear result is not an all-clear (cloud cover hides fires; small or new fires evade detection). The output frames all of this explicitly. Keyless data covers the last 24 hours; an optional free [`FIRMS_MAP_KEY`](https://firms.modaps.eosdis.nasa.gov/api/map_key/) unlocks targeted queries and up to 5 days of detection history (`day_range`).
@@ -324,7 +330,7 @@ Being honest about what free public data can and can't do:
 ```bash
 npm run build          # Compile TypeScript
 npm run dev            # Run in development mode
-npm test               # Run all 2,204 tests
+npm test               # Run all 2,274 tests
 npm run test:coverage  # Coverage report
 npm run audit          # Dependency vulnerability scan
 ```

package/dist/config/api.d.ts

@@ -77,4 +77,32 @@ export declare const GOOGLE_POLLEN_API_KEY: string | undefined;
  * Check if Google Pollen API key is available (key configured)
  */
 export declare function isGooglePollenKeyAvailable(): boolean;
+/**
+ * Google Weather API key
+ *
+ * OPTIONAL: Create a key in the Google Cloud console
+ * (https://console.cloud.google.com/). Unlike the NCEI and FIRMS keys above,
+ * this one is **not a free registration**: it has a free usage tier, but
+ * **requires a Google Cloud billing account** (credit card on file).
+ * The **Weather API** must be enabled on the project.
+ *
+ * Benefits of providing a key:
+ * - Official weather alerts for ~45+ additional territories (Australia, Japan,
+ *   Brazil, Mexico, and others) via the Google Weather API
+ *
+ * If not provided:
+ * - US, Canadian, and European alerts continue to work keyless
+ * - Alerts outside these regions are unavailable
+ * - No setup required
+ *
+ * Rate limits with key:
+ * - Per Google's Weather API free tier
+ *
+ * Setup guide: docs/GOOGLE_WEATHER_KEY_SETUP.md
+ */
+export declare const GOOGLE_WEATHER_API_KEY: string | undefined;
+/**
+ * Check if Google Weather API key is available (key configured)
+ */
+export declare function isGoogleWeatherKeyAvailable(): boolean;
 //# sourceMappingURL=api.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/config/api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,oBAA6B,CAAC;AAEzD;;GAEG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,oBAA4B,CAAC;AAEvD;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,qBAAqB,oBAAoC,CAAC;AAEvE;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/config/api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,oBAA6B,CAAC;AAEzD;;GAEG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,oBAA4B,CAAC;AAEvD;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,qBAAqB,oBAAoC,CAAC;AAEvE;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,sBAAsB,oBAAqC,CAAC;AAEzE;;GAEG;AACH,wBAAgB,2BAA2B,IAAI,OAAO,CAErD"}

package/dist/config/api.js

@@ -83,4 +83,34 @@ export const GOOGLE_POLLEN_API_KEY = process.env.GOOGLE_POLLEN_API_KEY;
 export function isGooglePollenKeyAvailable() {
     return !!GOOGLE_POLLEN_API_KEY && GOOGLE_POLLEN_API_KEY.trim().length > 0;
 }
+/**
+ * Google Weather API key
+ *
+ * OPTIONAL: Create a key in the Google Cloud console
+ * (https://console.cloud.google.com/). Unlike the NCEI and FIRMS keys above,
+ * this one is **not a free registration**: it has a free usage tier, but
+ * **requires a Google Cloud billing account** (credit card on file).
+ * The **Weather API** must be enabled on the project.
+ *
+ * Benefits of providing a key:
+ * - Official weather alerts for ~45+ additional territories (Australia, Japan,
+ *   Brazil, Mexico, and others) via the Google Weather API
+ *
+ * If not provided:
+ * - US, Canadian, and European alerts continue to work keyless
+ * - Alerts outside these regions are unavailable
+ * - No setup required
+ *
+ * Rate limits with key:
+ * - Per Google's Weather API free tier
+ *
+ * Setup guide: docs/GOOGLE_WEATHER_KEY_SETUP.md
+ */
+export const GOOGLE_WEATHER_API_KEY = process.env.GOOGLE_WEATHER_API_KEY;
+/**
+ * Check if Google Weather API key is available (key configured)
+ */
+export function isGoogleWeatherKeyAvailable() {
+    return !!GOOGLE_WEATHER_API_KEY && GOOGLE_WEATHER_API_KEY.trim().length > 0;
+}
 //# sourceMappingURL=api.js.map

package/dist/config/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/config/api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;AAEzD;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,CAAC,CAAC,cAAc,IAAI,cAAc,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;AAEvD;;GAEG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,CAAC,CAAC,aAAa,IAAI,aAAa,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;AAEvE;;GAEG;AACH,MAAM,UAAU,0BAA0B;IACxC,OAAO,CAAC,CAAC,qBAAqB,IAAI,qBAAqB,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC5E,CAAC"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/config/api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;AAEzD;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,CAAC,CAAC,cAAc,IAAI,cAAc,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;AAEvD;;GAEG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,CAAC,CAAC,aAAa,IAAI,aAAa,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;AAEvE;;GAEG;AACH,MAAM,UAAU,0BAA0B;IACxC,OAAO,CAAC,CAAC,qBAAqB,IAAI,qBAAqB,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;AAEzE;;GAEG;AACH,MAAM,UAAU,2BAA2B;IACzC,OAAO,CAAC,CAAC,sBAAsB,IAAI,sBAAsB,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9E,CAAC"}

package/dist/handlers/alertsHandler.d.ts

@@ -5,7 +5,14 @@
  *   US → NOAA (the original path, byte-identical output),
  *   Canada → MSC GeoMet (Environment and Climate Change Canada),
  *   MeteoAlarm member countries → the country's MeteoAlarm feed,
- *   elsewhere → a clean not-covered message.
+ *   elsewhere → the optional keyed Google Weather API fallback when a
+ *     `GOOGLE_WEATHER_API_KEY` is configured, else a clean not-covered
+ *     message (see docs/global-alerts-fallback-plan.md D1).
+ *
+ * The branch order is the invariant: a US, Canadian, or MeteoAlarm-country
+ * request never contacts Google, key or no key — those are jurisdictional
+ * authorities and stay first-choice. Without a key the elsewhere branch is
+ * byte-identical to before the fallback existed.
  *
  * Country resolution order: a `country_code` already carried by the resolved
  * location (saved location or geocoded city_name), else a cached
@@ -21,12 +28,13 @@ import { GeocodingService } from '../services/geocoding.js';
 import { MeteoAlarmService } from '../services/meteoalarm.js';
 import { GeoMetService } from '../services/geomet.js';
 import { NominatimService } from '../services/nominatim.js';
+import { GoogleWeatherService } from '../services/googleWeather.js';
 type HandlerResult = {
     content: Array<{
         type: string;
         text: string;
     }>;
 };
-export declare function handleGetAlerts(args: unknown, noaaService: NOAAService, locationStore: LocationStore, geocodingService: GeocodingService, meteoAlarmService?: MeteoAlarmService, geoMetService?: GeoMetService, nominatimService?: NominatimService): Promise<HandlerResult>;
+export declare function handleGetAlerts(args: unknown, noaaService: NOAAService, locationStore: LocationStore, geocodingService: GeocodingService, meteoAlarmService?: MeteoAlarmService, geoMetService?: GeoMetService, nominatimService?: NominatimService, googleWeatherService?: GoogleWeatherService): Promise<HandlerResult>;
 export {};
 //# sourceMappingURL=alertsHandler.d.ts.map

package/dist/handlers/alertsHandler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alertsHandler.d.ts","sourceRoot":"","sources":["../../src/handlers/alertsHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EACL,iBAAiB,EAGlB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAuB5D,KAAK,aAAa,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC;AAMxE,wBAAsB,eAAe,CACnC,IAAI,EAAE,OAAO,EACb,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,aAAa,EAC5B,gBAAgB,EAAE,gBAAgB,EAClC,iBAAiB,CAAC,EAAE,iBAAiB,EACrC,aAAa,CAAC,EAAE,aAAa,EAC7B,gBAAgB,CAAC,EAAE,gBAAgB,GAClC,OAAO,CAAC,aAAa,CAAC,CAsDxB"}
+{"version":3,"file":"alertsHandler.d.ts","sourceRoot":"","sources":["../../src/handlers/alertsHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EACL,iBAAiB,EAGlB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAuBpE,KAAK,aAAa,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC;AAMxE,wBAAsB,eAAe,CACnC,IAAI,EAAE,OAAO,EACb,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,aAAa,EAC5B,gBAAgB,EAAE,gBAAgB,EAClC,iBAAiB,CAAC,EAAE,iBAAiB,EACrC,aAAa,CAAC,EAAE,aAAa,EAC7B,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,oBAAoB,CAAC,EAAE,oBAAoB,GAC1C,OAAO,CAAC,aAAa,CAAC,CAsExB"}

package/dist/handlers/alertsHandler.js

@@ -5,7 +5,14 @@
  *   US → NOAA (the original path, byte-identical output),
  *   Canada → MSC GeoMet (Environment and Climate Change Canada),
  *   MeteoAlarm member countries → the country's MeteoAlarm feed,
- *   elsewhere → a clean not-covered message.
+ *   elsewhere → the optional keyed Google Weather API fallback when a
+ *     `GOOGLE_WEATHER_API_KEY` is configured, else a clean not-covered
+ *     message (see docs/global-alerts-fallback-plan.md D1).
+ *
+ * The branch order is the invariant: a US, Canadian, or MeteoAlarm-country
+ * request never contacts Google, key or no key — those are jurisdictional
+ * authorities and stay first-choice. Without a key the elsewhere branch is
+ * byte-identical to before the fallback existed.
  *
  * Country resolution order: a `country_code` already carried by the resolved
  * location (saved location or geocoded city_name), else a cached
@@ -24,7 +31,7 @@ import { logger } from '../utils/logger.js';
 /** Display caps for the international renderers (country feeds routinely carry 50+ warnings). */
 const STANDARD_DISPLAY_CAP = 10;
 const FULL_DISPLAY_CAP = 25;
-export async function handleGetAlerts(args, noaaService, locationStore, geocodingService, meteoAlarmService, geoMetService, nominatimService) {
+export async function handleGetAlerts(args, noaaService, locationStore, geocodingService, meteoAlarmService, geoMetService, nominatimService, googleWeatherService) {
     // Resolve location from coordinates, a saved location name, or a geocoded city name
     const resolved = await resolveLocationAsync(args, locationStore, geocodingService);
     const { latitude, longitude } = resolved;
@@ -67,6 +74,14 @@ export async function handleGetAlerts(args, noaaService, locationStore, geocodin
     if (!countryCode && isInUS(latitude, longitude)) {
         return handleNoaaAlerts(resolved, noaaService, active_only, detail);
     }
+    // 4. Elsewhere (D1): the optional keyed Google Weather API fallback. No
+    //    client-side country allowlist — Google answers the coverage question
+    //    per request, and a hardcoded list would drift and mis-gate border
+    //    regions. Reaching this line already proves the point is not US,
+    //    Canadian, or MeteoAlarm-covered.
+    if (googleWeatherService && googleWeatherService.isKeyAvailable()) {
+        return handleGoogleAlerts(resolved, googleWeatherService, countryCode, active_only, detail, reverseLookupFailed);
+    }
     return notCoveredResult(resolved, countryCode, reverseLookupFailed);
 }
 /**
@@ -220,8 +235,12 @@ function capSeverityEmoji(severity) {
 function capitalize(value) {
     return value.charAt(0).toUpperCase() + value.slice(1);
 }
-/** "…and N more warnings, mostly Minor" remainder line for capped lists. */
-function remainderNote(remainder) {
+/**
+ * "…and N more warnings, mostly Minor" remainder line for capped lists.
+ * Typed on the only field it reads so every CAP-shaped renderer can share it;
+ * `noun` defaults to the MeteoAlarm wording, keeping that output unchanged.
+ */
+function remainderNote(remainder, noun = 'warning') {
     const counts = new Map();
     for (const warning of remainder) {
         const severity = warning.severity ?? 'Unknown';
@@ -236,7 +255,7 @@ function remainderNote(remainder) {
         }
     }
     const plural = remainder.length > 1 ? 's' : '';
-    return `*…and ${remainder.length} more warning${plural}, mostly ${top}. Use detail="full" to see more.*\n\n`;
+    return `*…and ${remainder.length} more ${noun}${plural}, mostly ${top}. Use detail="full" to see more.*\n\n`;
 }
 /**
  * MeteoAlarm (Europe) renderer — CAP-shaped, so visually close to the NOAA
@@ -459,6 +478,296 @@ async function handleGeoMetAlerts(resolved, geoMetService, active_only, detail)
         content: [{ type: 'text', text: output }]
     }, resolved);
 }
+/**
+ * Coverage caveat shown on **both** empty and non-empty Google results (D5/D6).
+ * One constant serves both so the two paths cannot drift apart, and it does
+ * double duty: it explains why an alert may not match the exact point, and why
+ * an empty answer is "none found" rather than a guarantee of coverage.
+ */
+const GOOGLE_COVERAGE_CAVEAT = `*Coverage note: Google aggregates official national alert feeds across ~45+ territories and ` +
+    `matches them by provider polygon, so country and region coverage alignment may not be exact — ` +
+    `warnings may not correspond to your exact point, and an empty result means no alerts were ` +
+    `found rather than a guarantee that this location is covered.*\n\n`;
+/**
+ * Coverage caveat for the uncovered-region answer (HTTP 404). The shared
+ * caveat above is written for a location Google *does* serve, and its closing
+ * clause ("an empty result means no alerts were found") would be actively
+ * misleading here — nothing was searched at all.
+ */
+const GOOGLE_UNCOVERED_CAVEAT = `*Coverage note: Google aggregates official national alert feeds across ~45+ territories, ` +
+    `and this location falls outside that aggregation. Alerts for this area may still be ` +
+    `published directly by the responsible national weather service.*\n\n`;
+/**
+ * Google Weather API footer. The final sentence is the **exact mandatory
+ * attribution string** required by the Weather API policies — do not reword it
+ * (layer 1 of the two-layer attribution; layer 2 is the per-alert `dataSource`
+ * line rendered above).
+ */
+const GOOGLE_FOOTER = `---\n` +
+    `*Data source: official national weather services, aggregated by the Google Weather API. ` +
+    `Alert text is shown in its source language, as issued. ` +
+    `Source: Includes weather data from Google*\n`;
+/**
+ * `alertTitle` is documented as an object but its exact shape is a live
+ * to-verify (design upstream (g)), so both a plain string and a `{ text }`
+ * object are accepted. Anything else falls through to the caller's fallback.
+ */
+function googleAlertTitle(alert) {
+    const title = alert.alertTitle;
+    if (typeof title === 'string' && title.trim().length > 0) {
+        return title;
+    }
+    if (title && typeof title === 'object' && typeof title.text === 'string' && title.text.trim().length > 0) {
+        return title.text;
+    }
+    return humanizeEventType(alert.eventType) ?? 'Weather alert';
+}
+/**
+ * Google publishes CAP-family enums in SCREAMING_CASE (`"MINOR"`,
+ * `"EXPECTED"`, `"POSSIBLE"`) — **live-verified 2026-08-18**, and contrary to
+ * the design's assumption that "Google's severity enum is exactly NOAA's".
+ * It is the same vocabulary in different casing, so it is normalized to the
+ * project's title-case form once, here, before it reaches `capSeverityRank`
+ * or `capSeverityEmoji` — which would otherwise rank every alert `Unknown`
+ * and mark every one ⚪.
+ */
+function capEnumValue(value) {
+    if (!value || value.trim().length === 0) {
+        return undefined;
+    }
+    const cleaned = value.trim().toLowerCase().replace(/_/g, ' ');
+    return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+}
+/** `FLASH_FLOOD` → `Flash Flood`. Returns undefined for an absent/blank enum value. */
+function humanizeEventType(eventType) {
+    if (!eventType || eventType.trim().length === 0) {
+        return undefined;
+    }
+    return eventType
+        .toLowerCase()
+        .split(/[_\s]+/)
+        .filter(part => part.length > 0)
+        .map(capitalize)
+        .join(' ');
+}
+/**
+ * Parse Google's `timezoneOffset` into minutes east of UTC.
+ *
+ * **Live-verified 2026-08-18:** it is a protobuf *Duration in seconds*
+ * (`"28800s"` for UTC+08:00), not the `±HH:MM` the design plan assumed. The
+ * `±HH:MM` form is still accepted defensively, since misreading an offset
+ * silently shifts a safety-critical expiry time rather than failing loudly.
+ */
+function parseTimezoneOffsetMinutes(timezoneOffset) {
+    if (!timezoneOffset) {
+        return undefined;
+    }
+    const raw = timezoneOffset.trim();
+    const secondsMatch = /^(-?\d+)s$/.exec(raw);
+    if (secondsMatch) {
+        return Number(secondsMatch[1]) / 60;
+    }
+    const hhmmMatch = /^([+-])(\d{2}):?(\d{2})$/.exec(raw);
+    if (hhmmMatch) {
+        const [, sign, hours, minutes] = hhmmMatch;
+        return (sign === '-' ? -1 : 1) * (Number(hours) * 60 + Number(minutes));
+    }
+    return undefined;
+}
+/**
+ * Render a UTC instant in the alert's own timezone offset — the "times as
+ * issued" doctrine applied to a source that publishes the instant and the
+ * offset in separate fields. Falls back to `formatPublishedTime` (which
+ * renders the instant as published) when the offset is absent or unparseable.
+ * Deliberately does all arithmetic in UTC so the rendered string never depends
+ * on the server's own timezone.
+ */
+function formatGoogleAlertTime(iso, timezoneOffset) {
+    if (!iso) {
+        return undefined;
+    }
+    const offsetMinutes = parseTimezoneOffsetMinutes(timezoneOffset);
+    const instant = Date.parse(iso);
+    if (offsetMinutes === undefined || Number.isNaN(instant)) {
+        return formatPublishedTime(iso);
+    }
+    const shifted = new Date(instant + offsetMinutes * 60_000);
+    const pad = (value) => String(value).padStart(2, '0');
+    const sign = offsetMinutes < 0 ? '-' : '+';
+    const absolute = Math.abs(offsetMinutes);
+    const label = `${sign}${pad(Math.floor(absolute / 60))}:${pad(absolute % 60)}`;
+    const date = `${shifted.getUTCFullYear()}-${pad(shifted.getUTCMonth() + 1)}-${pad(shifted.getUTCDate())}`;
+    const time = `${pad(shifted.getUTCHours())}:${pad(shifted.getUTCMinutes())}`;
+    return `${date} ${time} (${label})`;
+}
+/**
+ * Google Weather API renderer (D5) — the fourth CAP-shaped renderer, kept
+ * deliberately close to the MeteoAlarm one and reusing the same severity rank,
+ * emoji, display caps, and remainder note (Google's severity enum is exactly
+ * NOAA's).
+ *
+ * **Failure posture is contract, not garnish (D6):** alerts *are* this tool's
+ * whole answer, so nothing here catches a service error. A rejected key, a
+ * timeout, a 429, or a network failure propagates with the service's fixed
+ * sanitized message, exactly as a GeoMet or MeteoAlarm failure surfaces today.
+ * A silent "✅ no alerts" produced by a failed fetch would be a dangerous lie
+ * on safety data.
+ */
+async function handleGoogleAlerts(resolved, googleWeatherService, countryCode, active_only, detail, reverseLookupFailed) {
+    const { alerts, covered } = await googleWeatherService.getPublicAlerts(resolved.latitude, resolved.longitude);
+    const regionName = countryCode ? regionDisplayName(countryCode) : null;
+    let output = regionName ? `# Weather Alerts — ${regionName}\n\n` : `# Weather Alerts\n\n`;
+    output += `**Location:** ${resolved.latitude.toFixed(4)}, ${resolved.longitude.toFixed(4)}\n\n`;
+    if (reverseLookupFailed) {
+        output += `*Note: the country lookup service was unavailable, so routing fell back to coordinate checks.*\n\n`;
+    }
+    if (!active_only) {
+        output += `*Note: historical alerts are not available for this region — showing current alerts only.*\n\n`;
+    }
+    if (alerts.length === 0 && !covered) {
+        // Google answered "I do not cover this place" (HTTP 404). Nothing was
+        // checked, so there is nothing to be reassured by: no ✅, and the text
+        // says out loud that this is not an all-clear. The premise behind the
+        // original single message — that Google returns the same shape for
+        // "quiet" and "uncovered" — was falsified by live testing.
+        output += `ℹ️ **No alert coverage for this location.**\n\n`;
+        output += `The Google Weather API does not cover this area, so **this is not an all-clear** — `;
+        output += `no check for active weather could be made here. A national or local weather service `;
+        output += `may still be issuing warnings.\n\n`;
+    }
+    else if (alerts.length === 0) {
+        // Honest empty (D6): a covered region with nothing active. The message
+        // still credits the source rather than claiming a bare all-clear — the
+        // FIRMS empty-result framing.
+        output += `✅ **No active weather alerts found for this location via the Google Weather API.**\n\n`;
+    }
+    else {
+        output += `⚠️ **${alerts.length} active alert${alerts.length > 1 ? 's' : ''} found**\n\n`;
+        // Sort by CAP severity (the NOAA Extreme→Unknown order), then by expiry.
+        const sorted = [...alerts].sort((a, b) => {
+            const bySeverity = capSeverityRank(capEnumValue(a.severity)) - capSeverityRank(capEnumValue(b.severity));
+            if (bySeverity !== 0) {
+                return bySeverity;
+            }
+            const aExpires = a.expirationTime ? new Date(a.expirationTime).getTime() : Infinity;
+            const bExpires = b.expirationTime ? new Date(b.expirationTime).getTime() : Infinity;
+            return aExpires - bExpires;
+        });
+        if (detail === 'summary') {
+            const bySeverity = new Map();
+            const byEvent = new Map();
+            for (const alert of sorted) {
+                const severity = capEnumValue(alert.severity) ?? 'Unknown';
+                bySeverity.set(severity, (bySeverity.get(severity) ?? 0) + 1);
+                const event = humanizeEventType(alert.eventType);
+                if (event) {
+                    byEvent.set(event, (byEvent.get(event) ?? 0) + 1);
+                }
+            }
+            output += `**By severity:** ${[...bySeverity.entries()]
+                .map(([severity, count]) => `${severity}: ${count}`)
+                .join(' | ')}\n`;
+            if (byEvent.size > 0) {
+                output += `**By type:** ${[...byEvent.entries()]
+                    .map(([event, count]) => `${event}: ${count}`)
+                    .join(' | ')}\n`;
+            }
+            output += `\n*Counts only at detail="summary". Use detail="standard" or detail="full" for the alerts themselves.*\n\n`;
+        }
+        else {
+            const cap = detail === 'full' ? FULL_DISPLAY_CAP : STANDARD_DISPLAY_CAP;
+            const shown = sorted.slice(0, cap);
+            const remainder = sorted.slice(cap);
+            for (const alert of shown) {
+                // The event-type suffix renders only when it says something the title
+                // does not already say — publishers routinely title an alert
+                // "Severe Thunderstorm Warning", and "(Severe Thunderstorm)" beside it
+                // is noise. (Found by reading real rendered output, not a failing test.)
+                const title = googleAlertTitle(alert);
+                const event = humanizeEventType(alert.eventType);
+                const eventSuffix = event && !title.toLowerCase().includes(event.toLowerCase()) ? ` (${event})` : '';
+                const severity = capEnumValue(alert.severity);
+                const urgency = capEnumValue(alert.urgency);
+                const certainty = capEnumValue(alert.certainty);
+                output += `${capSeverityEmoji(severity)} **${title}**${eventSuffix}\n`;
+                output += `---\n`;
+                // Live sampling found publishers that omit all three CAP fields; a line
+                // reading "Unknown | Unknown | Unknown" is noise, so it renders only
+                // when at least one is actually supplied.
+                if (severity || urgency || certainty) {
+                    output += `**Severity:** ${severity ?? 'Unknown'} | **Urgency:** ${urgency ?? 'Unknown'} | **Certainty:** ${certainty ?? 'Unknown'}\n`;
+                }
+                if (alert.areaName) {
+                    output += `**Area:** ${alert.areaName}\n`;
+                }
+                // Times render in the alert's own offset; a null expirationTime
+                // (documented as possible) simply omits its line.
+                const effective = formatGoogleAlertTime(alert.startTime, alert.timezoneOffset);
+                const expires = formatGoogleAlertTime(alert.expirationTime, alert.timezoneOffset);
+                if (effective) {
+                    output += `**Effective:** ${effective}\n`;
+                }
+                if (expires) {
+                    output += `**Expires:** ${expires}\n`;
+                }
+                // Source text renders verbatim, in the publisher's language: the full
+                // description at full only, instructions at standard+full, safety
+                // recommendations at full — the NOAA detail contract.
+                if (detail === 'full' && alert.description) {
+                    output += `\n**Description:**\n${alert.description}\n`;
+                }
+                if (alert.instruction && alert.instruction.length > 0) {
+                    output += `\n**Instructions:**\n${alert.instruction.map(line => `- ${line}`).join('\n')}\n`;
+                }
+                // Live-verified as objects (`{ directive, subtext }`), not strings.
+                // The subtext is the publisher's own expansion of the directive, so it
+                // renders alongside rather than being dropped.
+                if (detail === 'full' && alert.safetyRecommendations && alert.safetyRecommendations.length > 0) {
+                    const recommendations = alert.safetyRecommendations
+                        .map(item => {
+                        const directive = item?.directive?.trim();
+                        const subtext = item?.subtext?.trim();
+                        if (!directive && !subtext) {
+                            return undefined;
+                        }
+                        if (directive && subtext) {
+                            return `- ${directive} ${subtext}`;
+                        }
+                        return `- ${directive ?? subtext}`;
+                    })
+                        .filter((line) => line !== undefined);
+                    if (recommendations.length > 0) {
+                        output += `\n**Safety recommendations:**\n${recommendations.join('\n')}\n`;
+                    }
+                }
+                // Layer 2 of the mandatory attribution (upstream (d)): the original
+                // publisher of this alert, with its authority URI.
+                // Live-verified shape: `{ publisher, name, authorityUri }` — there is no
+                // `fullName`. `name` is the human-readable short form ("PAGASA");
+                // `publisher` is the enum form, used only as a fallback.
+                const publisher = alert.dataSource?.name ?? alert.dataSource?.publisher;
+                if (publisher) {
+                    const uri = alert.dataSource?.authorityUri ? ` (${alert.dataSource.authorityUri})` : '';
+                    output += `\n**Source:** ${publisher}${uri}\n`;
+                }
+                output += `\n`;
+            }
+            if (remainder.length > 0) {
+                // Normalized here too, so the remainder line reads "mostly Minor"
+                // rather than echoing Google's raw "MINOR".
+                output += remainderNote(remainder.map(alert => ({ severity: capEnumValue(alert.severity) })), 'alert');
+            }
+            if (detail !== 'full') {
+                output += `*Showing standard detail. Use detail="full" for complete alert descriptions.*\n\n`;
+            }
+        }
+    }
+    output += covered ? GOOGLE_COVERAGE_CAVEAT : GOOGLE_UNCOVERED_CAVEAT;
+    output += GOOGLE_FOOTER;
+    return prependLocationLine({
+        content: [{ type: 'text', text: output }]
+    }, resolved);
+}
 /**
  * The clean not-covered message (D1): names the region, states the current
  * coverage, and never surfaces a wrong-country upstream error. The one-line