@dangahagan/weather-mcp 1.25.18 → 1.26.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%2C942%20passing-brightgreen)](./docs/testing/TEST_SUITE_README.md)
+[![Tests](https://img.shields.io/badge/tests-3%2C011%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.**
@@ -58,7 +58,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,942 tests. Audit it, fork it, fix it.
+- **Fully open source** — MIT licensed, readable TypeScript, 3,011 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.
 
@@ -80,7 +80,7 @@ All 17 tools, documented in detail in **[docs/TOOLS.md](./docs/TOOLS.md)**:
 | `get_marine_conditions` | Wave height, swell, ocean currents, sea state on WMO Code Table 3700 (Douglas sea scale) with a severity marker and legend — includes Great Lakes and major US bays; forecast up to 16 days | 🌍 Global |
 | `get_weather_imagery` | Precipitation radar (static or 2-hour animated loops) + GOES satellite imagery; `composite: true` returns a finished radar map over a base map as an image | 🌍 Global |
 | `get_lightning_activity` | Real-time strike detection with 4-level proximity safety assessment | 🌍 Global |
-| `get_river_conditions` | US: NWPS gauge levels, flood stages, streamflow, rise/fall trends, forecast series. Elsewhere: GloFAS modeled discharge snapped to the nearest river channel, with ensemble forecast | 🌍 Global |
+| `get_river_conditions` | US: NWPS gauge levels, flood stages, streamflow, rise/fall trends, forecast series. Great Britain: Environment Agency observed river levels against each gauge's published typical range. Elsewhere: GloFAS modeled discharge snapped to the nearest river channel, with ensemble forecast | 🌍 Global |
 | `get_wildfire_info` | US: named incidents with containment, size, and safety guidance from the nearest *uncontained* fire. Elsewhere: NASA FIRMS satellite heat detections (VIIRS, near real-time), clustered with distance, bearing, and intensity | 🌍 Global |
 | `check_service_status` | Health checks for all upstream APIs plus cache statistics | — |
 | `save_location` | Save places as aliases ("home", "cabin") with optional activity tags | — |
@@ -120,6 +120,7 @@ All free, all public, no authentication required:
 | [NOAA Weather API](https://www.weather.gov/documentation/services-web-api) | US forecasts, current conditions, alerts, fire weather | US |
 | [Open-Meteo](https://open-meteo.com/) | Global forecasts, historical data (1940+), air quality, marine, geocoding, climate normals, fire-weather inputs | Global |
 | [NOAA NWPS](https://water.noaa.gov/) | River levels, streamflow, flood stages | US |
+| [Environment Agency](https://environment.data.gov.uk/flood-monitoring/doc/reference) | Observed river levels from the real-time gauge network, with published typical ranges — Open Government Licence v3 | Great Britain |
 | [RCC ACIS](https://www.rcc-acis.org/) | Daily record high/low temperatures | US |
 | [EUMETNET MeteoAlarm](https://meteoalarm.org/) | Official national weather warnings (38 European countries) | Europe |
 | [MSC GeoMet](https://api.weather.gc.ca/) | Environment and Climate Change Canada weather alerts | Canada |
@@ -250,7 +251,7 @@ Or per call — the AI can honor "in Celsius" on the fly:
 { "latitude": 47.6, "longitude": -122.3, "wind_speed_unit": "kn", "pressure_unit": "hPa" }
 ```
 
-Supported on `get_forecast`, `get_current_conditions`, and `get_historical_weather`. Wind accepts `mph`/`kmh`/`ms`/`kn`; pressure `inHg`/`hPa`. Domain-specialized readings (fire-weather heights, river gauge stage, and the marine tool's dual-unit wave output) keep their conventional units.
+Supported on `get_forecast`, `get_current_conditions`, and `get_historical_weather`. Wind accepts `mph`/`kmh`/`ms`/`kn`; pressure `inHg`/`hPa`. Domain-specialized readings (fire-weather heights, NWPS river gauge stage, and the marine tool's dual-unit wave output) keep their conventional units — NWPS stage is always feet. The Environment Agency river level is the exception: it is published in metres and follows the distance preference, so it renders in metres under `km` and feet under `mi`.
 
 ### Other settings
 
@@ -354,7 +355,7 @@ Being honest about what free public data can and can't do:
 | 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, 38 European countries, India, the Philippines, and Indonesia keyless; ~45+ more territories with an optional key | NWS zone-level precision; Europe and India country-level; Philippines and Indonesia polygon-level |
-| River conditions | ✅ (GloFAS modeled discharge) | Gauge observations + official flood stages via NWPS |
+| River conditions | ✅ (GloFAS modeled discharge; Environment Agency gauge observations in Great Britain) | 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` |
@@ -378,7 +379,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,942 tests
+npm test               # Run all 3,011 tests
 npm run test:coverage  # Coverage report
 npm run audit          # Dependency vulnerability scan
 ```

package/dist/config/cache.d.ts

@@ -34,6 +34,8 @@ export declare const CacheConfig: {
         readonly firmsAreaQuery: number;
         readonly firmsRegionalFile: number;
         readonly capDocument: number;
+        readonly eaLatestReadings: number;
+        readonly eaStationDetail: number;
     };
 };
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/config/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkDH,eAAO,MAAM,WAAW;aAEtB,OAAO;aAIP,OAAO;aAIP,YAAY;aAGZ,GAAG;iBAGD,eAAe;iBAIf,SAAS;iBAIT,QAAQ;iBAIR,QAAQ;iBAIR,iBAAiB;iBAIjB,MAAM;iBAIN,gBAAgB;iBAIhB,cAAc;iBAKd,OAAO;iBAIP,aAAa;iBAMb,cAAc;iBAOd,eAAe;iBAMf,YAAY;iBAMZ,OAAO;iBAIP,cAAc;iBAMd,iBAAiB;iBAQjB,YAAY;iBAQZ,cAAc;iBAKd,cAAc;iBAKd,cAAc;iBAKd,iBAAiB;iBAOjB,WAAW;;CAEL,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAYrE"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/config/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkDH,eAAO,MAAM,WAAW;aAEtB,OAAO;aAIP,OAAO;aAIP,YAAY;aAGZ,GAAG;iBAGD,eAAe;iBAIf,SAAS;iBAIT,QAAQ;iBAIR,QAAQ;iBAIR,iBAAiB;iBAIjB,MAAM;iBAIN,gBAAgB;iBAIhB,cAAc;iBAKd,OAAO;iBAIP,aAAa;iBAMb,cAAc;iBAOd,eAAe;iBAMf,YAAY;iBAMZ,OAAO;iBAIP,cAAc;iBAMd,iBAAiB;iBAQjB,YAAY;iBAQZ,cAAc;iBAKd,cAAc;iBAKd,cAAc;iBAKd,iBAAiB;iBAOjB,WAAW;iBAMX,gBAAgB;iBAYhB,eAAe;;CAET,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAYrE"}

package/dist/config/cache.js

@@ -153,6 +153,22 @@ export const CacheConfig = {
         // 24h entry rather than Infinity so a long-running server's LRU is not
         // pinned with dead alerts.
         capDocument: 24 * HOUR,
+        // UK Environment Agency bulk latest-readings pull (GET /data/readings?latest&
+        // parameter=level). Every EA gauge measure publishes on a 15-minute period
+        // (period: 900), so a shorter TTL buys nothing real — the value cannot
+        // change between now and the next 15-minute tick.
+        eaLatestReadings: 15 * MINUTE,
+        // EA per-station detail (GET /id/stations/{ref}?_view=full) — mirrors
+        // nwpsGaugeDetail: read only for its stageScale threshold fields
+        // (datum, typicalRangeHigh/Low, scaleMax, min/maxOnRecord), which are
+        // gauge metadata revised on the order of years. This entry MUST carry the
+        // threshold fields only and never a reading — the same response body also
+        // carries each measure's 15-minute-volatile latestReading, and caching
+        // that whole would serve a day-old river level as current on a
+        // safety-critical output surface (see G7). The service builds a fresh
+        // copy each refresh and merges the volatile reading into that copy;
+        // only the threshold projection is cached at this TTL.
+        eaStationDetail: 24 * HOUR,
     },
 };
 /**

package/dist/config/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/config/cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/config/cache.ts"],"names":[],"mappings":"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"}

package/dist/handlers/riverConditionsHandler.d.ts

@@ -6,6 +6,7 @@ import { OpenMeteoService } from '../services/openmeteo.js';
 import { LocationStore } from '../services/locationStore.js';
 import { GeocodingService } from '../services/geocoding.js';
 import { NominatimService } from '../services/nominatim.js';
+import { EnvironmentAgencyService } from '../services/environmentAgency.js';
 import type { GaugeStatus, StageFlowDataPoint } from '../types/noaa.js';
 /**
  * True only for a real, present numeric reading (not null, not a missing-data sentinel).
@@ -39,14 +40,32 @@ export declare function formatStageTrend(trend: StageTrend): string;
 /**
  * Route a river request to gauge observations or to the global discharge model.
  *
- * `auto` sends US coordinates to NOAA's NWPS gauge network (unchanged) and
- * everywhere else to the Open-Meteo Flood API. An explicit `source` forces the
- * branch. There is deliberately no cross-fallback: an observed river stage in
- * feet against official flood categories and a modeled discharge in m³/s
- * against its own history are different claims, and silently swapping one for
- * the other would misrepresent the data (design D1).
+ * `auto` sends US coordinates to NOAA's NWPS gauge network (unchanged), Great
+ * Britain to the Environment Agency's real gauge network, and everywhere else
+ * to the Open-Meteo Flood API. An explicit `source` forces the branch. There is
+ * deliberately no cross-fallback: an observed river stage in feet against
+ * official flood categories, an observed level in metres against a published
+ * typical range, and a modeled discharge in m³/s against its own history are
+ * three different claims, and silently swapping one for another would
+ * misrepresent the data (design D1).
+ *
+ * **Why the GB arm is gated on a box before a country lookup.** Routing Great
+ * Britain on a country code alone would fire a Nominatim reverse-geocode on
+ * every `auto` river request on Earth outside the US boxes, against a 1 req/sec
+ * server-wide limit, to answer `'gb'` for a fraction of a percent of them.
+ * `isInGreatBritain` is the cheap pre-gate that decides whether the lookup is
+ * worth making; the country code is what actually decides. The box routes and
+ * never renders — no sentence below is derived from it (G53).
+ *
+ * **The EA arm requires a positively-resolved `'gb'`, never a negative test.**
+ * With no country signal at all — no saved `country_code` and no Nominatim
+ * service — `resolveCountryCode` returns `{ countryCode: null }`, which is not
+ * `'gb'`, so `auto` falls to GloFAS. That is a required behaviour, not an
+ * accident: 19 existing tests in `tests/unit/river-conditions-global.test.ts`
+ * pass London on `auto` with no Nominatim fake wired and assert the Open-Meteo
+ * path, and this condition is the single thing keeping all of them green.
  */
-export declare function handleGetRiverConditions(args: unknown, noaaService: NOAAService, locationStore: LocationStore, geocodingService: GeocodingService, openMeteoService?: OpenMeteoService, nominatimService?: NominatimService): Promise<{
+export declare function handleGetRiverConditions(args: unknown, noaaService: NOAAService, locationStore: LocationStore, geocodingService: GeocodingService, openMeteoService?: OpenMeteoService, nominatimService?: NominatimService, eaService?: EnvironmentAgencyService): Promise<{
     content: Array<{
         type: string;
         text: string;

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

@@ -1 +1 @@
-{"version":3,"file":"riverConditionsHandler.d.ts","sourceRoot":"","sources":["../../src/handlers/riverConditionsHandler.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAuB5D,OAAO,KAAK,EAAa,WAAW,EAAyB,kBAAkB,EAAmB,MAAM,kBAAkB,CAAC;AAgC3H;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,IAAI,MAAM,CAE7E;AAcD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAE7D;AAoCD,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,kBAAkB,EAAE,GAAG,SAAS,EACxC,WAAW,GAAE,MAA2B,GACvC,UAAU,GAAG,SAAS,CA6BxB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAO1D;AAaD;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,OAAO,EACb,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,aAAa,EAC5B,gBAAgB,EAAE,gBAAgB,EAClC,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,gBAAgB,CAAC,EAAE,gBAAgB,GAClC,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAyB7D"}
+{"version":3,"file":"riverConditionsHandler.d.ts","sourceRoot":"","sources":["../../src/handlers/riverConditionsHandler.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAsB5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAS5E,OAAO,KAAK,EAAa,WAAW,EAAyB,kBAAkB,EAAmB,MAAM,kBAAkB,CAAC;AAgC3H;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,IAAI,MAAM,CAE7E;AAcD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAE7D;AAoCD,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,kBAAkB,EAAE,GAAG,SAAS,EACxC,WAAW,GAAE,MAA2B,GACvC,UAAU,GAAG,SAAS,CA6BxB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAO1D;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,OAAO,EACb,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,aAAa,EAC5B,gBAAgB,EAAE,gBAAgB,EAClC,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,SAAS,CAAC,EAAE,wBAAwB,GACnC,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CA6D7D"}

package/dist/handlers/riverConditionsHandler.js

@@ -3,13 +3,14 @@
  */
 import { resolveCountryCode, resolveLocationAsync, prependLocationLine } from '../utils/locationResolver.js';
 import { validateDetail, validatePositiveInteger } from '../utils/validation.js';
-import { formatInTimezone, guessTimezoneFromCoords } from '../utils/timezone.js';
+import { formatInTimezone, formatObservationAge, guessTimezoneFromCoords } from '../utils/timezone.js';
 import { calculateDistance } from '../utils/distance.js';
 import { displayValue } from '../utils/displayBanding.js';
-import { isInUS } from '../utils/geography.js';
+import { isInUS, isInGreatBritain } from '../utils/geography.js';
 import { resolveUnitPreferences } from '../utils/unitPreferences.js';
 import { cubicMetersPerSecondToCubicFeetPerSecond } from '../utils/units.js';
 import { buildProbeGrid, pickChannelCell, findTodayIndex, pastWindowValues, recentWindowValues, classifyDischargeTrend, formatDischargeTrend, classifyAgainstRecentMean, describeMinorDrainage, formatSnapNote, PROBE_GRID_CENTER_INDEX } from '../utils/riverDischarge.js';
+import { filterStationsWithRiverName, selectStageMeasure, formatStageLevel, bandRiverLevel } from '../utils/eaGauges.js';
 import { RateLimitError } from '../errors/ApiError.js';
 /**
  * Countries NWPS actually gauges. Measured live 2026-08-28 against
@@ -133,26 +134,81 @@ export function formatStageTrend(trend) {
 /**
  * Route a river request to gauge observations or to the global discharge model.
  *
- * `auto` sends US coordinates to NOAA's NWPS gauge network (unchanged) and
- * everywhere else to the Open-Meteo Flood API. An explicit `source` forces the
- * branch. There is deliberately no cross-fallback: an observed river stage in
- * feet against official flood categories and a modeled discharge in m³/s
- * against its own history are different claims, and silently swapping one for
- * the other would misrepresent the data (design D1).
+ * `auto` sends US coordinates to NOAA's NWPS gauge network (unchanged), Great
+ * Britain to the Environment Agency's real gauge network, and everywhere else
+ * to the Open-Meteo Flood API. An explicit `source` forces the branch. There is
+ * deliberately no cross-fallback: an observed river stage in feet against
+ * official flood categories, an observed level in metres against a published
+ * typical range, and a modeled discharge in m³/s against its own history are
+ * three different claims, and silently swapping one for another would
+ * misrepresent the data (design D1).
+ *
+ * **Why the GB arm is gated on a box before a country lookup.** Routing Great
+ * Britain on a country code alone would fire a Nominatim reverse-geocode on
+ * every `auto` river request on Earth outside the US boxes, against a 1 req/sec
+ * server-wide limit, to answer `'gb'` for a fraction of a percent of them.
+ * `isInGreatBritain` is the cheap pre-gate that decides whether the lookup is
+ * worth making; the country code is what actually decides. The box routes and
+ * never renders — no sentence below is derived from it (G53).
+ *
+ * **The EA arm requires a positively-resolved `'gb'`, never a negative test.**
+ * With no country signal at all — no saved `country_code` and no Nominatim
+ * service — `resolveCountryCode` returns `{ countryCode: null }`, which is not
+ * `'gb'`, so `auto` falls to GloFAS. That is a required behaviour, not an
+ * accident: 19 existing tests in `tests/unit/river-conditions-global.test.ts`
+ * pass London on `auto` with no Nominatim fake wired and assert the Open-Meteo
+ * path, and this condition is the single thing keeping all of them green.
  */
-export async function handleGetRiverConditions(args, noaaService, locationStore, geocodingService, openMeteoService, nominatimService) {
+export async function handleGetRiverConditions(args, noaaService, locationStore, geocodingService, openMeteoService, nominatimService, eaService) {
     // Resolve location from coordinates, a saved location name, or a geocoded city name
     const resolved = await resolveLocationAsync(args, locationStore, geocodingService);
     const { latitude, longitude } = resolved;
     // Output verbosity: 'full' lifts the gauge/crest display caps to 25 (not unbounded).
     const detail = validateDetail(args?.detail);
     const requestedSource = args?.source || 'auto';
-    const useNOAA = requestedSource === 'auto'
-        ? isInUS(latitude, longitude)
-        : requestedSource === 'noaa';
-    const output = useNOAA
-        ? await formatNOAARiverConditions(noaaService, latitude, longitude, args, detail, resolved.country_code, nominatimService)
-        : await formatOpenMeteoRiverConditions(openMeteoService, latitude, longitude, args, detail);
+    // A three-way decision resolved before any request is made. An *unrecognized*
+    // source string must still land on Open-Meteo exactly as it did before this
+    // arm existed: the pre-existing `|| 'auto'` above catches only falsy values,
+    // so an unknown string fell through `=== 'noaa'` being false. The final
+    // `else` preserves that byte-for-byte. Deliberately not the coerce-to-`auto`
+    // shape used in `wildfireHandler.ts` — that would change existing behaviour
+    // on a path this change may not touch.
+    let route;
+    if (requestedSource === 'noaa') {
+        route = 'noaa';
+    }
+    else if (requestedSource === 'ea') {
+        // Honoured anywhere, with a coverage disclosure when it returns nothing.
+        route = 'ea';
+    }
+    else if (requestedSource === 'auto') {
+        if (isInUS(latitude, longitude)) {
+            route = 'noaa';
+        }
+        else if (isInGreatBritain(latitude, longitude)) {
+            // Only inside the box, and only on `auto`, is the lookup worth making.
+            // `resolveCountryCode` lowercases, and a saved location's stored
+            // `country_code` (documented as e.g. `"GB"`) short-circuits it entirely.
+            const { countryCode } = await resolveCountryCode(resolved.country_code, latitude, longitude, nominatimService);
+            route = countryCode === 'gb' ? 'ea' : 'openmeteo';
+        }
+        else {
+            route = 'openmeteo';
+        }
+    }
+    else {
+        route = 'openmeteo';
+    }
+    let output;
+    if (route === 'noaa') {
+        output = await formatNOAARiverConditions(noaaService, latitude, longitude, args, detail, resolved.country_code, nominatimService);
+    }
+    else if (route === 'ea') {
+        output = await formatEARiverConditions(eaService, latitude, longitude, args, detail);
+    }
+    else {
+        output = await formatOpenMeteoRiverConditions(openMeteoService, latitude, longitude, args, detail);
+    }
     return prependLocationLine({
         content: [
             {
@@ -340,6 +396,264 @@ async function formatNOAARiverConditions(noaaService, latitude, longitude, args,
     output += `*River conditions are updated hourly. Always consult official sources for critical decisions.*\n`;
     return output;
 }
+/** Header line naming the authority behind the Great Britain path. */
+const EA_SOURCE_LINE = '**Source:** Environment Agency real-time river level gauges (observed, 15-minute)';
+/**
+ * The attribution the Open Government Licence requires for this API, quoted
+ * **exactly** as the Environment Agency publishes it at
+ * `environment.data.gov.uk/flood-monitoring/doc/reference` (fetched
+ * 2026-09-02): "If you make use of this data please acknowledge this with the
+ * following attribution statement".
+ *
+ * A licence-mandated string is not ours to reword, reflow, or capitalise
+ * differently. Copy it, do not retype it.
+ */
+const EA_ATTRIBUTION = 'this uses Environment Agency flood and river level data from the real-time data API (Beta)';
+/**
+ * How many gauges get their published typical range fetched, regardless of
+ * `detail`.
+ *
+ * Measured parallel fan-out for `/id/stations/{ref}?_view=full` is
+ * non-monotonic, with a local worst case at 8 concurrent requests (15.6 s) —
+ * not at the top of the sweep. So the bound is 5, and the remaining gauges
+ * render without a typical range rather than paying for it.
+ *
+ * **G8 — this is an enrichment bound and nothing else.** It must never change
+ * which gauges are listed, which are counted in the "found N gauges" line, or
+ * which are considered. A bound that trims a set used for exclusion is exactly
+ * how a defensive limit fabricates an all-clear.
+ */
+const EA_DETAIL_FAN_OUT = 5;
+/**
+ * Default search radius for the EA path, in km. Deliberately smaller than the
+ * NOAA path's 50: the EA network is dense, and a 25 km search at York returns
+ * 80 stations of which 68 are river gauges (measured live 2026-09-02).
+ */
+const EA_DEFAULT_RADIUS_KM = 25;
+/**
+ * What an EA level number is measured *from*, in words.
+ *
+ * This is not cosmetic. The EA publishes stage in more than one basis, and 21
+ * of the 68 river gauges around York publish theirs only in `mAOD` — metres
+ * Above Ordnance Datum, which is a water-surface **elevation above sea level**,
+ * not a river depth. Rendering "24.88 ft" for a gauge on the River Foss without
+ * saying so invites the reader to conclude the river is twenty-five feet deep.
+ * On a safety-critical surface that is the mislabelled-quantity defect this
+ * project has produced before, so the basis is always stated beside the number.
+ *
+ * `m` and `mASD` are heights above the gauge's own zero; `mAOD` is an absolute
+ * elevation. The published typical range is in the same basis as the station's
+ * own live stage measure, so the comparison stays coherent either way.
+ */
+function eaLevelBasis(unitName) {
+    switch (unitName) {
+        case 'm':
+        case 'mASD':
+            return 'above the gauge datum';
+        case 'mAOD':
+            return 'above Ordnance Datum (a water-surface elevation, not river depth)';
+        default:
+            return '';
+    }
+}
+/**
+ * The Great Britain path: Environment Agency gauge observations.
+ *
+ * **Contract, not garnish.** A failed EA fetch propagates rather than
+ * degrading to an empty gauge list, because an empty gauge list reads as "no
+ * flooding here". This function therefore does not wrap the fetch in a
+ * catch-all that returns a successful-looking empty render.
+ *
+ * The coverage claim this renders is **the EA river-gauge network**, and it is
+ * made true by construction by the `riverName` filter, not by any geographic
+ * box. A station carrying `riverName` is a river gauge wherever it sits —
+ * Sprouston on the Tweed is in Scotland and is correctly included; Leith is a
+ * tide gauge and is correctly excluded (G53).
+ */
+async function formatEARiverConditions(eaService, latitude, longitude, args, detail) {
+    // A missing service is a wiring fault, not an empty result. Reporting "no
+    // gauges" here would be the fabricated all-clear this whole path is built to
+    // avoid, so it is a contract failure with a message that names the cause.
+    if (!eaService) {
+        throw new Error('Environment Agency river gauge data is unavailable: the service is not configured');
+    }
+    let radius = args?.radius ?? EA_DEFAULT_RADIUS_KM;
+    if (typeof radius !== 'number' || isNaN(radius) || !isFinite(radius)) {
+        radius = EA_DEFAULT_RADIUS_KM;
+    }
+    radius = Math.max(1, Math.min(radius, 500));
+    const prefs = resolveUnitPreferences(args);
+    let output = `# River Conditions Report\n\n`;
+    output += `**Location:** ${latitude.toFixed(4)}, ${longitude.toFixed(4)}\n`;
+    output += `**Search Radius:** ${radius} km (${(radius * 0.621371).toFixed(1)} miles)\n`;
+    output += `${EA_SOURCE_LINE}\n\n`;
+    // Both fetches propagate on failure — see the contract note above.
+    const [stationsResult, readingsResult] = await Promise.all([
+        eaService.getStationsNear(latitude, longitude, radius),
+        eaService.getLatestLevelReadings()
+    ]);
+    // G6 — the list is cached unfiltered; the filter that establishes the
+    // coverage claim runs here, at read time, on every return.
+    const riverStations = filterStationsWithRiverName(stationsResult.stations);
+    const withReadings = riverStations
+        .map(station => ({
+        station,
+        selected: selectStageMeasure(station, readingsResult.readings),
+        distance: station.lat != null && station.long != null
+            ? calculateDistance(latitude, longitude, station.lat, station.long)
+            : undefined
+    }))
+        .sort((a, b) => (a.distance ?? Infinity) - (b.distance ?? Infinity));
+    if (withReadings.length === 0) {
+        // Two different empty results, told apart by the DATA rather than by any
+        // geographic box — the box routes and must never decide a rendered claim
+        // (G53). Zero stations of any kind means the network does not reach here;
+        // stations that are all tidal means it reaches here but publishes no river
+        // gauge. Those are different statements and a reader can act on the
+        // difference.
+        //
+        // G47 — a zero here is a real zero, not a throttled one: this service
+        // treats any non-2xx as a thrown error that propagates, so a rate-limited
+        // upstream can never arrive at this branch looking like an empty result.
+        if (stationsResult.stations.length === 0) {
+            output += `**No Environment Agency monitoring stations were found within ${radius} km.**\n\n`;
+            output += `That is an absence of coverage, not an all-clear. Rivers here may be in `;
+            output += `flood; the Environment Agency simply does not monitor them at this `;
+            output += `location.\n\n`;
+            output += `Try a larger \`radius\`, or use \`source: "openmeteo"\` for Open-Meteo `;
+            output += `Flood (GloFAS) modeled river discharge, which is global.\n`;
+        }
+        else {
+            output += `**No Environment Agency river gauges were found within ${radius} km.**\n\n`;
+            output += `${stationsResult.stations.length} Environment Agency monitoring `;
+            output += `station${stationsResult.stations.length > 1 ? 's were' : ' was'} found nearby, but `;
+            output += `${stationsResult.stations.length > 1 ? 'none of them publish' : 'it does not publish'} `;
+            output += `a river name — they are tidal or coastal gauges, which this tool does not `;
+            output += `report as river levels.\n\n`;
+            output += `That is an absence of river gauging, not an all-clear. Try a larger `;
+            output += `\`radius\`, or use \`source: "openmeteo"\` for Open-Meteo Flood (GloFAS) `;
+            output += `modeled river discharge, which is global.\n`;
+        }
+        output += `\n---\n`;
+        output += `*${EA_ATTRIBUTION}*\n`;
+        return output;
+    }
+    const maxGaugesToShow = detail === 'full' ? 25 : 5;
+    const gaugesToShow = withReadings.slice(0, maxGaugesToShow);
+    // G8 — the count is derived from the full filtered set, never from the
+    // display slice or the enrichment slice. A cap that changed the reported
+    // number would be a defensive limit quietly rewriting what the reader is
+    // told.
+    output += `📊 **Found ${withReadings.length} river gauge${withReadings.length > 1 ? 's' : ''}**\n\n`;
+    // The typical range is GARNISH inside a contract. It is fetched for at most
+    // EA_DETAIL_FAN_OUT of the *displayed* gauges, in parallel, in one try/catch
+    // with no retries — a failure here must add no latency and must never fail
+    // the request. A gauge without a range renders its level and says nothing
+    // more; it is still listed and still counted.
+    const enrichTargets = gaugesToShow.slice(0, EA_DETAIL_FAN_OUT);
+    const thresholdsByRef = new Map();
+    await Promise.all(enrichTargets.map(async ({ station }) => {
+        const ref = station.notation ?? station.stationReference;
+        if (!ref) {
+            return;
+        }
+        try {
+            const thresholds = await eaService.getStationDetail(ref);
+            if (thresholds) {
+                thresholdsByRef.set(ref, thresholds);
+            }
+        }
+        catch {
+            // Garnish: degrade to no range for this gauge, silently and without
+            // retrying. The level itself is already in hand.
+        }
+    }));
+    for (const { station, selected, distance } of gaugesToShow) {
+        const label = typeof station.label === 'string' ? station.label : station.riverName;
+        output += `### ${station.riverName}${label && label !== station.riverName ? ` — ${label}` : ''}\n`;
+        if (distance !== undefined) {
+            // Both units unconditionally, matching the NWPS gauge block below.
+            output += `- **Distance:** ${distance.toFixed(1)} km (${(distance * 0.621371).toFixed(1)} mi)\n`;
+        }
+        if (!selected) {
+            // Honest absence: the station exists and is a river gauge, but no
+            // qualifying level reading is currently published for it. Never a value,
+            // and never anything that could read as "the river is fine".
+            output += `- **Level:** not currently reported by this gauge\n`;
+            output += `\n`;
+            continue;
+        }
+        const level = formatStageLevel(selected.value, prefs);
+        const basis = eaLevelBasis(selected.unitName);
+        output += `- **Level:** ${level.formatted}${basis ? ` ${basis}` : ''}\n`;
+        output += `- **Observed:** ${formatObservationAge(selected.ageMinutes)}\n`;
+        const ref = station.notation ?? station.stationReference;
+        const thresholds = ref ? thresholdsByRef.get(ref) : undefined;
+        // Banded in display space with the same prefs used to print the level
+        // above, so the words and the figures cannot disagree at a rounding edge.
+        // A position report against the published range — never a flood category;
+        // the EA publishes no action/minor/moderate/major equivalent on this API
+        // and `typicalRangeHigh` is not a flood threshold.
+        const band = thresholds ? bandRiverLevel(selected, thresholds, prefs) : null;
+        // **The range is printed only when it is comparable to the level above it.**
+        // `bandRiverLevel` refuses a measure whose qualifier is not `Stage`, because
+        // `stageScale` belongs to the station's Stage measure — and some stations
+        // carry a `riverName` while publishing only a `Tidal Level` measure (the
+        // River Tweed at Berwick is one, live). Printing the range anyway and
+        // merely withholding our own verdict would be worse than useless: the two
+        // numbers sit adjacent and the reader makes the unsafe comparison instead
+        // of us. So when there is no band, there is no range either.
+        if (band && thresholds) {
+            const low = thresholds.typicalRangeLow === undefined
+                ? undefined
+                : formatStageLevel(thresholds.typicalRangeLow, prefs);
+            const high = thresholds.typicalRangeHigh === undefined
+                ? undefined
+                : formatStageLevel(thresholds.typicalRangeHigh, prefs);
+            if (low && high) {
+                output += `- **Typical range:** ${low.formatted} to ${high.formatted}\n`;
+            }
+            else if (high) {
+                output += `- **Typical range:** up to ${high.formatted}\n`;
+            }
+            else if (low) {
+                output += `- **Typical range:** from ${low.formatted}\n`;
+            }
+            output += `- **Against typical range:** ${band.description}\n`;
+        }
+        output += `\n`;
+    }
+    if (gaugesToShow.length > EA_DETAIL_FAN_OUT) {
+        // Say plainly why some gauges carry a range and others do not, so a
+        // missing range reads as "not fetched" rather than "none published".
+        const without = gaugesToShow.length - EA_DETAIL_FAN_OUT;
+        output += `*Note: typical ranges were fetched for the nearest ${EA_DETAIL_FAN_OUT} gauges only; `;
+        output += `the other ${without} are listed without one.*\n`;
+    }
+    if (withReadings.length > maxGaugesToShow) {
+        const remaining = withReadings.length - maxGaugesToShow;
+        const plural = remaining > 1 ? 's' : '';
+        if (detail === 'full') {
+            output += `*Note: ${remaining} additional gauge${plural} found within radius (showing nearest ${maxGaugesToShow})*\n`;
+        }
+        else {
+            output += `*Note: ${remaining} additional gauge${plural} found within radius (showing nearest ${maxGaugesToShow} only — use detail="full" for more)*\n`;
+        }
+    }
+    if (stationsResult.truncated || readingsResult.truncated) {
+        output += `\n*Note: the upstream response exceeded this server's processing limit and was `;
+        output += `trimmed, so this list may be incomplete.*\n`;
+    }
+    output += `\n---\n`;
+    output += `*${EA_ATTRIBUTION}*\n`;
+    // The flood-monitoring API publishes observations only — no forecast. Say so,
+    // rather than letting the absence of a forecast section imply one was checked.
+    output += `*These are observed levels, not a forecast. The Environment Agency publishes `;
+    output += `no flood-stage categories on this API, so the typical range is a normal-conditions `;
+    output += `reference and not a flood threshold. Always consult official flood warnings for `;
+    output += `critical decisions.*\n`;
+    return output;
+}
 /** Header line naming the model behind the global path. */
 const OPENMETEO_SOURCE_LINE = '**Source:** Open-Meteo Flood API (GloFAS v4, ~5 km model grid)';
 /**