anchorage-parcels-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Development Commands

uv is NOT installed on every dev machine here, and Windows has python rather than python3. Every command below is given in the form that works without uv; prefix with uv run if you have it.

# Install dependencies
pip install -r requirements.txt      # or: uv sync
pip install -r requirements-dev.txt  # pytest, jsonschema, pre-commit

# Run local MCP server (no Lambda needed). Routes through the SAME
# UniversalHTTPHandler as the Lambda adapter, so the Origin and
# MCP-Protocol-Version checks are exercised locally.
python scripts/local_server.py       # Serves on http://localhost:8000/mcp
# Or: python local_server.py         # Alternate entry point, serves on / and /mcp
# On Windows set PYTHONUTF8=1 first -- the startup banner prints emoji.

# Validate config
python -c "from core.validators import load_and_validate_config; load_and_validate_config('config.yaml')"

# Tests
python -m pytest tests/ -q                                           # All tests
python -m pytest tests/test_ckan_plugin.py -v                        # Single file
python -m pytest tests/test_ckan_plugin.py::TestClass::test_name -v  # Single test
python -m pytest tests/ --cov=core --cov=plugins --cov-report=term-missing
# No coverage threshold is configured -- the report is informational.

# Linting (ruff)
python -m ruff check core/ plugins/ server/ tests/       # Check
python -m ruff check core/ plugins/ server/ tests/ --fix # Auto-fix
python -m ruff format core/ plugins/ server/ tests/      # Format
# The tree is fully format-clean and CI enforces it, so a wholesale
# `ruff format` is safe and produces no diff.

# Smoke test a deployed endpoint (55 HTTP-level checks)
python scripts/smoke_http.py [prod|staging|<url>]
# Works against the local server too:
#   python scripts/smoke_http.py http://localhost:8000/mcp

# Pre-commit hooks
pre-commit run --all-files

# Go client (requires Go 1.21+)
cd client && make build

# Deploy to AWS (repackages, plans, applies)
bash ./scripts/deploy.sh --environment <staging|prod> --yes