aerospace-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.

Commands

Development Setup

# Install with UV (recommended)
uv venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv sync

# Alternative: Install with pip
pip install -e .[dev]

Running the Application

# Run FastAPI HTTP server
aerospace-mcp-http
# Or with custom config
UVICORN_HOST=localhost UVICORN_PORT=8080 aerospace-mcp-http

# Run MCP server (stdio mode for production)
aerospace-mcp

# Run MCP server in SSE mode for debugging (defaults localhost:8001)
aerospace-mcp sse [host] [port]

# Invoke any tool directly from the terminal
aerospace-mcp-cli run convert_units --value 100 --from_unit kts --to_unit mps

Development & Testing

# Run all tests
pytest

# Run tests with coverage
pytest --cov=app --cov=aerospace_mcp --cov-report=html

# Run specific test file
pytest tests/test_plan.py

# Run single test
pytest tests/test_plan.py::test_flight_planning_sjc_nrt -v

# Code formatting and linting
black .
ruff check .
ruff check --fix .

# Type checking
mypy app/ aerospace_mcp/

# Pre-commit hooks (runs all checks)
pre-commit run --all-files

Docker Operations

# Build and run with Docker
docker build -t aerospace-mcp .
docker run -p 8080:8080 aerospace-mcp

# Run with Docker Compose
docker-compose up
docker-compose up --build  # Rebuild image

Architecture

This is a dual-mode aerospace flight planning system that provides identical functionality through both HTTP API (FastAPI) and Model Context Protocol (MCP) interfaces.

Core Architecture

The system follows a layered architecture with shared business logic:

Shared Core Layer (aerospace_mcp/core.py):

• Airport data management using airportsdata (loaded once at module level)
• Great-circle route calculations with geographiclib
• OpenAP aircraft performance modeling (with graceful fallback)
• Pydantic models for all data structures (AirportOut, PlanRequest, PlanResponse, SegmentEst)
• Business logic functions: health(), airports_by_city(), plan_flight()