Aerospace MCP

Instructions

Implementation Reference

• aerospace_mcp/tools/orbits.py:9-51 (handler)

  MCP tool handler: Converts input orbital elements dictionary to OrbitElements, calls the core conversion function from integrations, formats and returns JSON state vector with position and velocity in J2000 frame.

  def elements_to_state_vector(orbital_elements: dict) -> str:
      """Convert orbital elements to state vector in J2000 frame.
  
      Args:
          orbital_elements: Dict with orbital elements (semi_major_axis_m, eccentricity, etc.)
  
      Returns:
          JSON string with state vector components
      """
      try:
          from ..integrations.orbits import (
              OrbitElements,
          )
          from ..integrations.orbits import (
              elements_to_state_vector as _elements_to_state,
          )
  
          elements = OrbitElements(**orbital_elements)
          result = _elements_to_state(elements)
  
          return json.dumps(
              {
                  "position_m": {
                      "x": result.position_m[0],
                      "y": result.position_m[1],
                      "z": result.position_m[2],
                  },
                  "velocity_ms": {
                      "x": result.velocity_ms[0],
                      "y": result.velocity_ms[1],
                      "z": result.velocity_ms[2],
                  },
                  "reference_frame": "J2000",
                  "units": {"position": "meters", "velocity": "m/s"},
              },
              indent=2,
          )
  
      except ImportError:
          return "Orbital mechanics not available - install orbital packages"
      except Exception as e:
          logger.error(f"Elements to state vector error: {str(e)}", exc_info=True)
          return f"Elements to state vector error: {str(e)}"

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

  Registration of orbital mechanics tools including elements_to_state_vector in the FastMCP server.

  mcp.tool(elements_to_state_vector)
  mcp.tool(state_vector_to_elements)
  mcp.tool(propagate_orbit_j2)
  mcp.tool(calculate_ground_track)
  mcp.tool(hohmann_transfer)
  mcp.tool(orbital_rendezvous_planning)

• aerospace_mcp/tools/agents.py:121-129 (schema)

  Schema definition for the elements_to_state_vector tool used by agent tools, including parameters and example.

      name="elements_to_state_vector",
      description="Convert orbital elements to state vector",
      parameters={
          "elements": "dict - Orbital elements with semi_major_axis_m, eccentricity, inclination_deg, raan_deg, arg_periapsis_deg, true_anomaly_deg, epoch_utc"
      },
      examples=[
          'elements_to_state_vector({"semi_major_axis_m": 6793000, "eccentricity": 0.001, "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"})'
      ],
  ),

• aerospace_mcp/integrations/orbits.py:148-219 (helper)

  Core helper function that performs the actual orbital elements to state vector conversion using classical orbital mechanics formulas and rotation matrices to J2000 frame.

  def elements_to_state_vector(elements: OrbitElements) -> StateVector:
      """
      Convert orbital elements to state vector using manual calculations.
  
      Args:
          elements: Orbital elements
  
      Returns:
          State vector in J2000 frame
      """
      # Convert angles to radians
      i = deg_to_rad(elements.inclination_deg)
      raan = deg_to_rad(elements.raan_deg)
      arg_pe = deg_to_rad(elements.arg_periapsis_deg)
      nu = deg_to_rad(elements.true_anomaly_deg)
  
      # Semi-major axis and eccentricity
      a = elements.semi_major_axis_m
      e = elements.eccentricity
  
      # Calculate distance and flight path angle
      r = a * (1 - e**2) / (1 + e * math.cos(nu))
  
      # Position in perifocal coordinates
      r_peri = [r * math.cos(nu), r * math.sin(nu), 0.0]
  
      # Velocity in perifocal coordinates
      p = a * (1 - e**2)
  
      v_peri = [
          -math.sqrt(MU_EARTH / p) * math.sin(nu),
          math.sqrt(MU_EARTH / p) * (e + math.cos(nu)),
          0.0,
      ]
  
      # Rotation matrices
      cos_raan, sin_raan = math.cos(raan), math.sin(raan)
      cos_i, sin_i = math.cos(i), math.sin(i)
      cos_arg, sin_arg = math.cos(arg_pe), math.sin(arg_pe)
  
      # Rotation matrix from perifocal to J2000
      R11 = cos_raan * cos_arg - sin_raan * sin_arg * cos_i
      R12 = -cos_raan * sin_arg - sin_raan * cos_arg * cos_i
      R13 = sin_raan * sin_i
  
      R21 = sin_raan * cos_arg + cos_raan * sin_arg * cos_i
      R22 = -sin_raan * sin_arg + cos_raan * cos_arg * cos_i
      R23 = -cos_raan * sin_i
  
      R31 = sin_arg * sin_i
      R32 = cos_arg * sin_i
      R33 = cos_i
  
      # Transform to J2000 frame
      r_j2000 = [
          R11 * r_peri[0] + R12 * r_peri[1] + R13 * r_peri[2],
          R21 * r_peri[0] + R22 * r_peri[1] + R23 * r_peri[2],
          R31 * r_peri[0] + R32 * r_peri[1] + R33 * r_peri[2],
      ]
  
      v_j2000 = [
          R11 * v_peri[0] + R12 * v_peri[1] + R13 * v_peri[2],
          R21 * v_peri[0] + R22 * v_peri[1] + R23 * v_peri[2],
          R31 * v_peri[0] + R32 * v_peri[1] + R33 * v_peri[2],
      ]
  
      return StateVector(
          position_m=r_j2000,
          velocity_ms=v_j2000,
          epoch_utc=elements.epoch_utc,
          frame="J2000",
      )