get_moon_info

Instructions

Implementation Reference

• src/functions/celestial/impl.py:67-97 (handler)

  The MCP tool handler for get_moon_info. Decorated with @mcp.tool(), it validates and parses the time input, localizes to timezone, calls the calculate_moon_info helper in a thread, and formats the response.

  @mcp.tool()
  async def get_moon_info(
      time: str,
      time_zone: str
  ) -> Dict[str, Any]:
      """Get detailed information about the Moon's phase and position.
      
      Args:
          time: Date string "YYYY-MM-DD HH:MM:SS"
          time_zone: IANA timezone string
          
      Returns:
          Dict with keys "data", "_meta". "data" contains illumination, phase_name, age_days, etc.
      """
      try:
          # Try standard format first
          dt = datetime.strptime(time, "%Y-%m-%d %H:%M:%S")
      except ValueError:
          try:
              # Try ISO format
              dt = datetime.fromisoformat(time)
          except ValueError:
               raise ValueError(f"Time string '{time}' matches neither '%Y-%m-%d %H:%M:%S' nor ISO format.")
  
      if dt.tzinfo is None:
          tz = pytz.timezone(time_zone)
          dt = tz.localize(dt)
          
      result = await asyncio.to_thread(calculate_moon_info, dt)
      return format_response(result)

• src/celestial.py:96-169 (helper)

  Supporting helper function that performs the actual astronomical calculations for moon phase, illumination, age, elongation, and distance using Astropy.

  def calculate_moon_info(time: Union[Time, datetime]) -> Dict[str, Any]:
      """
      Calculate detailed information about the Moon's phase and position.
      
      Args:
          time: Observation time (Astropy Time or timezone-aware datetime).
          
      Returns:
          Dict containing:
          - illumination: Fraction of the moon illuminated (0.0 to 1.0)
          - phase_name: String description of the phase (e.g. "Waxing Gibbous")
          - age_days: Approximate age of the moon in days (since New Moon)
          - elongation: Angular separation from Sun in degrees
          - earth_distance: Distance from Earth in km
      """
      # Convert local time to UTC if input is datetime
      if isinstance(time, datetime):
          if time.tzinfo is None:
              raise ValueError("Input datetime must be timezone-aware for local time.")
          time = Time(time.astimezone(pytz.UTC))
  
      sun = get_sun(time)
      moon = get_body("moon", time)
  
      # Elongation (angular separation)
      elongation = sun.separation(moon)
      
      # Illumination fraction (0-1)
      # The illuminated fraction k is given by k = (1 - cos(i))/2 where i is phase angle (approx elongation)
      # New Moon (0 deg): (1 - 1)/2 = 0
      # Full Moon (180 deg): (1 - (-1))/2 = 1
      illumination = (1 - np.cos(elongation.rad)) / 2.0
      
      # Phase angle for naming (requires Ecliptic longitude)
      sun_ecl = sun.transform_to(GeocentricTrueEcliptic(obstime=time))
      moon_ecl = moon.transform_to(GeocentricTrueEcliptic(obstime=time))
      
      # Calculate longitude difference (Moon - Sun)
      lon_diff = (moon_ecl.lon.deg - sun_ecl.lon.deg) % 360
      
      # Determine Phase Name
      # New Moon: 0
      # First Quarter: 90
      # Full Moon: 180
      # Last Quarter: 270
      
      if lon_diff < 1 or lon_diff > 359:
          phase_name = "New Moon"
      elif 1 <= lon_diff < 89:
          phase_name = "Waxing Crescent"
      elif 89 <= lon_diff <= 91:
           phase_name = "First Quarter"
      elif 91 < lon_diff < 179:
          phase_name = "Waxing Gibbous"
      elif 179 <= lon_diff <= 181:
          phase_name = "Full Moon"
      elif 181 < lon_diff < 269:
          phase_name = "Waning Gibbous"
      elif 269 <= lon_diff <= 271:
          phase_name = "Last Quarter"
      else:
          phase_name = "Waning Crescent"
  
      # Age in days (approximate)
      # Synodic month is ~29.53 days. Age = (lon_diff / 360) * 29.53
      age_days = (lon_diff / 360.0) * 29.53059
      
      return {
          "illumination": float(illumination),
          "phase_name": phase_name,
          "age_days": float(age_days),
          "elongation": float(elongation.deg),
          "earth_distance": float(moon.distance.to(u.km).value)
      }