solar-data-mcp 0.1.0__tar.gz

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

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: solar-data-mcp
+Version: 0.1.0
+Summary: All US open solar data in one MCP server: PVWatts production, tariffs & ROI, market intelligence, forecasts
+Project-URL: Homepage, https://github.com/hoodsy/solar-data-mcp
+Author: Logan Bernard
+License-Expression: MIT
+Keywords: eia,forecast,mcp,nrel,open-data,pvwatts,solar,solartrace,urdb,uspvdb
+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: duckdb<2,>=1.1
+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-economics<0.2,>=0.1
+Requires-Dist: solar-data-mcp-forecast<0.2,>=0.1
+Requires-Dist: solar-data-mcp-market<0.2,>=0.1
+Requires-Dist: solar-data-mcp-nrel<0.2,>=0.1
+Description-Content-Type: text/markdown
+
+# solar-data-mcp
+
+All US open solar data in **one MCP server**: NREL PVWatts production modeling,
+tariffs & ROI economics, market intelligence, and generation forecasts — 18
+tools, every result carrying data + units + source + assumptions + warnings.
+Part of [solar-data-mcp](https://github.com/hoodsy/solar-data-mcp), which also ships
+each domain as a standalone server.
+
+## Add it to your agent
+
+```json
+{
+  "mcpServers": {
+    "solar-data": {
+      "command": "uvx",
+      "args": ["solar-data-mcp"],
+      "env": {
+        "NREL_API_KEY": "YOUR_KEY",
+        "OPENEI_API_KEY": "YOUR_KEY",
+        "EIA_API_KEY": "YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+Snippets for Claude Code, Codex, OpenCode, and Hermes live in the
+[repo README](https://github.com/hoodsy/solar-data-mcp#add-it-to-your-agent).
+
+## Keys (all free; every one optional to start)
+
+| Env var | Unlocks | Get one |
+| --- | --- | --- |
+| `NREL_API_KEY` | estimate_production, get_solar_resource, compare_orientations, size_system_for_target, estimate_roi, compare_forecast_to_model | <https://developer.nlr.gov/signup/> (`DEMO_KEY` works for ~10 req/hr) |
+| `OPENEI_API_KEY` | lookup_tariffs | <https://openei.org/services/api/signup/> |
+| `EIA_API_KEY` | get_electricity_prices | <https://www.eia.gov/opendata/register.php> |
+| `AHJ_REGISTRY_TOKEN` (optional) | identify_ahj | email <support@sunspec.org> |
+
+Market tools (USPVDB, Tracking the Sun, SolarTRACE) and forecasts need no key.
+The server starts with zero keys set — tools missing a key return setup
+instructions instead of failing silently. Check your setup any time:
+
+```console
+$ uvx solar-data-mcp doctor
+```
+
+## Skills
+
+The server also ships eleven **skills** — procedural instructions that teach an agent
+how to chain the tools for common question shapes (site assessment, quote review,
+market briefs, …), including sync prerequisites and reporting rules. They are served
+as MCP resources: `skill://solar/index` is the routing table (match the question
+against it, load the referenced `skill://solar/<name>`), and the server instructions
+point agents there automatically. Catalog and design rationale:
+[`docs/skills.md`](https://github.com/hoodsy/solar-data-mcp/blob/main/docs/skills.md).
+
+Four of the skills produce **reports** with a fixed document shape, and each is also
+exposed as an MCP prompt your host surfaces natively — `market_brief(state)`,
+`site_assessment(location, usage)`, `quote_review(quote_details)`, and
+`proposal_builder(customer_details)` — e.g. `/mcp__solar-data__market_brief` in
+Claude Code.
+
+## Forecast model note
+
+`forecast_generation` uses the open Quartz model, whose package pins an old
+pydantic and cannot live in an ephemeral `uvx` environment. Forecast tools
+degrade to an actionable install message without it; for real forecasts use a
+persistent install (`uv tool install solar-data-mcp`) plus the steps in the
+[solar-data-mcp-forecast README](https://github.com/hoodsy/solar-data-mcp/tree/main/packages/solar-forecast).

solar_data_mcp-0.1.0/README.md

@@ -0,0 +1,69 @@
+# solar-data-mcp
+
+All US open solar data in **one MCP server**: NREL PVWatts production modeling,
+tariffs & ROI economics, market intelligence, and generation forecasts — 18
+tools, every result carrying data + units + source + assumptions + warnings.
+Part of [solar-data-mcp](https://github.com/hoodsy/solar-data-mcp), which also ships
+each domain as a standalone server.
+
+## Add it to your agent
+
+```json
+{
+  "mcpServers": {
+    "solar-data": {
+      "command": "uvx",
+      "args": ["solar-data-mcp"],
+      "env": {
+        "NREL_API_KEY": "YOUR_KEY",
+        "OPENEI_API_KEY": "YOUR_KEY",
+        "EIA_API_KEY": "YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+Snippets for Claude Code, Codex, OpenCode, and Hermes live in the
+[repo README](https://github.com/hoodsy/solar-data-mcp#add-it-to-your-agent).
+
+## Keys (all free; every one optional to start)
+
+| Env var | Unlocks | Get one |
+| --- | --- | --- |
+| `NREL_API_KEY` | estimate_production, get_solar_resource, compare_orientations, size_system_for_target, estimate_roi, compare_forecast_to_model | <https://developer.nlr.gov/signup/> (`DEMO_KEY` works for ~10 req/hr) |
+| `OPENEI_API_KEY` | lookup_tariffs | <https://openei.org/services/api/signup/> |
+| `EIA_API_KEY` | get_electricity_prices | <https://www.eia.gov/opendata/register.php> |
+| `AHJ_REGISTRY_TOKEN` (optional) | identify_ahj | email <support@sunspec.org> |
+
+Market tools (USPVDB, Tracking the Sun, SolarTRACE) and forecasts need no key.
+The server starts with zero keys set — tools missing a key return setup
+instructions instead of failing silently. Check your setup any time:
+
+```console
+$ uvx solar-data-mcp doctor
+```
+
+## Skills
+
+The server also ships eleven **skills** — procedural instructions that teach an agent
+how to chain the tools for common question shapes (site assessment, quote review,
+market briefs, …), including sync prerequisites and reporting rules. They are served
+as MCP resources: `skill://solar/index` is the routing table (match the question
+against it, load the referenced `skill://solar/<name>`), and the server instructions
+point agents there automatically. Catalog and design rationale:
+[`docs/skills.md`](https://github.com/hoodsy/solar-data-mcp/blob/main/docs/skills.md).
+
+Four of the skills produce **reports** with a fixed document shape, and each is also
+exposed as an MCP prompt your host surfaces natively — `market_brief(state)`,
+`site_assessment(location, usage)`, `quote_review(quote_details)`, and
+`proposal_builder(customer_details)` — e.g. `/mcp__solar-data__market_brief` in
+Claude Code.
+
+## Forecast model note
+
+`forecast_generation` uses the open Quartz model, whose package pins an old
+pydantic and cannot live in an ephemeral `uvx` environment. Forecast tools
+degrade to an actionable install message without it; for real forecasts use a
+persistent install (`uv tool install solar-data-mcp`) plus the steps in the
+[solar-data-mcp-forecast README](https://github.com/hoodsy/solar-data-mcp/tree/main/packages/solar-forecast).

solar_data_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "solar-data-mcp"
+version = "0.1.0"
+description = "All US open solar data in one MCP server: PVWatts production, tariffs & ROI, market intelligence, forecasts"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Logan Bernard" }]
+keywords = ["solar", "mcp", "nrel", "pvwatts", "urdb", "eia", "uspvdb", "solartrace", "forecast", "open-data"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "solar-data-mcp-core>=0.1,<0.2",
+    "solar-data-mcp-nrel>=0.1,<0.2",
+    "solar-data-mcp-economics>=0.1,<0.2",
+    "solar-data-mcp-market>=0.1,<0.2",
+    "solar-data-mcp-forecast>=0.1,<0.2",
+    "mcp>=1.26,<2",
+    "httpx>=0.27,<1",
+    "pydantic>=2.7,<3",
+    "duckdb>=1.1,<2",
+]
+
+[project.urls]
+Homepage = "https://github.com/hoodsy/solar-data-mcp"
+
+[project.scripts]
+solar-data-mcp = "solar_data_mcp.server:main"
+
+[tool.uv.sources]
+solar-data-mcp-core = { workspace = true }
+solar-data-mcp-nrel = { workspace = true }
+solar-data-mcp-economics = { workspace = true }
+solar-data-mcp-market = { workspace = true }
+solar-data-mcp-forecast = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/solar_data_mcp"]

solar_data_mcp-0.1.0/src/solar_data_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""All four solar-data-mcp domain servers' tools on one MCP server."""
+
+__version__ = "0.1.0"

solar_data_mcp-0.1.0/src/solar_data_mcp/prompts.py

@@ -0,0 +1,77 @@
+"""MCP prompts: user-facing entry points to the report-shaped skills.
+
+Skills route agents by question shape; prompts let a *user* pick a deliverable
+from their host's UI (Claude Desktop / Claude Code surface these natively) and
+parameterize it. Each prompt expands to the same instruction: load the skill,
+run its workflow for the given inputs, render its report template. Nothing is
+duplicated — the skill file stays the single source of procedure.
+"""
+
+from mcp.server.fastmcp import FastMCP
+
+# prompt name -> skill name; tests cross-check both directions.
+PROMPT_SKILLS = {
+    "market_brief": "solar-market-brief",
+    "site_assessment": "solar-site-assessment",
+    "quote_review": "solar-quote-review",
+    "proposal_builder": "solar-proposal-builder",
+}
+
+
+def _expand(skill: str, task: str) -> str:
+    return (
+        f"Read the resource skill://solar/{skill} and follow it exactly: run its "
+        f"Workflow for the inputs below, honor its Sharp edges, and render its "
+        f"Report template as the final answer (including the assumptions and "
+        f"data-gap sections). Also apply skill://solar/solar-data-conventions.\n\n"
+        f"{task}"
+    )
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.prompt(
+        name="market_brief",
+        title="Solar market brief",
+        description="Standardized state solar-market report: adoption, pricing, policy, "
+        "utility-scale infrastructure, permitting friction.",
+    )
+    def market_brief(state: str) -> str:
+        return _expand("solar-market-brief", f"State to brief: {state}")
+
+    @mcp.prompt(
+        name="site_assessment",
+        title="Solar site assessment",
+        description="Would solar pay off here? Sizing, production, incentives, and "
+        "screening ROI for one location.",
+    )
+    def site_assessment(location: str, annual_usage_or_bill: str) -> str:
+        return _expand(
+            "solar-site-assessment",
+            f"Location: {location}\nAnnual usage or bill: {annual_usage_or_bill}",
+        )
+
+    @mcp.prompt(
+        name="quote_review",
+        title="Solar quote review",
+        description="Audit an installer's quote against market prices, modeled "
+        "production, and the incentive schedule.",
+    )
+    def quote_review(quote_details: str) -> str:
+        return _expand(
+            "solar-quote-review",
+            "Quote to review (size, price, promised production/payback, location): "
+            f"{quote_details}",
+        )
+
+    @mcp.prompt(
+        name="proposal_builder",
+        title="Solar proposal builder",
+        description="Turn a customer address, usage, roof planes, and your cost basis "
+        "into a full proposal package.",
+    )
+    def proposal_builder(customer_details: str) -> str:
+        return _expand(
+            "solar-proposal-builder",
+            "Customer inputs (location, annual kWh, roof planes, cost per watt): "
+            f"{customer_details}",
+        )

solar_data_mcp-0.1.0/src/solar_data_mcp/server.py

@@ -0,0 +1,164 @@
+"""The umbrella server: all four domain servers' tools on one FastMCP over
+stdio, so consumers install one `uvx solar-data-mcp` instead of four servers.
+
+Each domain package exposes register_tools() typed against a Protocol of the
+context fields its tools read; CompositeContext provides the union, and mypy
+proves the wiring at every register call. The sharing is load-bearing, not
+just convenient: one NREL client means one token bucket for the 1,000 req/hr
+quota that nrel, economics, and forecast tools all draw from, and one
+BulkStore handle sidesteps DuckDB's one-process-per-file lock that separate
+economics and market processes fight over.
+"""
+
+import sys
+from collections.abc import AsyncIterator, Callable
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+from mcp.server.fastmcp import FastMCP
+from solar_mcp_core.bulk import BulkStore
+from solar_mcp_core.cli import main as core_cli_main
+from solar_mcp_core.config import AHJ, EIA, NREL, OPENEI, USPVDB, api_key_for
+from solar_mcp_core.http import SolarHttpClient, configure_debug_logging
+from solar_mcp_economics import resources as economics_resources
+from solar_mcp_economics import server as economics_server
+from solar_mcp_forecast import resources as forecast_resources
+from solar_mcp_forecast import server as forecast_server
+from solar_mcp_forecast.predictor import Predictor, quartz_predictor
+from solar_mcp_market import resources as market_resources
+from solar_mcp_market import server as market_server
+from solar_mcp_nrel import resources as nrel_resources
+from solar_mcp_nrel import server as nrel_server
+
+from solar_data_mcp import prompts, skills
+
+INSTRUCTIONS = (
+    "All US open solar data in one server: NREL production modeling "
+    "(estimate_production, get_solar_resource, compare_orientations, "
+    "size_system_for_target), economics (lookup_tariffs, get_electricity_prices, "
+    "get_incentives, sync_incentives, estimate_roi), market intelligence "
+    "(query_installed_systems, get_permitting_timelines, "
+    "find_utility_scale_projects, identify_ahj, market_snapshot, sync_* loaders), "
+    "and forecasts (forecast_generation, compare_forecast_to_model). Every tool "
+    "returns data + units + source + assumptions + warnings; read the "
+    "assumptions before quoting numbers. Keys (env vars): NREL_API_KEY unlocks "
+    "the production, ROI, and forecast-vs-model tools; OPENEI_API_KEY unlocks "
+    "lookup_tariffs; EIA_API_KEY unlocks get_electricity_prices; "
+    "AHJ_REGISTRY_TOKEN (optional) unlocks identify_ahj. Market and forecast "
+    "tools need no key. Run `solar-data-mcp doctor` to check setup. "
+    "Before any multi-tool workflow, read skill://solar/index and load the "
+    "matching skill://solar/<name> resource — skills encode tool ordering, "
+    "sync prerequisites, and reporting rules for common question shapes."
+)
+
+
+@dataclass
+class CompositeContext:
+    """The union of the four domain packages' Deps protocols.
+
+    client and nrel are the SAME SolarHttpClient in default_context: nrel
+    tools read .client while economics/forecast tools read .nrel, and all of
+    them share one NREL token bucket only if the instance is shared.
+    """
+
+    client: SolarHttpClient
+    nrel: SolarHttpClient
+    openei: SolarHttpClient
+    eia: SolarHttpClient
+    uspvdb: SolarHttpClient
+    ahj: SolarHttpClient
+    store: BulkStore
+    predictor: Predictor
+
+    async def aclose(self) -> None:
+        # Dedupe by identity: client is normally the same object as nrel.
+        seen: set[int] = set()
+        for client in (self.client, self.nrel, self.openei, self.eia, self.uspvdb, self.ahj):
+            if id(client) not in seen:
+                seen.add(id(client))
+                await client.aclose()
+        self.store.close()
+
+
+def default_context() -> CompositeContext:
+    nrel = SolarHttpClient(NREL)
+    return CompositeContext(
+        client=nrel,
+        nrel=nrel,
+        openei=SolarHttpClient(OPENEI),
+        eia=SolarHttpClient(EIA),
+        uspvdb=SolarHttpClient(USPVDB),
+        ahj=SolarHttpClient(AHJ),
+        store=BulkStore(),
+        predictor=quartz_predictor,
+    )
+
+
+def create_server(context_factory: Callable[[], CompositeContext] | None = None) -> FastMCP:
+    factory = context_factory if context_factory is not None else default_context
+
+    @asynccontextmanager
+    async def lifespan(_server: FastMCP) -> AsyncIterator[CompositeContext]:
+        context = factory()
+        try:
+            yield context
+        finally:
+            await context.aclose()
+
+    mcp: FastMCP[CompositeContext] = FastMCP(
+        "solar-data",
+        instructions=INSTRUCTIONS,
+        lifespan=lifespan,
+    )
+    nrel_server.register_tools(mcp)
+    economics_server.register_tools(mcp)
+    market_server.register_tools(mcp)
+    forecast_server.register_tools(mcp)
+    for resources in (nrel_resources, economics_resources, market_resources, forecast_resources):
+        resources.register(mcp)
+    skills.register(mcp)
+    prompts.register(mcp)
+    return mcp
+
+
+def missing_key_note() -> str | None:
+    """One startup line naming unset keys, or None when everything is set.
+
+    Startup must stay fast and offline, so this only reads the environment —
+    `solar-data-mcp doctor` is the live check.
+    """
+    required = [config for config in (NREL, OPENEI, EIA) if api_key_for(config) is None]
+    optional = [config for config in (AHJ,) if api_key_for(config) is None]
+    if not required and not optional:
+        return None
+    parts = []
+    if required:
+        keys = ", ".join(f"{c.api_key_env} (get one: {c.signup_url})" for c in required)
+        parts.append(f"missing keys: {keys}")
+    if optional:
+        keys = ", ".join(f"{c.api_key_env} ({c.signup_url})" for c in optional)
+        parts.append(f"optional: {keys}")
+    return (
+        "solar-data-mcp: "
+        + "; ".join(parts)
+        + ". Tools needing a missing key return setup instructions; run "
+        "`solar-data-mcp doctor` to verify your setup."
+    )
+
+
+def main(argv: list[str] | None = None) -> None:
+    configure_debug_logging()
+    args = sys.argv[1:] if argv is None else argv
+    if args == ["doctor"]:
+        raise SystemExit(core_cli_main(["doctor"]))
+    if args:
+        print("usage: solar-data-mcp [doctor]", file=sys.stderr)
+        raise SystemExit(2)
+    note = missing_key_note()
+    if note is not None:
+        print(note, file=sys.stderr)  # stderr: stdout belongs to the stdio transport
+    create_server().run()
+
+
+if __name__ == "__main__":
+    main()

solar_data_mcp-0.1.0/src/solar_data_mcp/skills/__init__.py

@@ -0,0 +1,107 @@
+"""Agent skills: procedural instructions served as MCP resources.
+
+Tools are capability; skills are procedure. Each *.md file in this package
+teaches an agent how to orchestrate the tools for one shape of question —
+tool ordering, sync prerequisites, defaults to override, reporting rules.
+skill://solar/index is the routing table: the server instructions point hosts
+at it, and hosts with a native skill concept can lift the frontmatter
+descriptions directly.
+
+Frontmatter is deliberately minimal (name, description, tools as one
+comma-separated line) so it parses without a YAML dependency while remaining
+valid YAML for hosts that repackage skills as plugins.
+"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from importlib import resources
+
+from mcp.server.fastmcp import FastMCP
+
+INDEX_URI = "skill://solar/index"
+
+_INDEX_PREAMBLE = """\
+Solar skill routing table.
+
+Skills are procedures: each teaches the tool ordering, sync prerequisites,
+defaults to override, and reporting rules for one shape of question. Route by
+what is being asked, never by who is asking — a homeowner, an installer, and
+an analyst asking the same question get the same skill.
+
+How to route:
+1. Match the question against the descriptions below and read that
+   skill://solar/<name> resource before calling tools.
+2. Always apply skill://solar/solar-data-conventions — the contract for
+   reading every tool's result envelope (assumptions, warnings, provenance).
+3. If a tool fails with "snapshot not synced", switch to
+   skill://solar/solar-data-sync, run the named sync, then resume.
+
+Skills:
+"""
+
+
+@dataclass(frozen=True)
+class Skill:
+    """One parsed *.md skill file; text is the full raw file, served as-is."""
+
+    name: str
+    description: str
+    tools: tuple[str, ...]
+    text: str
+
+
+def parse_skill(stem: str, text: str) -> Skill:
+    """Parse frontmatter; strict, so a malformed skill fails at load, not at read."""
+    lines = text.splitlines()
+    if not lines or lines[0] != "---":
+        raise ValueError(f"skill {stem}: file must start with '---' frontmatter")
+    try:
+        end = lines.index("---", 1)
+    except ValueError:
+        raise ValueError(f"skill {stem}: unterminated frontmatter") from None
+    fields: dict[str, str] = {}
+    for line in lines[1:end]:
+        key, sep, value = line.partition(":")
+        if not sep:
+            raise ValueError(f"skill {stem}: bad frontmatter line {line!r}")
+        fields[key.strip()] = value.strip()
+    name = fields.get("name", "")
+    description = fields.get("description", "")
+    if not name or not description:
+        raise ValueError(f"skill {stem}: frontmatter must set name and description")
+    if name != stem:
+        raise ValueError(f"skill {stem}: frontmatter name {name!r} does not match filename")
+    tools = tuple(tool.strip() for tool in fields.get("tools", "").split(",") if tool.strip())
+    return Skill(name=name, description=description, tools=tools, text=text)
+
+
+def load_skills() -> list[Skill]:
+    skills_dir = resources.files(__name__)
+    return [
+        parse_skill(entry.name.removesuffix(".md"), entry.read_text(encoding="utf-8"))
+        for entry in sorted(skills_dir.iterdir(), key=lambda entry: entry.name)
+        if entry.name.endswith(".md")
+    ]
+
+
+def build_index(skills: Sequence[Skill]) -> str:
+    entries = "\n".join(f"- skill://solar/{s.name} — {s.description}" for s in skills)
+    return _INDEX_PREAMBLE + entries + "\n"
+
+
+def register(mcp: FastMCP) -> None:
+    skills = load_skills()
+
+    @mcp.resource(INDEX_URI, title="Solar skills: routing table")
+    def index() -> str:
+        return build_index(skills)
+
+    for skill in skills:
+        _register_one(mcp, skill)
+
+
+def _register_one(mcp: FastMCP, skill: Skill) -> None:
+    # Separate function so the closure binds this skill, not the loop variable.
+    @mcp.resource(f"skill://solar/{skill.name}", title=f"Skill: {skill.name}")
+    def read_skill() -> str:
+        return skill.text

solar_data_mcp-0.1.0/src/solar_data_mcp/skills/solar-data-conventions.md

@@ -0,0 +1,67 @@
+---
+name: solar-data-conventions
+description: How to read and report every tool's result envelope — assumptions, warnings, provenance, error recovery, API keys, and quota. Use alongside every other solar skill; it is the contract the whole server follows.
+tools:
+---
+
+# Data conventions
+
+Every tool returns the same envelope: `data` + `units` + `source` +
+`assumptions` + `warnings`. These rules apply to every workflow.
+
+## Reporting rules
+
+- When a number matters, surface its `assumptions` and `warnings` — every
+  default the tools injected on the caller's behalf is listed there by
+  design. A parameter you passed explicitly never appears.
+- Cite `source.name` and `retrieved_at`. Units for any field are in `units`,
+  keyed by field path (`ranked[].ac_annual_kwh`).
+- Composites (`estimate_roi`, `market_snapshot`,
+  `compare_forecast_to_model`) carry a placeholder top-level source; the real
+  per-component provenance is in `data.audit_trail` — cite from there.
+- A freshness warning means a stale cache entry was served because quota ran
+  out: the number is real but old. Say so.
+- License and attribution text for any dataset is served at
+  `source://<name>/license`; coverage limits at `source://<name>/coverage`.
+
+## Error recovery
+
+- **Input errors** name the exact field and allowed range — correct the
+  parameter and retry once.
+- **Quota errors**: back off; the client never retries a 429, so hammering
+  only burns the next hour's budget. Cached repeats of earlier calls are
+  free.
+- **Source-unavailable errors** name the fix: an unset env var (with its
+  signup URL) or a missing `sync_*` prerequisite (see solar-data-sync).
+
+## Setup
+
+- Keys (all free): NREL_API_KEY (production, ROI, forecast-vs-model),
+  OPENEI_API_KEY (tariffs), EIA_API_KEY (electricity prices);
+  AHJ_REGISTRY_TOKEN is optional (email-issued). Market and forecast tools
+  need no key. Verify with `solar-data-mcp doctor`.
+- DEMO_KEY works for NREL at ~10 requests/hour — expect real 429s on sweeps,
+  and note the one NREL quota is shared across production, ROI, and
+  forecast-vs-model tools.
+- The HTTP cache and bulk store live under `~/.cache/solar-data-mcp`
+  (relocatable via SOLAR_DATA_MCP_CACHE_DIR).
+
+## Formatted data (exports)
+
+When the user asks for spreadsheet/CSV-shaped output:
+
+- One column per relevant `data` field, with the unit from the envelope's
+  `units` map in the header: `median_price_per_watt (USD/W)`.
+- One leading comment row citing provenance:
+  `# source: <source.name> · retrieved <retrieved_at> · vintage <vintage>`.
+- Aggregates only — never promise row-level Tracking the Sun records; the
+  tools do not return them.
+- List-shaped data (`ranked[]`, `projects[]`, `trend[]`) becomes one row per
+  element; scalar summary fields go in a separate single-row table rather
+  than being repeated down a column.
+
+## What not to promise
+
+TOU tariff simulation, REopt-style optimization, PVDAQ measured production,
+and non-US coverage are out of scope. Decline gracefully and name the closest
+tool family instead of improvising.