eo-processor-mcp: Instructions file for GitHub Copilot

STAC MCP Server Development Guide

STAC MCP Server is a Python-based Model Context Protocol (MCP) server that provides access to STAC (SpatioTemporal Asset Catalog) APIs for geospatial data discovery and access. It enables AI assistants to search for satellite imagery, weather data, and other geospatial datasets.

Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

Working Effectively

Bootstrap, Build, and Test Repository

Run these commands in order to set up a working development environment:

# Install dependencies (takes ~15 seconds, NEVER CANCEL, set timeout to 120+ seconds)
# May fail due to network timeouts in sandbox environments
pip install -e ".[dev]"

# Run tests (takes ~1 second, NEVER CANCEL, set timeout to 30+ seconds)
pytest

# Run formatting and linting (takes ~0.2 seconds total)
ruff format stac_mcp/ tests/
ruff check stac_mcp/ tests/ --fix

• After ANY code edit (even small), re-run ruff format and ruff check --fix locally before committing to keep diffs clean and surface issues early.

Run the MCP Server

# Run as MCP server (stdin/stdout transport, waits for MCP protocol messages)
stac-mcp

# Test server functionality with example script (takes ~1 second)
python examples/example_usage.py

Key Timing Expectations

• NEVER CANCEL: Set timeout to 120+ seconds for pip install (may timeout due to network issues)
• NEVER CANCEL: Set timeout to 30+ seconds for pytest (runs in ~1 second)
• Ruff formatting: ~0.2 seconds
• Ruff linting: ~0.02 seconds
• Example script: ~0.6 seconds
• MCP server timeout test: 5 seconds (expected timeout with exit code 124)

Validation

Always Run These Validation Steps After Making Changes

MUST run these commands and ensure they pass before every git commit and git push.

1. Format Code:

   uv run ruff format stac_mcp/ tests/
   

2. Lint and Auto-Fix:

   uv run ruff check stac_mcp/ tests/ --fix --no-cache
   

3. Run Tests:

   uv run pytest -q
   

4. Verify Test Coverage:

   uv run coverage run -m pytest -v
   uv run coverage report --fail-under=85