# Aerospace MCP - Flight Planning API & MCP Server [](https://www.python.org/downloads/) [](https://fastapi.tiangolo.com/) [](https://github.com/TUDelft-CNS-ATM/openap) [](https://modelcontextprotocol.io/) [](https://opensource.org/licenses/MIT) 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) \`\`\`bash # 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 # 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 \`\`\`bash 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: \`\`\`json \{ "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 \`\`\`bash # 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](#features) - [Installation](#installation) - [Usage Examples](#usage-examples) - [Architecture](#architecture) - [FastMCP Migration](#fastmcp-migration) - [Performance](#performance) - [API Documentation](#api-documentation) - [MCP Integration](#mcp-integration) - [Development](#development) - [Contributing](#contributing) - [License](#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: \`\`\`bash # 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 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) \`\`\`bash # 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 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 \`\`\`bash # 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 \`\`\`bash # 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**: \`\`\`bash # 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**: \`\`\`bash # 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**: \`\`\`bash # 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 \`\`\`bash # 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 \`\`\`bash # 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 \`\`\`bash # 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 \`\`\`python 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 \`\`\`python 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 \`\`\`python 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 \`\`\`python # 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 \`\`\`typescript 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 \`\`\`mermaid 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
28,000+ airports] OpenAP[OpenAP Models
190+ aircraft] Geodesic[GeographicLib
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](https://github.com/jlowin/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):** \`\`\`python 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 \`\`\` ## ️ 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-... \`\`\` **After (FastMCP):** \`\`\`python @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**: \`\`\`json \{ "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**: \`\`\`json \{ "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: \`\`\`json \{ "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: \`\`\`json \{ "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\`: \`\`\`json \{ "mcpServers": [ \{ "name": "aerospace-mcp", "command": "python", "args": ["-m", "aerospace_mcp.server"], "workingDirectory": "/path/to/aerospace-mcp" \} ] \} \`\`\` ## ️ Development ### Development Setup \`\`\`bash # 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 \`\`\`bash # 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 \`\`\`bash # 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](docs/CONTRIBUTING.md) for detailed guidelines. ### Quick Contributing Guide 1. **Fork & Clone** \`\`\`bash git clone https://github.com/yourusername/aerospace-mcp.git cd aerospace-mcp \`\`\` 2. **Setup Development Environment** \`\`\`bash 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** \`\`\`bash 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**](docs/QUICKSTART.md) - Get up and running in 5 minutes - [**API Reference**](docs/API.md) - Complete REST API documentation - [**MCP Integration**](docs/MCP_INTEGRATION.md) - Model Context Protocol setup - [**Architecture Guide**](docs/ARCHITECTURE.md) - System design and components - [**Deployment Guide**](docs/DEPLOYMENT.md) - Production deployment strategies - [**Contributing Guide**](docs/CONTRIBUTING.md) - Development and contribution guidelines - [**Integration Guide**](docs/INTEGRATION.md) - Client integration examples ### Examples Repository Check out the [examples repository](https://github.com/username/aerospace-mcp-examples) for: - Complete client implementations - Integration patterns - Performance benchmarks - Real-world use cases ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ### Third-Party Acknowledgments - **OpenAP**: Aircraft performance modeling - [TU Delft](https://github.com/TUDelft-CNS-ATM/openap) - **AirportsData**: Airport database - [mborsetti](https://github.com/mborsetti/airportsdata) - **GeographicLib**: Geodesic calculations - [Charles Karney](https://geographiclib.sourceforge.io/) - **FastAPI**: Modern web framework - [Sebastián Ramírez](https://github.com/tiangolo/fastapi) ## 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.