mcp-stargazing

Instructions

Implementation Reference

• src/functions/celestial/impl.py:98-121 (handler)

  MCP tool handler for 'get_visible_planets'. Processes location/time inputs, delegates to core calculation via asyncio.to_thread, and formats the response with format_response.

  @mcp.tool()
  async def get_visible_planets(
      lon: float,
      lat: float,
      time: str,
      time_zone: str
  ) -> Dict[str, Any]:
      """Get a list of solar system planets currently visible (above horizon).
      
      Args:
          lon: Observer longitude in degrees
          lat: Observer latitude in degrees
          time: Observation time string "YYYY-MM-DD HH:MM:SS"
          time_zone: IANA timezone string
          
      Returns:
          Dict with keys "data", "_meta". "data" is a list of planet dicts (name, altitude, azimuth).
      """
      location, time_info = process_location_and_time(lon, lat, time, time_zone)
      # Note: Function name collision with imported function 'get_visible_planets'
      # Use the imported function from src.celestial
      from src.celestial import get_visible_planets as calc_visible_planets
      planets = await asyncio.to_thread(calc_visible_planets, location, time_info)
      return format_response(planets)

• src/celestial.py:171-210 (helper)

  Core implementation that iterates over solar system planets, computes their alt/az using astropy.get_body and AltAz frame, and collects those with altitude > 0.

  def get_visible_planets(
      observer_location: EarthLocation,
      time: Union[Time, datetime]
  ) -> list[Dict[str, Any]]:
      """
      Get a list of planets currently above the horizon.
      
      Args:
          observer_location: Observer's EarthLocation.
          time: Observation time.
          
      Returns:
          List of dicts containing planet name, altitude, azimuth, and magnitude (if available).
      """
      # 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))
  
      planets = ["mercury", "venus", "mars", "jupiter", "saturn", "uranus", "neptune"]
      visible_planets = []
      
      for planet in planets:
          # Get coordinates
          obj_coord = get_body(planet, time)
          altaz_frame = AltAz(obstime=time, location=observer_location)
          altaz = obj_coord.transform_to(altaz_frame)
          
          # Check if above horizon
          if altaz.alt.deg > 0:
              visible_planets.append({
                  "name": planet.capitalize(),
                  "altitude": float(altaz.alt.deg),
                  "azimuth": float(altaz.az.deg),
                  "constellation": None # Placeholder for future implementation
              })
              
      return visible_planets