solar-data-mcp-forecast 0.1.0__tar.gz

solar_data_mcp_forecast-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_forecast-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_forecast-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: solar-data-mcp-forecast
+Version: 0.1.0
+Summary: MCP server for solar generation forecasts via the open Quartz Solar Forecast model (Open Climate Fix)
+Project-URL: Homepage, https://github.com/hoodsy/solar-data-mcp
+Author: Logan Bernard
+License-Expression: MIT
+License-File: LICENSE
+Keywords: forecast,mcp,open-climate-fix,quartz,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: mcp<2,>=1.26
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: solar-data-mcp-core<0.2,>=0.1
+Requires-Dist: solar-data-mcp-nrel<0.2,>=0.1
+Description-Content-Type: text/markdown
+
+# solar-data-mcp-forecast
+
+MCP server wrapping the open [Quartz Solar Forecast](https://github.com/openclimatefix/quartz-solar-forecast)
+model (Open Climate Fix) — the forecast domain of
+[solar-data-mcp](https://github.com/hoodsy/solar-data-mcp). No API key needed.
+
+| Tool | Answers |
+|---|---|
+| `forecast_generation` | "What will my array generate tomorrow?" (hourly, ≤48 h) |
+| `compare_forecast_to_model` | "Is today unusually sunny?" (forecast vs PVWatts typical-year) |
+
+Run standalone: `uvx --from solar-data-mcp-forecast solar-forecast-mcp` — but see the
+model-install note below; most users want the combined
+[`solar-data-mcp`](https://github.com/hoodsy/solar-data-mcp/blob/main/packages/solar-data-mcp/README.md)
+server, which adds the other three domains plus the skill and report layer.
+
+## Installing the model
+
+`quartz-solar-forecast` pins `pydantic==2.6.2`, which conflicts with the MCP SDK,
+so it is not a declared dependency. Install it alongside (it runs fine on newer
+pydantic; the pin is conservative):
+
+```console
+$ pip install solar-data-mcp-forecast
+$ pip install --no-deps quartz-solar-forecast
+$ pip install pv-site-prediction xarray xgboost openmeteo-requests requests-cache retry-requests
+```
+
+Without the model installed, the server still starts and its tools return an
+error containing these instructions.
+
+## Using forecasts with the combined `solar-data-mcp` server
+
+An ephemeral `uvx` environment cannot hold the side-install above. Use a
+persistent venv and point your agent at its entry point:
+
+```console
+$ python3 -m venv ~/.venvs/solar-data-mcp
+$ ~/.venvs/solar-data-mcp/bin/pip install solar-data-mcp
+$ ~/.venvs/solar-data-mcp/bin/pip install --no-deps quartz-solar-forecast
+$ ~/.venvs/solar-data-mcp/bin/pip install pv-site-prediction xarray xgboost openmeteo-requests requests-cache retry-requests
+```
+
+Then in the agent config, replace `"command": "uvx", "args": ["solar-data-mcp"]`
+with `"command": "~/.venvs/solar-data-mcp/bin/solar-data-mcp"`.

solar_data_mcp_forecast-0.1.0/README.md

@@ -0,0 +1,45 @@
+# solar-data-mcp-forecast
+
+MCP server wrapping the open [Quartz Solar Forecast](https://github.com/openclimatefix/quartz-solar-forecast)
+model (Open Climate Fix) — the forecast domain of
+[solar-data-mcp](https://github.com/hoodsy/solar-data-mcp). No API key needed.
+
+| Tool | Answers |
+|---|---|
+| `forecast_generation` | "What will my array generate tomorrow?" (hourly, ≤48 h) |
+| `compare_forecast_to_model` | "Is today unusually sunny?" (forecast vs PVWatts typical-year) |
+
+Run standalone: `uvx --from solar-data-mcp-forecast solar-forecast-mcp` — but see the
+model-install note below; most users want the combined
+[`solar-data-mcp`](https://github.com/hoodsy/solar-data-mcp/blob/main/packages/solar-data-mcp/README.md)
+server, which adds the other three domains plus the skill and report layer.
+
+## Installing the model
+
+`quartz-solar-forecast` pins `pydantic==2.6.2`, which conflicts with the MCP SDK,
+so it is not a declared dependency. Install it alongside (it runs fine on newer
+pydantic; the pin is conservative):
+
+```console
+$ pip install solar-data-mcp-forecast
+$ pip install --no-deps quartz-solar-forecast
+$ pip install pv-site-prediction xarray xgboost openmeteo-requests requests-cache retry-requests
+```
+
+Without the model installed, the server still starts and its tools return an
+error containing these instructions.
+
+## Using forecasts with the combined `solar-data-mcp` server
+
+An ephemeral `uvx` environment cannot hold the side-install above. Use a
+persistent venv and point your agent at its entry point:
+
+```console
+$ python3 -m venv ~/.venvs/solar-data-mcp
+$ ~/.venvs/solar-data-mcp/bin/pip install solar-data-mcp
+$ ~/.venvs/solar-data-mcp/bin/pip install --no-deps quartz-solar-forecast
+$ ~/.venvs/solar-data-mcp/bin/pip install pv-site-prediction xarray xgboost openmeteo-requests requests-cache retry-requests
+```
+
+Then in the agent config, replace `"command": "uvx", "args": ["solar-data-mcp"]`
+with `"command": "~/.venvs/solar-data-mcp/bin/solar-data-mcp"`.

solar_data_mcp_forecast-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "solar-data-mcp-forecast"
+version = "0.1.0"
+description = "MCP server for solar generation forecasts via the open Quartz Solar Forecast model (Open Climate Fix)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Logan Bernard" }]
+keywords = ["solar", "mcp", "forecast", "quartz", "open-climate-fix"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+# quartz-solar-forecast is deliberately NOT a dependency: it pins pydantic==2.6.2,
+# which conflicts with the MCP SDK. See README for the documented install path;
+# the server starts without it and returns actionable errors from forecast tools.
+dependencies = [
+    "solar-data-mcp-core>=0.1,<0.2",
+    "solar-data-mcp-nrel>=0.1,<0.2",
+    "mcp>=1.26,<2",
+    "httpx>=0.27,<1",
+    "pydantic>=2.7,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/hoodsy/solar-data-mcp"
+
+[project.scripts]
+solar-forecast-mcp = "solar_mcp_forecast.server:main"
+
+[tool.uv.sources]
+solar-data-mcp-core = { workspace = true }
+solar-data-mcp-nrel = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/solar_mcp_forecast"]

solar_data_mcp_forecast-0.1.0/src/solar_mcp_forecast/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for open solar generation forecasts (Quartz / Open Climate Fix)."""
+
+__version__ = "0.1.0"

solar_data_mcp_forecast-0.1.0/src/solar_mcp_forecast/predictor.py

@@ -0,0 +1,72 @@
+"""The predictor seam: everything model-specific behind one callable type.
+
+Tools depend on `Predictor`, not on quartz — tests stub it, CI never loads the
+ML stack, and the quartz import failure turns into an actionable message
+instead of a broken server.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from solar_mcp_core.errors import SolarMCPError
+
+QUARTZ_URL = "https://github.com/openclimatefix/quartz-solar-forecast"
+QUARTZ_LICENSE = "MIT (Open Climate Fix); open NWP inputs, no API key"
+
+INSTALL_HINT = (
+    "quartz-solar-forecast is not installed. It pins pydantic==2.6.2 (conflicts "
+    "with the MCP SDK) so it is not auto-installed; add it alongside with: "
+    "pip install --no-deps quartz-solar-forecast && pip install "
+    "pv-site-prediction xarray xgboost openmeteo-requests requests-cache "
+    "retry-requests  (see the solar-data-mcp-forecast README)"
+)
+
+
+@dataclass(frozen=True)
+class ForecastRequest:
+    lat: float
+    lon: float
+    capacity_kw: float
+    tilt_deg: float
+    azimuth_deg: float
+    horizon_hours: int
+
+
+@dataclass(frozen=True)
+class ForecastPoint:
+    time: str  # ISO 8601 UTC, hourly steps
+    power_kw: float
+
+
+# Synchronous by design — model inference is CPU-bound; tools run it in a thread.
+Predictor = Callable[[ForecastRequest], list[ForecastPoint]]
+
+
+def quartz_predictor(request: ForecastRequest) -> list[ForecastPoint]:
+    """Run the real Quartz model. Imported lazily; see INSTALL_HINT."""
+    try:
+        from quartz_solar_forecast.forecast import run_forecast
+        from quartz_solar_forecast.pydantic_models import PVSite
+    except ImportError as exc:
+        raise SolarMCPError(INSTALL_HINT) from exc
+
+    site = PVSite(
+        latitude=request.lat,
+        longitude=request.lon,
+        capacity_kwp=request.capacity_kw,
+        tilt=request.tilt_deg,
+        orientation=request.azimuth_deg,
+    )
+    frame = run_forecast(site=site, ts=datetime.now(tz=UTC).replace(tzinfo=None))
+    # Contract: hourly points. Quartz emits sub-hourly steps; resample to 1h means.
+    hourly = frame.resample("1h").mean().head(request.horizon_hours)
+    points: list[ForecastPoint] = []
+    for timestamp, row in hourly.iterrows():
+        points.append(
+            ForecastPoint(
+                time=timestamp.strftime("%Y-%m-%dT%H:%M:%SZ"),
+                power_kw=float(row["power_kw"]),
+            )
+        )
+    return points

solar_data_mcp_forecast-0.1.0/src/solar_mcp_forecast/resources.py

@@ -0,0 +1,34 @@
+"""MCP resources: provenance agents can cite (license, coverage)."""
+
+from mcp.server.fastmcp import FastMCP
+
+QUARTZ_LICENSE_TEXT = """\
+Quartz Solar Forecast — Open Climate Fix.
+
+- Model and code: MIT license, https://github.com/openclimatefix/quartz-solar-forecast
+- Inputs: open numerical weather prediction data; no API key, no live PV feed.
+- Cite "Open Climate Fix, Quartz Solar Forecast" with the run timestamp.
+"""
+
+COVERAGE = """\
+Coverage notes for the solar-forecast server.
+
+- Forecasts are cold-start (weather-only) site-level estimates, horizon <= 48h,
+  global NWP coverage; accuracy is best where NWP models are strong (US/EU).
+- Screening-grade output: planning and "is today unusual" questions — not for
+  grid settlement, bidding, or contractual commitments.
+- The comparison baseline is PVWatts TMY (typical meteorological year) spread
+  uniformly over the month's hours; see each result's assumptions.
+- The quartz-solar-forecast package must be installed separately (its pydantic
+  pin conflicts with the MCP SDK — see the package README for the exact steps).
+"""
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.resource("source://quartz/license", title="Quartz model license & citation")
+    def quartz_license() -> str:
+        return QUARTZ_LICENSE_TEXT
+
+    @mcp.resource("source://solar-forecast/coverage", title="Forecast coverage & limits")
+    def coverage() -> str:
+        return COVERAGE

solar_data_mcp_forecast-0.1.0/src/solar_mcp_forecast/server.py

@@ -0,0 +1,161 @@
+"""FastMCP server exposing the solar-forecast tools over stdio.
+
+The Quartz model is behind the Predictor seam: the server starts without it
+installed, and forecast tools fail with install instructions rather than
+breaking the whole server. compare_forecast_to_model additionally shares one
+NREL client for the PVWatts TMY baseline.
+"""
+
+from collections.abc import AsyncIterator, Callable
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Protocol, TypeVar
+
+from mcp.server.fastmcp import Context, FastMCP
+from mcp.server.session import ServerSession
+from solar_mcp_core.config import NREL
+from solar_mcp_core.envelope import ToolResult
+from solar_mcp_core.http import SolarHttpClient, configure_debug_logging
+
+from solar_mcp_forecast import resources
+from solar_mcp_forecast.predictor import Predictor, quartz_predictor
+from solar_mcp_forecast.tools.compare_forecast_to_model import (
+    compare_forecast_to_model as _compare,
+)
+from solar_mcp_forecast.tools.forecast_generation import forecast_generation as _forecast
+
+
+@dataclass
+class AppContext:
+    predictor: Predictor
+    nrel: SolarHttpClient
+
+    async def aclose(self) -> None:
+        await self.nrel.aclose()
+
+
+class ForecastDeps(Protocol):
+    """Context fields the forecast tools read. Any hosting server's lifespan
+    context must provide these — this package's AppContext does, and so does
+    the solar-data-mcp umbrella's composite context."""
+
+    nrel: SolarHttpClient
+
+    # Read-only property, not a plain attribute: mypy treats Callable-typed
+    # dataclass fields as read-only, and a settable protocol member would
+    # reject every conforming AppContext.
+    @property
+    def predictor(self) -> Predictor: ...
+
+
+DepsT = TypeVar("DepsT", bound=ForecastDeps)
+
+ToolContext = Context[ServerSession, ForecastDeps]
+
+
+def default_context() -> AppContext:
+    return AppContext(predictor=quartz_predictor, nrel=SolarHttpClient(NREL))
+
+
+def register_tools(mcp: FastMCP[DepsT]) -> None:
+    @mcp.tool()
+    async def forecast_generation(
+        ctx: ToolContext,
+        lat: float,
+        lon: float,
+        capacity_kw: float,
+        tilt_deg: float | None = None,
+        azimuth_deg: float | None = None,
+        horizon_hours: int | None = None,
+    ) -> ToolResult:
+        """Hourly generation forecast for the next hours (Quartz open model).
+
+        Use this for "how much will this system produce today/tomorrow".
+        Use nrel-solar's estimate_production for typical-year expectations,
+        and compare_forecast_to_model to judge whether the forecast is unusual.
+        Defaults: tilt = site latitude, azimuth 180 (south), horizon 48h —
+        each stated in assumptions. Max horizon 48 hours.
+
+        Example: forecast_generation(lat=39.74, lon=-105.18, capacity_kw=6)
+        -> hourly kW series, total_kwh, peak_kw.
+
+        Units: power in kW AC; energy in kWh; times ISO 8601 UTC.
+        """
+        return await _forecast(
+            ctx.request_context.lifespan_context.predictor,
+            lat=lat,
+            lon=lon,
+            capacity_kw=capacity_kw,
+            tilt_deg=tilt_deg,
+            azimuth_deg=azimuth_deg,
+            horizon_hours=horizon_hours,
+        )
+
+    @mcp.tool()
+    async def compare_forecast_to_model(
+        ctx: ToolContext,
+        lat: float,
+        lon: float,
+        capacity_kw: float,
+        tilt_deg: float | None = None,
+        azimuth_deg: float | None = None,
+        horizon_hours: int | None = None,
+    ) -> ToolResult:
+        """Is the forecast unusual? Quartz forecast vs PVWatts typical-year rate.
+
+        Use this for "is today a good solar day here". Returns the forecast
+        total, the TMY-typical total for the same horizon, their ratio, and a
+        plain-language verdict. Horizons in multiples of 24h compare cleanest
+        (see assumptions for the uniform-spread simplification).
+
+        Example: compare_forecast_to_model(lat=39.74, lon=-105.18,
+        capacity_kw=6, horizon_hours=24) -> ratio_pct ~120 on a clear day.
+
+        Units: energies in kWh; ratio in percent.
+        """
+        context = ctx.request_context.lifespan_context
+        return await _compare(
+            context.predictor,
+            context.nrel,
+            lat=lat,
+            lon=lon,
+            capacity_kw=capacity_kw,
+            tilt_deg=tilt_deg,
+            azimuth_deg=azimuth_deg,
+            horizon_hours=horizon_hours,
+        )
+
+
+def create_server(context_factory: Callable[[], AppContext] | None = None) -> FastMCP:
+    factory = context_factory if context_factory is not None else default_context
+
+    @asynccontextmanager
+    async def lifespan(_server: FastMCP) -> AsyncIterator[AppContext]:
+        context = factory()
+        try:
+            yield context
+        finally:
+            await context.aclose()
+
+    mcp: FastMCP[AppContext] = FastMCP(
+        "solar-forecast",
+        instructions=(
+            "Solar generation forecasts from the open Quartz model (Open Climate "
+            "Fix) — no API key. forecast_generation for the next <=48h; "
+            "compare_forecast_to_model for 'is today unusual?' against PVWatts "
+            "TMY. Screening-grade, not grid settlement."
+        ),
+        lifespan=lifespan,
+    )
+    register_tools(mcp)
+    resources.register(mcp)
+    return mcp
+
+
+def main() -> None:
+    configure_debug_logging()
+    create_server().run()
+
+
+if __name__ == "__main__":
+    main()

solar_data_mcp_forecast-0.1.0/src/solar_mcp_forecast/tools/__init__.py

@@ -0,0 +1 @@
+"""Tool implementations. Plain typed async functions; MCP shims live in server.py."""

solar_data_mcp_forecast-0.1.0/src/solar_mcp_forecast/tools/compare_forecast_to_model.py

@@ -0,0 +1,103 @@
+"""compare_forecast_to_model: is the next-hours forecast unusual vs TMY typical?"""
+
+import calendar
+from datetime import UTC, datetime
+
+from solar_mcp_core import units
+from solar_mcp_core.envelope import ToolResult, audit_entry, composite_source_ref
+from solar_mcp_core.http import SolarHttpClient
+from solar_mcp_nrel.models import SystemSpec
+from solar_mcp_nrel.tools.estimate_production import estimate_production
+
+from solar_mcp_forecast.predictor import Predictor
+from solar_mcp_forecast.tools.forecast_generation import forecast_generation
+
+UNIFORM_ASSUMPTION = (
+    "TMY expectation spreads the month's typical production uniformly across "
+    "its hours; forecasts covering mostly daylight (or night) will skew high "
+    "(or low) against it — horizons in multiples of 24h compare cleanest"
+)
+
+
+async def compare_forecast_to_model(
+    predictor: Predictor,
+    nrel_client: SolarHttpClient,
+    *,
+    lat: float,
+    lon: float,
+    capacity_kw: float,
+    tilt_deg: float | None = None,
+    azimuth_deg: float | None = None,
+    horizon_hours: int | None = None,
+) -> ToolResult:
+    forecast = await forecast_generation(
+        predictor,
+        lat=lat,
+        lon=lon,
+        capacity_kw=capacity_kw,
+        tilt_deg=tilt_deg,
+        azimuth_deg=azimuth_deg,
+        horizon_hours=horizon_hours,
+    )
+    horizon = int(forecast.data["horizon_hours"])
+    hours_returned = int(forecast.data["hours_returned"])
+    forecast_kwh = float(forecast.data["total_kwh"])
+
+    typical = await estimate_production(
+        nrel_client,
+        SystemSpec(lat=lat, lon=lon, tilt_deg=tilt_deg, azimuth_deg=azimuth_deg),
+        capacity_kw,
+    )
+    now = datetime.now(tz=UTC)
+    month_kwh = float(typical.data["ac_monthly"][now.month - 1])
+    days_in_month = calendar.monthrange(now.year, now.month)[1]
+    expected_kwh = round(month_kwh / (days_in_month * 24) * hours_returned, 2)
+
+    ratio_pct = round(forecast_kwh / expected_kwh * 100, 1) if expected_kwh > 0 else None
+    if ratio_pct is None:
+        verdict = "no typical-production baseline for this month"
+    elif ratio_pct >= 115:
+        verdict = f"unusually sunny: ~{ratio_pct - 100:.0f}% above a typical {now:%B}"
+    elif ratio_pct <= 85:
+        verdict = f"below typical: ~{100 - ratio_pct:.0f}% under a typical {now:%B}"
+    else:
+        verdict = f"close to typical for {now:%B}"
+
+    warnings = list(dict.fromkeys([*forecast.warnings, *typical.warnings]))
+    if hours_returned % 24 != 0:
+        warnings.append(
+            f"compared window of {hours_returned}h is not a whole number of days; "
+            "the daylight share skews the ratio (see assumptions)"
+        )
+
+    return ToolResult(
+        data={
+            "forecast_kwh": forecast_kwh,
+            "tmy_expected_kwh": expected_kwh,
+            "ratio_pct": ratio_pct,
+            "verdict": verdict,
+            "horizon_hours": horizon,
+            "month": f"{now:%Y-%m}",
+            "audit_trail": [
+                audit_entry("forecast", forecast.source),
+                audit_entry("tmy_baseline", typical.source),
+            ],
+        },
+        units={
+            "forecast_kwh": units.KWH,
+            "tmy_expected_kwh": units.KWH,
+            "ratio_pct": units.PERCENT,
+            "verdict": units.LABEL,
+            "horizon_hours": units.HOURS,
+            "month": units.ISO_DATE,
+            "audit_trail[].component": units.LABEL,
+            "audit_trail[].retrieved_at": units.ISO_DATE,
+        },
+        source=composite_source_ref(),
+        assumptions=[
+            *forecast.assumptions,
+            *(f"tmy_baseline: {line}" for line in typical.assumptions),
+            UNIFORM_ASSUMPTION,
+        ],
+        warnings=warnings,
+    )

solar_data_mcp_forecast-0.1.0/src/solar_mcp_forecast/tools/forecast_generation.py

@@ -0,0 +1,123 @@
+"""forecast_generation: next-hours generation forecast from the open Quartz model."""
+
+import asyncio
+
+from solar_mcp_core import units
+from solar_mcp_core.envelope import SourceRef, ToolResult, utc_now_iso
+from solar_mcp_core.errors import BadInput, SolarMCPError, SourceUnavailable
+from solar_mcp_core.validation import (
+    default_tilt_azimuth,
+    validate_capacity_kw,
+    validate_lat_lon,
+)
+
+from solar_mcp_forecast.predictor import (
+    QUARTZ_LICENSE,
+    QUARTZ_URL,
+    ForecastRequest,
+    Predictor,
+)
+
+MAX_HORIZON_HOURS = 48
+OPEN_MODEL_CAVEAT = (
+    "Open-source ML forecast from public weather models (no live PV feed); "
+    "useful for planning, not for grid settlement or contractual commitments."
+)
+
+
+def resolve_forecast_request(
+    *,
+    lat: float,
+    lon: float,
+    capacity_kw: float,
+    tilt_deg: float | None,
+    azimuth_deg: float | None,
+    horizon_hours: int | None,
+) -> tuple[ForecastRequest, list[str], list[str]]:
+    """Validate and default-fill, recording every injected default. Pure."""
+    validate_lat_lon(lat, lon)
+    validate_capacity_kw(capacity_kw)
+    tilt_deg, azimuth_deg, assumptions, warnings = default_tilt_azimuth(lat, tilt_deg, azimuth_deg)
+    if not 0 <= tilt_deg <= 90:
+        raise BadInput(field="tilt_deg", value=tilt_deg, allowed="0 to 90")
+    if not 0 <= azimuth_deg < 360:
+        raise BadInput(field="azimuth_deg", value=azimuth_deg, allowed="0 to <360")
+    if horizon_hours is None:
+        horizon_hours = MAX_HORIZON_HOURS
+        assumptions.append(f"horizon_hours not provided; defaulted to {MAX_HORIZON_HOURS}")
+    if not 1 <= horizon_hours <= MAX_HORIZON_HOURS:
+        raise BadInput(
+            field="horizon_hours", value=horizon_hours, allowed=f"1 to {MAX_HORIZON_HOURS}"
+        )
+    request = ForecastRequest(
+        lat=lat,
+        lon=lon,
+        capacity_kw=capacity_kw,
+        tilt_deg=tilt_deg,
+        azimuth_deg=azimuth_deg,
+        horizon_hours=horizon_hours,
+    )
+    return request, assumptions, warnings
+
+
+async def forecast_generation(
+    predictor: Predictor,
+    *,
+    lat: float,
+    lon: float,
+    capacity_kw: float,
+    tilt_deg: float | None = None,
+    azimuth_deg: float | None = None,
+    horizon_hours: int | None = None,
+) -> ToolResult:
+    request, assumptions, site_warnings = resolve_forecast_request(
+        lat=lat,
+        lon=lon,
+        capacity_kw=capacity_kw,
+        tilt_deg=tilt_deg,
+        azimuth_deg=azimuth_deg,
+        horizon_hours=horizon_hours,
+    )
+    try:
+        points = await asyncio.to_thread(predictor, request)  # model inference is CPU-bound
+    except SolarMCPError:
+        raise
+    except Exception as exc:  # NWP download / schema errors from the model stack
+        raise SourceUnavailable("quartz", f"{type(exc).__name__}: {exc}") from exc
+
+    warnings = [*site_warnings, OPEN_MODEL_CAVEAT]
+    if len(points) < request.horizon_hours:
+        warnings.append(
+            f"model returned {len(points)} of {request.horizon_hours} requested hours; "
+            "totals cover the returned hours only"
+        )
+
+    total_kwh = round(sum(p.power_kw for p in points), 2)  # hourly points -> kW*1h
+    peak = max(points, key=lambda p: p.power_kw) if points else None
+    return ToolResult(
+        data={
+            "series": [{"time": p.time, "power_kw": round(p.power_kw, 3)} for p in points],
+            "total_kwh": total_kwh,
+            "peak_kw": round(peak.power_kw, 3) if peak else 0.0,
+            "peak_time": peak.time if peak else None,
+            "horizon_hours": request.horizon_hours,
+            "hours_returned": len(points),
+        },
+        units={
+            "series[].time": units.ISO_DATE,
+            "series[].power_kw": units.KW_AC,
+            "total_kwh": units.KWH,
+            "peak_kw": units.KW_AC,
+            "peak_time": units.ISO_DATE,
+            "horizon_hours": units.HOURS,
+            "hours_returned": units.HOURS,
+        },
+        source=SourceRef(
+            name="Quartz Solar Forecast (Open Climate Fix)",
+            url=QUARTZ_URL,
+            retrieved_at=utc_now_iso(),
+            license=QUARTZ_LICENSE,
+        ),
+        assumptions=[*assumptions, "cold-start forecast from NWP weather only (no live PV feed)"],
+        warnings=warnings,
+    )

solar_data_mcp_forecast-0.1.0/tests/test_compare_forecast.py

@@ -0,0 +1,81 @@
+import calendar
+from datetime import UTC, datetime
+from pathlib import Path
+
+import httpx
+import pytest
+from solar_mcp_core.config import NREL
+from solar_mcp_core.http import SolarHttpClient
+from solar_mcp_forecast.predictor import ForecastPoint, ForecastRequest, Predictor
+from solar_mcp_forecast.tools.compare_forecast_to_model import compare_forecast_to_model
+
+from conftest import assert_envelope, build_client
+
+
+def flat_predictor(power_kw: float) -> Predictor:
+    def predict(request: ForecastRequest) -> list[ForecastPoint]:
+        return [
+            ForecastPoint(time=f"2026-07-05T{hour:02d}:00:00Z", power_kw=power_kw)
+            for hour in range(request.horizon_hours)
+        ]
+
+    return predict
+
+
+def nrel_client_with_flat_months(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> SolarHttpClient:
+    """PVWatts stub tuned to exactly 1 kWh per hour in every calendar month."""
+    monkeypatch.setenv("NREL_API_KEY", "TESTKEY")
+    year = datetime.now(tz=UTC).year
+    ac_monthly = [calendar.monthrange(year, month)[1] * 24.0 for month in range(1, 13)]
+    body = {
+        "errors": [],
+        "warnings": [],
+        "station_info": {"lat": 39.7, "lon": -105.2},
+        "outputs": {
+            "ac_annual": sum(ac_monthly),
+            "ac_monthly": ac_monthly,
+            "solrad_annual": 4.8,
+            "capacity_factor": 16.4,
+        },
+    }
+    return build_client(NREL, lambda request: httpx.Response(200, json=body), tmp_path)
+
+
+@pytest.mark.anyio
+async def test_sunny_forecast_flagged_above_typical(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    client = nrel_client_with_flat_months(tmp_path, monkeypatch)
+    result = await compare_forecast_to_model(
+        flat_predictor(1.25), client, lat=39.74, lon=-105.18, capacity_kw=6.0, horizon_hours=24
+    )
+    assert_envelope(result)
+    assert result.data["tmy_expected_kwh"] == pytest.approx(24.0)
+    assert result.data["forecast_kwh"] == pytest.approx(30.0)
+    assert result.data["ratio_pct"] == pytest.approx(125.0)
+    assert "unusually sunny" in result.data["verdict"]
+    assert not any("not a whole number of days" in w for w in result.warnings)
+
+
+@pytest.mark.anyio
+async def test_cloudy_forecast_flagged_below_typical(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    client = nrel_client_with_flat_months(tmp_path, monkeypatch)
+    result = await compare_forecast_to_model(
+        flat_predictor(0.5), client, lat=39.74, lon=-105.18, capacity_kw=6.0, horizon_hours=24
+    )
+    assert result.data["ratio_pct"] == pytest.approx(50.0)
+    assert "below typical" in result.data["verdict"]
+
+
+@pytest.mark.anyio
+async def test_partial_day_horizon_warns(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    client = nrel_client_with_flat_months(tmp_path, monkeypatch)
+    result = await compare_forecast_to_model(
+        flat_predictor(1.0), client, lat=39.74, lon=-105.18, capacity_kw=6.0, horizon_hours=30
+    )
+    assert any("not a whole number of days" in w for w in result.warnings)
+    assert any("uniformly" in a for a in result.assumptions)

solar_data_mcp_forecast-0.1.0/tests/test_forecast_generation.py

@@ -0,0 +1,110 @@
+import pytest
+from solar_mcp_core.errors import BadInput
+from solar_mcp_forecast.predictor import ForecastPoint, ForecastRequest
+from solar_mcp_forecast.tools.forecast_generation import (
+    forecast_generation,
+    resolve_forecast_request,
+)
+
+from conftest import assert_envelope
+
+
+def stub_predictor(request: ForecastRequest) -> list[ForecastPoint]:
+    """Deterministic hourly ramp: 0, 2, 1 kW then zeros to the horizon."""
+    shape = [0.0, 2.0, 1.0]
+    points = []
+    for hour in range(request.horizon_hours):
+        power = shape[hour] if hour < len(shape) else 0.0
+        points.append(ForecastPoint(time=f"2026-07-05T{hour:02d}:00:00Z", power_kw=power))
+    return points
+
+
+class TestResolveForecastRequest:
+    def test_defaults_are_recorded(self) -> None:
+        request, assumptions, _warnings = resolve_forecast_request(
+            lat=39.74,
+            lon=-105.18,
+            capacity_kw=6.0,
+            tilt_deg=None,
+            azimuth_deg=None,
+            horizon_hours=None,
+        )
+        assert request.tilt_deg == pytest.approx(39.74)
+        assert request.azimuth_deg == 180.0
+        assert request.horizon_hours == 48
+        text = " ".join(assumptions)
+        for expected in ("tilt_deg", "azimuth_deg", "horizon_hours"):
+            assert expected in text
+
+    def test_explicit_values_produce_no_assumptions(self) -> None:
+        _, assumptions, _warnings = resolve_forecast_request(
+            lat=39.74,
+            lon=-105.18,
+            capacity_kw=6.0,
+            tilt_deg=25.0,
+            azimuth_deg=180.0,
+            horizon_hours=24,
+        )
+        assert assumptions == []
+
+    @pytest.mark.parametrize(
+        ("field", "kwargs"),
+        [
+            ("lat", {"lat": 91.0}),
+            ("capacity_kw", {"capacity_kw": 0.01}),
+            ("tilt_deg", {"tilt_deg": 95.0}),
+            ("azimuth_deg", {"azimuth_deg": 360.0}),
+            ("horizon_hours", {"horizon_hours": 49}),
+            ("horizon_hours", {"horizon_hours": 0}),
+        ],
+    )
+    def test_out_of_range_rejected(self, field: str, kwargs: dict[str, float]) -> None:
+        base: dict[str, object] = {
+            "lat": 39.74,
+            "lon": -105.18,
+            "capacity_kw": 6.0,
+            "tilt_deg": 25.0,
+            "azimuth_deg": 180.0,
+            "horizon_hours": 24,
+        }
+        base.update(kwargs)
+        with pytest.raises(BadInput) as excinfo:
+            resolve_forecast_request(**base)  # type: ignore[arg-type]
+        assert excinfo.value.field == field
+
+
+@pytest.mark.anyio
+async def test_forecast_generation_totals_and_peak() -> None:
+    result = await forecast_generation(
+        stub_predictor, lat=39.74, lon=-105.18, capacity_kw=6.0, horizon_hours=6
+    )
+    assert_envelope(result)
+    assert result.data["total_kwh"] == pytest.approx(3.0)  # 0 + 2 + 1 kW over hourly steps
+    assert result.data["peak_kw"] == pytest.approx(2.0)
+    assert result.data["peak_time"] == "2026-07-05T01:00:00Z"
+    assert len(result.data["series"]) == 6
+    assert any("Open-source ML forecast" in w for w in result.warnings)
+    assert result.source.name.startswith("Quartz")
+
+
+@pytest.mark.anyio
+async def test_predictor_crash_maps_to_source_unavailable() -> None:
+    from solar_mcp_core.errors import SourceUnavailable
+
+    def broken(request: ForecastRequest) -> list[ForecastPoint]:
+        raise RuntimeError("open-meteo download failed")
+
+    with pytest.raises(SourceUnavailable, match="RuntimeError"):
+        await forecast_generation(broken, lat=39.74, lon=-105.18, capacity_kw=6.0)
+
+
+@pytest.mark.anyio
+async def test_shortfall_hours_are_reported() -> None:
+    def short(request: ForecastRequest) -> list[ForecastPoint]:
+        return [ForecastPoint(time="2026-07-05T00:00:00Z", power_kw=1.0)]
+
+    result = await forecast_generation(
+        short, lat=39.74, lon=-105.18, capacity_kw=6.0, horizon_hours=24
+    )
+    assert result.data["hours_returned"] == 1
+    assert any("1 of 24 requested hours" in w for w in result.warnings)

solar_data_mcp_forecast-0.1.0/tests/test_forecast_server.py

@@ -0,0 +1,98 @@
+"""Server-level tests over an in-memory MCP session (no subprocess, no network)."""
+
+from collections.abc import AsyncIterator, Callable
+
+import pytest
+from mcp.shared.memory import create_connected_server_and_client_session
+from mcp.types import TextContent
+from solar_mcp_core.config import NREL, SourceConfig
+from solar_mcp_core.errors import SolarMCPError
+from solar_mcp_core.http import SolarHttpClient
+from solar_mcp_forecast.predictor import (
+    INSTALL_HINT,
+    ForecastPoint,
+    ForecastRequest,
+    quartz_predictor,
+)
+from solar_mcp_forecast.server import AppContext, create_server
+
+from conftest import assert_tool_docs
+
+ClientFor = Callable[[SourceConfig], SolarHttpClient]
+
+EXPECTED_TOOLS = {"forecast_generation", "compare_forecast_to_model"}
+
+
+def stub_predictor(request: ForecastRequest) -> list[ForecastPoint]:
+    return [
+        ForecastPoint(time=f"2026-07-05T{hour:02d}:00:00Z", power_kw=1.0)
+        for hour in range(request.horizon_hours)
+    ]
+
+
+@pytest.fixture
+async def session(client_for: ClientFor) -> AsyncIterator[object]:
+    def context() -> AppContext:
+        return AppContext(predictor=stub_predictor, nrel=client_for(NREL))
+
+    server = create_server(context_factory=context)
+    async with create_connected_server_and_client_session(
+        server._mcp_server, raise_exceptions=True
+    ) as client_session:
+        yield client_session
+
+
+@pytest.mark.anyio
+async def test_lists_both_tools_with_docs(session) -> None:  # type: ignore[no-untyped-def]
+    tools = await session.list_tools()
+    assert {tool.name for tool in tools.tools} == EXPECTED_TOOLS
+    assert_tool_docs(tools.tools)
+
+
+@pytest.mark.anyio
+async def test_forecast_over_mcp(session) -> None:  # type: ignore[no-untyped-def]
+    result = await session.call_tool(
+        "forecast_generation",
+        {"lat": 39.74, "lon": -105.18, "capacity_kw": 6.0, "horizon_hours": 12},
+    )
+    assert not result.isError
+    structured = result.structuredContent
+    assert structured is not None
+    for key in ("data", "units", "source", "assumptions", "warnings"):
+        assert key in structured
+    assert structured["data"]["total_kwh"] == pytest.approx(12.0)
+
+
+@pytest.mark.anyio
+async def test_bad_horizon_reported_not_crash(session) -> None:  # type: ignore[no-untyped-def]
+    result = await session.call_tool(
+        "forecast_generation",
+        {"lat": 39.74, "lon": -105.18, "capacity_kw": 6.0, "horizon_hours": 99},
+    )
+    assert result.isError
+    assert isinstance(result.content[0], TextContent)
+    assert "horizon_hours" in result.content[0].text
+
+
+@pytest.mark.anyio
+async def test_resources_exposed(session) -> None:  # type: ignore[no-untyped-def]
+    resources = await session.list_resources()
+    uris = {str(resource.uri) for resource in resources.resources}
+    assert {"source://quartz/license", "source://solar-forecast/coverage"} <= uris
+
+
+def test_quartz_predictor_missing_is_actionable() -> None:
+    """quartz-solar-forecast is not installed in this workspace (pydantic pin
+    conflict) — the predictor must fail with install instructions, not a bare
+    ImportError."""
+    request = ForecastRequest(
+        lat=39.74,
+        lon=-105.18,
+        capacity_kw=6.0,
+        tilt_deg=25.0,
+        azimuth_deg=180.0,
+        horizon_hours=4,
+    )
+    with pytest.raises(SolarMCPError) as excinfo:
+        quartz_predictor(request)
+    assert str(excinfo.value) == INSTALL_HINT