solar-mcp 0.1.0__tar.gz

solar_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build dependencies
+        run: pip install build
+      - name: Build package
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

solar_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/

solar_mcp-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  For the full license text, see <https://www.gnu.org/licenses/gpl-3.0.html>

solar_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: solar-mcp
+Version: 0.1.0
+Summary: MCP server for solar indices and space weather — SFI, SSN, Kp, DSCOVR, alerts
+Project-URL: Homepage, https://qso-graph.io/
+Project-URL: Repository, https://github.com/qso-graph/solar-mcp
+Project-URL: Issues, https://github.com/qso-graph/solar-mcp/issues
+Author: Greg Beam, KI7MT
+License: GPL-3.0-or-later
+License-File: LICENSE
+Keywords: amateur-radio,dscovr,ham-radio,kp-index,mcp,model-context-protocol,noaa,propagation,sfi,solar,space-weather
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Ham Radio
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=3.0
+Description-Content-Type: text/markdown
+
+# solar-mcp
+
+MCP server for space weather and HF propagation conditions — live solar flux, Kp index, DSCOVR solar wind, X-ray flux, alerts, 27-day forecast, and band-by-band outlook through any MCP-compatible AI assistant.
+
+Part of the [qso-graph](https://qso-graph.io/) project. **No authentication required** — all data from [NOAA SWPC](https://www.swpc.noaa.gov/) public endpoints.
+
+## Install
+
+```bash
+pip install solar-mcp
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `solar_conditions` | Current SFI, Kp, and NOAA R/S/G space weather scales |
+| `solar_forecast` | 27-day SFI and Kp forecast from NOAA |
+| `solar_alerts` | Active space weather alerts and warnings |
+| `solar_wind` | Real-time DSCOVR L1 solar wind (Bz, speed, density) |
+| `solar_xray` | GOES X-ray flux and solar flare classification |
+| `solar_band_outlook` | HF band-by-band propagation assessment (160m-6m) |
+
+## Quick Start
+
+No credentials needed — just install and configure your MCP client.
+
+### Configure your MCP client
+
+#### Claude Desktop
+
+Add to `claude_desktop_config.json` (`~/Library/Application Support/Claude/` on macOS, `%APPDATA%\Claude\` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "solar": {
+      "command": "solar-mcp"
+    }
+  }
+}
+```
+
+#### Claude Code
+
+Add to `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "solar": {
+      "command": "solar-mcp"
+    }
+  }
+}
+```
+
+#### ChatGPT Desktop
+
+```json
+{
+  "mcpServers": {
+    "solar": {
+      "command": "solar-mcp"
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "solar": {
+      "command": "solar-mcp"
+    }
+  }
+}
+```
+
+#### VS Code / GitHub Copilot
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "solar": {
+      "command": "solar-mcp"
+    }
+  }
+}
+```
+
+#### Gemini CLI
+
+Add to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "solar": {
+      "command": "solar-mcp"
+    }
+  }
+}
+```
+
+### Ask questions
+
+> "What are the current solar conditions?"
+
+> "Is the solar wind causing any geomagnetic disturbance?"
+
+> "What's the 27-day solar forecast look like?"
+
+> "Are any bands open right now on HF?"
+
+> "Are there any active space weather alerts?"
+
+> "What class solar flare is happening?"
+
+## Testing Without Network
+
+```bash
+SOLAR_MCP_MOCK=1 solar-mcp
+```
+
+## MCP Inspector
+
+```bash
+solar-mcp --transport streamable-http --port 8008
+```
+
+## Development
+
+```bash
+git clone https://github.com/qso-graph/solar-mcp.git
+cd solar-mcp
+pip install -e .
+```
+
+## License
+
+GPL-3.0-or-later

solar_mcp-0.1.0/README.md

@@ -0,0 +1,148 @@
+# solar-mcp
+
+MCP server for space weather and HF propagation conditions — live solar flux, Kp index, DSCOVR solar wind, X-ray flux, alerts, 27-day forecast, and band-by-band outlook through any MCP-compatible AI assistant.
+
+Part of the [qso-graph](https://qso-graph.io/) project. **No authentication required** — all data from [NOAA SWPC](https://www.swpc.noaa.gov/) public endpoints.
+
+## Install
+
+```bash
+pip install solar-mcp
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `solar_conditions` | Current SFI, Kp, and NOAA R/S/G space weather scales |
+| `solar_forecast` | 27-day SFI and Kp forecast from NOAA |
+| `solar_alerts` | Active space weather alerts and warnings |
+| `solar_wind` | Real-time DSCOVR L1 solar wind (Bz, speed, density) |
+| `solar_xray` | GOES X-ray flux and solar flare classification |
+| `solar_band_outlook` | HF band-by-band propagation assessment (160m-6m) |
+
+## Quick Start
+
+No credentials needed — just install and configure your MCP client.
+
+### Configure your MCP client
+
+#### Claude Desktop
+
+Add to `claude_desktop_config.json` (`~/Library/Application Support/Claude/` on macOS, `%APPDATA%\Claude\` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "solar": {
+      "command": "solar-mcp"
+    }
+  }
+}
+```
+
+#### Claude Code
+
+Add to `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "solar": {
+      "command": "solar-mcp"
+    }
+  }
+}
+```
+
+#### ChatGPT Desktop
+
+```json
+{
+  "mcpServers": {
+    "solar": {
+      "command": "solar-mcp"
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "solar": {
+      "command": "solar-mcp"
+    }
+  }
+}
+```
+
+#### VS Code / GitHub Copilot
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "solar": {
+      "command": "solar-mcp"
+    }
+  }
+}
+```
+
+#### Gemini CLI
+
+Add to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "solar": {
+      "command": "solar-mcp"
+    }
+  }
+}
+```
+
+### Ask questions
+
+> "What are the current solar conditions?"
+
+> "Is the solar wind causing any geomagnetic disturbance?"
+
+> "What's the 27-day solar forecast look like?"
+
+> "Are any bands open right now on HF?"
+
+> "Are there any active space weather alerts?"
+
+> "What class solar flare is happening?"
+
+## Testing Without Network
+
+```bash
+SOLAR_MCP_MOCK=1 solar-mcp
+```
+
+## MCP Inspector
+
+```bash
+solar-mcp --transport streamable-http --port 8008
+```
+
+## Development
+
+```bash
+git clone https://github.com/qso-graph/solar-mcp.git
+cd solar-mcp
+pip install -e .
+```
+
+## License
+
+GPL-3.0-or-later

solar_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "solar-mcp"
+version = "0.1.0"
+description = "MCP server for solar indices and space weather — SFI, SSN, Kp, DSCOVR, alerts"
+readme = "README.md"
+license = {text = "GPL-3.0-or-later"}
+authors = [{name = "Greg Beam, KI7MT"}]
+requires-python = ">=3.10"
+dependencies = [
+    "fastmcp>=3.0",
+]
+keywords = [
+    "amateur-radio", "ham-radio", "solar", "space-weather", "sfi", "kp-index",
+    "mcp", "model-context-protocol", "noaa", "dscovr", "propagation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Communications :: Ham Radio",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://qso-graph.io/"
+Repository = "https://github.com/qso-graph/solar-mcp"
+Issues = "https://github.com/qso-graph/solar-mcp/issues"
+
+[project.scripts]
+solar-mcp = "solar_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/solar_mcp"]

solar_mcp-0.1.0/src/solar_mcp/__init__.py

@@ -0,0 +1,10 @@
+"""MCP server for solar indices and space weather — SFI, SSN, Kp, DSCOVR, alerts."""
+
+from __future__ import annotations
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("solar-mcp")
+except Exception:
+    __version__ = "0.0.0-dev"

solar_mcp-0.1.0/src/solar_mcp/client.py

@@ -0,0 +1,469 @@
+"""NOAA Space Weather Prediction Center client — all public JSON endpoints."""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+import urllib.request
+from typing import Any
+
+from . import __version__
+
+_SWPC = "https://services.swpc.noaa.gov"
+
+# Cache TTLs
+_CONDITIONS_TTL = 900.0  # 15 minutes (SFI/Kp update slowly)
+_FORECAST_TTL = 3600.0  # 1 hour
+_ALERTS_TTL = 300.0  # 5 minutes
+_WIND_TTL = 300.0  # 5 minutes (near-real-time DSCOVR)
+_XRAY_TTL = 300.0  # 5 minutes
+
+# Rate limiting
+_MIN_DELAY = 0.2
+
+
+def _is_mock() -> bool:
+    return os.getenv("SOLAR_MCP_MOCK") == "1"
+
+
+# ---------------------------------------------------------------------------
+# Mock data
+# ---------------------------------------------------------------------------
+
+_MOCK_SFI = {"timeStamp": "2026-03-04 20:00:00.000", "flux": "175", "area": ""}
+_MOCK_KP = [
+    ["time_tag", "Kp", "Kp_fraction", "a_running", "station_count"],
+    ["2026-03-04 21:00:00.000", "3", "2.67", "15", "8"],
+]
+_MOCK_SCALES = {
+    "0": {
+        "R": {"Scale": "R0", "Text": "none"},
+        "S": {"Scale": "S0", "Text": "none"},
+        "G": {"Scale": "G0", "Text": "none"},
+    },
+    "-1": {
+        "R": {"Scale": "R1", "Text": "minor"},
+        "S": {"Scale": "S0", "Text": "none"},
+        "G": {"Scale": "G1", "Text": "minor"},
+    },
+}
+_MOCK_WIND_MAG = [
+    ["time_tag", "bx_gsm", "by_gsm", "bz_gsm", "bt"],
+    ["2026-03-04 21:00:00.000", "-2.1", "1.5", "-3.2", "4.1"],
+]
+_MOCK_WIND_PLASMA = [
+    ["time_tag", "density", "speed", "temperature"],
+    ["2026-03-04 21:00:00.000", "5.2", "425.0", "85000"],
+]
+_MOCK_XRAY = [
+    {"time_tag": "2026-03-04T21:00:00Z", "satellite": 16, "current_class": "B5.2",
+     "current_ratio": 5.2e-7, "current_int_xrlong": 5.2e-7},
+]
+_MOCK_ALERTS = [
+    {
+        "product_id": "ALTK04",
+        "issue_datetime": "2026-03-04T18:00:00Z",
+        "message": "ALERT: Geomagnetic K-index of 4\nThreshold Reached: 2026 Mar 04 1800 UTC\nSynoptic Period: 1500-1800 UTC",
+    },
+]
+_MOCK_FORECAST = [
+    ["2026 Mar 05", "172", "3"],
+    ["2026 Mar 06", "170", "2"],
+    ["2026 Mar 07", "168", "2"],
+]
+
+
+class SolarClient:
+    """NOAA SWPC client with rate limiting and caching."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._last_request: float = 0.0
+        self._cache: dict[str, tuple[float, Any]] = {}
+
+    # ------------------------------------------------------------------
+    # Cache + HTTP
+    # ------------------------------------------------------------------
+
+    def _cache_get(self, key: str) -> Any | None:
+        entry = self._cache.get(key)
+        if entry is None:
+            return None
+        expires, value = entry
+        if time.monotonic() > expires:
+            del self._cache[key]
+            return None
+        return value
+
+    def _cache_set(self, key: str, value: Any, ttl: float) -> None:
+        self._cache[key] = (time.monotonic() + ttl, value)
+
+    def _rate_limit(self) -> None:
+        with self._lock:
+            now = time.monotonic()
+            elapsed = now - self._last_request
+            if elapsed < _MIN_DELAY:
+                time.sleep(_MIN_DELAY - elapsed)
+            self._last_request = time.monotonic()
+
+    def _get_json(self, url: str) -> Any:
+        self._rate_limit()
+        req = urllib.request.Request(url, method="GET")
+        req.add_header("User-Agent", f"solar-mcp/{__version__}")
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            body = resp.read().decode("utf-8", errors="replace")
+        if not body or body.strip() == "":
+            return None
+        return json.loads(body)
+
+    # ------------------------------------------------------------------
+    # Tools
+    # ------------------------------------------------------------------
+
+    def conditions(self) -> dict[str, Any]:
+        """Current solar conditions: SFI, Kp, NOAA scales."""
+        key = "conditions"
+        cached = self._cache_get(key)
+        if cached is not None:
+            return cached
+
+        if _is_mock():
+            sfi_data = _MOCK_SFI
+            kp_data = _MOCK_KP
+            scales_data = _MOCK_SCALES
+        else:
+            sfi_data = self._get_json(f"{_SWPC}/products/summary/10cm-flux.json") or {}
+            kp_data = self._get_json(f"{_SWPC}/products/noaa-planetary-k-index.json") or []
+            scales_data = self._get_json(f"{_SWPC}/products/noaa-scales.json") or {}
+
+        # Parse SFI
+        sfi = None
+        sfi_time = None
+        if isinstance(sfi_data, dict):
+            try:
+                sfi = int(sfi_data.get("flux", "0"))
+            except (ValueError, TypeError):
+                pass
+            sfi_time = sfi_data.get("timeStamp")
+
+        # Parse latest Kp
+        kp = None
+        kp_time = None
+        if isinstance(kp_data, list) and len(kp_data) > 1:
+            latest = kp_data[-1]
+            if isinstance(latest, list) and len(latest) >= 2:
+                try:
+                    kp = float(latest[1])
+                except (ValueError, TypeError):
+                    pass
+                kp_time = latest[0]
+
+        # Parse NOAA scales (current = "0", 24hr max = "-1")
+        r_scale = s_scale = g_scale = "unknown"
+        if isinstance(scales_data, dict):
+            current = scales_data.get("0", {})
+            r_scale = current.get("R", {}).get("Scale", "unknown")
+            s_scale = current.get("S", {}).get("Scale", "unknown")
+            g_scale = current.get("G", {}).get("Scale", "unknown")
+
+        result: dict[str, Any] = {
+            "sfi": sfi,
+            "sfi_timestamp": sfi_time,
+            "kp": kp,
+            "kp_timestamp": kp_time,
+            "noaa_r_scale": r_scale,
+            "noaa_s_scale": s_scale,
+            "noaa_g_scale": g_scale,
+        }
+
+        # Band outlook
+        if sfi is not None and kp is not None:
+            result["band_outlook"] = self._band_outlook(sfi, kp)
+
+        self._cache_set(key, result, _CONDITIONS_TTL)
+        return result
+
+    def forecast(self) -> dict[str, Any]:
+        """3-day SFI/Kp forecast from NOAA 27-day outlook."""
+        key = "forecast"
+        cached = self._cache_get(key)
+        if cached is not None:
+            return cached
+
+        if _is_mock():
+            rows = _MOCK_FORECAST
+        else:
+            data = self._get_json(f"{_SWPC}/products/27-day-outlook.json") or []
+            # Format: [date, sfi, kp] rows, first row may be header
+            rows = []
+            for row in data:
+                if isinstance(row, list) and len(row) >= 3:
+                    try:
+                        int(row[1])  # test if SFI is numeric
+                        rows.append(row)
+                    except (ValueError, TypeError):
+                        continue
+
+        days = []
+        for row in rows[:27]:
+            try:
+                days.append({
+                    "date": row[0],
+                    "predicted_sfi": int(row[1]),
+                    "predicted_kp": int(row[2]),
+                })
+            except (ValueError, TypeError, IndexError):
+                continue
+
+        result = {"total_days": len(days), "forecast": days}
+        self._cache_set(key, result, _FORECAST_TTL)
+        return result
+
+    def alerts(self) -> dict[str, Any]:
+        """Active SWPC alerts and warnings."""
+        key = "alerts"
+        cached = self._cache_get(key)
+        if cached is not None:
+            return cached
+
+        if _is_mock():
+            data = list(_MOCK_ALERTS)
+        else:
+            data = self._get_json(f"{_SWPC}/products/alerts.json") or []
+
+        alerts = []
+        for item in data:
+            if isinstance(item, dict):
+                alerts.append({
+                    "product_id": item.get("product_id", ""),
+                    "issue_time": item.get("issue_datetime", ""),
+                    "message": item.get("message", ""),
+                })
+
+        result = {"total": len(alerts), "alerts": alerts}
+        self._cache_set(key, result, _ALERTS_TTL)
+        return result
+
+    def solar_wind(self) -> dict[str, Any]:
+        """Real-time DSCOVR L1 solar wind data."""
+        key = "wind"
+        cached = self._cache_get(key)
+        if cached is not None:
+            return cached
+
+        if _is_mock():
+            mag_data = _MOCK_WIND_MAG
+            plasma_data = _MOCK_WIND_PLASMA
+        else:
+            mag_data = self._get_json(f"{_SWPC}/products/solar-wind/mag-5-minute.json") or []
+            plasma_data = self._get_json(f"{_SWPC}/products/solar-wind/plasma-5-minute.json") or []
+
+        # Latest magnetic field
+        bz = bt = None
+        mag_time = None
+        if isinstance(mag_data, list) and len(mag_data) > 1:
+            latest = mag_data[-1]
+            if isinstance(latest, list) and len(latest) >= 4:
+                mag_time = latest[0]
+                try:
+                    bz = float(latest[3])
+                except (ValueError, TypeError):
+                    pass
+                try:
+                    bt = float(latest[4]) if len(latest) > 4 else None
+                except (ValueError, TypeError):
+                    pass
+
+        # Latest plasma
+        speed = density = None
+        plasma_time = None
+        if isinstance(plasma_data, list) and len(plasma_data) > 1:
+            latest = plasma_data[-1]
+            if isinstance(latest, list) and len(latest) >= 3:
+                plasma_time = latest[0]
+                try:
+                    density = float(latest[1])
+                except (ValueError, TypeError):
+                    pass
+                try:
+                    speed = float(latest[2])
+                except (ValueError, TypeError):
+                    pass
+
+        result: dict[str, Any] = {
+            "bz_gsm_nt": bz,
+            "bt_nt": bt,
+            "mag_timestamp": mag_time,
+            "speed_km_s": speed,
+            "density_p_cm3": density,
+            "plasma_timestamp": plasma_time,
+        }
+
+        # Geomagnetic storm assessment
+        if bz is not None:
+            if bz < -10:
+                result["assessment"] = "Strongly southward Bz — major storm likely"
+            elif bz < -5:
+                result["assessment"] = "Southward Bz — moderate storm possible"
+            elif bz < 0:
+                result["assessment"] = "Mildly southward Bz — minor disturbance possible"
+            else:
+                result["assessment"] = "Northward or neutral Bz — quiet conditions"
+
+        self._cache_set(key, result, _WIND_TTL)
+        return result
+
+    def xray(self) -> dict[str, Any]:
+        """GOES X-ray flux and solar flare status."""
+        key = "xray"
+        cached = self._cache_get(key)
+        if cached is not None:
+            return cached
+
+        if _is_mock():
+            data = _MOCK_XRAY
+        else:
+            data = self._get_json(f"{_SWPC}/json/goes/primary/xrays-6-hour.json") or []
+
+        # Latest reading
+        flare_class = "unknown"
+        xray_time = None
+        flux = None
+        if isinstance(data, list) and len(data) > 0:
+            latest = data[-1] if isinstance(data[-1], dict) else {}
+            flare_class = latest.get("current_class", "unknown")
+            xray_time = latest.get("time_tag")
+            flux = latest.get("current_ratio") or latest.get("current_int_xrlong")
+
+        result: dict[str, Any] = {
+            "flare_class": flare_class,
+            "flux_w_m2": flux,
+            "timestamp": xray_time,
+        }
+
+        # Classify
+        if isinstance(flare_class, str) and len(flare_class) > 0:
+            c = flare_class[0].upper()
+            if c == "X":
+                result["level"] = "Extreme — HF blackout likely"
+            elif c == "M":
+                result["level"] = "Strong — HF degradation possible"
+            elif c == "C":
+                result["level"] = "Moderate — minor HF impact"
+            elif c == "B":
+                result["level"] = "Low — no significant impact"
+            elif c == "A":
+                result["level"] = "Minimal — background levels"
+
+        self._cache_set(key, result, _XRAY_TTL)
+        return result
+
+    def band_outlook(self) -> dict[str, Any]:
+        """HF band condition assessment derived from current indices."""
+        key = "band_outlook"
+        cached = self._cache_get(key)
+        if cached is not None:
+            return cached
+
+        # Need current SFI and Kp
+        cond = self.conditions()
+        sfi = cond.get("sfi")
+        kp = cond.get("kp")
+
+        if sfi is None or kp is None:
+            return {"error": "Unable to fetch current conditions"}
+
+        result = self._band_outlook(sfi, kp)
+        result["sfi"] = sfi
+        result["kp"] = kp
+        self._cache_set(key, result, _CONDITIONS_TTL)
+        return result
+
+    @staticmethod
+    def _band_outlook(sfi: int, kp: float) -> dict[str, Any]:
+        """Generate band-by-band outlook from SFI and Kp."""
+        storm = kp >= 5
+        disturbed = kp >= 4
+        active = kp >= 3
+
+        bands = {}
+
+        # 160m — always NVIS night, storms help (absorption kills skip)
+        if storm:
+            bands["160m"] = "Poor — storm absorption"
+        elif active:
+            bands["160m"] = "Fair — some noise"
+        else:
+            bands["160m"] = "Good — quiet night conditions"
+
+        # 80m
+        if storm:
+            bands["80m"] = "Poor — D-layer absorption and noise"
+        elif disturbed:
+            bands["80m"] = "Fair — elevated absorption"
+        else:
+            bands["80m"] = "Good — reliable night band"
+
+        # 40m
+        if storm:
+            bands["40m"] = "Fair — reduced DX"
+        else:
+            bands["40m"] = "Good — workhorse band, day and night"
+
+        # 30m
+        bands["30m"] = "Good — transition band, usually open"
+
+        # 20m
+        if sfi >= 150:
+            bands["20m"] = "Excellent — strong F-layer, long openings"
+        elif sfi >= 100:
+            bands["20m"] = "Good — reliable daytime DX"
+        else:
+            bands["20m"] = "Fair — shorter openings at low solar flux"
+
+        # 17m
+        if sfi >= 120:
+            bands["17m"] = "Good — DX openings likely"
+        elif sfi >= 90:
+            bands["17m"] = "Fair — marginal openings"
+        else:
+            bands["17m"] = "Poor — insufficient ionization"
+
+        # 15m
+        if sfi >= 140:
+            bands["15m"] = "Excellent — wide open DX"
+        elif sfi >= 100:
+            bands["15m"] = "Good — daytime openings"
+        elif sfi >= 80:
+            bands["15m"] = "Fair — sporadic openings"
+        else:
+            bands["15m"] = "Poor — band likely closed"
+
+        # 12m
+        if sfi >= 150:
+            bands["12m"] = "Good — DX openings around midday"
+        elif sfi >= 120:
+            bands["12m"] = "Fair — brief openings possible"
+        else:
+            bands["12m"] = "Poor — band likely closed"
+
+        # 10m
+        if sfi >= 160:
+            bands["10m"] = "Excellent — worldwide DX"
+        elif sfi >= 130:
+            bands["10m"] = "Good — daytime DX openings"
+        elif sfi >= 100:
+            bands["10m"] = "Fair — short openings or sporadic-E"
+        else:
+            bands["10m"] = "Poor — closed except sporadic-E"
+
+        # 6m
+        bands["6m"] = "Sporadic — watch for Es openings"
+
+        if storm:
+            for b in ["20m", "17m", "15m", "12m", "10m"]:
+                bands[b] = bands[b].split(" — ")[0] + " — degraded by geomagnetic storm"
+
+        return {"bands": bands}

solar_mcp-0.1.0/src/solar_mcp/server.py

@@ -0,0 +1,162 @@
+"""solar-mcp: MCP server for space weather and HF propagation conditions."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+from fastmcp import FastMCP
+
+from . import __version__
+from .client import SolarClient
+
+mcp = FastMCP(
+    "solar-mcp",
+    version=__version__,
+    instructions=(
+        "MCP server for space weather and HF propagation conditions. "
+        "Live solar flux (SFI), Kp index, DSCOVR solar wind, X-ray flux, "
+        "space weather alerts, 27-day forecast, and HF band outlook. "
+        "All data from NOAA SWPC public endpoints, no authentication required."
+    ),
+)
+
+_client: SolarClient | None = None
+
+
+def _get_client() -> SolarClient:
+    global _client
+    if _client is None:
+        _client = SolarClient()
+    return _client
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def solar_conditions() -> dict[str, Any]:
+    """Get current solar conditions — SFI, Kp, and NOAA space weather scales.
+
+    Returns the latest 10.7 cm solar flux index (SFI), planetary Kp index,
+    and NOAA R/S/G scales (radio blackout, solar radiation, geomagnetic storm).
+    Includes an HF band outlook derived from current indices.
+
+    Returns:
+        Current SFI, Kp, NOAA scales, and band-by-band propagation outlook.
+    """
+    try:
+        return _get_client().conditions()
+    except Exception as e:
+        return {"error": str(e)}
+
+
+@mcp.tool()
+def solar_forecast() -> dict[str, Any]:
+    """Get the NOAA 27-day solar flux and geomagnetic forecast.
+
+    Shows predicted SFI and Kp values for the next 27 days, useful for
+    planning DX operations, contests, and POTA/SOTA activations.
+
+    Returns:
+        Day-by-day forecast with predicted SFI and Kp values.
+    """
+    try:
+        return _get_client().forecast()
+    except Exception as e:
+        return {"error": str(e)}
+
+
+@mcp.tool()
+def solar_alerts() -> dict[str, Any]:
+    """Get active NOAA space weather alerts and warnings.
+
+    Shows current solar flare alerts, geomagnetic storm warnings,
+    radiation storm alerts, and other SWPC bulletins.
+
+    Returns:
+        List of active alerts with product ID, issue time, and message text.
+    """
+    try:
+        return _get_client().alerts()
+    except Exception as e:
+        return {"error": str(e)}
+
+
+@mcp.tool()
+def solar_wind() -> dict[str, Any]:
+    """Get real-time DSCOVR L1 solar wind data.
+
+    Shows interplanetary magnetic field (Bz component), solar wind speed,
+    and proton density from the DSCOVR satellite at L1 (~1.5M km sunward).
+    Southward Bz (negative) drives geomagnetic storms.
+
+    Returns:
+        Bz (nT), Bt (nT), wind speed (km/s), density (p/cm³),
+        and geomagnetic storm assessment.
+    """
+    try:
+        return _get_client().solar_wind()
+    except Exception as e:
+        return {"error": str(e)}
+
+
+@mcp.tool()
+def solar_xray() -> dict[str, Any]:
+    """Get GOES X-ray flux and solar flare status.
+
+    Shows the current X-ray classification (A, B, C, M, X) from
+    GOES satellite data. M and X class flares can cause HF radio blackouts.
+
+    Returns:
+        Current flare class, X-ray flux, and HF impact assessment.
+    """
+    try:
+        return _get_client().xray()
+    except Exception as e:
+        return {"error": str(e)}
+
+
+@mcp.tool()
+def solar_band_outlook() -> dict[str, Any]:
+    """Get HF band-by-band propagation outlook based on current conditions.
+
+    Derives a propagation assessment for each HF band (160m through 6m)
+    from the current SFI and Kp values. Useful for deciding which band
+    to operate on right now.
+
+    Returns:
+        Per-band condition rating (Poor/Fair/Good/Excellent) with explanation,
+        plus current SFI and Kp values.
+    """
+    try:
+        return _get_client().band_outlook()
+    except Exception as e:
+        return {"error": str(e)}
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    """Run the solar-mcp server."""
+    transport = "stdio"
+    port = 8008
+    for i, arg in enumerate(sys.argv[1:], 1):
+        if arg == "--transport" and i < len(sys.argv) - 1:
+            transport = sys.argv[i + 1]
+        if arg == "--port" and i < len(sys.argv) - 1:
+            port = int(sys.argv[i + 1])
+
+    if transport == "streamable-http":
+        mcp.run(transport=transport, port=port)
+    else:
+        mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()