mcp-stargazing

Instructions

Implementation Reference

• src/functions/celestial/impl.py:39-65 (handler)

  MCP tool handler implementation for 'get_celestial_rise_set'. Includes @mcp.tool() decorator for registration, input processing via process_location_and_time, calls core celestial_rise_set in thread, and formats response with ISO timestamps.

  @mcp.tool()
  async def get_celestial_rise_set(
      celestial_object: str,
      lon: float,
      lat: float,
      time: str,
      time_zone: str
  ) -> Dict[str, Any]:
      """Calculate the rise and set times of a celestial object.
  
      Args:
          celestial_object: Name of object (e.g. "sun", "moon", "andromeda")
          lon: Observer longitude in degrees
          lat: Observer latitude in degrees
          time: Date string "YYYY-MM-DD HH:MM:SS"
          time_zone: IANA timezone string
  
      Returns:
          Dict with keys "data", "_meta". "data" contains "rise_time" and "set_time".
      """
      location, time_info = process_location_and_time(lon, lat, time, time_zone)
      # Run synchronous celestial calculations in a separate thread
      rise_time, set_time = await asyncio.to_thread(celestial_rise_set, celestial_object, location, time_info)
      return format_response({
          "rise_time": rise_time.isoformat() if rise_time else None,
          "set_time": set_time.isoformat() if set_time else None
      })

• src/celestial.py:50-94 (helper)

  Core helper function implementing the rise/set calculation logic using Astropy. Generates time grid, computes altitudes, finds horizon crossings. Called by the tool handler.

  def celestial_rise_set(
      celestial_object: str,
      observer_location: EarthLocation,
      date: datetime,
      horizon: float = 0.0
  ) -> Tuple[Optional[Time], Optional[Time]]:
      """
      Calculate rise and set times of a celestial object.
      Args:
          celestial_object: Name of the object ("sun", "moon", or planet name).
          observer_location: Observer's EarthLocation.
          date: Date for calculation (timezone-aware datetime).
          horizon: Horizon elevation in degrees (default: 0).
      Returns:
          Tuple[Optional[Time], Optional[Time]]: (rise_time, set_time) in UTC.
      Raises:
          ValueError: If the object is not supported or horizon is invalid.
      """
      if not -90 <= horizon <= 90:
          raise ValueError("Horizon must be between -90 and 90 degrees.")
      time_zone = pytz.timezone(zone=str(date.tzinfo))
      origin_zone = pytz.timezone(zone='UTC')
      time_grid = _generate_time_grid(date)
      name = celestial_object.lower()
      altaz_frame = AltAz(obstime=time_grid, location=observer_location)
      if name == "sun":
          obj_coord = get_sun(time_grid)
      elif name == "moon":
          obj_coord = get_body("moon", time_grid)
      elif name in ["mercury", "venus", "mars", "jupiter", "saturn", "uranus", "neptune"]:
          obj_coord = get_body(name, time_grid)
      else:
          base_coord = _resolve_simbad_object(celestial_object)
          obj_coord = base_coord
      altaz = obj_coord.transform_to(altaz_frame)
      altitudes = np.array(altaz.alt.deg)
      def __convert_timezone(time):
          t = time.to_datetime()
          t = origin_zone.localize(t)
          return t.astimezone(time_zone)
      
      rise_idx, set_idx = _find_rise_set_indices(altitudes, horizon)
      rise_time = __convert_timezone(time_grid[rise_idx]) if rise_idx is not None else None
      set_time = __convert_timezone(time_grid[set_idx]) if set_idx is not None else None
      return rise_time, set_time