planetary-computer-mcp 1.1.0__py3-none-any.whl

planetary_computer_mcp/__init__.py

@@ -0,0 +1,11 @@
+"""
+Planetary Computer MCP Server.
+
+A Model Context Protocol (MCP) server for accessing Microsoft's
+Planetary Computer geospatial data catalog.
+"""
+
+from planetary_computer_mcp import core, server, tools
+
+__version__ = "0.1.0"
+__all__ = ["core", "server", "tools"]

planetary_computer_mcp/core/__init__.py

@@ -0,0 +1,41 @@
+"""
+Core utilities for Planetary Computer MCP server.
+"""
+
+from planetary_computer_mcp.core.collections import (
+    COLLECTION_KEYWORDS,
+    COLLECTION_TYPES,
+    detect_collection_from_query,
+    get_collection_type,
+)
+from planetary_computer_mcp.core.geocoding import place_to_bbox, validate_bbox
+from planetary_computer_mcp.core.stac_client import PlanetaryComputerSTAC, stac_client
+from planetary_computer_mcp.core.zarr_utils import (
+    COORD_MAPPINGS,
+    DEFAULT_VARIABLES,
+    get_available_variables,
+    get_zarr_metadata,
+    get_zarr_store_url,
+    load_and_compute_zarr,
+    load_zarr_data,
+    save_zarr_subset_as_netcdf,
+)
+
+__all__ = [
+    "COLLECTION_KEYWORDS",
+    "COLLECTION_TYPES",
+    "COORD_MAPPINGS",
+    "DEFAULT_VARIABLES",
+    "PlanetaryComputerSTAC",
+    "detect_collection_from_query",
+    "get_available_variables",
+    "get_collection_type",
+    "get_zarr_metadata",
+    "get_zarr_store_url",
+    "load_and_compute_zarr",
+    "load_zarr_data",
+    "place_to_bbox",
+    "save_zarr_subset_as_netcdf",
+    "stac_client",
+    "validate_bbox",
+]

planetary_computer_mcp/core/collections.py

@@ -0,0 +1,112 @@
+"""
+Collection mapping and metadata for dataset auto-detection.
+"""
+
+# Mapping of query keywords to collection IDs
+COLLECTION_KEYWORDS: dict[str, str] = {
+    # Optical imagery
+    "sentinel-1": "sentinel-1-rtc",
+    "sentinel": "sentinel-2-l2a",
+    "sentinel-2": "sentinel-2-l2a",
+    "satellite": "sentinel-2-l2a",  # Default optical
+    "naip": "naip",
+    "aerial": "naip",
+    "landsat": "landsat-c2-l2",
+    # DEMs
+    "dem": "cop-dem-glo-30",
+    "elevation": "cop-dem-glo-30",
+    "terrain": "cop-dem-glo-30",
+    "copernicus": "cop-dem-glo-30",
+    "alos": "alos-dem",
+    # Land cover
+    "land cover": "esa-worldcover",
+    "landcover": "esa-worldcover",
+    "lulc": "io-lulc-annual-v02",
+    "land use": "io-lulc-annual-v02",
+    "worldcover": "esa-worldcover",
+    # Vectors
+    "building": "ms-buildings",
+    "buildings": "ms-buildings",
+    "footprint": "ms-buildings",
+    # SAR
+    "sar": "sentinel-1-rtc",
+    "radar": "sentinel-1-rtc",
+    # Climate / Weather (Zarr-based)
+    "gridmet": "gridmet",
+    "terraclimate": "terraclimate",
+    "daymet": "daymet-daily-na",
+    "climate": "gridmet",  # Default to GridMET (CONUS, 4km, 1979-2020)
+    "weather": "gridmet",
+    "temperature": "gridmet",
+    "precipitation": "gridmet",
+}
+
+
+def detect_collection_from_query(query: str) -> str | None:
+    """
+    Detect collection ID from natural language query.
+
+    Parameters
+    ----------
+    query : str
+        User query string
+
+    Returns
+    -------
+    str or None
+        Collection ID or None if not detected
+    """
+    query_lower = query.lower()
+
+    # Direct collection name matches
+    for keyword, collection in COLLECTION_KEYWORDS.items():
+        if keyword in query_lower:
+            return collection
+
+    # Fallback to Sentinel-2 for general imagery queries
+    if any(word in query_lower for word in ["imagery", "image", "satellite", "remote sensing"]):
+        return "sentinel-2-l2a"
+
+    return None
+
+
+# Collection metadata for tool routing
+COLLECTION_TYPES: dict[str, str] = {
+    # Raster (COG-based via STAC)
+    "sentinel-2-l2a": "raster",
+    "naip": "raster",
+    "landsat-c2-l2": "raster",
+    "cop-dem-glo-30": "raster",
+    "alos-dem": "raster",
+    "esa-worldcover": "raster",
+    "io-lulc-annual-v02": "raster",
+    "sentinel-1-rtc": "raster",
+    # Zarr-based climate/weather data
+    "gridmet": "zarr",
+    "terraclimate": "zarr",
+    "daymet-daily-na": "zarr",
+    "daymet-daily-hi": "zarr",
+    "daymet-daily-pr": "zarr",
+    "daymet-monthly-na": "zarr",
+    "daymet-annual-na": "zarr",
+    "era5-pds": "zarr",
+    # Vector (GeoParquet)
+    "ms-buildings": "vector",
+}
+
+
+def get_collection_type(collection_id: str) -> str:
+    """
+    Get the data type for a collection.
+
+    Parameters
+    ----------
+    collection_id : str
+        Collection ID
+
+    Returns
+    -------
+    str
+        "raster", "vector", or "zarr"
+    """
+    return COLLECTION_TYPES.get(collection_id, "raster")  # Default to raster

planetary_computer_mcp/core/geocoding.py

@@ -0,0 +1,79 @@
+"""
+Geocoding utilities for converting place names to bounding boxes.
+"""
+
+from geopy.extra.rate_limiter import RateLimiter
+from geopy.geocoders import Nominatim
+
+
+def place_to_bbox(place_name: str) -> list[float]:
+    """
+    Convert place name to [west, south, east, north] bbox.
+
+    Examples:
+        "San Antonio" → [-98.79, 29.22, -98.28, 29.76]
+        "New York City" → [-74.26, 40.50, -73.70, 40.92]
+
+    Parameters
+    ----------
+    place_name : str
+        Human-readable place name
+
+    Returns
+    -------
+    list[float]
+        Bounding box as [west, south, east, north]
+
+    Raises
+    ------
+    ValueError
+        If geocoding fails
+    """
+    geolocator = Nominatim(user_agent="planetary-computer-mcp")
+    geocode = RateLimiter(geolocator.geocode, min_delay_seconds=1)
+    location = geocode(place_name, exactly_one=True)
+
+    if location and hasattr(location, "raw") and location.raw.get("boundingbox"):
+        bb = location.raw["boundingbox"]
+        # boundingbox is [south, north, west, east] as strings
+        return [float(bb[2]), float(bb[0]), float(bb[3]), float(bb[1])]
+
+    raise ValueError(f"Could not geocode: {place_name}")
+
+
+def validate_bbox(bbox: list[float]) -> list[float]:
+    """
+    Validate and normalize a bounding box.
+
+    Parameters
+    ----------
+    bbox : list[float]
+        [west, south, east, north]
+
+    Returns
+    -------
+    list[float]
+        Normalized bbox
+
+    Raises
+    ------
+    ValueError
+        If bbox is invalid
+    """
+    if len(bbox) != 4:
+        raise ValueError("Bbox must have 4 elements [west, south, east, north]")
+
+    west, south, east, north = bbox
+
+    if west >= east:
+        raise ValueError("West must be less than east")
+    if south >= north:
+        raise ValueError("South must be less than north")
+
+    # Basic bounds checking
+    if not (-180 <= west <= 180 and -180 <= east <= 180):
+        raise ValueError("Longitude must be between -180 and 180")
+    if not (-90 <= south <= 90 and -90 <= north <= 90):
+        raise ValueError("Latitude must be between -90 and 90")
+
+    return [west, south, east, north]

planetary_computer_mcp/core/raster_utils.py

@@ -0,0 +1,278 @@
+"""
+Raster utilities using odc-stac for COG loading and processing.
+"""
+
+import contextlib
+from typing import Any
+
+import rioxarray  # noqa: F401
+import xarray as xr
+from odc.stac import load
+from pystac import Item
+
+
+def load_raster_from_stac(
+    items: list[Item],
+    bbox: list[float] | None = None,
+    bands: list[str] | None = None,
+    resolution: float | None = None,
+    crs: str = "EPSG:4326",
+) -> xr.Dataset:
+    """
+    Load raster data from STAC items using odc-stac.
+
+    Parameters
+    ----------
+    items : list[Item]
+        Signed STAC items
+    bbox : list[float] or None, optional
+        Bounding box [west, south, east, north]
+    bands : list[str] or None, optional
+        Specific bands to load (None for all)
+    resolution : float or None, optional
+        Output resolution in CRS units
+    crs : str, optional
+        Output CRS (default EPSG:4326)
+
+    Returns
+    -------
+    xr.Dataset
+        Xarray Dataset with raster data
+    """
+    load_kwargs: dict[str, Any] = {
+        "crs": crs,
+    }
+
+    if bands:
+        load_kwargs["bands"] = bands
+
+    # Resolution must be provided - caller should pass native resolution
+    if resolution:
+        load_kwargs["resolution"] = resolution
+    else:
+        raise ValueError("Resolution is required for odc-stac loading")
+
+    # Bbox must be passed to odc-stac load() for proper clipping
+    if bbox:
+        load_kwargs["bbox"] = bbox
+
+    # Load with odc-stac
+    return load(items, **load_kwargs)
+
+
+def load_multiband_asset(
+    items: list[Item],
+    asset_name: str,
+    bbox: list[float] | None = None,
+    resolution: float | None = None,
+    band_names: list[str] | None = None,
+) -> xr.Dataset:
+    """
+    Load a multi-band asset (like NAIP 'image') using rioxarray.
+
+    odc-stac doesn't handle multi-band single-asset collections well,
+    so we use rioxarray directly for these cases.
+
+    Parameters
+    ----------
+    items : list[Item]
+        Signed STAC items (uses first item only)
+    asset_name : str
+        Name of the asset to load (e.g., 'image')
+    bbox : list[float] or None, optional
+        Bounding box [west, south, east, north] in EPSG:4326
+    resolution : float or None, optional
+        Output resolution in degrees (ignored - uses native resolution)
+    band_names : list[str] or None, optional
+        Names for the bands (e.g., ['red', 'green', 'blue', 'nir'])
+
+    Returns
+    -------
+    xr.Dataset
+        Xarray Dataset with named bands
+    """
+    import rioxarray as rxr  # Local import for type checking
+    from rasterio.crs import CRS  # type: ignore[import-not-found]
+    from rasterio.warp import transform_bounds  # type: ignore[import-not-found]
+
+    if not items:
+        raise ValueError("No items provided")
+
+    item = items[0]  # Use first item
+    if asset_name not in item.assets:
+        raise ValueError(f"Asset '{asset_name}' not found in item")
+
+    href = item.assets[asset_name].href
+
+    # Load with rioxarray (supports COGs with windowed reads)
+    data = rxr.open_rasterio(href)
+    if not isinstance(data, xr.DataArray):
+        raise TypeError("Expected DataArray from rioxarray")
+
+    # Clip and reproject if bbox provided
+    if bbox:
+        native_crs = data.rio.crs
+
+        # Transform bbox from WGS84 to native CRS for clipping
+        if native_crs and str(native_crs) != "EPSG:4326":
+            west, south, east, north = bbox
+            native_bounds = transform_bounds(
+                CRS.from_epsg(4326),
+                native_crs,
+                west,
+                south,
+                east,
+                north,
+            )
+            # Clip in native CRS (preserves native resolution)
+            with contextlib.suppress(Exception):
+                data = data.rio.clip_box(*native_bounds)
+
+            # Reproject to WGS84 after clipping
+            data = data.rio.reproject("EPSG:4326")
+        else:
+            # Already in WGS84, just clip
+            with contextlib.suppress(Exception):
+                data = data.rio.clip_box(*bbox)
+
+    # Convert to Dataset with named bands
+    num_bands = data.shape[0] if len(data.shape) > 2 else 1
+    if band_names and len(band_names) <= num_bands:
+        # Create dataset with named bands
+        datasets = {}
+        for i, name in enumerate(band_names):
+            if i < num_bands:
+                band_data = data.isel(band=i) if len(data.shape) > 2 else data
+                datasets[name] = band_data.drop_vars("band", errors="ignore")
+        return xr.Dataset(datasets)
+    else:
+        # Return as single variable
+        return xr.Dataset({"data": data})
+
+
+def save_raster_as_geotiff(
+    data: xr.Dataset,
+    output_path: str,
+    nodata: float | None = None,
+) -> str:
+    """
+    Save raster data as GeoTIFF.
+
+    Parameters
+    ----------
+    data : xr.Dataset
+        Xarray Dataset
+    output_path : str
+        Output file path
+    nodata : float or None, optional
+        NoData value
+
+    Returns
+    -------
+    str
+        Path to saved file
+    """
+    # Handle temporal data - take the most recent if multiple time slices
+    if "time" in data.sizes and data.sizes["time"] > 1:
+        # Take the last (most recent) time slice
+        data = data.isel(time=-1)
+    elif "time" in data.sizes and data.sizes["time"] == 1:
+        # Remove singleton time dimension
+        data = data.isel(time=0)
+
+    # For multi-band data, save as multi-band GeoTIFF
+    # For single band, extract the DataArray
+    if isinstance(data, xr.Dataset) and len(data.data_vars) == 1:
+        data_array = data[next(iter(data.data_vars.keys()))]
+    elif isinstance(data, xr.Dataset):
+        # Multi-band - convert to DataArray with band dimension
+        data_array = data.to_array(dim="band")
+    else:
+        data_array = data
+
+    # Ensure the data has proper CRS and transform
+    if not hasattr(data_array, "rio") or data_array.rio.crs is None:
+        # Assume WGS84 if no CRS
+        data_array = data_array.rio.write_crs("EPSG:4326")
+
+    # Set nodata if provided
+    if nodata is not None:
+        data_array = data_array.rio.write_nodata(nodata)
+
+    # Save as GeoTIFF
+    data_array.rio.to_raster(output_path)
+
+    return output_path
+
+
+def get_raster_metadata(data: xr.Dataset) -> dict[str, Any]:
+    """
+    Extract metadata from raster Dataset.
+
+    Parameters
+    ----------
+    data : xr.Dataset
+        Xarray Dataset
+
+    Returns
+    -------
+    dict[str, Any]
+        Dictionary with metadata
+    """
+    # Use the first variable for metadata
+    if isinstance(data, xr.Dataset) and len(data.data_vars) > 0:
+        sample_var = next(iter(data.data_vars.keys()))
+        data_array = data[sample_var]
+    else:
+        data_array = data
+
+    return {
+        "crs": str(data_array.rio.crs)
+        if hasattr(data_array, "rio") and data_array.rio.crs
+        else None,
+        "bounds": data_array.rio.bounds() if hasattr(data_array, "rio") else None,
+        "resolution": data_array.rio.resolution() if hasattr(data_array, "rio") else None,
+        "shape": data_array.shape,
+        "dtype": str(data_array.dtype),
+        "bands": list(data.data_vars)
+        if isinstance(data, xr.Dataset)
+        else [data_array.name]
+        if data_array.name
+        else ["data"],
+    }
+
+
+def crop_raster_to_bbox(
+    data: xr.Dataset,
+    bbox: list[float],
+) -> xr.Dataset:
+    """
+    Crop raster to bounding box.
+
+    Parameters
+    ----------
+    data : xr.Dataset
+        Xarray Dataset
+    bbox : list[float]
+        [west, south, east, north]
+
+    Returns
+    -------
+    xr.Dataset
+        Cropped Dataset
+    """
+    west, south, east, north = bbox
+
+    # Apply to all variables
+    cropped = {}
+    for var_name in data.data_vars:
+        try:
+            cropped[var_name] = data[var_name].rio.clip_box(
+                west, south, east, north, allow_one_dimensional_raster=True
+            )
+        except Exception as e:
+            # If clipping fails, return original
+            print(f"Warning: Clipping failed for {var_name}: {e}")
+            cropped[var_name] = data[var_name]
+
+    return xr.Dataset(cropped, attrs=data.attrs)

planetary_computer_mcp/core/stac_client.py

@@ -0,0 +1,91 @@
+"""
+STAC client wrapper for Planetary Computer.
+"""
+
+import planetary_computer as pc
+from pystac import Item
+from pystac_client import Client
+
+
+class PlanetaryComputerSTAC:
+    """Wrapper for Planetary Computer STAC operations."""
+
+    def __init__(self) -> None:
+        self.catalog_url = "https://planetarycomputer.microsoft.com/api/stac/v1"
+        self.client = Client.open(self.catalog_url)
+
+    def search_items(
+        self,
+        collections: list[str],
+        bbox: list[float] | None = None,
+        datetime: str | None = None,
+        max_cloud_cover: int | None = None,
+        limit: int | None = None,
+    ) -> list[Item]:
+        """
+        Search for STAC items.
+
+        Parameters
+        ----------
+        collections : list[str]
+            List of collection IDs
+        bbox : list[float] or None, optional
+            Bounding box [west, south, east, north]
+        datetime : str or None, optional
+            ISO8601 datetime range
+        max_cloud_cover : int or None, optional
+            Maximum cloud cover percentage
+        limit : int or None, optional
+            Maximum number of items to return
+
+        Returns
+        -------
+        list[Item]
+            List of signed STAC items
+        """
+        query_params = {}
+        if max_cloud_cover is not None:
+            query_params["eo:cloud_cover"] = {"lt": max_cloud_cover}
+
+        search = self.client.search(
+            collections=collections,
+            bbox=bbox,
+            datetime=datetime,
+            query=query_params if query_params else None,
+            limit=limit,
+        )
+
+        items = list(search.items())
+        return [pc.sign(item) for item in items]
+
+    def get_collection_info(self, collection_id: str) -> dict:
+        """
+        Get basic info about a collection.
+
+        Parameters
+        ----------
+        collection_id : str
+            Collection ID
+
+        Returns
+        -------
+        dict
+            Dictionary with collection metadata
+        """
+        collection = self.client.get_collection(collection_id)
+        return {
+            "id": collection.id,
+            "title": collection.title or "",
+            "description": collection.description or "",
+            "providers": [p.name for p in collection.providers] if collection.providers else [],
+            "extent": {
+                "temporal": collection.extent.temporal.intervals
+                if collection.extent.temporal
+                else None,
+                "spatial": collection.extent.spatial.bboxes if collection.extent.spatial else None,
+            },
+        }
+
+
+# Global instance
+stac_client = PlanetaryComputerSTAC()