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/username/aerospace-mcp.git
cd aerospace-mcp
uv venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv sync

# Run HTTP server
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/username/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"
    }
  }
}

📋 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

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

💾 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/username/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
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/username/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

# Install optional dependencies
pip install openap  # For performance estimates
pip install mcp     # For MCP server

# 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/username/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/username/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/server.py)

   • Model Context Protocol implementation
   • 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

🚀 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)
    # ... 30+ 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

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 30+ tools maintain exact same names and parameters

⚡ Performance

Benchmarks

Operation	Response Time	Throughput	Memory Usage
Health Check	< 1ms	10,000+ req/sec	~5MB
Airport Search	1-5ms	1,000+ req/sec	~50MB
Flight Planning	200-500ms	5-10 req/sec	~100MB
Distance Calc	10-50ms	100+ req/sec	~50MB

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

📖 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

Tool	Description	Parameters
search_airports	Find airports by IATA or city	query, country, query_type
plan_flight	Complete flight planning	departure, arrival, aircraft, route_options
calculate_distance	Great-circle distance	origin, destination, step_km
get_aircraft_performance	Performance estimates	aircraft_type, distance_km, cruise_altitude
get_atmosphere_profile	ISA atmosphere conditions	altitudes_m, model_type
wind_model_simple	Wind profile calculation	altitudes_m, surface_wind_mps, model
transform_frames	Coordinate transformations	xyz, from_frame, to_frame, epoch_iso
geodetic_to_ecef	Lat/lon to ECEF conversion	latitude_deg, longitude_deg, altitude_m
ecef_to_geodetic	ECEF to lat/lon conversion	x, y, z
wing_vlm_analysis	Wing aerodynamics analysis (VLM)	geometry, alpha_deg_list, mach
airfoil_polar_analysis	Airfoil polar generation	airfoil_name, alpha_deg_list, reynolds, mach
calculate_stability_derivatives	Stability derivatives calculation	geometry, alpha_deg, mach
propeller_bemt_analysis	Propeller performance (BEMT)	geometry, rpm_list, velocity_ms, altitude_m
uav_energy_estimate	UAV endurance and energy analysis	uav_config, battery_config, mission_profile
get_airfoil_database	Available airfoil coefficients	None
get_propeller_database	Available propeller data	None
rocket_3dof_trajectory	3DOF rocket trajectory simulation	geometry, dt_s, max_time_s, launch_angle_deg
estimate_rocket_sizing	Rocket sizing for mission requirements	target_altitude_m, payload_mass_kg, propellant_type
optimize_launch_angle	Launch angle optimization	geometry, objective, angle_bounds
optimize_thrust_profile	Thrust profile optimization	geometry, burn_time_s, total_impulse_target, n_segments, objective
trajectory_sensitivity_analysis	Parameter sensitivity analysis	base_geometry, parameter_variations, objective
get_system_status	System health and capabilities	None
elements_to_state_vector	Convert orbital elements to state vector	elements
state_vector_to_elements	Convert state vector to orbital elements	state_vector
propagate_orbit_j2	Propagate orbit with J2 perturbations	initial_state, time_span_s, time_step_s
calculate_ground_track	Calculate satellite ground track	orbit_states, time_step_s
hohmann_transfer	Calculate Hohmann transfer orbit	r1_m, r2_m
orbital_rendezvous_planning	Plan orbital rendezvous maneuvers	chaser_elements, target_elements
genetic_algorithm_optimization	Trajectory optimization using GA	initial_trajectory, objective, constraints
particle_swarm_optimization	Trajectory optimization using PSO	initial_trajectory, objective, constraints
monte_carlo_uncertainty_analysis	Monte Carlo trajectory uncertainty analysis	trajectory, uncertainty_params, num_samples
porkchop_plot_analysis	Generate porkchop plot for interplanetary transfers	departure_body, arrival_body, departure_dates, arrival_dates, min_tof_days, max_tof_days

Claude Desktop Setup

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

{
  "mcpServers": {
    "aerospace-mcp": {
      "command": "python",
      "args": ["-m", "aerospace_mcp.server"],
      "cwd": "/path/to/aerospace-mcp",
      "env": {
        "PYTHONPATH": "/path/to/aerospace-mcp"
      }
    }
  }
}

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

VS Code Continue Setup

Add to your config.json:

{
  "mcpServers": [
    {
      "name": "aerospace-mcp",
      "command": "python",
      "args": ["-m", "aerospace_mcp.server"],
      "workingDirectory": "/path/to/aerospace-mcp"
    }
  ]
}

🛠️ Development

Development Setup

# Clone and setup
git clone https://github.com/username/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          # MCP server
│   └── core.py            # Shared business logic
├── app/                   # Alternative FastAPI structure
│   ├── __init__.py
│   └── main.py
├── tests/                 # Test suite
│   ├── conftest.py
│   ├── test_main.py
│   ├── test_airports.py
│   ├── test_plan.py
│   └── test_mcp.py
├── 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 CONTRIBUTING.md 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

📚 Documentation

Complete Documentation

• Quick Start Guide - Get up and running in 5 minutes
• API Reference - Complete REST API documentation
• MCP Integration - Model Context Protocol setup
• Architecture Guide - System design and components
• Deployment Guide - Production deployment strategies
• Contributing Guide - Development and contribution guidelines
• Integration Guide - Client integration examples

Examples Repository

Check out the examples repository for:

• Complete client implementations
• Integration patterns
• Performance benchmarks
• Real-world use cases

📄 License

This project is licensed under the MIT License - see the LICENSE 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: Join our Discord for real-time chat
• Twitter: @AerospaceMCP for updates
• Blog: Read our blog for tutorials and news

Professional Support

For enterprise support, consulting, or custom development:

• Email: support@aerospace-mcp.com
• Website: https://aerospace-mcp.com
• LinkedIn: Aerospace MCP

---

⭐ Star this repository if you find it useful!

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