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

Building from source needs a Rust toolchain (rustup): the trajectory/orbit core is a PyO3 extension (rust/, built by maturin, imported as aerospace_mcp._native). uv sync rebuilds it when Rust sources change. End users never need Rust: releases publish prebuilt abi3 wheels (see Distribution below).

# 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

# Native core (from rust/): format, lint, unit tests without Python
cargo fmt --check
cargo clippy --no-default-features --all-targets -- -D warnings
cargo test --no-default-features

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.