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

package/dist/services/space-weather/space-weather-service.d.ts

@@ -8,9 +8,50 @@
 import type { Context } from '@cyanheads/mcp-ts-core';
 import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
 import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
-import type { AuroraForecastData, KpForecast, KpObservation, NoaaScalesData, ProtonFlux, SolarProbabilities, SolarRegion, SolarWindMag, SolarWindPlasma, SpaceWeatherAlert, XrayFlux } from './types.js';
-/** Maps Kp value (0–9) to NOAA G-scale level (0–5). Shared with get-kp-index tool. */
+import type { AuroraForecastData, F107Observation, ForecastDiscussion, KpForecast, KpObservation, NoaaScalesData, ProtonFlux, SolarProbabilities, SolarRegion, SolarWindMag, SolarWindPlasma, SpaceWeatherAlert, XrayFlare, XrayFlux } from './types.js';
+/**
+ * Maps a Kp value (0–9) to its NOAA G-scale level (0–5). Shared with the
+ * get-kp-index tool.
+ *
+ * SWPC publishes Kp in thirds and starts each G level at that level's "minus"
+ * value, so G1 begins at 5− (4.67) rather than 5. Rounding to thirds
+ * (`Math.round(kp * 3)`) maps every spelling of a third — 4.67, 4.66 — onto one
+ * integer, which makes the bands exact integer comparisons instead of float
+ * compares needing a tuned epsilon per band. The top boundary follows the NOAA
+ * scales page, which gives G4 as "Kp = 8, including a 9-" and G5 as "Kp = 9": 8.67
+ * is G4 and only 9.00 is G5.
+ */
 export declare function kpToGScale(kp: number): number;
+/** One geomagnetic-latitude band of the aurora reachability table. */
+export interface AuroraBand {
+    /** Equatorward edge of the band, in degrees of geomagnetic latitude. */
+    geomagneticLatitude: number;
+    /** NOAA G level that reaches this band; 0 means inside the quiet-time oval. */
+    gScale: number;
+    /** Kp floor at which that G level begins; 0 inside the oval. */
+    minKp: number;
+}
+/**
+ * Aurora reachability by geomagnetic latitude, keyed on NOAA G level, ordered
+ * poleward-first. The single table for the whole server: aurora-latitude guidance
+ * on the Kp tools and the Kp threshold the aurora tool reports for a location both
+ * read it, so the two can no longer state different thresholds for one place.
+ *
+ * Latitudes for G2–G5 are the NOAA scales page figures. The 60° G1 row is this
+ * server's interpolation between that page's G2 row and the oval edge — the page
+ * states no G1 latitude. The 65° row is not a storm level at all: it is the
+ * quiet-time equatorward edge of the auroral oval, where aurora needs no elevated
+ * Kp. Below the 40° G5 row no level on the scale reaches.
+ *
+ * Each Kp floor is its level's "minus" third — the value at which SWPC starts the
+ * level, per {@link kpToGScale} — except G5, which begins at a whole Kp 9.
+ */
+export declare const AURORA_BANDS: readonly AuroraBand[];
+/**
+ * Resolve the aurora band a geomagnetic latitude sits in, north or south. Returns
+ * null equatorward of the 40° G5 edge, where no NOAA storm level reaches.
+ */
+export declare function auroraBandForGeomagneticLatitude(geomagneticLatitude: number): AuroraBand | null;
 /** NOAA SWPC public feeds client. Initialized once; accessed via accessor. */
 export declare class SpaceWeatherService {
     /**
@@ -21,6 +62,11 @@ export declare class SpaceWeatherService {
     constructor(config: AppConfig, _storage: StorageService);
     /** Fetch current NOAA storm scales (today + 3-day forecast). */
     getNoaaScales(ctx: Context): Promise<NoaaScalesData>;
+    /**
+     * Fetch the SWPC Forecast Discussion — the forecaster-written narrative explaining
+     * what is driving the storm scales, split into its topic sections.
+     */
+    getForecastDiscussion(ctx: Context): Promise<ForecastDiscussion>;
     /** Fetch observed Kp index history. */
     getKpObserved(ctx: Context): Promise<KpObservation[]>;
     /** Fetch Kp 3-day forecast. */
@@ -40,8 +86,35 @@ export declare class SpaceWeatherService {
      * {@link SpaceWeatherService.getSolarWindPlasma}.
      */
     getSolarWindMag(ctx: Context): Promise<SolarWindMag[]>;
-    /** Fetch GOES X-ray flux (7-day, long-channel 0.1-0.8nm only). */
+    /**
+     * Fetch GOES X-ray flux (6-hour, long-channel 0.1-0.8nm only).
+     *
+     * The 6-hour feed's records are byte-identical to the newest 710 of the 7-day
+     * feed — same seven keys, same two energy channels, same 1-minute cadence, same
+     * newest time tag — so the past-hour slice its only caller takes is the same 61
+     * records either way, for ~4.36 MB less per call.
+     */
     getXrayFlux(ctx: Context): Promise<XrayFlux[]>;
+    /**
+     * Fetch discrete GOES X-ray flare events (rolling 7 days), oldest-first.
+     *
+     * Classes are read as published, not derived from the flux. Ordering is
+     * normalized here rather than depending on upstream's, the same as the solar-wind
+     * series: it makes oldest-first an invariant of the domain type instead of an
+     * accident of the feed.
+     */
+    getXrayFlares(ctx: Context): Promise<XrayFlare[]>;
+    /**
+     * Fetch the latest daily F10.7 solar radio flux report, or null when the feed
+     * carries no Noon record.
+     *
+     * The newest record is not the answer: the feed serves three reports per UTC day
+     * and its index 0 is often that day's Afternoon report, while SWPC's own one-value
+     * summary product reports the Noon one — which is also the only schedule carrying
+     * `ninety_day_mean`. Selection is by time among the Noon records, so it does not
+     * depend on the order upstream serves.
+     */
+    getF107(ctx: Context): Promise<F107Observation | null>;
     /** Fetch active solar regions (most recent observed date only). */
     getSolarRegions(ctx: Context): Promise<SolarRegion[]>;
     /** Fetch solar flare probabilities (3-day forward outlook from the latest issued entry). */

package/dist/services/space-weather/space-weather-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"space-weather-service.d.ts","sourceRoot":"","sources":["../../../src/services/space-weather/space-weather-service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,OAAO,KAAK,EACV,kBAAkB,EAClB,UAAU,EACV,aAAa,EACb,cAAc,EAEd,UAAU,EACV,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,QAAQ,EACT,MAAM,YAAY,CAAC;AAqBpB,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAO7C;AAkXD,8EAA8E;AAC9E,qBAAa,mBAAmB;IAC9B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAInC,YAAY,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAEtD;IAID,gEAAgE;IAC1D,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CA8CzD;IAID,uCAAuC;IACjC,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAkB1D;IAED,+BAA+B;IACzB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAYvD;IAID,qDAAqD;IAC/C,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAoBjE;IAID;;;;;OAKG;IACG,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAYjE;IAED;;;;OAIG;IACG,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAa3D;IAID,kEAAkE;IAC5D,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAcnD;IAED,mEAAmE;IAC7D,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAgC1D;IAED,4FAA4F;IACtF,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAuCvE;IAED,gEAAgE;IAC1D,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAcvD;IAID,gDAAgD;IAC1C,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CA0C1D;CACF;AAMD,0EAA0E;AAC1E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAExF;AAED,4DAA4D;AAC5D,wBAAgB,sBAAsB,IAAI,mBAAmB,CAM5D"}
+{"version":3,"file":"space-weather-service.d.ts","sourceRoot":"","sources":["../../../src/services/space-weather/space-weather-service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,UAAU,EACV,aAAa,EACb,cAAc,EAEd,UAAU,EACV,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,QAAQ,EACT,MAAM,YAAY,CAAC;AAqBpB;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAED,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAO7C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,mBAAmB,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAG/F;AAwwBD,8EAA8E;AAC9E,qBAAa,mBAAmB;IAC9B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAInC,YAAY,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAEtD;IAID,gEAAgE;IAC1D,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAsDzD;IAID;;;OAGG;IACG,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAkBrE;IAID,uCAAuC;IACjC,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAkB1D;IAED,+BAA+B;IACzB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAYvD;IAID,qDAAqD;IAC/C,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsBjE;IAID;;;;;OAKG;IACG,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAYjE;IAED;;;;OAIG;IACG,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAa3D;IAID;;;;;;;OAOG;IACG,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAcnD;IAED;;;;;;;OAOG;IACG,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAkBtD;IAED;;;;;;;;;OASG;IACG,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAe3D;IAED,mEAAmE;IAC7D,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAgC1D;IAED,4FAA4F;IACtF,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA0CvE;IAED,gEAAgE;IAC1D,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAcvD;IAID,gDAAgD;IAC1C,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAiD1D;CACF;AAMD,0EAA0E;AAC1E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAExF;AAED,4DAA4D;AAC5D,wBAAgB,sBAAsB,IAAI,mBAAmB,CAM5D"}