stac-eo-mcp 0.1.0__py3-none-any.whl

stac_eo_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for searching STAC catalogs and analysing Earth observation data."""
+
+__version__ = "0.1.0"

stac_eo_mcp/__main__.py

@@ -0,0 +1,4 @@
+from stac_eo_mcp.server import main
+
+if __name__ == "__main__":
+    main()

stac_eo_mcp/analysis.py

@@ -0,0 +1,241 @@
+"""Tool workflows: scene -> window read -> reflectance -> index -> stats/files."""
+
+import logging
+from collections import defaultdict
+from concurrent.futures import ThreadPoolExecutor
+
+import numpy as np
+import pystac
+import xarray as xr
+from shapely.geometry import box, shape
+
+from stac_eo_mcp import catalog, raster
+from stac_eo_mcp.config import CatalogName, Settings
+from stac_eo_mcp.errors import InvalidInputError, StacMcpError
+from stac_eo_mcp.indices import INDEX_DEFINITIONS, compute_index, compute_stats, to_reflectance
+from stac_eo_mcp.models import (
+    BBox,
+    DateRange,
+    IndexResult,
+    IndexStats,
+    SaveFormat,
+    SkippedScene,
+    SpectralIndex,
+    TimeSeriesPoint,
+    TimeSeriesResult,
+    TimeSeriesSummary,
+)
+
+log = logging.getLogger(__name__)
+
+RESOLUTION_M = 10.0
+LOW_VALID_PCT = 20.0
+# Metadata-only search pool for time series; pixels are read for max_scenes at most.
+SEARCH_POOL = 500
+READ_WORKERS = 4
+
+
+# --- Single scene ---------------------------------------------------------
+
+
+def check_overlap(item: pystac.Item, bbox: BBox) -> None:
+    if item.geometry and not shape(item.geometry).intersects(box(*bbox.as_list())):
+        raise InvalidInputError(
+            f"The bbox does not overlap scene {item.id}.",
+            hint="Use search_scenes with this bbox to find scenes that cover it.",
+        )
+
+
+def index_from_dataset(
+    ds: xr.Dataset, item: pystac.Item, asset_keys: dict[str, str], index: SpectralIndex
+) -> xr.DataArray:
+    """Turn a raw-DN window into a masked index DataArray on the same grid."""
+    definition = INDEX_DEFINITIONS[index]
+    bands = {}
+    for name in definition.bands:
+        scaling = catalog.band_scaling(item, asset_keys[name])
+        bands[name] = to_reflectance(ds[name].values, scaling.offset_dn, scaling.scale)
+    scl = ds["scl"].values if "scl" in ds else None
+    values = compute_index(index, bands, scl=scl)
+    template = ds[definition.a]
+    return xr.DataArray(values, coords=template.coords, dims=template.dims, name=index.value)
+
+
+def index_on_item(
+    catalog_name: CatalogName, item: pystac.Item, index: SpectralIndex, bbox: BBox
+) -> tuple[xr.DataArray, IndexStats]:
+    """Read the bbox window of one scene and compute the masked index."""
+    check_overlap(item, bbox)
+    keys = catalog.band_asset_keys(catalog_name, item, [*INDEX_DEFINITIONS[index].bands, "scl"])
+    sign = catalog.get_config(catalog_name).sign
+    ds = raster.load_window(item, keys, bbox, resolution=RESOLUTION_M, sign=sign)
+    index_da = index_from_dataset(ds, item, keys, index)
+    return index_da, compute_stats(index_da.values)
+
+
+def compute_index_for_item(
+    settings: Settings,
+    catalog_name: CatalogName,
+    item_id: str,
+    index: SpectralIndex,
+    bbox: BBox,
+    save: SaveFormat = SaveFormat.NONE,
+) -> IndexResult:
+    bbox.check_area(settings.max_area_km2)
+    cfg = catalog.get_config(catalog_name)
+    item = catalog.get_item(catalog_name, cfg.s2_collection, item_id)
+    index_da, stats = index_on_item(catalog_name, item, index, bbox)
+
+    outputs: dict[str, str] = {}
+    if save is not SaveFormat.NONE and stats.valid_pixels:
+        stem = settings.output_dir / raster.output_stem(item.id, index, bbox)
+        if save in (SaveFormat.PNG, SaveFormat.BOTH):
+            outputs["png"] = str(raster.save_png(index_da.values, index, stem.with_suffix(".png")))
+        if save in (SaveFormat.GEOTIFF, SaveFormat.BOTH):
+            outputs["geotiff"] = str(raster.save_geotiff(index_da, stem.with_suffix(".tif")))
+
+    return IndexResult(
+        item_id=item.id,
+        index=index,
+        datetime=catalog.summarize_item(item, catalog_name).datetime,
+        bbox=bbox.as_list(),
+        stats=stats,
+        resolution_m=RESOLUTION_M,
+        outputs=outputs,
+        note=_quality_note(stats.valid_pixel_pct),
+    )
+
+
+def _quality_note(valid_pct: float) -> str | None:
+    if valid_pct == 0:
+        return (
+            "All pixels are masked (cloud, shadow or no data) over this bbox, so no statistics "
+            "and no files. Try another scene from search_scenes with a lower max_cloud_cover."
+        )
+    if valid_pct < LOW_VALID_PCT:
+        return (
+            f"Only {valid_pct:.1f}% of pixels are clear; the statistics may not be "
+            "representative. Consider another scene."
+        )
+    return None
+
+
+# --- Time series ----------------------------------------------------------
+
+
+def _day(item: pystac.Item) -> str:
+    return item.datetime.date().isoformat() if item.datetime else "unknown"
+
+
+def one_per_day(items: list[pystac.Item], bbox: BBox) -> list[pystac.Item]:
+    """Keep one scene per acquisition day, oldest first.
+
+    Areas on a tile overlap are covered by two items per pass. Pick the one
+    whose footprint covers most of the bbox, then the lower cloud cover.
+    """
+    target = box(*bbox.as_list())
+    by_day: dict[str, list[pystac.Item]] = defaultdict(list)
+    for item in items:
+        by_day[_day(item)].append(item)
+
+    def rank(item: pystac.Item) -> tuple[float, float]:
+        covered = shape(item.geometry).intersection(target).area if item.geometry else 0.0
+        cloud = item.properties.get("eo:cloud_cover", 100.0)
+        return (-round(covered / target.area, 3), cloud)
+
+    return [min(group, key=rank) for _, group in sorted(by_day.items())]
+
+
+def sample_evenly(items: list[pystac.Item], n: int) -> list[pystac.Item]:
+    """Pick n items spread across the list, always keeping first and last."""
+    if len(items) <= n:
+        return items
+    idx = np.unique(np.linspace(0, len(items) - 1, n).round().astype(int))
+    return [items[i] for i in idx]
+
+
+def time_series(
+    settings: Settings,
+    catalog_name: CatalogName,
+    index: SpectralIndex,
+    bbox: BBox,
+    date_range: DateRange,
+    max_cloud_cover: float | None = None,
+) -> TimeSeriesResult:
+    bbox.check_area(settings.max_area_km2)
+    cfg = catalog.get_config(catalog_name)
+    found = catalog.search_items(
+        catalog_name, cfg.s2_collection, bbox, date_range, max_cloud_cover, limit=SEARCH_POOL
+    )
+    daily = one_per_day(found, bbox)
+    selected = sample_evenly(daily, settings.max_scenes)
+    log.info("time_series: %d scenes, %d dates, reading %d", len(found), len(daily), len(selected))
+
+    def analyse(item: pystac.Item) -> TimeSeriesPoint | SkippedScene:
+        try:
+            _, stats = index_on_item(catalog_name, item, index, bbox)
+        except StacMcpError as exc:
+            return SkippedScene(date=_day(item), item_id=item.id, reason=exc.message)
+        except Exception as exc:  # one bad scene must not sink the series
+            log.warning("time_series: %s failed: %s", item.id, exc)
+            return SkippedScene(date=_day(item), item_id=item.id, reason=f"read error: {exc}")
+        if stats.mean is None or stats.valid_pixel_pct < LOW_VALID_PCT:
+            return SkippedScene(
+                date=_day(item),
+                item_id=item.id,
+                reason=f"only {stats.valid_pixel_pct:.1f}% clear pixels over the bbox",
+            )
+        return TimeSeriesPoint(
+            date=_day(item),
+            item_id=item.id,
+            mean=stats.mean,
+            std=stats.std,
+            valid_pixel_pct=stats.valid_pixel_pct,
+        )
+
+    with ThreadPoolExecutor(max_workers=READ_WORKERS) as pool:
+        results = list(pool.map(analyse, selected))
+
+    points = [r for r in results if isinstance(r, TimeSeriesPoint)]
+    skipped = [r for r in results if isinstance(r, SkippedScene)]
+    return TimeSeriesResult(
+        index=index,
+        bbox=bbox.as_list(),
+        date_range=f"{date_range.start}/{date_range.end}",
+        scenes_found=len(found),
+        dates_analysed=len(selected),
+        points=points,
+        skipped=skipped,
+        summary=_summarize(points),
+        note=_series_note(len(daily), len(selected), points, settings.max_scenes),
+    )
+
+
+def _summarize(points: list[TimeSeriesPoint]) -> TimeSeriesSummary | None:
+    if not points:
+        return None
+    return TimeSeriesSummary(
+        mean_of_means=round(float(np.mean([p.mean for p in points])), 4),
+        min=min(points, key=lambda p: p.mean),
+        max=max(points, key=lambda p: p.mean),
+        change=round(points[-1].mean - points[0].mean, 4),
+    )
+
+
+def _series_note(
+    n_dates: int, n_selected: int, points: list[TimeSeriesPoint], max_scenes: int
+) -> str | None:
+    notes = []
+    if n_selected < n_dates:
+        notes.append(
+            f"{n_dates} acquisition dates matched; {n_selected} were sampled evenly "
+            f"(limit {max_scenes}). Narrow the date range for every date."
+        )
+    if not points:
+        notes.append(
+            "No date had enough clear pixels. Raise max_cloud_cover, widen the date range "
+            "or move the bbox."
+        )
+    elif len(points) < 3:
+        notes.append("Fewer than 3 usable dates: treat any trend with caution.")
+    return " ".join(notes) or None

stac_eo_mcp/catalog.py

@@ -0,0 +1,353 @@
+"""STAC catalog access: clients, search, item lookup and Sentinel-2 band mapping.
+
+Supported catalogs:
+- Microsoft Planetary Computer (assets are signed with planetary-computer)
+- Element84 Earth Search (public, no signing)
+"""
+
+import difflib
+import logging
+import warnings
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Any
+
+import planetary_computer
+import pystac
+from pystac_client import Client
+from pystac_client.exceptions import APIError
+from shapely.geometry import mapping, shape
+
+from stac_eo_mcp.config import CatalogName
+from stac_eo_mcp.errors import CatalogError, DataUnavailableError, InvalidInputError, NoScenesError
+from stac_eo_mcp.indices import S2_BASELINE_OFFSET_DN, S2_SCALE
+from stac_eo_mcp.models import (
+    AssetInfo,
+    BBox,
+    CollectionSummary,
+    DateRange,
+    SceneDetails,
+    SceneSummary,
+)
+
+log = logging.getLogger(__name__)
+
+# Earth Search items trigger a harmless pystac storage-extension migration warning.
+warnings.filterwarnings("ignore", message="Could not parse bucket/account from href")
+
+# Canonical band name -> asset key, per catalog.
+CANONICAL_BANDS = ("blue", "green", "red", "nir", "swir16", "swir22", "scl")
+
+
+@dataclass(frozen=True)
+class CatalogConfig:
+    name: CatalogName
+    url: str
+    title: str
+    s2_collection: str
+    band_assets: dict[str, str]
+    preview_asset: str
+    sign: bool = False
+
+
+CATALOGS: dict[CatalogName, CatalogConfig] = {
+    CatalogName.PLANETARY_COMPUTER: CatalogConfig(
+        name=CatalogName.PLANETARY_COMPUTER,
+        url="https://planetarycomputer.microsoft.com/api/stac/v1",
+        title="Microsoft Planetary Computer",
+        s2_collection="sentinel-2-l2a",
+        band_assets={
+            "blue": "B02",
+            "green": "B03",
+            "red": "B04",
+            "nir": "B08",
+            "swir16": "B11",
+            "swir22": "B12",
+            "scl": "SCL",
+        },
+        preview_asset="rendered_preview",
+        sign=True,
+    ),
+    CatalogName.EARTH_SEARCH: CatalogConfig(
+        name=CatalogName.EARTH_SEARCH,
+        url="https://earth-search.aws.element84.com/v1",
+        title="Element84 Earth Search",
+        s2_collection="sentinel-2-c1-l2a",
+        band_assets={b: b for b in CANONICAL_BANDS},
+        preview_asset="thumbnail",
+    ),
+}
+
+# Short names an agent is likely to use for Sentinel-2 L2A.
+S2_ALIASES = {"sentinel-2", "sentinel2", "s2", "sentinel-2-l2a", "s2-l2a", "sentinel-2-c1-l2a"}
+
+# Item properties worth showing an LLM (the rest is noise).
+DETAIL_PROPERTIES = (
+    "datetime",
+    "platform",
+    "constellation",
+    "eo:cloud_cover",
+    "s2:mgrs_tile",
+    "mgrs:utm_zone",
+    "proj:code",
+    "proj:epsg",
+    "s2:processing_baseline",
+    "s2:nodata_pixel_percentage",
+    "s2:vegetation_percentage",
+    "s2:water_percentage",
+    "s2:snow_ice_percentage",
+    "s2:high_proba_clouds_percentage",
+    "s2:cloud_shadow_percentage",
+    "sat:relative_orbit",
+    "sat:orbit_state",
+    "view:sun_elevation",
+)
+
+
+def get_config(catalog: CatalogName | str) -> CatalogConfig:
+    try:
+        return CATALOGS[CatalogName(catalog)]
+    except ValueError:
+        options = ", ".join(c.value for c in CatalogName)
+        raise InvalidInputError(
+            f"Unknown catalog '{catalog}'.", hint=f"Use one of: {options}."
+        ) from None
+
+
+@lru_cache
+def get_client(catalog: CatalogName, signed: bool = True) -> Client:
+    """STAC client; `signed` signs Planetary Computer asset URLs in results.
+
+    Listing collections must use signed=False: signing every collection costs one
+    token request each, which takes ~60 s on Planetary Computer instead of <1 s.
+    """
+    cfg = get_config(catalog)
+    modifier = planetary_computer.sign_inplace if cfg.sign and signed else None
+    try:
+        log.info("Opening STAC catalog %s (signed=%s)", cfg.url, modifier is not None)
+        return Client.open(cfg.url, modifier=modifier)
+    except Exception as exc:
+        raise CatalogError(
+            f"Could not reach {cfg.title} ({cfg.url}): {exc}",
+            hint="Check the network connection, or try the other catalog.",
+        ) from exc
+
+
+# --- Collections ----------------------------------------------------------
+
+
+@lru_cache
+def _collections(catalog: CatalogName) -> tuple[CollectionSummary, ...]:
+    client = get_client(catalog, signed=False)
+    try:
+        cols = list(client.get_collections())
+    except APIError as exc:
+        raise CatalogError(f"Listing collections failed: {exc}") from exc
+    return tuple(
+        CollectionSummary(id=c.id, title=c.title, description=_first_sentence(c.description))
+        for c in sorted(cols, key=lambda c: c.id)
+    )
+
+
+def list_collections(catalog: CatalogName) -> list[CollectionSummary]:
+    return list(_collections(catalog))
+
+
+def resolve_collection(catalog: CatalogName, collection: str) -> str:
+    """Map S2 aliases to the catalog's collection and check that it exists."""
+    cfg = get_config(catalog)
+    collection = collection.strip()
+    if collection.lower() in S2_ALIASES:
+        return cfg.s2_collection
+    ids = [c.id for c in _collections(catalog)]
+    if collection in ids:
+        return collection
+    close = difflib.get_close_matches(collection, ids, n=3, cutoff=0.5)
+    hint = f"Did you mean: {', '.join(close)}?" if close else "Call list_collections to see ids."
+    raise InvalidInputError(f"Collection '{collection}' is not in {cfg.title}.", hint=hint)
+
+
+# --- Search and lookup ----------------------------------------------------
+
+
+def search_items(
+    catalog: CatalogName,
+    collection: str,
+    bbox: BBox,
+    date_range: DateRange,
+    max_cloud_cover: float | None = None,
+    limit: int = 10,
+) -> list[pystac.Item]:
+    """Search scenes, newest first. Raises NoScenesError if none match."""
+    collection = resolve_collection(catalog, collection)
+    params: dict[str, Any] = {
+        "collections": [collection],
+        "bbox": bbox.as_list(),
+        "datetime": date_range.to_stac(),
+        "max_items": limit,
+        "sortby": [{"field": "properties.datetime", "direction": "desc"}],
+    }
+    if max_cloud_cover is not None:
+        params["query"] = {"eo:cloud_cover": {"lte": max_cloud_cover}}
+    try:
+        items = list(get_client(catalog).search(**params).items())
+    except APIError as exc:
+        raise CatalogError(f"Search failed on {get_config(catalog).title}: {exc}") from exc
+    if not items:
+        raise _no_scenes(collection, date_range, max_cloud_cover)
+    items.sort(key=lambda i: i.datetime or 0, reverse=True)
+    return items
+
+
+def _no_scenes(collection: str, dr: DateRange, max_cc: float | None) -> NoScenesError:
+    if max_cc is not None:
+        msg = (
+            f"No {collection} scenes with cloud cover <= {max_cc:g}% "
+            f"between {dr.start} and {dr.end} for this bbox."
+        )
+        hint = "Raise max_cloud_cover or widen the date range."
+    else:
+        msg = f"No {collection} scenes between {dr.start} and {dr.end} for this bbox."
+        hint = "Widen the date range, or check the collection covers this area and period."
+    return NoScenesError(msg, hint=hint)
+
+
+def get_item(catalog: CatalogName, collection: str, item_id: str) -> pystac.Item:
+    collection = resolve_collection(catalog, collection)
+    try:
+        items = list(
+            get_client(catalog).search(collections=[collection], ids=[item_id], max_items=1).items()
+        )
+    except APIError as exc:
+        raise CatalogError(f"Looking up '{item_id}' failed: {exc}") from exc
+    if not items:
+        raise NoScenesError(
+            f"Scene '{item_id}' was not found in {collection} on {get_config(catalog).title}.",
+            hint="Use an id returned by search_scenes, with the same catalog.",
+        )
+    return items[0]
+
+
+# --- Summaries ------------------------------------------------------------
+
+
+def summarize_item(item: pystac.Item, catalog: CatalogName) -> SceneSummary:
+    cfg = get_config(catalog)
+    preview = item.assets.get(cfg.preview_asset)
+    return SceneSummary(
+        id=item.id,
+        datetime=_iso(item),
+        cloud_cover=_round(item.properties.get("eo:cloud_cover")),
+        bbox=[round(v, 5) for v in item.bbox] if item.bbox else None,
+        footprint=simplify_geometry(item.geometry),
+        preview_url=preview.href if preview else None,
+    )
+
+
+def describe_item(item: pystac.Item) -> SceneDetails:
+    props = {k: item.properties[k] for k in DETAIL_PROPERTIES if item.properties.get(k) is not None}
+    props.pop("datetime", None)
+    assets = [
+        AssetInfo(
+            key=key,
+            title=a.title,
+            media_type=a.media_type,
+            roles=a.roles or [],
+            gsd=a.extra_fields.get("gsd"),
+        )
+        for key, a in sorted(item.assets.items())
+    ]
+    return SceneDetails(
+        id=item.id,
+        collection=item.collection_id or "",
+        datetime=_iso(item),
+        bbox=[round(v, 5) for v in item.bbox] if item.bbox else None,
+        properties=props,
+        assets=assets,
+    )
+
+
+def simplify_geometry(geom: dict[str, Any] | None, tolerance: float = 0.001) -> dict | None:
+    """Simplify (~100 m) and round a GeoJSON geometry to keep responses small."""
+    if not geom:
+        return None
+    simple = shape(geom).simplify(tolerance, preserve_topology=True)
+    return _round_coords(mapping(simple))
+
+
+def _round_coords(obj: Any, nd: int = 4) -> Any:
+    if isinstance(obj, float):
+        return round(obj, nd)
+    if isinstance(obj, list | tuple):
+        return [_round_coords(o, nd) for o in obj]
+    if isinstance(obj, dict):
+        return {k: _round_coords(v, nd) for k, v in obj.items()}
+    return obj
+
+
+# --- Sentinel-2 bands -----------------------------------------------------
+
+
+@dataclass(frozen=True)
+class BandScaling:
+    scale: float
+    offset_dn: float  # added to DN before scaling
+
+
+def band_asset_keys(catalog: CatalogName, item: pystac.Item, bands: list[str]) -> dict[str, str]:
+    """Canonical band -> asset key, checking that the item has each asset."""
+    cfg = get_config(catalog)
+    keys = {b: cfg.band_assets[b] for b in bands}
+    missing = [f"{b} ({k})" for b, k in keys.items() if k not in item.assets]
+    if missing:
+        raise DataUnavailableError(
+            f"Scene {item.id} lacks assets {missing}.",
+            hint=f"Only Sentinel-2 L2A scenes ({cfg.s2_collection}) are supported for indices.",
+        )
+    return keys
+
+
+def band_scaling(item: pystac.Item, asset_key: str) -> BandScaling:
+    """DN -> reflectance parameters for a Sentinel-2 L2A band.
+
+    Prefer raster:bands scale/offset from the asset (Earth Search). Otherwise
+    fall back to the processing baseline (Planetary Computer): baseline 04.00
+    and later store DN with a +1000 offset.
+    """
+    raster_bands = item.assets[asset_key].extra_fields.get("raster:bands") or []
+    if raster_bands and "scale" in raster_bands[0]:
+        scale = float(raster_bands[0]["scale"])
+        offset = float(raster_bands[0].get("offset", 0.0))
+        return BandScaling(scale=scale, offset_dn=offset / scale)
+    baseline = item.properties.get("s2:processing_baseline")
+    offset_dn = S2_BASELINE_OFFSET_DN if _baseline_ge(baseline, 4.0) else 0.0
+    return BandScaling(scale=S2_SCALE, offset_dn=offset_dn)
+
+
+def _baseline_ge(baseline: Any, threshold: float) -> bool:
+    try:
+        return float(baseline) >= threshold
+    except (TypeError, ValueError):
+        # Unknown baseline: assume modern data, which is the common case since 2022.
+        return True
+
+
+# --- Helpers --------------------------------------------------------------
+
+
+def _iso(item: pystac.Item) -> str | None:
+    return item.datetime.isoformat().replace("+00:00", "Z") if item.datetime else None
+
+
+def _round(v: Any, nd: int = 2) -> float | None:
+    return round(float(v), nd) if v is not None else None
+
+
+def _first_sentence(text: str | None, max_len: int = 200) -> str | None:
+    if not text:
+        return None
+    text = " ".join(text.split())
+    cut = text.find(". ")
+    if 0 < cut < max_len:
+        return text[: cut + 1]
+    return text if len(text) <= max_len else text[: max_len - 1].rstrip() + "…"

stac_eo_mcp/config.py

@@ -0,0 +1,41 @@
+"""Settings read from environment variables (prefix STAC_EO_MCP_)."""
+
+from enum import StrEnum
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class CatalogName(StrEnum):
+    PLANETARY_COMPUTER = "planetary-computer"
+    EARTH_SEARCH = "earth-search"
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="STAC_EO_MCP_", extra="ignore")
+
+    catalog: CatalogName = Field(
+        default=CatalogName.PLANETARY_COMPUTER,
+        description="Catalog used when a tool call does not name one.",
+    )
+    output_dir: Path = Field(
+        default=Path.home() / "stac-eo-mcp-output",
+        description="Folder where PNG/GeoTIFF outputs are written.",
+    )
+    max_area_km2: float = Field(
+        default=100.0, gt=0, description="Largest bbox accepted for raster reads."
+    )
+    max_scenes: int = Field(
+        default=24, ge=1, le=200, description="Most scenes read by time_series."
+    )
+    max_search_limit: int = Field(
+        default=50, ge=1, le=500, description="Most scenes returned by search_scenes."
+    )
+    log_level: str = Field(default="INFO", description="Python logging level (to stderr).")
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

stac_eo_mcp/errors.py

@@ -0,0 +1,39 @@
+"""Errors meant to be read by an AI agent.
+
+Every error carries a short message (what went wrong) and an optional hint
+(what to try next), so the agent can recover without guessing.
+"""
+
+
+class StacMcpError(Exception):
+    """Base error. str() gives 'message Hint: hint'."""
+
+    def __init__(self, message: str, hint: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.hint = hint
+
+    def __str__(self) -> str:
+        if self.hint:
+            return f"{self.message} Hint: {self.hint}"
+        return self.message
+
+
+class InvalidInputError(StacMcpError):
+    """A tool argument is malformed or out of range."""
+
+
+class AreaTooLargeError(InvalidInputError):
+    """The bbox exceeds the configured maximum area."""
+
+
+class NoScenesError(StacMcpError):
+    """A search matched no scenes."""
+
+
+class CatalogError(StacMcpError):
+    """The STAC catalog failed or returned something unusable."""
+
+
+class DataUnavailableError(StacMcpError):
+    """A scene exists but lacks the assets or valid pixels needed."""