Aerospace MCP

Instructions

Implementation Reference

• aerospace_mcp/tools/orbits.py:172-204 (handler)

  MCP tool handler function for orbital_rendezvous_planning. Converts input dicts to OrbitElements, calls core implementation from integrations, returns JSON result or error message.

  def orbital_rendezvous_planning(
      chaser_elements: dict, target_elements: dict, rendezvous_options: dict | None = None
  ) -> str:
      """Plan orbital rendezvous maneuvers between two spacecraft.
  
      Args:
          chaser_elements: Chaser spacecraft orbital elements
          target_elements: Target spacecraft orbital elements
          rendezvous_options: Optional rendezvous planning parameters
  
      Returns:
          JSON string with rendezvous plan
      """
      try:
          from ..integrations.orbits import (
              OrbitElements,
          )
          from ..integrations.orbits import (
              orbital_rendezvous_planning as _rendezvous,
          )
  
          chaser = OrbitElements(**chaser_elements)
          target = OrbitElements(**target_elements)
  
          result = _rendezvous(chaser, target, rendezvous_options or {})
  
          return json.dumps(result, indent=2)
  
      except ImportError:
          return "Rendezvous planning not available - install orbital packages"
      except Exception as e:
          logger.error(f"Rendezvous planning error: {str(e)}", exc_info=True)
          return f"Rendezvous planning error: {str(e)}"

• aerospace_mcp/integrations/orbits.py:609-731 (helper)

  Core implementation of orbital rendezvous planning. Computes relative positions, phase angles, orbital properties, estimates phasing time and delta-V for maneuvers like circularization and altitude adjustment, returns detailed plan dictionary.

  def orbital_rendezvous_planning(
      chaser_elements: OrbitElements, target_elements: OrbitElements
  ) -> dict[str, Any]:
      """
      Plan orbital rendezvous maneuvers between two spacecraft.
  
      Args:
          chaser_elements: Chaser spacecraft orbital elements
          target_elements: Target spacecraft orbital elements
  
      Returns:
          Rendezvous plan with phasing and approach maneuvers
      """
      # Convert to state vectors for analysis
      chaser_state = elements_to_state_vector(chaser_elements)
      target_state = elements_to_state_vector(target_elements)
  
      # Calculate relative position
      rel_pos = [
          target_state.position_m[i] - chaser_state.position_m[i] for i in range(3)
      ]
      rel_distance = vector_magnitude(rel_pos)
  
      # Orbital properties
      chaser_props = calculate_orbit_properties(chaser_elements)
      target_props = calculate_orbit_properties(target_elements)
  
      # Phase angle between spacecraft
      chaser_r = vector_magnitude(chaser_state.position_m)
      target_r = vector_magnitude(target_state.position_m)
  
      cos_phase = vector_dot(chaser_state.position_m, target_state.position_m) / (
          chaser_r * target_r
      )
      cos_phase = max(-1, min(1, cos_phase))
      phase_angle_rad = math.acos(cos_phase)
  
      # Estimate phasing time
      if abs(chaser_props.period_s - target_props.period_s) > 1:
          synodic_period = abs(
              chaser_props.period_s
              * target_props.period_s
              / (chaser_props.period_s - target_props.period_s)
          )
          phasing_time_s = phase_angle_rad / (2 * math.pi) * synodic_period
      else:
          phasing_time_s = float("inf")  # Coplanar, similar orbits
  
      # Delta-V estimates for circularization if needed
      chaser_circ_dv = 0.0
  
      if chaser_elements.eccentricity > 0.01:
          # Circularization delta-V (rough estimate)
          v_ap = math.sqrt(
              MU_EARTH
              * (
                  2
                  / (
                      chaser_elements.semi_major_axis_m
                      * (1 + chaser_elements.eccentricity)
                  )
                  - 1 / chaser_elements.semi_major_axis_m
              )
          )
          v_circ = math.sqrt(
              MU_EARTH
              / (chaser_elements.semi_major_axis_m * (1 + chaser_elements.eccentricity))
          )
          chaser_circ_dv = abs(v_circ - v_ap)
  
      # Create sample maneuvers
      maneuvers = []
  
      # Add a simple phasing maneuver
      if chaser_circ_dv > 0:
          maneuvers.append(
              {
                  "delta_v_ms": chaser_circ_dv,
                  "type": "circularization",
                  "description": "Circularize chaser orbit",
              }
          )
  
      # Add altitude matching maneuver if needed
      altitude_diff = abs(chaser_props.apoapsis_m - target_props.apoapsis_m)
      if altitude_diff > 1000:  # More than 1 km difference
          altitude_dv = 50.0  # Rough estimate for altitude adjustment
          maneuvers.append(
              {
                  "delta_v_ms": altitude_dv,
                  "type": "altitude_adjustment",
                  "description": "Match target altitude",
              }
          )
  
      # Calculate total delta-V
      total_dv = sum(m["delta_v_ms"] for m in maneuvers)
  
      return {
          "relative_distance_m": rel_distance,
          "relative_distance_km": rel_distance / 1000,
          "phase_angle_deg": rad_to_deg(phase_angle_rad),
          "phasing_time_s": phasing_time_s,
          "phasing_time_h": (
              phasing_time_s / 3600 if phasing_time_s != float("inf") else float("inf")
          ),
          "time_to_rendezvous_s": phasing_time_s,  # Add expected key
          "chaser_period_s": chaser_props.period_s,
          "target_period_s": target_props.period_s,
          "period_difference_s": abs(chaser_props.period_s - target_props.period_s),
          "altitude_difference_m": abs(chaser_props.apoapsis_m - target_props.apoapsis_m),
          "estimated_circularization_dv_ms": chaser_circ_dv,
          "total_delta_v_ms": total_dv,  # Add expected key
          "maneuvers": maneuvers,  # Add expected key
          "feasibility": (
              "Good"
              if rel_distance < 100000
              and abs(chaser_elements.inclination_deg - target_elements.inclination_deg)
              < 5.0
              else "Challenging"
          ),
      }

• aerospace_mcp/fastmcp_server.py:121-121 (registration)

  Registers the orbital_rendezvous_planning tool function with the FastMCP server instance.

  mcp.tool(orbital_rendezvous_planning)

• aerospace_mcp/integrations/orbits.py:20-30 (schema)

  Dataclass defining the OrbitElements structure used for input validation and type hinting in the rendezvous planning functions.

  @dataclass
  class OrbitElements:
      """Classical orbital elements."""
  
      semi_major_axis_m: float  # Semi-major axis (m)
      eccentricity: float  # Eccentricity (dimensionless)
      inclination_deg: float  # Inclination (degrees)
      raan_deg: float  # Right ascension of ascending node (degrees)
      arg_periapsis_deg: float  # Argument of periapsis (degrees)
      true_anomaly_deg: float  # True anomaly (degrees)
      epoch_utc: str  # Epoch in UTC ISO format