planetary-computer-mcp: Instructions file for Codex

AGENTS.md

Agentic coding guide for planetary-computer-mcp - a Python MCP server for Microsoft Planetary Computer STAC catalog.

Quick Reference

# Install dependencies
uv sync

# Run all tests
uv run pytest

# Run single test
uv run pytest tests/test_download_data.py::test_download_sentinel2_data -v

# Run tests excluding integration (network-dependent)
uv run pytest -m "not integration"

# Lint + format
uv run ruff check . --fix
uv run ruff format .

# Type check
uv run ty check

# Full validation (pre-commit)
pre-commit run --all-files

# Run MCP server
uv run python -m planetary_computer_mcp.server

Project Structure

src/planetary_computer_mcp/
├── core/                    # Core utilities
│   ├── __init__.py         # Public API exports
│   ├── collections.py      # Collection keyword mapping
│   ├── geocoding.py        # Place name → bbox
│   ├── raster_utils.py     # odc-stac/rioxarray loading
│   ├── stac_client.py      # STAC search wrapper
│   ├── vector_utils.py     # GeoParquet/DuckDB queries
│   ├── visualization.py    # RGB/colormap generation
│   └── zarr_utils.py       # Climate data (placeholder)
├── tools/                   # MCP tool implementations
│   ├── download_data.py    # Raster download + NATIVE_RESOLUTIONS
│   └── download_geometries.py  # Vector download (MS Buildings)
└── server.py               # FastMCP server entry point
tests/
└── test_download_data.py   # Integration tests (marked @pytest.mark.integration)

Code Style

Imports

• Standard library → third-party → local (enforced by ruff isort)
• Use absolute imports for cross-module: from planetary_computer_mcp.core import ...
• Use relative imports within same package: from ..core import ...
• Group imports in __init__.py with explicit __all__

Formatting

• Line length: 100 chars
• Target Python: 3.13 (supports 3.10-3.13)
• Formatter: ruff format (black-compatible)
• Quotes: Double quotes for strings

Type Hints