spaceweather-mcp 0.1.0__tar.gz

spaceweather_mcp-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Build artifacts
+build/
+dist/
+
+# Virtual envs
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Local Claude Code settings
+.claude/settings.local.json
+
+# MCP registry publisher binary
+mcp-publisher.exe
+mcp-publisher.tar.gz
+
+# OS
+.DS_Store
+Thumbs.db

spaceweather_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 matt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spaceweather_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: spaceweather-mcp
+Version: 0.1.0
+Summary: Space-weather and geomagnetic conditions (NOAA SWPC planetary Kp, solar wind, storm scales, alerts, 27-day outlook) as a Model Context Protocol server.
+Project-URL: Homepage, https://github.com/hoon1983/spaceweather-mcp
+Project-URL: Repository, https://github.com/hoon1983/spaceweather-mcp
+Project-URL: Issues, https://github.com/hoon1983/spaceweather-mcp/issues
+Author: matt
+License: MIT
+License-File: LICENSE
+Keywords: aurora,geomagnetic,heliophysics,kp-index,mcp,model-context-protocol,noaa,solar-wind,space-weather,swpc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=3.0
+Requires-Dist: httpx[http2]>=0.27
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# spaceweather-mcp
+
+<!-- mcp-name: io.github.hoon1983/spaceweather-mcp -->
+
+A Model Context Protocol server for **space weather and geomagnetic conditions** — solar flares, the solar wind, geomagnetic storms (Kp/Dst), radiation storms, sunspot regions, aurora forecasts, and a catalogued event history — so an AI agent can answer "what's the sun/space weather doing right now, and will I see aurora?" from authoritative data.
+
+Sibling to [seismic-mcp](https://github.com/hoon1983/seismic-mcp): that one reconciles earthquakes across agencies; this one reports solar/geomagnetic conditions. They install side by side.
+
+## Status
+
+**15 tools across 4 data sources — all live and verified.** Everything is U.S./NASA public domain except the Kyoto Dst index, which is non-commercial and clearly labeled (and kept segregated from the public-domain feeds).
+
+## Tools
+
+**NOAA SWPC** (public domain)
+| Tool | Returns |
+| --- | --- |
+| `get_conditions_now` | One-call snapshot: Kp, Bz/Bt, wind speed/density, G/S/R, storm flag, summary |
+| `get_kp_index` | Observed planetary Kp series (~1 week) |
+| `get_kp_forecast` | NOAA 3-day Kp forecast |
+| `get_solar_wind` | L1 magnetic field + plasma (`window`: `1-day`/`7-day`) |
+| `get_alerts` | Recent SWPC alerts/watches/warnings |
+| `get_noaa_scales` | G/S/R scales for today + 3 days |
+| `get_27day_outlook` | Daily F10.7 flux, Ap, largest Kp for 27 days |
+| `get_solar_flares` | Recent GOES X-ray flares (C/M/X class events) |
+| `get_radiation_storm` | Current proton flux + NOAA S-scale (radiation storm) |
+| `get_solar_regions` | Today's sunspot regions + C/M/X flare probabilities |
+| `get_aurora_forecast` | OVATION aurora probability (pass lat/lon for a local %) |
+
+**NASA DONKI** (public domain) — `get_space_weather_events` (CME / GST / FLR / SEP / IPS / HSS event catalog)
+
+**USGS Geomagnetism** (public domain) — `list_observatories`, `get_observatory` (magnetometer X/Y/Z/F)
+
+**Kyoto WDC** (non-commercial) — `get_dst` (hourly disturbance storm-time index)
+
+## Run
+
+```bash
+uv run spaceweather-mcp        # stdio MCP server
+uv run pytest                  # tests
+```
+
+Add to `claude_desktop_config.json` (after publishing to PyPI):
+
+```json
+{ "mcpServers": { "spaceweather": { "command": "uvx", "args": ["spaceweather-mcp"] } } }
+```
+
+## Data sources, attribution & licensing
+
+- **NOAA SWPC** (`services.swpc.noaa.gov`) — U.S. public domain. Credit NOAA SWPC.
+- **NASA DONKI** via CCMC (`kauai.ccmc.gsfc.nasa.gov/DONKI`) — U.S. public domain (no API key needed). Credit NASA/CCMC DONKI.
+- **USGS Geomagnetism** (`geomag.usgs.gov`) — U.S. public domain. Credit the U.S. Geological Survey. (Sourced directly from USGS, not via INTERMAGNET, to keep public-domain status.)
+- **Kyoto WDC for Geomagnetism** — Dst index, **non-commercial use only**: acknowledge "WDC for Geomagnetism, Kyoto", cite the Dst DOI; real-time values are provisional. The non-commercial restriction is documented in the `get_dst` tool description and the `DstReading` schema (both surfaced to MCP clients), and this feed is kept separate from the public-domain ones.
+
+> ⚠️ Only the Kyoto Dst feed is non-commercial. It is segregated, and its non-commercial terms are stated in the tool/schema docs the client sees, so a downstream commercial user is not silently bound by those terms.
+
+**Deliberately not included:** INTERMAGNET and SILSO sunspot number (both CC BY-**NC** — would taint the otherwise commercially-usable server); JPL Horizons ephemeris (different domain). F10.7 is available via `get_27day_outlook`; GFZ Hp30/Hp60 high-cadence indices (CC BY 4.0) are a possible future add.
+
+## Safety
+
+Informational only. **Not** for operational decisions affecting power grids, aviation, satellites, or human safety — consult official NOAA SWPC products for those. Real-time values are preliminary and routinely revised.

spaceweather_mcp-0.1.0/README.md

@@ -0,0 +1,62 @@
+# spaceweather-mcp
+
+<!-- mcp-name: io.github.hoon1983/spaceweather-mcp -->
+
+A Model Context Protocol server for **space weather and geomagnetic conditions** — solar flares, the solar wind, geomagnetic storms (Kp/Dst), radiation storms, sunspot regions, aurora forecasts, and a catalogued event history — so an AI agent can answer "what's the sun/space weather doing right now, and will I see aurora?" from authoritative data.
+
+Sibling to [seismic-mcp](https://github.com/hoon1983/seismic-mcp): that one reconciles earthquakes across agencies; this one reports solar/geomagnetic conditions. They install side by side.
+
+## Status
+
+**15 tools across 4 data sources — all live and verified.** Everything is U.S./NASA public domain except the Kyoto Dst index, which is non-commercial and clearly labeled (and kept segregated from the public-domain feeds).
+
+## Tools
+
+**NOAA SWPC** (public domain)
+| Tool | Returns |
+| --- | --- |
+| `get_conditions_now` | One-call snapshot: Kp, Bz/Bt, wind speed/density, G/S/R, storm flag, summary |
+| `get_kp_index` | Observed planetary Kp series (~1 week) |
+| `get_kp_forecast` | NOAA 3-day Kp forecast |
+| `get_solar_wind` | L1 magnetic field + plasma (`window`: `1-day`/`7-day`) |
+| `get_alerts` | Recent SWPC alerts/watches/warnings |
+| `get_noaa_scales` | G/S/R scales for today + 3 days |
+| `get_27day_outlook` | Daily F10.7 flux, Ap, largest Kp for 27 days |
+| `get_solar_flares` | Recent GOES X-ray flares (C/M/X class events) |
+| `get_radiation_storm` | Current proton flux + NOAA S-scale (radiation storm) |
+| `get_solar_regions` | Today's sunspot regions + C/M/X flare probabilities |
+| `get_aurora_forecast` | OVATION aurora probability (pass lat/lon for a local %) |
+
+**NASA DONKI** (public domain) — `get_space_weather_events` (CME / GST / FLR / SEP / IPS / HSS event catalog)
+
+**USGS Geomagnetism** (public domain) — `list_observatories`, `get_observatory` (magnetometer X/Y/Z/F)
+
+**Kyoto WDC** (non-commercial) — `get_dst` (hourly disturbance storm-time index)
+
+## Run
+
+```bash
+uv run spaceweather-mcp        # stdio MCP server
+uv run pytest                  # tests
+```
+
+Add to `claude_desktop_config.json` (after publishing to PyPI):
+
+```json
+{ "mcpServers": { "spaceweather": { "command": "uvx", "args": ["spaceweather-mcp"] } } }
+```
+
+## Data sources, attribution & licensing
+
+- **NOAA SWPC** (`services.swpc.noaa.gov`) — U.S. public domain. Credit NOAA SWPC.
+- **NASA DONKI** via CCMC (`kauai.ccmc.gsfc.nasa.gov/DONKI`) — U.S. public domain (no API key needed). Credit NASA/CCMC DONKI.
+- **USGS Geomagnetism** (`geomag.usgs.gov`) — U.S. public domain. Credit the U.S. Geological Survey. (Sourced directly from USGS, not via INTERMAGNET, to keep public-domain status.)
+- **Kyoto WDC for Geomagnetism** — Dst index, **non-commercial use only**: acknowledge "WDC for Geomagnetism, Kyoto", cite the Dst DOI; real-time values are provisional. The non-commercial restriction is documented in the `get_dst` tool description and the `DstReading` schema (both surfaced to MCP clients), and this feed is kept separate from the public-domain ones.
+
+> ⚠️ Only the Kyoto Dst feed is non-commercial. It is segregated, and its non-commercial terms are stated in the tool/schema docs the client sees, so a downstream commercial user is not silently bound by those terms.
+
+**Deliberately not included:** INTERMAGNET and SILSO sunspot number (both CC BY-**NC** — would taint the otherwise commercially-usable server); JPL Horizons ephemeris (different domain). F10.7 is available via `get_27day_outlook`; GFZ Hp30/Hp60 high-cadence indices (CC BY 4.0) are a possible future add.
+
+## Safety
+
+Informational only. **Not** for operational decisions affecting power grids, aviation, satellites, or human safety — consult official NOAA SWPC products for those. Real-time values are preliminary and routinely revised.

spaceweather_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "spaceweather-mcp"
+version = "0.1.0"
+description = "Space-weather and geomagnetic conditions (NOAA SWPC planetary Kp, solar wind, storm scales, alerts, 27-day outlook) as a Model Context Protocol server."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "matt" }]
+license = { text = "MIT" }
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "space-weather",
+    "geomagnetic",
+    "kp-index",
+    "solar-wind",
+    "aurora",
+    "noaa",
+    "swpc",
+    "heliophysics",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+dependencies = [
+    "fastmcp>=3.0",
+    "httpx[http2]>=0.27",
+    "pydantic>=2.7",
+]
+
+[project.scripts]
+spaceweather-mcp = "spaceweather_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/hoon1983/spaceweather-mcp"
+Repository = "https://github.com/hoon1983/spaceweather-mcp"
+Issues = "https://github.com/hoon1983/spaceweather-mcp/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spaceweather_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+filterwarnings = ["ignore::DeprecationWarning"]

spaceweather_mcp-0.1.0/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.hoon1983/spaceweather-mcp",
+  "description": "Space weather and geomagnetic conditions (NOAA SWPC, NASA DONKI, USGS Geomag, Kyoto Dst) as a Model Context Protocol server.",
+  "repository": {
+    "url": "https://github.com/hoon1983/spaceweather-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "spaceweather-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

spaceweather_mcp-0.1.0/src/spaceweather_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""spaceweather-mcp: space-weather and geomagnetic conditions as an MCP server."""
+
+__version__ = "0.1.0"

spaceweather_mcp-0.1.0/src/spaceweather_mcp/cache.py

@@ -0,0 +1,51 @@
+"""Tiny async TTL cache with in-flight de-duplication.
+
+SWPC products update every 1-5 minutes; a short TTL turns a burst of tool
+calls (and a UI poll loop) into a single upstream fetch. The per-key lock
+collapses concurrent misses so we never fire the same request twice at once.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Awaitable, Callable, TypeVar
+
+T = TypeVar("T")
+
+
+class TTLCache:
+    def __init__(self, ttl_seconds: float = 60.0) -> None:
+        self.ttl = ttl_seconds
+        self._store: dict[str, tuple[float, object]] = {}
+        self._locks: dict[str, asyncio.Lock] = {}
+
+    async def get_or_fetch(self, key: str, fetch: Callable[[], Awaitable[T]]) -> T:
+        hit = self._store.get(key)
+        if hit is not None and (time.monotonic() - hit[0]) < self.ttl:
+            return hit[1]  # type: ignore[return-value]
+
+        lock = self._locks.setdefault(key, asyncio.Lock())
+        async with lock:
+            # Re-check: another coroutine may have filled it while we waited.
+            hit = self._store.get(key)
+            if hit is not None and (time.monotonic() - hit[0]) < self.ttl:
+                return hit[1]  # type: ignore[return-value]
+            value = await fetch()
+            self._store[key] = (time.monotonic(), value)
+            self._prune()
+            return value
+
+    def _prune(self) -> None:
+        """Drop expired entries (and their now-idle locks) so the cache stays
+        bounded even when callers key on ever-changing URLs (time windows)."""
+        now = time.monotonic()
+        for k in [k for k, (ts, _) in self._store.items() if (now - ts) >= self.ttl]:
+            self._store.pop(k, None)
+            lk = self._locks.get(k)
+            if lk is not None and not lk.locked():
+                self._locks.pop(k, None)
+
+    def clear(self) -> None:
+        self._store.clear()
+        self._locks.clear()

spaceweather_mcp-0.1.0/src/spaceweather_mcp/schemas.py

@@ -0,0 +1,210 @@
+"""Canonical schemas for space-weather data returned by the MCP tools.
+
+All times are timezone-aware UTC. Missing numeric values are ``None`` (never
+NaN) so the output is always valid JSON.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class KpReading(BaseModel):
+    """One observed planetary K-index sample (3-hour cadence, NOAA SWPC)."""
+
+    time: datetime
+    kp: float = Field(..., description="Planetary K-index, 0-9. >=5 is geomagnetic storm level.")
+    a_running: Optional[float] = Field(None, description="Running estimate of the daily Ap index.")
+    station_count: Optional[int] = None
+
+
+class KpForecastPoint(BaseModel):
+    time: datetime
+    kp: float
+    observed: str = Field("predicted", description="'observed', 'estimated', or 'predicted'.")
+
+
+class SolarWindMag(BaseModel):
+    """Interplanetary magnetic field, GSM coordinates (nT)."""
+
+    time: datetime
+    bx: Optional[float] = None
+    by: Optional[float] = None
+    bz: Optional[float] = Field(None, description="Southward (negative) Bz couples energy into the magnetosphere.")
+    bt: Optional[float] = Field(None, description="Total field magnitude.")
+
+
+class SolarWindPlasma(BaseModel):
+    time: datetime
+    density: Optional[float] = Field(None, description="Proton density, particles/cm^3.")
+    speed: Optional[float] = Field(None, description="Bulk solar wind speed, km/s.")
+    temperature: Optional[float] = Field(None, description="Kelvin.")
+
+
+class SolarWind(BaseModel):
+    window: str
+    mag: list[SolarWindMag]
+    plasma: list[SolarWindPlasma]
+
+
+class Alert(BaseModel):
+    """A NOAA SWPC alert/watch/warning bulletin."""
+
+    product_id: str
+    issued: datetime
+    message: str
+
+
+class ScaleValue(BaseModel):
+    scale: Optional[int] = Field(None, description="0-5 on the NOAA scale (0 = none).")
+    text: Optional[str] = Field(None, description="e.g. 'Minor', 'Moderate', 'Strong'.")
+
+
+class ScaleDay(BaseModel):
+    index: int = Field(..., description="0 = current/today, 1-3 = following days.")
+    date_stamp: Optional[str] = None
+    g: Optional[ScaleValue] = Field(None, description="G - geomagnetic storm.")
+    s: Optional[ScaleValue] = Field(None, description="S - solar radiation storm.")
+    r: Optional[ScaleValue] = Field(None, description="R - radio blackout.")
+
+
+class NoaaScales(BaseModel):
+    days: list[ScaleDay]
+
+
+class OutlookRow(BaseModel):
+    date: str
+    radio_flux_107: int = Field(..., description="F10.7 cm solar radio flux (sfu).")
+    planetary_a: int = Field(..., description="Predicted planetary Ap index.")
+    largest_kp: int = Field(..., description="Largest predicted Kp for the day.")
+
+
+class Outlook(BaseModel):
+    issued: str
+    rows: list[OutlookRow]
+
+
+class ConditionsNow(BaseModel):
+    """A single-call snapshot of current space-weather conditions."""
+
+    kp: Optional[float] = None
+    kp_time: Optional[datetime] = None
+    bz_nt: Optional[float] = None
+    bt_nt: Optional[float] = None
+    solar_wind_speed_kms: Optional[float] = None
+    density_per_cc: Optional[float] = None
+    scale_g: Optional[ScaleValue] = None
+    scale_s: Optional[ScaleValue] = None
+    scale_r: Optional[ScaleValue] = None
+    geomagnetic_storm: bool = Field(False, description="True when current Kp >= 5.")
+    summary: str = Field("", description="Human-readable one-line status.")
+
+
+class Observatory(BaseModel):
+    """A magnetic observatory whose data is queryable via get_observatory."""
+
+    id: str = Field(..., description="3-letter IAGA code, e.g. 'BOU', 'HON'.")
+    name: str
+    latitude: float
+    longitude: float
+    network: str = "USGS"
+
+
+class ObservatorySeries(BaseModel):
+    """Ground magnetometer time series for one observatory (USGS Geomagnetism)."""
+
+    station: str
+    name: Optional[str] = None
+    latitude: Optional[float] = None
+    longitude: Optional[float] = None
+    sampling_period_s: int
+    data_type: str = Field(..., description="variation | adjusted | quasi-definitive | definitive")
+    times: list[datetime]
+    values: dict[str, list[Optional[float]]] = Field(
+        default_factory=dict, description="Per-element series (nT), e.g. {'X': [...], 'Y': [...]}."
+    )
+    latest: dict[str, Optional[float]] = Field(
+        default_factory=dict, description="Most recent finite value per element (nT)."
+    )
+
+
+class DstReading(BaseModel):
+    """One hourly Dst (disturbance storm-time) index value, in nT (Kyoto WDC).
+
+    Dst measures the ring-current depression during geomagnetic storms: roughly
+    > -30 quiet, -30..-50 unsettled, -50..-100 moderate storm, -100..-250 intense,
+    < -250 great storm.
+
+    NON-COMMERCIAL data: cite "WDC for Geomagnetism, Kyoto" and the Dst DOI;
+    real-time values are provisional ("quicklook") and subject to revision.
+    """
+
+    time: datetime
+    dst_nt: int
+
+
+class SolarFlare(BaseModel):
+    """One GOES X-ray flare event (NOAA SWPC)."""
+
+    begin_time: Optional[datetime] = None
+    begin_class: Optional[str] = None
+    max_time: Optional[datetime] = None
+    max_class: Optional[str] = Field(None, description="Peak GOES class, e.g. 'C3.2', 'M2.1', 'X1.0'.")
+    max_flux: Optional[float] = Field(None, description="Peak long-channel flux, W/m^2.")
+    end_time: Optional[datetime] = None
+    satellite: Optional[int] = None
+
+
+class RadiationStatus(BaseModel):
+    """Current solar radiation (energetic proton) environment, NOAA SWPC GOES."""
+
+    time: Optional[datetime] = None
+    flux_by_energy: dict[str, Optional[float]] = Field(
+        default_factory=dict, description="Latest integral proton flux (pfu) per energy threshold, e.g. {'>=10 MeV': 0.3}."
+    )
+    s_scale: int = Field(0, description="NOAA S (radiation storm) scale 0-5, from the >=10 MeV flux.")
+    s_text: str = ""
+    radiation_storm: bool = Field(False, description="True when S >= 1 (>=10 MeV flux >= 10 pfu).")
+
+
+class SolarRegion(BaseModel):
+    """An active sunspot region with flare probabilities (NOAA SWPC)."""
+
+    region: Optional[int] = None
+    observed_date: Optional[str] = None
+    location: Optional[str] = None
+    latitude: Optional[float] = None
+    longitude: Optional[float] = None
+    area: Optional[int] = None
+    number_spots: Optional[int] = None
+    spot_class: Optional[str] = None
+    mag_class: Optional[str] = None
+    c_flare_probability: Optional[int] = None
+    m_flare_probability: Optional[int] = None
+    x_flare_probability: Optional[int] = None
+    proton_probability: Optional[int] = None
+
+
+class AuroraForecast(BaseModel):
+    """OVATION short-term auroral-oval forecast (NOAA SWPC)."""
+
+    observation_time: Optional[datetime] = None
+    forecast_time: Optional[datetime] = None
+    latitude: Optional[float] = None
+    longitude: Optional[float] = None
+    aurora_probability: Optional[int] = Field(None, description="Auroral activity probability (%) at the requested point.")
+    global_max_probability: Optional[int] = Field(None, description="Peak probability anywhere on the oval.")
+    note: str = ""
+
+
+class SpaceWeatherEvent(BaseModel):
+    """A catalogued space-weather event from NASA DONKI (CME/GST/FLR/SEP/IPS/HSS)."""
+
+    event_type: str
+    event_id: str
+    time: Optional[datetime] = None
+    summary: str = Field("", description="Type-specific highlight, e.g. 'max Kp 6.33' or 'class M2.1'.")
+    link: Optional[str] = Field(None, description="DONKI detail page for the full record.")