@cyanheads/noaa-spaceweather-mcp-server 0.1.13 → 0.1.14

package/AGENTS.md

@@ -1,11 +1,11 @@
 # Developer Protocol
 
 **Server:** noaa-spaceweather-mcp-server
-**Version:** 0.1.13
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.2`
+**Version:** 0.1.14
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.3`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0 (protocol revisions 2026-07-28 and 2025-*)
-**Zod:** ^4.6.4
+**Zod:** ^4.6.5
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
 
@@ -217,7 +217,7 @@ Available skills:
 | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
 | `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |
-| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixup commits autosquashed into the stack, PR body kept in sync. Release PR mode only |
+| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
 | `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
@@ -268,6 +268,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
 | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
+**CI is one file.** `.github/workflows/codeql.yml` (scaffolded) is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
+
 ---
 
 ## Bundling

package/CLAUDE.md

@@ -1,11 +1,11 @@
 # Developer Protocol
 
 **Server:** noaa-spaceweather-mcp-server
-**Version:** 0.1.13
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.2`
+**Version:** 0.1.14
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.3`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0 (protocol revisions 2026-07-28 and 2025-*)
-**Zod:** ^4.6.4
+**Zod:** ^4.6.5
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
 
@@ -217,7 +217,7 @@ Available skills:
 | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
 | `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |
-| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixup commits autosquashed into the stack, PR body kept in sync. Release PR mode only |
+| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
 | `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
@@ -268,6 +268,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
 | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
+**CI is one file.** `.github/workflows/codeql.yml` (scaffolded) is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
+
 ---
 
 ## Bundling

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.1.13-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/noaa-spaceweather-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/noaa-spaceweather-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/noaa-spaceweather-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.1.14-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/noaa-spaceweather-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/noaa-spaceweather-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/noaa-spaceweather-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -57,6 +57,7 @@ Space weather from NOAA's Space Weather Prediction Center (SWPC) — geomagnetic
 
 - `window_days` (1–7, default 1) bounds the observed series; the forecast series is always SWPC's full 3-day forecast
 - Each observed/forecast record carries Kp, G-scale equivalent, G-scale label, and aurora-latitude guidance
+- G levels follow SWPC's minus-third band floors — G1 starts at Kp 4.67 (5−), G4 runs through 8.67 (9−), and only Kp 9 is G5
 - Forecast excludes the feed's embedded historical "observed" entries — only forward-looking `estimated`/`predicted` rows
 - `observedCount` reports how many observed readings matched the window
 
@@ -65,7 +66,7 @@ Space weather from NOAA's Space Weather Prediction Center (SWPC) — geomagnetic
 ### `noaa_spaceweather_get_aurora_forecast` <sub>tool</sub>
 
 - Without coordinates: global metadata only — grid point count, global peak probability, peak region
-- With `latitude`/`longitude` (WGS84, required together): nearest 1°-grid lookup, minimum Kp needed at that latitude, and a plain-language go/no-go verdict
+- With `latitude`/`longitude` (WGS84, required together): nearest 1°-grid lookup, the centered-dipole geomagnetic latitude those coordinates convert to, the minimum Kp and G level needed at that geomagnetic latitude, and a plain-language go/no-go verdict
 - `invalid_coordinates` error when only one of the pair is supplied
 - OVATION model updates every ~5 minutes; forecast horizon is ~30–60 minutes ahead
 
@@ -92,10 +93,11 @@ Space weather from NOAA's Space Weather Prediction Center (SWPC) — geomagnetic
 
 ### `noaa_spaceweather_get_alerts` <sub>tool</sub>
 
-- `active_only` (default true) — in-force Warnings/Watches/Alerts only; cancellations and Summaries excluded
-- `max_age_hours` (1–720, default 48) bounds how far back to look; the SWPC feed itself has no expiry
-- Each record carries product type, NOAA scale + level (0 means "no scale stated," not zero severity), parsed validity window, and full message text
-- `cancelled` flags a record that cancels a prior product rather than being active
+- `active_only` (default true) — in-force Warnings/Watches/Alerts only. A product stays in force until the feed says otherwise, so this also drops any product a later cancellation names by serial, and all but the newest Watch carrying `THIS SUPERSEDES ANY/ALL PRIOR WATCHES IN EFFECT` — alongside cancellations, Summaries, and products whose validity end has passed
+- `max_age_hours` (1–720, default 48) bounds how far back to look for candidates; the SWPC feed itself has no expiry. Under `active_only=true` it does not cut off a product whose validity end is still ahead, so a multi-day Watch survives until the last day it forecasts a storm for ends; under `active_only=false` it is a literal age cutoff
+- Each record carries product type, NOAA scale + level (0 means "no scale stated," not zero severity), serial number, parsed validity window, and full message text
+- `cancelled` flags a record that cancels a prior product rather than being active; the product it cancels is a separate record, excluded by the serial link rather than by this flag
+- Under `active_only=true` the response echoes the applied window and counts what it excluded, by reason — so an empty result reads as "quiet" or "everything was filtered" without a second call
 
 ---
 
@@ -116,7 +118,7 @@ Agent-friendly output:
 - Observed timestamps on every response so agents can reason about data freshness
 - Plain-language summaries and verdicts alongside raw values — agents can display or reason without re-interpreting indices
 - Bz component surfaced as a first-class field in solar wind output (southward Bz = primary storm driver)
-- Typed error contracts with recovery hints: `feed_unavailable` → "Retry in 30–60 s"
+- Typed error contracts with recovery hints, split on whether retrying can help: a transient feed failure is `feed_unavailable` → "Retry in 30–60 s"; a feed path SWPC no longer serves is `feed_moved` → "Retrying will not help", raised on the first attempt
 
 ---
 

package/changelog/0.1.x/0.1.14.md

@@ -0,0 +1,32 @@
+---
+summary: "Kp→G-scale thresholds follow SWPC thirds, aurora forecast converts to geomagnetic latitude, get_alerts correctly excludes cancelled/superseded Watches, feed failures carry a typed reason, DST-safe forecast dates, NaN token repair"
+breaking: false
+security: false
+---
+
+# 0.1.14 — 2026-09-17
+
+## Added
+
+- **`get_alerts` `serialNumber` field** on every record, plus an `activeOnly` echo of the request scope — resolves the `Cancel Serial Number:` / `Continuation of Serial Number:` chains in the message body. ([#29](https://github.com/cyanheads/noaa-spaceweather-mcp-server/issues/29))
+- **`get_alerts` exclusion disclosure** — under `active_only=true`, enrichment fields `appliedWindowHours`, `appliedCutoff`, and per-reason `exclusions` counts report what was filtered, so an empty result reads as "quiet" or "everything was filtered" without a second call. ([#29](https://github.com/cyanheads/noaa-spaceweather-mcp-server/issues/29))
+- **`get_aurora_forecast` `localLookup.geomagneticLatitude` and `minGScale`** — the centered-dipole geomagnetic latitude the requested coordinates convert to, and the NOAA G level backing `minKpRequired`. ([#28](https://github.com/cyanheads/noaa-spaceweather-mcp-server/issues/28))
+- **`feed_moved` error reason**, declared on all six tools — a permanent 4xx (or the scales feed missing its `"0"` period) now fails in one attempt with a "retrying will not help" recovery hint, instead of retrying or surfacing an unclassified error. ([#30](https://github.com/cyanheads/noaa-spaceweather-mcp-server/issues/30))
+
+## Changed
+
+- **`get_solar_activity` per-region flare-probability fields** (`cFlareProbability`, `mFlareProbability`, `xFlareProbability`, `protonProbability`) now state they cover the UTC day after `observedDate`, matching what SWPC's feed reports. ([#22](https://github.com/cyanheads/noaa-spaceweather-mcp-server/issues/22))
+
+## Fixed
+
+- **`kpToGScale()` follows SWPC's minus-third band floors** (G1 at Kp 4.67, G2 5.67, G3 6.67, G4 7.67, G5 9.00) instead of whole-number cutoffs — `get_kp_index` and `get_conditions` no longer disagree with SWPC's own `noaa_scale`. ([#27](https://github.com/cyanheads/noaa-spaceweather-mcp-server/issues/27))
+- **`get_aurora_forecast` converts geographic coordinates to geomagnetic latitude** before the Kp lookup and wraps longitude at the antimeridian in the nearest-grid-point search — Denver and San Francisco no longer read "aurora not visible" during a storm. Shares one latitude-band table with `gScaleToAuroraLatitude()`. ([#28](https://github.com/cyanheads/noaa-spaceweather-mcp-server/issues/28))
+- **`get_alerts` `active_only=true`** now drops a product named by a later cancellation's `Cancel Serial Number:` and all but the newest Watch carrying the supersede line, and keeps a Watch active past `max_age_hours` while a day it forecasts a storm for is still running. The empty-state text no longer claims "no active alerts" for an unfiltered request. ([#29](https://github.com/cyanheads/noaa-spaceweather-mcp-server/issues/29))
+- **Feed failures carry a declared reason and recovery hint on the wire** — every SWPC feed error now reaches the client as `feed_unavailable` or `feed_moved` with `data.reason`, `data.recovery.hint`, and a `Recovery:` line in `content[]`. ([#30](https://github.com/cyanheads/noaa-spaceweather-mcp-server/issues/30))
+- **`get_solar_activity` forecast dates use UTC epoch arithmetic** instead of local-calendar `setDate`/`getDate` — a 3-day window crossing a DST transition in the process timezone no longer duplicates a forecast day or drifts off midnight UTC. ([#22](https://github.com/cyanheads/noaa-spaceweather-mcp-server/issues/22))
+- **A bare `NaN`/`Infinity` token in any SWPC feed body is repaired to `null`** before the retry loop, instead of failing the parse and burning all four retry attempts on bytes that will never parse differently. ([#25](https://github.com/cyanheads/noaa-spaceweather-mcp-server/issues/25))
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` `^0.13.2` → `^0.13.3`
+- `zod` `^4.6.4` → `^4.6.5`

package/dist/mcp-server/tools/definitions/get-alerts.tool.d.ts

@@ -21,6 +21,7 @@ export declare const getAlerts: import("@cyanheads/mcp-ts-core").ToolDefinition<
         level: z.ZodNumber;
         noaaScale: z.ZodNullable<z.ZodString>;
         cancelled: z.ZodBoolean;
+        serialNumber: z.ZodNullable<z.ZodString>;
         phenomenon: z.ZodString;
         issueDatetime: z.ZodString;
         validFrom: z.ZodNullable<z.ZodString>;
@@ -28,14 +29,31 @@ export declare const getAlerts: import("@cyanheads/mcp-ts-core").ToolDefinition<
         message: z.ZodString;
     }, z.core.$strip>>;
     totalCount: z.ZodNumber;
+    activeOnly: z.ZodBoolean;
     fetchedAt: z.ZodString;
 }, z.core.$strip>, readonly [{
     readonly reason: "feed_unavailable";
     readonly code: JsonRpcErrorCode.ServiceUnavailable;
-    readonly when: "SWPC endpoint returns non-OK status or times out after retries.";
+    readonly when: "SWPC feed returns 5xx or 429, times out, or answers with a body that is not parseable JSON. Retried before failing.";
     readonly retryable: true;
     readonly recovery: "Retry in 30–60 seconds; SWPC feeds occasionally lag during high-activity events.";
+}, {
+    readonly reason: "feed_moved";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "SWPC feed path returns a permanent 4xx (404, 410, 401, 403). Fails in one attempt.";
+    readonly retryable: false;
+    readonly recovery: "Retrying will not help — the SWPC feed path no longer resolves or no longer has the expected shape; the feed URL needs updating against SWPC current inventory.";
 }], {
     readonly notice: z.ZodOptional<z.ZodString>;
+    readonly appliedWindowHours: z.ZodOptional<z.ZodNumber>;
+    readonly appliedCutoff: z.ZodOptional<z.ZodString>;
+    readonly exclusions: z.ZodOptional<z.ZodObject<{
+        agedOut: z.ZodNumber;
+        productType: z.ZodNumber;
+        cancellationRecord: z.ZodNumber;
+        cancelledBySerial: z.ZodNumber;
+        superseded: z.ZodNumber;
+        validityElapsed: z.ZodNumber;
+    }, z.core.$strip>>;
 }>;
 //# sourceMappingURL=get-alerts.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-alerts.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-alerts.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-alerts.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAwDjE,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4IpB,CAAC"}
+{"version":3,"file":"get-alerts.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-alerts.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA+NjE,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqPpB,CAAC"}

package/dist/mcp-server/tools/definitions/get-alerts.tool.js

@@ -5,6 +5,154 @@
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { getSpaceWeatherService } from '../../../services/space-weather/space-weather-service.js';
+/**
+ * Why a record was left out of an `active_only=true` result, in the precedence order a
+ * record is attributed to — each record is counted under the first reason that fires, so
+ * the counts partition the feed rather than overlapping.
+ *
+ * The window leads because it decides which records were candidates at all, and product
+ * type follows because a Summary is never in force whatever its body says. Then the
+ * reasons that name a *replacement* — this record is itself a cancellation, a later
+ * record cancelled it, a later record superseded it — and only last the generic
+ * "its stated end passed".
+ *
+ * That ordering is deliberate: a superseded Watch has usually outlived its own forecast
+ * days too, so ranking elapsed validity higher would report the whole Watch chain as
+ * merely stale and never mention that a newer forecast replaced it. The specific reason
+ * is the one a caller can act on — it points at a successor record.
+ */
+const EXCLUSION_REASONS = [
+    'agedOut',
+    'productType',
+    'cancellationRecord',
+    'cancelledBySerial',
+    'superseded',
+    'validityElapsed',
+];
+/** Product types that can be in force; everything else is informational or unparsed. */
+const IN_FORCE_TYPES = new Set([
+    'Warning',
+    'Watch',
+    'Alert',
+]);
+/**
+ * The record's stated end as an epoch, or null when nothing usable is stated. A validity
+ * line SWPC wrote as prose survives parsing as raw text (see `parseValidity`), and an end
+ * that cannot be read is not evidence the product has finished — those return null and
+ * the record is treated as in force.
+ */
+function endMs(alert) {
+    if (alert.validTo === null)
+        return null;
+    const ms = Date.parse(alert.validTo);
+    return Number.isNaN(ms) ? null : ms;
+}
+/**
+ * Resolve each cancellation to the single record it names, as indices into `all`.
+ *
+ * Serials are per-message-code counters, so the match is scoped to the cancelling
+ * record's own code — the same serial under another code is a different product. SWPC
+ * reuses a serial within a code on a corrected reissue, so "Original Issue Time:" picks
+ * between them when it names one of the candidates; when it names none (a formatting
+ * drift upstream), the nearest preceding record under that code and serial is taken
+ * rather than missing the cancellation entirely.
+ *
+ * Resolving one target per cancellation is what keeps a cancellation from clearing its
+ * whole message code: a single code cycles CONTINUED → CANCEL → CONTINUED within minutes,
+ * and the records either side of the cancellation are still in force.
+ */
+function resolveCancelledBySerial(all) {
+    const cancelled = new Set();
+    for (const cancellation of all) {
+        if (!cancellation.cancelled || !cancellation.cancelsSerialNumber)
+            continue;
+        const cancelIssuedMs = Date.parse(cancellation.issueDatetime);
+        const candidates = all
+            .map((alert, index) => ({ alert, index }))
+            .filter(({ alert }) => alert !== cancellation &&
+            alert.messageCode === cancellation.messageCode &&
+            alert.serialNumber === cancellation.cancelsSerialNumber &&
+            Date.parse(alert.issueDatetime) < cancelIssuedMs)
+            .sort((a, b) => Date.parse(a.alert.issueDatetime) - Date.parse(b.alert.issueDatetime));
+        if (candidates.length === 0)
+            continue;
+        const named = cancellation.cancelsOriginalIssueDatetime;
+        // The two times come from different feed fields — the body's minute-precision
+        // "Issue Time:" versus the record's sub-second `issue_datetime` — so they agree only
+        // to the minute.
+        const exact = named
+            ? candidates.filter(({ alert }) => sameMinute(alert.issueDatetime, named))
+            : [];
+        const target = (exact.length > 0 ? exact : candidates).at(-1);
+        if (target)
+            cancelled.add(target.index);
+    }
+    return cancelled;
+}
+/** True when two ISO 8601 instants fall in the same UTC minute. */
+function sameMinute(a, b) {
+    const aMs = Date.parse(a);
+    const bMs = Date.parse(b);
+    if (Number.isNaN(aMs) || Number.isNaN(bMs))
+        return false;
+    return Math.floor(aMs / 60_000) === Math.floor(bMs / 60_000);
+}
+/**
+ * Indices of every record a later supersede-carrying record has replaced — all of them
+ * but the newest by issue time.
+ *
+ * The rule keys on the line rather than the message code because the line says any and
+ * all: the live Watches are sequential revisions of one three-day forecast, issued under
+ * whichever `WATA*` code matches the level they predict, so scoping per code returns two
+ * conflicting outlooks for the same day. The newest is chosen across the whole feed, not
+ * just the records the window admitted — a superseding record outside the caller's
+ * lookback still happened.
+ *
+ * An unreadable issue time sorts oldest rather than unbeatable: every `>` comparison
+ * against `NaN` is false, so seeding it at 0 is what stops one undated record from
+ * standing as the newest carrier and superseding every genuine Watch behind it.
+ */
+function resolveSuperseded(all) {
+    const issuedMs = ({ alert }) => Date.parse(alert.issueDatetime) || 0;
+    const carriers = all
+        .map((alert, index) => ({ alert, index }))
+        .filter(({ alert }) => alert.supersedes);
+    if (carriers.length <= 1)
+        return new Set();
+    const newest = carriers.reduce((best, current) => issuedMs(current) > issuedMs(best) ? current : best);
+    return new Set(carriers.filter(({ index }) => index !== newest.index).map(({ index }) => index));
+}
+/**
+ * The first reason a record is not in force, or null when it is. A product is in force
+ * until something in the feed says otherwise — a stated end that has passed, a
+ * cancellation naming it, or a later product that supersedes it.
+ */
+function exclusionReason(alert, index, ctx) {
+    const end = endMs(alert);
+    const issuedMs = Date.parse(alert.issueDatetime);
+    // `max_age_hours` bounds how far back to look for candidates; it is not itself a
+    // statement about whether a product is in force. A product whose end is still ahead
+    // stays in scope however old its issue time — without that, the default window drops a
+    // Watch hours before the storm day it forecasts finishes. An issue time that cannot be
+    // read counts as outside the window: nothing places it inside one.
+    const outsideWindow = Number.isNaN(issuedMs) || issuedMs < ctx.cutoffMs;
+    const endAhead = end !== null && end >= ctx.nowMs;
+    if (outsideWindow && !endAhead)
+        return 'agedOut';
+    if (!IN_FORCE_TYPES.has(alert.productType))
+        return 'productType';
+    // A cancellation carries the cancelled product's own type and no validity window, so
+    // neither check above excludes it.
+    if (alert.cancelled)
+        return 'cancellationRecord';
+    if (ctx.cancelledBySerial.has(index))
+        return 'cancelledBySerial';
+    if (ctx.superseded.has(index))
+        return 'superseded';
+    if (end !== null && end < ctx.nowMs)
+        return 'validityElapsed';
+    return null;
+}
 const AlertSchema = z
     .object({
     productId: z
@@ -25,7 +173,11 @@ const AlertSchema = z
         .describe('NOAA scale stated in the message body, e.g. "G1", "R2", "S1"; null when the product states none.'),
     cancelled: z
         .boolean()
-        .describe('True when this record cancels a previously issued product ("CANCEL WARNING:"/"CANCEL ALERT:" headline) rather than being in force. Always false when active_only=true, which excludes cancellations; set active_only=false to see them.'),
+        .describe('True when this record cancels a previously issued product ("CANCEL WARNING:"/"CANCEL WATCH:"/"CANCEL ALERT:" headline) rather than being in force. Always false when active_only=true, which excludes both the cancellation record and the product it names — a cancelled product carries cancelled: false itself, so this flag does not identify one. Set active_only=false to see cancellations and what they cancelled.'),
+    serialNumber: z
+        .string()
+        .nullable()
+        .describe('The record\'s SWPC "Serial Number:" value, e.g. "1125"; null when the body carries no such line. A per-message-code counter, not a globally unique ID — it repeats across codes and within one code on a corrected reissue, so quote it together with messageCode. It is the key the "Cancel Serial Number:", "Extension to Serial Number:", and "Continuation of Serial Number:" lines in message point at, which is what makes those chains navigable.'),
     phenomenon: z
         .string()
         .describe('Short phenomenon name derived from the body\'s NOAA scale letter, e.g. "Geomagnetic", "Radio Blackout", "Solar Radiation".'),
@@ -37,43 +189,55 @@ const AlertSchema = z
     validTo: z
         .string()
         .nullable()
-        .describe('Validity-window end as ISO 8601 UTC, parsed from the message body ("Valid To", "Now Valid Until", or "End Time"); null when the product carries no end line.'),
+        .describe('Validity-window end as ISO 8601 UTC. Read from the message body\'s "Valid To", "Now Valid Until", or "End Time" label when the product states one. A Watch states none, so its end is derived from the "Highest Storm Level Predicted by Day:" list instead: the instant the last listed UTC day forecasting a storm ends (a trailing "None" day is a forecast of quiet, not coverage), so a Watch listing Sep 17 as its last storm day ends at 2026-09-18T00:00:00Z. Null when nothing in the body states or implies an end — a point-in-time Alert, or a Watch forecasting no storm on any listed day.'),
     message: z.string().describe('Full plain-text message body.'),
 })
     .describe('One SWPC alert, watch, warning, or summary.');
 export const getAlerts = tool('noaa_spaceweather_get_alerts', {
     title: 'Get Space Weather Alerts',
     description: 'Active SWPC alerts, watches, and warnings — parsed into structured records with product type, ' +
-        'NOAA scale and level, issue time, validity window, and plain text. Covers geomagnetic storms, ' +
-        'radio blackouts, and radiation storms. With active_only=false, also returns informational ' +
-        'summaries, expired notices, and cancellations. max_age_hours controls how far back to look ' +
-        '(default 48 h); the SWPC feed keeps all historical records and has no built-in expiry.',
+        'NOAA scale and level, issue time, serial number, validity window, and plain text. Covers ' +
+        'geomagnetic storms, radio blackouts, and radiation storms. With active_only=false, also ' +
+        'returns informational summaries, expired notices, and cancellations. max_age_hours controls ' +
+        'how far back to look for candidates (default 48 h) — under active_only=true it does not cut ' +
+        'off a product whose validity end is still in the future, and under active_only=false it is a ' +
+        'literal age cutoff. The SWPC feed keeps all historical records and has no built-in expiry.',
     annotations: { readOnlyHint: true, openWorldHint: true, idempotentHint: true },
     input: z.object({
         active_only: z
             .boolean()
             .default(true)
-            .describe('When true (default), return only in-force Warnings, Watches, and Alerts; exclude Summaries, Other, expired products, and cancellation notices. Set false to return all products, including cancellations (flagged by the cancelled field).'),
+            .describe('When true (default), return only in-force Warnings, Watches, and Alerts. Excluded: Summaries and unrecognized products; products whose validity end has passed; cancellation notices; any product a later cancellation names by serial; and all but the newest record carrying the "THIS SUPERSEDES ANY/ALL PRIOR WATCHES IN EFFECT" line. Counts per reason ride in the exclusions enrichment field. Set false to return every product in the window, cancellations included (flagged by the cancelled field).'),
         max_age_hours: z
             .number()
             .min(1)
             .max(720)
             .default(48)
-            .describe('Maximum age of alerts to return, in hours (default 48). The SWPC feed retains all historical records — this window prevents returning weeks of historical notices as "active."'),
+            .describe('How far back to look for products, in hours (default 48). The SWPC feed retains all historical records, so this bounds the candidate set rather than declaring what is current. Under active_only=true a product whose validity end is still in the future is returned even when its issue time falls outside this window — a multi-day Watch would otherwise disappear while a day it forecasts a storm for is still running. Under active_only=false it is literal and cuts at exactly the requested age.'),
     }),
     output: z.object({
         alerts: z.array(AlertSchema).describe('Matching SWPC alert/watch/warning records.'),
         totalCount: z.number().describe('Count of records in the alerts array.'),
+        activeOnly: z
+            .boolean()
+            .describe('Echo of the active_only input: true when the records are the in-force set, false when they are every product in the window. Distinguishes an empty in-force result from an empty feed window.'),
         fetchedAt: z.string().describe('ISO 8601 timestamp of when this data was fetched.'),
     }),
     errors: [
         {
             reason: 'feed_unavailable',
             code: JsonRpcErrorCode.ServiceUnavailable,
-            when: 'SWPC endpoint returns non-OK status or times out after retries.',
+            when: 'SWPC feed returns 5xx or 429, times out, or answers with a body that is not parseable JSON. Retried before failing.',
             retryable: true,
             recovery: 'Retry in 30–60 seconds; SWPC feeds occasionally lag during high-activity events.',
         },
+        {
+            reason: 'feed_moved',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'SWPC feed path returns a permanent 4xx (404, 410, 401, 403). Fails in one attempt.',
+            retryable: false,
+            recovery: 'Retrying will not help — the SWPC feed path no longer resolves or no longer has the expected shape; the feed URL needs updating against SWPC current inventory.',
+        },
     ],
     async handler(input, ctx) {
         ctx.log.info('Fetching SWPC alerts', {
@@ -82,38 +246,58 @@ export const getAlerts = tool('noaa_spaceweather_get_alerts', {
         });
         const svc = getSpaceWeatherService();
         const all = await svc.getAlerts(ctx);
-        // Apply recency window first — the feed keeps all historical records with no
-        // expiry; without this, active_only=true returns weeks of historical notices.
-        // Compare as Date objects (epoch) — string comparison would silently fail when
-        // issueDatetime and the ISO cutoff don't share the exact same format.
+        // Compare as epochs — string comparison would silently fail when issueDatetime and
+        // the ISO cutoff don't share the exact same format.
         const nowMs = Date.now();
         const cutoffMs = nowMs - input.max_age_hours * 60 * 60 * 1000;
-        const recents = all.filter((a) => new Date(a.issueDatetime).getTime() >= cutoffMs);
-        // active_only admits only in-force Warnings/Watches/Alerts. A product whose
-        // parsed validTo has already elapsed is dropped; Watch/Alert notices carry no
-        // validTo (point-in-time), and a validTo we cannot parse is treated as in-force
-        // — both fall back to the recency window above, so an "active" query never
-        // silently hides a warning whose end time is missing or unreadable.
-        const filtered = input.active_only
-            ? recents.filter((a) => {
-                if (a.productType !== 'Warning' &&
-                    a.productType !== 'Watch' &&
-                    a.productType !== 'Alert') {
-                    return false;
-                }
-                // A cancellation carries the cancelled product's own type and no validity
-                // window, so neither check above excludes it — it must be dropped explicitly.
-                if (a.cancelled)
-                    return false;
-                if (a.validTo === null)
-                    return true;
-                const validToMs = new Date(a.validTo).getTime();
-                return Number.isNaN(validToMs) || validToMs >= nowMs;
-            })
-            : recents;
+        let filtered;
+        let excluded;
+        if (input.active_only) {
+            // Both cross-record rules read the whole feed, not just the records the window
+            // admitted: a cancellation or a superseding Watch issued outside the caller's
+            // lookback still happened.
+            const filterCtx = {
+                nowMs,
+                cutoffMs,
+                cancelledBySerial: resolveCancelledBySerial(all),
+                superseded: resolveSuperseded(all),
+            };
+            const counts = Object.fromEntries(EXCLUSION_REASONS.map((r) => [r, 0]));
+            filtered = [];
+            all.forEach((alert, index) => {
+                const reason = exclusionReason(alert, index, filterCtx);
+                if (reason)
+                    counts[reason] += 1;
+                else
+                    filtered.push(alert);
+            });
+            // Zeros across the board would tell a caller nothing it can act on; the window
+            // echo below already says filtering was applied.
+            if (filtered.length < all.length)
+                excluded = counts;
+            ctx.enrich({
+                appliedWindowHours: input.max_age_hours,
+                appliedCutoff: new Date(cutoffMs).toISOString(),
+            });
+            // Written separately rather than spread in conditionally: enrich accumulates, and
+            // an absent field must stay absent rather than arrive as an explicit undefined.
+            if (excluded)
+                ctx.enrich({ exclusions: excluded });
+        }
+        else {
+            // A literal history window — nothing is filtered by reason, so no counts.
+            filtered = all.filter((a) => Date.parse(a.issueDatetime) >= cutoffMs);
+        }
         if (filtered.length === 0) {
+            // ctx.enrich.notice is last-wins, so the whole empty-state message is composed
+            // once here rather than appended to across branches.
+            const excludedCount = excluded
+                ? Object.values(excluded).reduce((sum, n) => sum + n, 0)
+                : undefined;
             ctx.enrich.notice(input.active_only
-                ? 'No active alerts, watches, or warnings. Set active_only=false to include summaries.'
+                ? excludedCount
+                    ? `No active alerts, watches, or warnings — all ${excludedCount} products in the feed were excluded; see exclusions for the breakdown, or set active_only=false to see them.`
+                    : 'No active alerts, watches, or warnings. Set active_only=false to include summaries.'
                 : 'No space weather products issued in the requested window.');
         }
         return {
@@ -124,6 +308,7 @@ export const getAlerts = tool('noaa_spaceweather_get_alerts', {
                 level: a.level,
                 noaaScale: a.noaaScale,
                 cancelled: a.cancelled,
+                serialNumber: a.serialNumber,
                 phenomenon: a.phenomenon,
                 issueDatetime: a.issueDatetime,
                 validFrom: a.validFrom,
@@ -131,18 +316,69 @@ export const getAlerts = tool('noaa_spaceweather_get_alerts', {
                 message: a.message,
             })),
             totalCount: filtered.length,
+            activeOnly: input.active_only,
             fetchedAt: new Date().toISOString(),
         };
     },
     enrichment: {
-        notice: z.string().optional().describe('Status notice when no alerts are active.'),
+        notice: z.string().optional().describe('Status notice when no products were returned.'),
+        appliedWindowHours: z
+            .number()
+            .optional()
+            .describe('The max_age_hours window as applied, echoed so a caller can see what bounded the candidate set. Present only under active_only=true, where a future validity end can keep an older product in scope.'),
+        appliedCutoff: z
+            .string()
+            .optional()
+            .describe('ISO 8601 UTC instant the applied window starts at: a product issued before this is outside it. Present only under active_only=true.'),
+        exclusions: z
+            .object({
+            agedOut: z
+                .number()
+                .describe('Issued outside the applied window with no validity end still ahead.'),
+            productType: z
+                .number()
+                .describe('Summaries and unrecognized products, which are never in force.'),
+            cancellationRecord: z.number().describe('Cancellation notices themselves.'),
+            cancelledBySerial: z
+                .number()
+                .describe('Named by a later cancellation\'s "Cancel Serial Number:" under the same code.'),
+            superseded: z
+                .number()
+                .describe('Carries the supersede line but is not the newest record that does.'),
+            validityElapsed: z
+                .number()
+                .describe('Validity end already passed, with nothing newer cancelling or superseding it.'),
+        })
+            .optional()
+            .describe('How many products active_only=true left out, by reason. Reasons overlap, so each excluded record is counted under the first that applies, in this field order — these counts plus totalCount equal the number of records the feed carried. Emitted only when something was excluded, and never under active_only=false. Use it to tell "space weather is quiet" from "everything was filtered" without a second active_only=false call.'),
+    },
+    enrichmentTrailer: {
+        // A structured field would otherwise collapse to a JSON blob in the content[]
+        // trailer. Reasons that did not fire are dropped and the keys are left as the schema
+        // spells them, so a reader can map a count straight back to structuredContent.
+        exclusions: {
+            render: (value) => {
+                const counts = value ?? {};
+                const fired = Object.entries(counts)
+                    .filter(([, count]) => count > 0)
+                    .map(([reason, count]) => `${count} ${reason}`);
+                return `**Excluded:** ${fired.length > 0 ? fired.join(', ') : 'none'}`;
+            },
+        },
     },
     format: (result) => {
         const lines = [];
         lines.push(`## SWPC Space Weather Alerts — ${result.fetchedAt}`);
-        lines.push(`**Total:** ${result.totalCount}`);
+        // The scope belongs beside the count: a total of 0 means something different for an
+        // in-force query than for an unfiltered one.
+        const scope = result.activeOnly
+            ? 'active products only'
+            : 'all products in the requested window';
+        lines.push(`**Total:** ${result.totalCount} · **Scope:** ${scope}`);
         if (result.alerts.length === 0) {
-            lines.push('\n_No active alerts._');
+            lines.push(result.activeOnly
+                ? '\n_No active alerts._'
+                : '\n_No space weather products issued in the requested window._');
         }
         else {
             for (const alert of result.alerts) {
@@ -154,7 +390,11 @@ export const getAlerts = tool('noaa_spaceweather_get_alerts', {
                 // Spell out a scale-less product rather than leaving a bare "Level: 0", which
                 // reads as "calm" when it actually means the product states no NOAA scale.
                 const scale = alert.noaaScale ? ` (${alert.noaaScale})` : ' (no NOAA scale)';
-                lines.push(`**Issued:** ${alert.issueDatetime} | **Level:** ${alert.level}${scale}`);
+                // The serial is what makes the "Cancel Serial Number:" and "Continuation of
+                // Serial Number:" chains in the body navigable, so it rides here for clients
+                // that render only content[].
+                const serial = alert.serialNumber ?? 'not stated';
+                lines.push(`**Issued:** ${alert.issueDatetime} | **Level:** ${alert.level}${scale} | **Serial:** ${serial}`);
                 if (alert.validFrom)
                     lines.push(`**Valid From:** ${alert.validFrom}`);
                 if (alert.validTo)