stac-mcp: Instructions file for Codex

Agents / Contributor Guide — Python best practices & PEP adherence

Purpose

• Provide concise, actionable guidance for contributors and automated agents working on this repository.
• Emphasize adherence to Python PEPs (style, typing, docstrings) and the project's tooling.

Core principles

• Follow PEP 8 for style and naming (use snake_case for functions/variables, PascalCase for classes, UPPER_SNAKE for constants).
• Use PEP 257 docstrings for modules, classes, and public functions/methods.
• Prefer type hints (PEP 484). Keep signatures explicit and avoid overly broad Any where a concrete type helps readability.
• Always import generics from the typing module (List, Dict, Optional, Union, Tuple, Set, Iterable, Callable, etc.) instead of using builtin collection annotations like list[str] unless an ADR supersedes this rule. This maintains consistency across the codebase and clarifies intent for contributors and automated agents.
• Keep functions small and single-responsibility. Favor composition over inheritance when appropriate.

Public-API-first rule

• Prefer using public, documented APIs of third-party libraries. Do not reach into private or underscore-prefixed attributes or functions (for example, avoid accessing objects like client._stac_io, session._pool, or other internals).
• When interacting with STAC libraries prefer the public Client/IO abstractions (for example, pystac_client.Client and pystac.stac_io.StacIO/StacApiIO) or perform explicit HTTP calls with requests rather than reading or mutating private internals.

These rules keep behavior stable across upstream library upgrades and make code easier to test and maintain.

Formatting & Linting: Pre-Commit/Pre-Push Checklist

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/ examples/
   

2. Lint and Auto-Fix:

   uv run ruff check stac_mcp/ tests/ examples/ --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
   

IMPORTANT: Run the ruff format and ruff check commands multiple times in sequence to ensure all issues are resolved, as auto-fixing can sometimes introduce new formatting needs.

Testing & validation

• Write tests for behavior, not implementation; prefer parametrized tests for similar cases.
• Run the full test suite locally:
  • pytest -v
• Ensure all tests pass before pushing.
• Follow the repository's Validation checklist:
  • Ruff format and lint pass.
  • All tests pass.

Logging & errors

• Use the standard logging module; configure logging at entrypoints only.
• Do not swallow exceptions silently. Surface useful context and wrap exceptions only when adding helpful information.
• Avoid print() for diagnostics in library code.

Async & IO

• Prefer async APIs when interacting with network or IO in the MCP server; follow standard asyncio patterns.
• Avoid blocking calls in async code. Use run_in_executor for CPU-bound or blocking work.

Dependencies & environment

• Use virtual environments or tox for isolation.
• Pin dev dependencies in pyproject.toml where appropriate.
• Install in editable mode during development: pip install -e ".[dev]"

Commit & PR guidance

• Write clear commit messages with intent and scope.
• Run formatting and tests before pushing.
• Keep PRs focused and small; include a brief description of changes and validation steps.