solar-data-mcp-core 0.1.0__tar.gz

solar_data_mcp_core-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Environments & secrets
+.env
+.venv/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+
+# OS
+.DS_Store

solar_data_mcp_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Logan Bernard
+
+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.

solar_data_mcp_core-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: solar-data-mcp-core
+Version: 0.1.0
+Summary: Shared infrastructure for solar-data-mcp servers: HTTP client, cache, rate limiting, result envelope
+Project-URL: Homepage, https://github.com/hoodsy/solar-data-mcp
+Author: Logan Bernard
+License-Expression: MIT
+License-File: LICENSE
+Keywords: mcp,nrel,open-data,solar
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Description-Content-Type: text/markdown
+
+# solar-data-mcp-core
+
+Shared infrastructure for [solar-data-mcp](https://github.com/hoodsy/solar-data-mcp) —
+US open solar data, agent-accessible over MCP. One install gives an agent production
+modeling, solar economics, market intelligence, and generation forecasts, with every
+number carrying `data + units + source + assumptions + warnings`.
+
+This package is the plumbing the servers share: the HTTP client (retry, token-bucket
+rate limiting, SQLite cache), the `ToolResult` envelope, the DuckDB bulk store, the
+error taxonomy, and `solar-data-mcp doctor`. You usually don't install it directly.
+
+Where to go instead:
+
+| You want | Go to |
+|---|---|
+| Everything (18 tools + 11 skills + 4 report prompts, one install) | [`solar-data-mcp`](https://github.com/hoodsy/solar-data-mcp/blob/main/packages/solar-data-mcp/README.md) |
+| Production & sizing only (PVWatts, NSRDB) | [`solar-data-mcp-nrel`](https://github.com/hoodsy/solar-data-mcp/blob/main/packages/nrel-solar/README.md) |
+| Tariffs, incentives & ROI only | [`solar-data-mcp-economics`](https://github.com/hoodsy/solar-data-mcp/blob/main/packages/solar-economics/README.md) |
+| Installed prices, permitting & utility-scale only | [`solar-data-mcp-market`](https://github.com/hoodsy/solar-data-mcp/blob/main/packages/solar-market/README.md) |
+| 48-hour generation forecasts only | [`solar-data-mcp-forecast`](https://github.com/hoodsy/solar-data-mcp/blob/main/packages/solar-forecast/README.md) |
+| The skill catalog, routing design & report templates | [`docs/skills.md`](https://github.com/hoodsy/solar-data-mcp/blob/main/docs/skills.md) |
+| Quickstart & agent config snippets | [repo README](https://github.com/hoodsy/solar-data-mcp#quickstart) |

solar_data_mcp_core-0.1.0/README.md

@@ -0,0 +1,22 @@
+# solar-data-mcp-core
+
+Shared infrastructure for [solar-data-mcp](https://github.com/hoodsy/solar-data-mcp) —
+US open solar data, agent-accessible over MCP. One install gives an agent production
+modeling, solar economics, market intelligence, and generation forecasts, with every
+number carrying `data + units + source + assumptions + warnings`.
+
+This package is the plumbing the servers share: the HTTP client (retry, token-bucket
+rate limiting, SQLite cache), the `ToolResult` envelope, the DuckDB bulk store, the
+error taxonomy, and `solar-data-mcp doctor`. You usually don't install it directly.
+
+Where to go instead:
+
+| You want | Go to |
+|---|---|
+| Everything (18 tools + 11 skills + 4 report prompts, one install) | [`solar-data-mcp`](https://github.com/hoodsy/solar-data-mcp/blob/main/packages/solar-data-mcp/README.md) |
+| Production & sizing only (PVWatts, NSRDB) | [`solar-data-mcp-nrel`](https://github.com/hoodsy/solar-data-mcp/blob/main/packages/nrel-solar/README.md) |
+| Tariffs, incentives & ROI only | [`solar-data-mcp-economics`](https://github.com/hoodsy/solar-data-mcp/blob/main/packages/solar-economics/README.md) |
+| Installed prices, permitting & utility-scale only | [`solar-data-mcp-market`](https://github.com/hoodsy/solar-data-mcp/blob/main/packages/solar-market/README.md) |
+| 48-hour generation forecasts only | [`solar-data-mcp-forecast`](https://github.com/hoodsy/solar-data-mcp/blob/main/packages/solar-forecast/README.md) |
+| The skill catalog, routing design & report templates | [`docs/skills.md`](https://github.com/hoodsy/solar-data-mcp/blob/main/docs/skills.md) |
+| Quickstart & agent config snippets | [repo README](https://github.com/hoodsy/solar-data-mcp#quickstart) |

solar_data_mcp_core-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "solar-data-mcp-core"
+version = "0.1.0"
+description = "Shared infrastructure for solar-data-mcp servers: HTTP client, cache, rate limiting, result envelope"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Logan Bernard" }]
+keywords = ["solar", "mcp", "nrel", "open-data"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "httpx>=0.27,<1",
+    "pydantic>=2.7,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/hoodsy/solar-data-mcp"
+
+# No console script: the user-facing command (server + doctor passthrough) is
+# `solar-data-mcp`, owned by the umbrella package. PyPI's `solar-mcp` name
+# belongs to an unrelated project, so nothing here may claim that command.
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/solar_mcp_core"]

solar_data_mcp_core-0.1.0/src/solar_mcp_core/__init__.py

@@ -0,0 +1,3 @@
+"""Shared infrastructure for solar-data-mcp servers."""
+
+__version__ = "0.1.0"

solar_data_mcp_core-0.1.0/src/solar_mcp_core/bulk.py

@@ -0,0 +1,256 @@
+"""DuckDB-backed bulk store: the second cache tier, for datasets too large
+for the HTTP cache (DSIRE snapshots, Tracking the Sun, SolarTRACE).
+
+Populated only by explicit `sync_*` tools — never implicitly — and every
+dataset records its vintage so query results can cite how fresh the data is.
+The `duckdb` dependency is declared by the packages that use this module
+(solar-data-mcp-economics, solar-data-mcp-market), keeping solar-data-mcp-core
+lightweight.
+"""
+
+import asyncio
+import os
+import re
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from solar_mcp_core import units
+from solar_mcp_core.config import (
+    SourceConfig,
+    cache_dir,
+    ensure_private_dir,
+    harden_file_perms,
+)
+from solar_mcp_core.envelope import SourceRef, ToolResult, utc_now_iso
+from solar_mcp_core.errors import BadInput, SourceUnavailable
+from solar_mcp_core.net import assert_allowed_download_url
+
+_META_SCHEMA = """
+CREATE TABLE IF NOT EXISTS _meta (
+    dataset TEXT PRIMARY KEY,
+    vintage TEXT NOT NULL,
+    loaded_at TEXT NOT NULL,
+    schema_version INTEGER NOT NULL
+)
+"""
+
+_IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+# Shared-dataset contract: these names are used across packages (economics
+# reads the Tracking the Sun table that market syncs), so they live here.
+TTS_DATASET = "tts"
+TTS_TABLE = "tts_systems"
+SOLARTRACE_DATASET = "solartrace"
+SOLARTRACE_TABLE = "solartrace"
+DSIRE_DATASET = "dsire_programs"
+DSIRE_TABLE = "dsire_programs"
+
+
+@dataclass
+class DatasetVintage:
+    dataset: str
+    vintage: str
+    loaded_at: str  # ISO 8601 UTC
+    schema_version: int
+
+
+class BulkStore:
+    def __init__(self, path: Path | str | None = None) -> None:
+        """Open (or create) the bulk store. Pass ":memory:" for tests."""
+        try:
+            import duckdb
+        except ImportError as exc:  # pragma: no cover — dev/CI envs always have it
+            raise RuntimeError(
+                "BulkStore needs the 'duckdb' package. It is installed automatically "
+                "with solar-data-mcp-economics and solar-data-mcp-market; for "
+                "standalone use: pip install duckdb"
+            ) from exc
+        db = path if path is not None else cache_dir() / "bulk.duckdb"
+        if isinstance(db, Path):
+            ensure_private_dir(db.parent)  # bulk store holds locally synced data
+        self._conn = duckdb.connect(str(db))
+        if isinstance(db, Path):
+            harden_file_perms(db)
+        self._conn.execute(_META_SCHEMA)
+        # Serializes sync_* stage-validate-swap sections. The umbrella shares one
+        # store across all tool families, and every sync uses the same staging
+        # table on a single (non-thread-safe) DuckDB connection, so concurrent
+        # syncs must not overlap.
+        self.write_lock = asyncio.Lock()
+
+    def stage_csv(self, table: str, csv_path: Path) -> int:
+        """Load a CSV into `table` WITHOUT touching any vintage; return row count.
+
+        DuckDB streams the file — it is never held in memory, which is what
+        makes multi-GB sources like Tracking the Sun tractable. Sync loaders
+        stage into a scratch table, validate, swap, and only then record the
+        vintage — so a bad file can never corrupt a good snapshot or its
+        provenance.
+        """
+        _check_identifier(table)
+        self._conn.execute(
+            f'CREATE OR REPLACE TABLE "{table}" AS SELECT * FROM read_csv_auto(?)',
+            [str(csv_path)],
+        )
+        row = self._conn.execute(f'SELECT count(*) FROM "{table}"').fetchone()
+        return int(row[0]) if row else 0
+
+    def set_vintage(self, dataset: str, vintage: str, schema_version: int = 1) -> None:
+        self._conn.execute(
+            "INSERT OR REPLACE INTO _meta VALUES (?, ?, ?, ?)",
+            [dataset, vintage, utc_now_iso(), schema_version],
+        )
+
+    def load_csv(
+        self,
+        dataset: str,
+        table: str,
+        csv_path: Path,
+        vintage: str,
+        schema_version: int = 1,
+    ) -> int:
+        """stage_csv + set_vintage in one step, for loads needing no validation
+        or transform between the two."""
+        count = self.stage_csv(table, csv_path)
+        self.set_vintage(dataset, vintage, schema_version)
+        return count
+
+    def vintage(self, dataset: str) -> DatasetVintage | None:
+        row = self._conn.execute(
+            "SELECT dataset, vintage, loaded_at, schema_version FROM _meta WHERE dataset = ?",
+            [dataset],
+        ).fetchone()
+        if row is None:
+            return None
+        return DatasetVintage(*row)
+
+    def has_table(self, table: str) -> bool:
+        _check_identifier(table)
+        row = self._conn.execute(
+            "SELECT count(*) FROM information_schema.tables WHERE table_name = ?", [table]
+        ).fetchone()
+        return bool(row and row[0])
+
+    def query(self, sql: str, params: list[Any] | None = None) -> list[tuple[Any, ...]]:
+        """Run a read query. Callers own the SQL; parameters are always bound."""
+        result = self._conn.execute(sql, params or [])
+        return [tuple(row) for row in result.fetchall()]
+
+    def execute(self, sql: str, params: list[Any] | None = None) -> None:
+        """Run DDL/DML (CREATE TABLE AS, DROP) — for sync loaders' transforms."""
+        self._conn.execute(sql, params or [])
+
+    def close(self) -> None:
+        self._conn.close()
+
+
+def _check_identifier(name: str) -> None:
+    if not _IDENTIFIER.match(name):
+        raise ValueError(f"invalid table name: {name!r}")
+
+
+# Ceiling above the largest real dataset (Tracking the Sun is ~1-2 GB); bounds
+# disk use from a hostile or misconfigured endpoint without blocking real files.
+MAX_DOWNLOAD_BYTES = 4 * 1024**3
+_STREAM_TIMEOUT = 60.0  # per-connect/read; a stall aborts the socket
+_TOTAL_TIMEOUT = 3600.0  # wall-clock ceiling; defeats a slow-drip that resets read timeouts
+
+
+async def fetch_to_tempfile(url: str, *, config: SourceConfig, suffix: str = ".csv") -> Path:
+    """Stream a dataset's bulk file to a temp path (sync_* tools); caller deletes it.
+
+    Restricted to the dataset's official https host (see net.assert_allowed_download_url):
+    the agent-supplied `source` is untrusted, so this must not become an SSRF or
+    internal-fetch primitive. Redirects are refused, and the transfer is bounded
+    in both size and wall-clock time. Plain httpx rather than SolarHttpClient —
+    bulk files are not JSON and must never enter the HTTP cache tier.
+    """
+    assert_allowed_download_url(url, config)
+    descriptor, name = tempfile.mkstemp(suffix=suffix)
+    os.close(descriptor)
+    path = Path(name)
+    try:
+        await asyncio.wait_for(_stream_to_file(url, config.name, path), _TOTAL_TIMEOUT)
+    except TimeoutError as exc:
+        path.unlink(missing_ok=True)
+        raise SourceUnavailable(config.name, f"download exceeded {_TOTAL_TIMEOUT:.0f}s") from exc
+    except httpx.TransportError as exc:
+        path.unlink(missing_ok=True)
+        raise SourceUnavailable(config.name, f"download failed: {type(exc).__name__}") from exc
+    except BaseException:
+        # BadInput, HTTP-status/size failures, cancellation — never leak the temp file.
+        path.unlink(missing_ok=True)
+        raise
+    return path
+
+
+async def _stream_to_file(url: str, source: str, path: Path) -> None:
+    async with (
+        httpx.AsyncClient(follow_redirects=False, timeout=_STREAM_TIMEOUT) as client,
+        client.stream("GET", url) as response,
+    ):
+        if response.is_redirect:
+            raise BadInput(
+                field="source",
+                value=url,
+                allowed=(
+                    "a direct download URL (redirects are refused; "
+                    "pass the final URL or a local file)"
+                ),
+            )
+        if response.status_code != 200:
+            raise SourceUnavailable(source, f"download failed: HTTP {response.status_code}")
+        declared = response.headers.get("Content-Length")
+        if declared is not None and declared.isdigit() and int(declared) > MAX_DOWNLOAD_BYTES:
+            raise SourceUnavailable(
+                source, f"file too large ({declared} bytes; cap {MAX_DOWNLOAD_BYTES})"
+            )
+        written = 0
+        with path.open("wb") as out:
+            async for chunk in response.aiter_bytes():
+                written += len(chunk)
+                if written > MAX_DOWNLOAD_BYTES:
+                    raise SourceUnavailable(
+                        source, f"download exceeded size cap of {MAX_DOWNLOAD_BYTES} bytes"
+                    )
+                out.write(chunk)
+
+
+def default_vintage(vintage: str | None) -> tuple[str, list[str]]:
+    """Today's date when the caller gave no vintage, with the assumption line."""
+    if vintage is not None:
+        return vintage, []
+    today = utc_now_iso()[:10]
+    return today, [f"vintage not provided; defaulted to today ({today})"]
+
+
+def sync_result(
+    *,
+    dataset: str,
+    rows_loaded: int,
+    vintage: str,
+    source_name: str,
+    source_url: str,
+    license_note: str,
+    assumptions: list[str],
+    extra_data: dict[str, Any] | None = None,
+) -> ToolResult:
+    """The one envelope shape every sync_* tool returns."""
+    data: dict[str, Any] = {"dataset": dataset, "rows_loaded": rows_loaded, "vintage": vintage}
+    units_map = {"dataset": units.LABEL, "rows_loaded": units.COUNT, "vintage": units.LABEL}
+    for key in extra_data or {}:
+        units_map[key] = units.LABEL
+    data.update(extra_data or {})
+    return ToolResult(
+        data=data,
+        units=units_map,
+        source=SourceRef(
+            name=source_name, url=source_url, retrieved_at=utc_now_iso(), license=license_note
+        ),
+        assumptions=assumptions,
+        warnings=[],
+    )

solar_data_mcp_core-0.1.0/src/solar_mcp_core/cache.py

@@ -0,0 +1,111 @@
+"""SQLite HTTP cache keyed on canonicalized URL+params.
+
+Caching is a correctness feature here, not just a UX one: every source has a
+rate limit, and agents retry a lot. Sources whose responses are deterministic
+per request (e.g. TMY-based modeling) get long TTLs via SourceConfig. Stale
+entries are kept and can be served explicitly when a quota is exhausted.
+"""
+
+import math
+import sqlite3
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlencode
+
+from solar_mcp_core.config import cache_dir, ensure_private_dir, harden_file_perms
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS http_cache (
+    key TEXT PRIMARY KEY,
+    source TEXT NOT NULL,
+    status INTEGER NOT NULL,
+    body TEXT NOT NULL,
+    retrieved_at REAL NOT NULL,
+    expires_at REAL NOT NULL
+)
+"""
+
+
+def canonicalize(base_url: str, path: str, params: Mapping[str, object]) -> str:
+    """Stable cache/fixture key for a request: sorted params, api_key excluded.
+
+    The api_key is excluded so cache entries survive key rotation and recorded
+    fixtures never embed a secret in their key.
+    """
+    filtered = {k: _normalize(v) for k, v in sorted(params.items()) if k != "api_key"}
+    return f"{base_url.rstrip('/')}/{path.lstrip('/')}?{urlencode(filtered)}"
+
+
+def _normalize(value: object) -> str:
+    if isinstance(value, bool):
+        return "1" if value else "0"
+    if isinstance(value, float) and math.isfinite(value) and value == int(value):
+        return str(int(value))
+    return str(value)
+
+
+@dataclass
+class CacheEntry:
+    key: str
+    source: str
+    status: int
+    body: str
+    retrieved_at: float
+    expires_at: float
+
+    def is_fresh(self, now: float) -> bool:
+        return now < self.expires_at
+
+
+class HttpCache:
+    def __init__(
+        self,
+        path: Path | str | None = None,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        """SQLite-backed cache. Pass ":memory:" for an ephemeral cache
+        (e.g. doctor's liveness ping, which must never be answered from disk)."""
+        self._clock = clock
+        db_path = path if path is not None else cache_dir() / "http.db"
+        if isinstance(db_path, Path):
+            ensure_private_dir(db_path.parent)  # cache holds api-key-adjacent bodies
+        self._conn = sqlite3.connect(db_path)
+        if isinstance(db_path, Path):
+            harden_file_perms(db_path)
+        self._conn.execute(_SCHEMA)
+        self._conn.commit()
+
+    def get(self, key: str, *, allow_stale: bool = False) -> CacheEntry | None:
+        row = self._conn.execute(
+            "SELECT key, source, status, body, retrieved_at, expires_at"
+            " FROM http_cache WHERE key = ?",
+            (key,),
+        ).fetchone()
+        if row is None:
+            return None
+        entry = CacheEntry(*row)
+        if entry.is_fresh(self._clock()) or allow_stale:
+            return entry
+        return None
+
+    def put(self, key: str, source: str, status: int, body: str, ttl_seconds: int) -> CacheEntry:
+        now = self._clock()
+        entry = CacheEntry(
+            key=key,
+            source=source,
+            status=status,
+            body=body,
+            retrieved_at=now,
+            expires_at=now + ttl_seconds,
+        )
+        self._conn.execute(
+            "INSERT OR REPLACE INTO http_cache VALUES (?, ?, ?, ?, ?, ?)",
+            (key, source, status, body, entry.retrieved_at, entry.expires_at),
+        )
+        self._conn.commit()
+        return entry
+
+    def close(self) -> None:
+        self._conn.close()

solar_data_mcp_core-0.1.0/src/solar_mcp_core/cli.py

@@ -0,0 +1,112 @@
+"""The `doctor` command: checks keys and pings each registered source. Users
+reach it as `solar-data-mcp doctor` — the umbrella console script delegates here.
+
+This is the one component that intentionally makes live API calls — it exists
+so users can verify their setup before pointing an agent at a server.
+"""
+
+import argparse
+import asyncio
+import sys
+from collections.abc import Callable
+
+from solar_mcp_core.cache import HttpCache
+from solar_mcp_core.config import SOURCES, SourceConfig, api_key_for, cache_dir
+from solar_mcp_core.errors import QuotaExceeded, SourceUnavailable
+from solar_mcp_core.http import SolarHttpClient, configure_debug_logging
+from solar_mcp_core.ratelimit import TokenBucket
+
+# Test seam: tests swap this factory to inject a MockTransport-backed client.
+ClientFactory = Callable[[SourceConfig], SolarHttpClient]
+
+
+def _default_client_factory(config: SourceConfig) -> SolarHttpClient:
+    return SolarHttpClient(
+        config,
+        # Doctor must observe the live source, never a disk cache entry —
+        # an in-memory cache is created fresh and dies with the process.
+        cache=HttpCache(path=":memory:"),
+        bucket=TokenBucket(capacity=5, refill_per_second=1),
+    )
+
+
+def doctor(client_factory: ClientFactory = _default_client_factory) -> int:
+    ok = True
+    print(f"cache dir: {cache_dir()} ({'writable' if _cache_writable() else 'NOT WRITABLE'})")
+    for config in SOURCES.values():
+        ok &= _check_source(config, client_factory)
+    return 0 if ok else 1
+
+
+def _check_source(config: SourceConfig, client_factory: ClientFactory) -> bool:
+    label = f"[{config.name}]"
+    if config.api_key_env is None:
+        print(f"{label} no key required")
+    elif api_key_for(config) is None:
+        setup = f" Setup: {config.signup_url}" if config.signup_url else ""
+        if not config.required:
+            print(f"{label} SKIP — optional source; set {config.api_key_env} to enable.{setup}")
+            return True
+        print(f"{label} FAIL — {config.api_key_env} not set.{setup}")
+        return False
+    else:
+        print(f"{label} key present ({config.api_key_env})")
+
+    if config.ping_path is None:
+        print(f"{label} SKIP — no liveness ping defined for this source")
+        return True
+    try:
+        result = asyncio.run(
+            _ping(config, client_factory, config.ping_path, dict(config.ping_params))
+        )
+    except QuotaExceeded as exc:
+        print(f"{label} FAIL — {exc}")
+        return False
+    except SourceUnavailable as exc:
+        print(f"{label} FAIL — {exc.detail} (signup: {config.signup_url})")
+        return False
+
+    suffix = f", {result} requests remaining this hour" if result is not None else ""
+    print(f"{label} PASS — live ping OK{suffix}")
+    return True
+
+
+async def _ping(
+    config: SourceConfig,
+    client_factory: ClientFactory,
+    path: str,
+    params: dict[str, object],
+) -> int | None:
+    client = client_factory(config)
+    try:
+        fetched = await client.get_json(path, dict(params))
+        return fetched.ratelimit_remaining
+    finally:
+        await client.aclose()
+
+
+def _cache_writable() -> bool:
+    try:
+        cache_dir().mkdir(parents=True, exist_ok=True)
+        probe = cache_dir() / ".write-probe"
+        probe.touch()
+        probe.unlink()
+        return True
+    except OSError:
+        return False
+
+
+def main(argv: list[str] | None = None) -> int:
+    configure_debug_logging()
+    parser = argparse.ArgumentParser(prog="solar-data-mcp", description="solar-data-mcp utilities")
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("doctor", help="check API keys and ping each data source")
+    args = parser.parse_args(argv)
+
+    if args.command == "doctor":
+        return doctor()
+    return 2  # pragma: no cover — argparse enforces the choices
+
+
+if __name__ == "__main__":
+    sys.exit(main())