cheesejaguar/aerospace-mcp

Aerospace MCP - Flight Planning API & MCP Server

A comprehensive aerospace research and flight planning service providing both HTTP API and Model Context Protocol (MCP) integration. Built with FastMCP for streamlined MCP server development. Features intelligent airport resolution, great-circle route calculation, aircraft performance estimation, atmospheric modeling, coordinate frame transformations, aerodynamic analysis, propeller performance modeling, rocket trajectory optimization, orbital mechanics calculations, and spacecraft trajectory planning for aerospace operations.

⚠️ SAFETY DISCLAIMER

THIS SOFTWARE IS FOR EDUCATIONAL, RESEARCH, AND DEVELOPMENT PURPOSES ONLY

• NOT FOR REAL NAVIGATION: Do not use for actual flight planning or navigation
• NOT CERTIFIED: This system is not certified by any aviation authority
• ESTIMATES ONLY: Performance calculations are theoretical estimates
• NO WEATHER DATA: Does not account for weather, NOTAMs, or airspace restrictions
• NO LIABILITY: Authors assume no responsibility for any consequences of use

For real flight planning, always use certified aviation software and consult official sources including NOTAMs, weather reports, and air traffic control.

🚀 Quick Start

Option 1: UV (Recommended)

# Install UV (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/cheesejaguar/aerospace-mcp.git
cd aerospace-mcp
uv venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv sync

# Copy env and configure (optional but recommended)
cp .env.example .env
# Edit .env as needed (host/port/log level, optional LLM tools)

# Run HTTP server (package entrypoint)
uv run aerospace-mcp-http

# Alternatively (developer style)
uvicorn main:app --reload --host 0.0.0.0 --port 8080

# Test the API
curl "http://localhost:8080/health"

Option 2: Docker

git clone https://github.com/cheesejaguar/aerospace-mcp.git
cd aerospace-mcp
docker build -t aerospace-mcp .
docker run -p 8080:8080 aerospace-mcp

# Test the API
curl "http://localhost:8080/health"

Option 3: MCP Client (Claude Desktop)

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "aerospace-mcp": {
      "command": "uv",
      "args": ["run", "aerospace-mcp"],
      "cwd": "/path/to/aerospace-mcp",
      "env": {
        "LLM_TOOLS_ENABLED": "true",
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

Note: The env section is optional and only needed if you want to enable the AI-powered agent tools for enhanced user experience.

MCP via CLI

# Start the MCP server (stdio)
uv run aerospace-mcp

# Start in SSE mode (optional)
uv run aerospace-mcp sse 0.0.0.0 8001

📋 Table of Contents

• Features
• Installation
• Usage Examples
• Architecture
• FastMCP Migration
• Performance
• API Documentation
• MCP Integration
• Development
• Contributing
• License

✨ Features

Core Capabilities

• Airport Resolution: Intelligent city-to-airport mapping with 28,000+ airports worldwide
• Route Planning: Great-circle distance calculation with geodesic precision
• Performance Estimation: Aircraft-specific fuel and time calculations via OpenAP
• Atmospheric Modeling: ISA atmosphere profiles with optional enhanced precision
• Coordinate Transformations: ECEF, ECI, geodetic frame conversions for aerospace analysis
• Multiple Interfaces: HTTP REST API and Model Context Protocol (MCP) support
• Real-time Processing: Sub-second response times for flight planning requests

Space & Orbital Mechanics Capabilities

• 🛰️ Orbital Elements & State Vectors: Convert between Keplerian elements and Cartesian state vectors
• 🌍 Orbit Propagation: Numerical integration with J2 perturbations using RK4 method
• 🗺️ Ground Track Computation: Calculate satellite ground tracks for mission planning
• 🔄 Hohmann Transfers: Calculate optimal two-impulse orbital transfers
• 🤝 Orbital Rendezvous: Plan multi-maneuver rendezvous sequences
• 🎯 Trajectory Optimization: Genetic algorithms and particle swarm optimization
• 📊 Uncertainty Analysis: Monte Carlo sampling for trajectory robustness assessment
• 🚀 Lambert Problem: Two-body trajectory determination for given time-of-flight

Supported Operations

• ✅ Airport search by city name or IATA code
• ✅ Flight route planning with polyline generation
• ✅ Aircraft performance estimation (190+ aircraft types)
• ✅ Fuel consumption and flight time calculations
• ✅ Great-circle distance calculations
• ✅ Multi-leg journey planning
• ✅ Aircraft comparison analysis
• ✅ Atmospheric profile calculation (ISA standard atmosphere)
• ✅ Wind profile modeling (logarithmic/power law)
• ✅ Coordinate frame transformations (ECEF, ECI, geodetic)
• ✅ Wing aerodynamics analysis (VLM, lifting line theory)
• ✅ Airfoil polar generation and database access
• ✅ Aircraft stability derivatives calculation
• ✅ Propeller performance analysis (BEMT)
• ✅ UAV energy optimization and endurance estimation
• ✅ Motor-propeller matching analysis
• ✅ 3DOF rocket trajectory simulation with atmosphere integration
• ✅ Rocket sizing estimation for mission planning
• ✅ Launch angle optimization for maximum performance
• ✅ Thrust profile optimization using gradient descent
• ✅ Trajectory sensitivity analysis for design studies
• ✅ System capability discovery and status reporting
• ✅ Orbital mechanics calculations (Keplerian elements, state vectors, propagation)
• ✅ Ground track computation for satellite tracking and visualization
• ✅ Hohmann transfer planning for orbital maneuvers and mission design
• ✅ Orbital rendezvous planning for spacecraft proximity operations
• ✅ Trajectory optimization using genetic algorithms and particle swarm optimization
• ✅ Monte Carlo uncertainty analysis for trajectory robustness assessment
• ✅ Lambert problem solving for two-body trajectory determination
• ✅ Porkchop plot generation for interplanetary transfer opportunity analysis
• ✅ Optional SPICE integration with fallback to simplified ephemeris models
• ✅ Density altitude calculation for performance planning
• ✅ Airspeed conversions (IAS/CAS/EAS/TAS/Mach)
• ✅ Stall speed calculation for different configurations
• ✅ Weight and balance calculations with CG limits
• ✅ Takeoff/landing performance distance and V-speeds
• ✅ Fuel reserve calculation per FAR/ICAO regulations
• ✅ Kalman filter state estimation for sensor fusion
• ✅ LQR controller design for optimal control

Technical Features

• 🚀 Fast: In-memory airport database for microsecond lookups
• 🔧 Flexible: Pluggable backend system (currently OpenAP)
• 📊 Accurate: Uses WGS84 geodesic calculations
• 🌐 Standards: Follows ICAO aircraft codes and IATA airport codes
• 🔒 Reliable: Comprehensive error handling and graceful degradation
• 📚 Well-documented: Complete API documentation with examples
• ⚡ Hardware Optimized: NumPy vectorization with CuPy GPU acceleration support
• 🔄 Batch Processing: Vectorized operations for efficient bulk calculations
• 🔍 Tool Discovery: Dynamic tool search for finding relevant tools from 44+ available

💾 Installation

System Requirements

• Python: 3.11+ (3.12+ recommended for best performance)
• Memory: 512MB RAM minimum (1GB+ recommended)
• Storage: 200MB free space
• Network: Internet connection for initial setup

Method 1: UV Package Manager (Recommended)

UV is the fastest Python package manager and provides excellent dependency resolution:

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh  # Linux/macOS
# Or: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

# Clone repository
git clone https://github.com/cheesejaguar/aerospace-mcp.git
cd aerospace-mcp

# Create virtual environment
uv venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate     # Windows

# Install dependencies
uv add fastapi uvicorn[standard] airportsdata geographiclib pydantic python-dotenv
uv add openap  # Optional: for performance estimates
uv add mcp     # Optional: for MCP server functionality

# Install optional aerospace analysis dependencies
uv add --optional-dependencies atmosphere  # Ambiance for enhanced ISA
uv add --optional-dependencies space      # Astropy for coordinate frames
uv add --optional-dependencies all        # All optional dependencies

# Install development dependencies (optional)
uv add --dev pytest httpx black isort mypy pre-commit

# Verify installation
python -c "import main; print('✅ Installation successful')"

Method 2: Pip (Traditional)

# Clone repository
git clone https://github.com/cheesejaguar/aerospace-mcp.git
cd aerospace-mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate     # Windows

# Upgrade pip
pip install --upgrade pip

# Install core dependencies
pip install fastapi uvicorn[standard] airportsdata geographiclib pydantic python-dotenv

# Install optional dependencies
pip install openap  # For performance estimates
pip install mcp     # For MCP server
pip install python-dotenv  # For loading .env in local/dev

# Install from pyproject.toml
pip install -e .

# Verify installation
python -c "import main; print('✅ Installation successful')"

Method 3: Docker

# Clone repository
git clone https://github.com/cheesejaguar/aerospace-mcp.git
cd aerospace-mcp

# Build image
docker build -t aerospace-mcp .

# Run container
docker run -d -p 8080:8080 --name aerospace-mcp aerospace-mcp

# Health check
curl http://localhost:8080/health

# View logs
docker logs aerospace-mcp

# Stop container
docker stop aerospace-mcp

Method 4: Conda/Mamba

# Create conda environment
conda create -n aerospace-mcp python=3.11
conda activate aerospace-mcp

# Clone repository
git clone https://github.com/cheesejaguar/aerospace-mcp.git
cd aerospace-mcp

# Install dependencies
conda install fastapi uvicorn pydantic
pip install airportsdata geographiclib openap mcp

# Verify installation
python -c "import main; print('✅ Installation successful')"

Troubleshooting Installation

Common Issues

OpenAP Installation Problems:

# Try these alternatives if OpenAP fails to install
pip install openap --no-cache-dir
pip install openap --force-reinstall
# Or install without OpenAP (performance estimates will be unavailable)

GeographicLib Issues:

# Install system dependencies (Ubuntu/Debian)
sudo apt-get install libproj-dev proj-data proj-bin

# Install system dependencies (macOS)
brew install proj

# Install system dependencies (Windows)
# Download from: https://proj.org/download.html

Import Errors:

# Verify your Python environment
python --version  # Should be 3.11+
pip list | grep -E "(fastapi|openap|airportsdata)"

# Test individual imports
python -c "import fastapi; print('FastAPI OK')"
python -c "import airportsdata; print('AirportsData OK')"
python -c "import openap; print('OpenAP OK')" || echo "OpenAP not available (optional)"

🎯 Usage Examples

HTTP API Examples

Basic Flight Planning

# Plan a simple flight
curl -X POST "http://localhost:8080/plan" \
  -H "Content-Type: application/json" \
  -d '{
    "depart_city": "San Francisco",
    "arrive_city": "New York",
    "ac_type": "A320",
    "cruise_alt_ft": 37000,
    "backend": "openap"
  }'

Airport Search

# Find airports by city
curl "http://localhost:8080/airports/by_city?city=Tokyo"

# Filter by country
curl "http://localhost:8080/airports/by_city?city=London&country=GB"

# Multiple results
curl "http://localhost:8080/airports/by_city?city=Paris"

Advanced Flight Planning

# Specify exact airports and aircraft mass
curl -X POST "http://localhost:8080/plan" \
  -H "Content-Type: application/json" \
  -d '{
    "depart_city": "Los Angeles",
    "arrive_city": "Tokyo",
    "prefer_depart_iata": "LAX",
    "prefer_arrive_iata": "NRT",
    "ac_type": "B777",
    "cruise_alt_ft": 39000,
    "mass_kg": 220000,
    "route_step_km": 100.0,
    "backend": "openap"
  }'

Python Client Examples

Simple Client

import requests
import json

class AerospaceClient:
    def __init__(self, base_url="http://localhost:8080"):
        self.base_url = base_url

    def plan_flight(self, departure, arrival, aircraft="A320", altitude=35000):
        """Plan a flight between two cities."""
        response = requests.post(f"{self.base_url}/plan", json={
            "depart_city": departure,
            "arrive_city": arrival,
            "ac_type": aircraft,
            "cruise_alt_ft": altitude,
            "backend": "openap"
        })
        return response.json()

    def find_airports(self, city, country=None):
        """Find airports in a city."""
        params = {"city": city}
        if country:
            params["country"] = country
        response = requests.get(f"{self.base_url}/airports/by_city", params=params)
        return response.json()

# Usage
client = AerospaceClient()

# Find airports
airports = client.find_airports("Sydney", "AU")
print(f"Sydney has {len(airports)} airports")

# Plan flight
plan = client.plan_flight("Sydney", "Melbourne", "B737")
print(f"Flight distance: {plan['distance_nm']:.0f} NM")
print(f"Flight time: {plan['estimates']['block']['time_min']:.0f} minutes")

Batch Processing

import asyncio
import aiohttp
from typing import List, Dict

async def plan_multiple_flights(flights: List[Dict]) -> List[Dict]:
    """Plan multiple flights concurrently."""
    async with aiohttp.ClientSession() as session:
        tasks = []
        for flight in flights:
            task = plan_single_flight(session, flight)
            tasks.append(task)

        results = await asyncio.gather(*tasks, return_exceptions=True)
        return results

async def plan_single_flight(session, flight_data):
    """Plan a single flight."""
    async with session.post(
        "http://localhost:8080/plan",
        json=flight_data
    ) as response:
        return await response.json()

# Example usage
flights_to_plan = [
    {"depart_city": "New York", "arrive_city": "London", "ac_type": "A330"},
    {"depart_city": "London", "arrive_city": "Dubai", "ac_type": "B777"},
    {"depart_city": "Dubai", "arrive_city": "Singapore", "ac_type": "A350"}
]

# Run the batch planning
results = asyncio.run(plan_multiple_flights(flights_to_plan))
for i, result in enumerate(results):
    if not isinstance(result, Exception):
        print(f"Flight {i+1}: {result['distance_nm']:.0f} NM, {result['estimates']['block']['time_min']:.0f} min")

Orbital Mechanics Examples

Python Examples

import requests

class OrbitalMechanicsClient:
    def __init__(self, base_url="http://localhost:8080"):
        self.base_url = base_url

    def plan_hohmann_transfer(self, r1_km, r2_km):
        """Calculate Hohmann transfer between two circular orbits."""
        response = requests.post(f"{self.base_url}/hohmann_transfer", json={
            "r1_m": r1_km * 1000,  # Convert to meters
            "r2_m": r2_km * 1000
        })
        return response.json()

    def propagate_satellite_orbit(self, elements, duration_hours):
        """Propagate satellite orbit with J2 perturbations."""
        response = requests.post(f"{self.base_url}/propagate_orbit_j2", json={
            "initial_state": elements,
            "time_span_s": duration_hours * 3600,
            "time_step_s": 300  # 5-minute steps
        })
        return response.json()

# Example usage
client = OrbitalMechanicsClient()

# Plan a GTO to GEO transfer
gto_alt = 200    # km (perigee)
geo_alt = 35786  # km (GEO altitude)

transfer = client.plan_hohmann_transfer(
    6378 + gto_alt,  # Earth radius + altitude
    6378 + geo_alt
)

print(f"Transfer Delta-V: {transfer['delta_v_total_ms']/1000:.2f} km/s")
print(f"Transfer Time: {transfer['transfer_time_h']:.1f} hours")

# Propagate ISS orbit for one day
iss_elements = {
    "semi_major_axis_m": 6793000,  # ~415 km altitude
    "eccentricity": 0.0001,
    "inclination_deg": 51.6,
    "raan_deg": 0.0,
    "arg_periapsis_deg": 0.0,
    "true_anomaly_deg": 0.0,
    "epoch_utc": "2024-01-01T12:00:00"
}

orbit_states = client.propagate_satellite_orbit(iss_elements, 24)
print(f"Propagated {len(orbit_states)} orbital states over 24 hours")

Trajectory Optimization Example

# Optimize a lunar transfer trajectory
def optimize_lunar_transfer():
    initial_trajectory = [
        {
            "time_s": 0,
            "position_m": [6700000, 0, 0],      # LEO
            "velocity_ms": [0, 7500, 0]
        },
        {
            "time_s": 86400 * 3,  # 3 days
            "position_m": [384400000, 0, 0],    # Moon distance
            "velocity_ms": [0, 1000, 0]
        }
    ]

    response = requests.post("http://localhost:8080/genetic_algorithm_optimization", json={
        "initial_trajectory": initial_trajectory,
        "objective": "minimize_delta_v",
        "constraints": {
            "max_thrust_n": 50000,
            "max_acceleration_ms2": 10
        }
    })

    result = response.json()
    print(f"Optimized Delta-V: {result['total_delta_v_ms']/1000:.2f} km/s")
    print(f"Flight Time: {result['flight_time_s']/86400:.1f} days")
    return result

optimized_trajectory = optimize_lunar_transfer()

# Generate porkchop plot for Mars mission planning
def plan_mars_mission():
    response = requests.post("http://localhost:8080/porkchop_plot_analysis", json={
        "departure_body": "Earth",
        "arrival_body": "Mars",
        "min_tof_days": 200,
        "max_tof_days": 300
    })

    analysis = response.json()

    if analysis["summary_statistics"]["feasible_transfers"] > 0:
        optimal = analysis["optimal_transfer"]
        print(f"Optimal Mars Transfer:")
        print(f"  Launch: {optimal['departure_date']}")
        print(f"  Arrival: {optimal['arrival_date']}")
        print(f"  C3: {optimal['c3_km2_s2']:.2f} km²/s²")
        print(f"  Flight Time: {optimal['time_of_flight_days']:.0f} days")
    else:
        print("No feasible transfers found in date range")

plan_mars_mission()

JavaScript/TypeScript Examples

interface FlightPlan {
  depart_city: string;
  arrive_city: string;
  ac_type: string;
  cruise_alt_ft?: number;
  backend: "openap";
}

class AerospaceAPI {
  constructor(private baseUrl: string = "http://localhost:8080") {}

  async planFlight(request: FlightPlan) {
    const response = await fetch(`${this.baseUrl}/plan`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(request),
    });

    if (!response.ok) {
      throw new Error(`API Error: ${response.statusText}`);
    }

    return await response.json();
  }

  async findAirports(city: string, country?: string) {
    const params = new URLSearchParams({ city });
    if (country) params.append("country", country);

    const response = await fetch(`${this.baseUrl}/airports/by_city?${params}`);
    return await response.json();
  }
}

// Usage
const api = new AerospaceAPI();

try {
  const plan = await api.planFlight({
    depart_city: "Boston",
    arrive_city: "Seattle",
    ac_type: "B737",
    cruise_alt_ft: 36000,
    backend: "openap"
  });

  console.log(`Flight planned: ${plan.distance_nm} NM`);
  console.log(`Estimated time: ${plan.estimates.block.time_min} minutes`);
} catch (error) {
  console.error("Flight planning failed:", error);
}

🏗️ Architecture

System Overview

graph TB
    Users[Users/Clients] --> API[FastAPI REST API]
    Users --> MCP[MCP Server]

    API --> Core[Core Services]
    MCP --> Core

    subgraph "Core Services"
        Airport[Airport Resolution]
        Route[Route Calculation]
        Perf[Performance Estimation]
    end

    subgraph "Data Sources"
        AirportDB[Airport Database<br/>28,000+ airports]
        OpenAP[OpenAP Models<br/>190+ aircraft]
        Geodesic[GeographicLib<br/>WGS84 calculations]
    end

    Airport --> AirportDB
    Route --> Geodesic
    Perf --> OpenAP

Key Components

1. FastAPI Application (main.py)

   • RESTful endpoints for HTTP clients
   • Auto-generated OpenAPI documentation
   • Request/response validation with Pydantic

2. MCP Server (aerospace_mcp/fastmcp_server.py)

   • Model Context Protocol implementation via FastMCP
   • Tool-based interface for AI assistants
   • Async request handling

3. Core Services

   • Airport Resolution: City → Airport mapping with intelligent selection
   • Route Calculation: Great-circle paths with polyline generation
   • Performance Estimation: OpenAP-based fuel and time calculations

4. Data Layer

   • In-memory Airport Database: 28,000+ airports loaded at startup
   • OpenAP Integration: Aircraft performance models
   • GeographicLib: Precise geodesic calculations

Design Principles

• Performance First: In-memory data structures for sub-millisecond lookups
• Graceful Degradation: Works without optional dependencies
• Type Safety: Full type hints and Pydantic validation
• Extensible: Plugin architecture for new backends
• Standards Compliant: ICAO, IATA, and OpenAP standards
• Hardware Agnostic: NumPy/CuPy abstraction for CPU/GPU flexibility

🚀 FastMCP Migration

This project has been migrated from the traditional MCP SDK to FastMCP, providing significant improvements in developer experience and code maintainability.

What is FastMCP?

FastMCP is a high-level, Pythonic framework for building Model Context Protocol servers. It dramatically reduces boilerplate code while maintaining full MCP compatibility.

Migration Benefits

✅ 70% Less Code: Tool definitions went from verbose JSON schemas to simple Python decorators ✅ Better Type Safety: Automatic schema generation from type hints ✅ Cleaner Architecture: Modular tool organization across logical domains ✅ Improved Maintainability: Pythonic code that's easier to read and extend ✅ Full Compatibility: Same MCP protocol, works with all existing clients

Before vs After

Before (Traditional MCP SDK):

Tool(
    name="search_airports",
    description="Search for airports by IATA code or city name",
    inputSchema={
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "IATA code or city name"},
            "country": {"type": "string", "description": "Optional country filter"},
            "query_type": {"type": "string", "enum": ["iata", "city", "auto"]}
        },
        "required": ["query"]
    }
)

@server.call_tool()
async def handle_call_tool(name: str, arguments: dict):
    if name == "search_airports":
        return await _handle_search_airports(arguments)
    # ... 40+ more tool handlers

After (FastMCP):

@mcp.tool
def search_airports(
    query: str,
    country: str | None = None,
    query_type: Literal["iata", "city", "auto"] = "auto"
) -> str:
    """Search for airports by IATA code or city name."""
    # Implementation here

Architecture Improvements

The FastMCP refactoring introduced a modular architecture with tools organized by domain:

• tools/core.py - Core flight planning (search, plan, distance, performance)
• tools/atmosphere.py - Atmospheric modeling and wind analysis
• tools/frames.py - Coordinate frame transformations
• tools/aerodynamics.py - Wing analysis and airfoil polars
• tools/propellers.py - Propeller BEMT and UAV energy analysis
• tools/rockets.py - Rocket trajectory and sizing
• tools/orbits.py - Orbital mechanics and propagation
• tools/optimization.py - Trajectory optimization algorithms

Integration modules with NumPy vectorization:

• integrations/_array_backend.py - NumPy/CuPy abstraction layer for GPU support
• integrations/atmosphere.py - Vectorized ISA atmosphere calculations
• integrations/aero.py - Vectorized aerodynamics computations
• integrations/rockets.py - Vectorized trajectory integration
• integrations/frames.py - Vectorized coordinate transformations

Compatibility Notes

• Entry Point: Now uses aerospace_mcp.fastmcp_server:run
• Dependencies: Includes fastmcp>=2.11.3 instead of raw mcp
• Server Name: Still aerospace-mcp for client compatibility
• All Tools: All 44 tools maintain exact same names and parameters

⚙️ Configuration (.env)

Both the HTTP server and MCP servers automatically load environment variables from a local .env (via python-dotenv).

• AEROSPACE_MCP_MODE: http or mcp (Docker entrypoint switch)
• AEROSPACE_MCP_HOST: Bind host for HTTP (default 0.0.0.0)
• AEROSPACE_MCP_PORT: Port for HTTP (default 8080)
• AEROSPACE_MCP_LOG_LEVEL: debug|info|warning|error (default info)
• AEROSPACE_MCP_ENV: development|production (controls reload)
• LLM_TOOLS_ENABLED: true|false to enable AI agent tools (default false)
• OPENAI_API_KEY: Required if LLM tools are enabled

Example .env:

AEROSPACE_MCP_MODE=http
AEROSPACE_MCP_HOST=0.0.0.0
AEROSPACE_MCP_PORT=8080
AEROSPACE_MCP_LOG_LEVEL=debug
LLM_TOOLS_ENABLED=false
# OPENAI_API_KEY=sk-...

⚡ Performance

Benchmarks

Optimization Tips

1. Route Resolution: Use larger route_step_km values for faster processing
2. Caching: Implement client-side caching for repeated requests
3. Batch Processing: Use async clients for multiple concurrent requests
4. Memory: Increase available RAM for better OpenAP performance

Scaling Considerations

• Horizontal Scaling: Stateless design allows multiple instances
• Load Balancing: Standard HTTP load balancers work well
• Database: Consider external database for airport data at scale
• Caching: Add Redis for shared cache across instances

GPU Acceleration (CuPy)

The aerospace calculations are optimized using NumPy's vectorized operations, with a drop-in CuPy backend for GPU acceleration on CUDA-capable hardware.

Enabling GPU Acceleration

# In your code, before using aerospace functions:
from aerospace_mcp.integrations._array_backend import set_backend, get_backend_info

# Check available backends
print(get_backend_info())
# {'current_backend': 'numpy', 'numpy_available': True, 'cupy_available': True, ...}

# Switch to GPU (requires CuPy and CUDA)
set_backend('cupy')

# Switch back to CPU
set_backend('numpy')

Installing CuPy

# For CUDA 11.x
pip install cupy-cuda11x

# For CUDA 12.x
pip install cupy-cuda12x

# Auto-detect CUDA version
pip install cupy

Modules with GPU Support

The following integration modules support GPU acceleration via the array backend:

Note: GPU acceleration provides the most benefit for batch operations with 1000+ data points. For single calculations, CPU (NumPy) is typically faster due to GPU transfer overhead.

📖 API Documentation

Interactive Documentation

When running the server, comprehensive API documentation is available at:

• Swagger UI: http://localhost:8080/docs
• ReDoc: http://localhost:8080/redoc
• OpenAPI Schema: http://localhost:8080/openapi.json

Core Endpoints

GET /health

Health check and system status.

Response:

{
  "status": "ok",
  "openap": true,
  "airports_count": 28756
}

GET /airports/by_city

Search airports by city name.

Parameters:

• city (required): City name to search
• country (optional): ISO country code filter

Example: GET /airports/by_city?city=London&country=GB

POST /plan

Generate complete flight plan.

Request Body:

{
  "depart_city": "San Francisco",
  "arrive_city": "New York",
  "ac_type": "A320",
  "cruise_alt_ft": 37000,
  "mass_kg": 65000,
  "route_step_km": 25.0,
  "backend": "openap"
}

Response: Complete flight plan with route polyline and performance estimates.

Error Handling

All endpoints return standard HTTP status codes:

• 200: Success
• 400: Bad Request (invalid parameters)
• 404: Not Found (airport/city not found)
• 501: Not Implemented (backend unavailable)

Error responses include detailed messages:

{
  "detail": "departure: IATA 'XYZ' not found."
}

🤖 MCP Integration

Supported MCP Clients

• Claude Desktop: Native integration
• VS Code Continue: Plugin support
• Custom Clients: Standard MCP protocol

Available Tools

Claude Desktop Setup

1. Open Claude Desktop Settings
2. Add server configuration:

{
  "mcpServers": {
    "aerospace-mcp": {
      "command": "uv",
      "args": ["run", "aerospace-mcp"],
      "cwd": "/path/to/aerospace-mcp"
    }
  }
}

3. Restart Claude Desktop
4. Test with: "Search for airports in Tokyo"

Tool Discovery

With 44+ aerospace tools available, the MCP server includes a tool search tool following Anthropic's guide for dynamic tool discovery:

# Search by natural language
search_aerospace_tools("atmospheric pressure altitude")
# Returns: get_atmosphere_profile, wind_model_simple, ...

# Search by regex pattern
search_aerospace_tools("(?i)orbit", search_type="regex")
# Returns: propagate_orbit_j2, elements_to_state_vector, hohmann_transfer, ...

# Filter by category
search_aerospace_tools("calculate", category="orbits")
# Returns only orbital mechanics tools matching "calculate"

# List all categories
list_tool_categories()
# Returns: core, atmosphere, frames, aerodynamics, propellers, rockets, orbits, gnc, performance, optimization, agents

Available categories:

• core: Flight planning, airports, distance, aircraft performance
• atmosphere: ISA profiles, wind modeling
• frames: Coordinate transformations (ECEF, ECI, geodetic)
• aerodynamics: Wing analysis, airfoil polars, stability derivatives
• propellers: BEMT analysis, UAV energy estimation
• rockets: 3DOF trajectory, sizing, launch optimization
• orbits: Orbital elements, propagation, transfers, rendezvous, Lambert solver
• optimization: GA, PSO, Monte Carlo, porkchop plots
• gnc: Kalman filter state estimation, LQR controller design
• performance: Density altitude, airspeed conversion, stall speeds, W&B, takeoff/landing
• agents: LLM-powered tool selection and data formatting

Deferred Tool Loading

For applications with many tools, aerospace-mcp supports deferred tool loading to keep context windows efficient. When using the Anthropic API with MCP, configure your mcp_toolset to defer loading of all tools except the discovery tools:

{
  "tools": [
    {
      "type": "tool_search_tool_regex_20251119",
      "name": "tool_search_tool_regex"
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "aerospace-mcp",
      "default_config": {
        "defer_loading": true
      },
      "configs": {
        "search_aerospace_tools": { "defer_loading": false },
        "list_tool_categories": { "defer_loading": false }
      }
    }
  ]
}

This configuration:

1. Loads discovery tools immediately (search_aerospace_tools, list_tool_categories)
2. Defers all other tools until Claude searches for them
3. Automatically expands tool_reference blocks from search results into full definitions

When Claude needs a specific tool, it uses search_aerospace_tools which returns tool_reference blocks:

{
  "tool_references": [
    { "type": "tool_reference", "tool_name": "hohmann_transfer" },
    { "type": "tool_reference", "tool_name": "propagate_orbit_j2" }
  ]
}

The API automatically expands these references into full tool definitions, keeping context efficient while providing access to all 44+ tools.

VS Code Continue Setup

Add to your config.json:

{
  "mcpServers": [
    {
      "name": "aerospace-mcp",
      "command": "uv",
      "args": ["run", "aerospace-mcp"],
      "workingDirectory": "/path/to/aerospace-mcp"
    }
  ]
}

🛠️ Development

Development Setup

# Clone and setup
git clone https://github.com/cheesejaguar/aerospace-mcp.git
cd aerospace-mcp

# Create development environment
uv venv
source .venv/bin/activate
uv add --dev pytest httpx black isort mypy pre-commit

# Install pre-commit hooks
pre-commit install

# Run development server
uvicorn main:app --reload --log-level debug

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=. --cov-report=html

# Run specific test file
pytest tests/test_main.py -v

# Performance testing
pytest tests/test_performance.py -v

Code Quality

# Format code
black . && isort .

# Type checking
mypy main.py aerospace_mcp/

# Linting
ruff check .

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

Project Structure

aerospace-mcp/
├── main.py                 # FastAPI application
├── aerospace_mcp/          # MCP server implementation
│   ├── __init__.py
│   ├── server.py          # Legacy MCP server (deprecated)
│   ├── fastmcp_server.py  # FastMCP server entry point (primary)
│   ├── core.py            # Shared business logic
│   ├── tools/             # MCP tool definitions
│   │   ├── core.py        # Flight planning tools
│   │   ├── atmosphere.py  # Atmospheric modeling tools
│   │   ├── aerodynamics.py # Wing & airfoil analysis
│   │   ├── frames.py      # Coordinate transformations
│   │   ├── rockets.py     # Rocket trajectory tools
│   │   ├── orbits.py      # Orbital mechanics tools
│   │   ├── propellers.py  # Propeller analysis tools
│   │   ├── optimization.py # Trajectory optimization
│   │   ├── gnc.py         # GNC tools (Kalman filter, LQR)
│   │   ├── performance.py # Aircraft performance tools
│   │   ├── agents.py      # LLM-powered agent tools
│   │   └── tool_search.py # Tool discovery and search
│   └── integrations/      # Backend computation modules
│       ├── _array_backend.py # NumPy/CuPy abstraction (GPU support)
│       ├── atmosphere.py  # Vectorized ISA calculations
│       ├── aero.py        # Vectorized aerodynamics
│       ├── frames.py      # Vectorized coordinate transforms
│       ├── rockets.py     # Vectorized trajectory integration
│       ├── orbits.py      # Orbital mechanics computations
│       └── propellers.py  # Propeller BEMT analysis
├── app/                   # Alternative FastAPI structure
│   ├── __init__.py
│   └── main.py
├── tests/                 # Test suite (412 tests)
│   ├── conftest.py
│   ├── test_main.py
│   ├── test_airports.py
│   ├── test_plan.py
│   ├── test_mcp.py
│   ├── test_integrations_*.py  # Integration module tests
│   └── tools/             # Tool-specific tests
│       ├── test_tools_performance.py  # Performance tools tests
│       ├── test_tools_gnc.py          # GNC tools tests
│       └── test_tools_lambert.py      # Lambert solver tests
├── docs/                  # Documentation
│   ├── API.md
│   ├── ARCHITECTURE.md
│   ├── INTEGRATION.md
│   ├── QUICKSTART.md
│   ├── DEPLOYMENT.md
│   └── MCP_INTEGRATION.md
├── pyproject.toml         # Project configuration
├── requirements.txt       # Dependencies
├── Dockerfile            # Docker configuration
├── docker-compose.yml    # Multi-service setup
└── README.md             # This file

🤝 Contributing

We welcome contributions! Please see for detailed guidelines.

Quick Contributing Guide

1. Fork & Clone

   git clone https://github.com/yourusername/aerospace-mcp.git
   cd aerospace-mcp
   

2. Setup Development Environment

   uv venv && source .venv/bin/activate
   uv add --dev pytest httpx black isort mypy
   

3. Make Changes

   • Add features or fix bugs
   • Write tests for new functionality
   • Update documentation as needed

4. Test & Format

   pytest
   black . && isort .
   mypy main.py
   

5. Submit Pull Request

   • Clear title and description
   • Reference any related issues
   • Ensure CI/CD checks pass

Areas for Contribution

• New Aircraft Support: Add more aircraft types to OpenAP
• Weather Integration: Add weather data sources
• Route Optimization: Implement waypoint optimization
• UI/Frontend: Web interface for flight planning
• Database Backend: PostgreSQL/MongoDB integration
• Performance: Optimization and caching improvements
• GPU Optimization: Extend CuPy support to additional modules
• Vectorization: Improve NumPy vectorization coverage

📚 Documentation

Complete Documentation

• - Get up and running in 5 minutes
• - Complete REST API documentation
• - Model Context Protocol setup
• - System design and components
• - Production deployment strategies
• - Development and contribution guidelines
• - Client integration examples

📄 License

This project is licensed under the MIT License - see the file for details.

Third-Party Acknowledgments

• OpenAP: Aircraft performance modeling - TU Delft
• AirportsData: Airport database - mborsetti
• GeographicLib: Geodesic calculations - Charles Karney
• FastAPI: Modern web framework - Sebastián Ramírez

🆘 Support & Community

Getting Help

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: Questions and community support
• Documentation: Comprehensive guides in /docs
• Examples: Code examples and tutorials

Community

• Discord: WIP for real-time chat

Professional Support

For enterprise support, consulting, or custom development:

• Email: hello@aeroastro.org
• Website: https://aeroastro.org

⭐ Star this repository if you find it useful!

Built with ❤️ for the aviation and software development communities.