Celestial Position MCP Server

Instructions

Implementation Reference

• src/tools/CelestialDetailsTool.ts:17-20 (registration)

  Tool class definition with name 'getCelestialDetails' and description. Extends MCPTool for automatic discovery and registration by the MCP framework.
  class CelestialDetailsTool extends MCPTool<CelestialDetailsInput> { name = 'getCelestialDetails'; description = "Retrieves detailed astronomical information for a specified celestial object (e.g., planet, star, Messier object, NGC/IC object). Information includes current equatorial and horizontal (altitude/azimuth) coordinates, visibility status (above/below horizon), rise/transit/set times, and, where applicable, distance, phase illumination, and upcoming moon phases. All calculations are performed for the pre-configured observer location and the current system time. The tool automatically resolves common names (e.g., 'Andromeda Galaxy' to 'M31') and handles various catalog identifiers.";
• src/tools/CelestialDetailsTool.ts:21-27 (schema)

  Input schema definition using Zod for validation of objectName parameter.
  protected schema = { objectName: { type: z.string(), description: "The name or catalog identifier of the celestial object. Examples: 'Jupiter', 'Sirius', 'M31', 'NGC 7000', 'Crab Nebula'. The tool will attempt to resolve common names." } // Removed: useSystemTime, dateTime, latitude, longitude, elevation };
• src/tools/CelestialDetailsTool.ts:29-169 (handler)

  Core handler function that fetches equatorial coordinates, converts to alt/az, computes visibility (above horizon, rise/transit/set times), object details (distance, phase for Moon/planets), and formats response for the given celestial object using pre-configured observer location and current time.
  async execute(params: CelestialDetailsInput) { try { // Always use current system time const date = new Date(); // Always use pre-configured observer location const observer = { latitude: OBSERVER_CONFIG.latitude, longitude: OBSERVER_CONFIG.longitude, elevation: OBSERVER_CONFIG.altitude, temperature: OBSERVER_CONFIG.temperature, pressure: OBSERVER_CONFIG.pressure }; // Get equatorial coordinates for the object let equatorialCoords: EquatorialCoordinates; try { equatorialCoords = await getEquatorialCoordinates(params.objectName, date); } catch (error: any) { throw new Error(`Could not find object: ${params.objectName}. ${error.message}`); } // Convert to horizontal (altaz) coordinates (NEW) const altazCoords = convertToAltAz(equatorialCoords, observer, date); // Get detailed information const details = getObjectDetails(params.objectName, date, observer); // Format the location for display const locationName = `Configured (${OBSERVER_CONFIG.latitude.toFixed(4)}°, ${OBSERVER_CONFIG.longitude.toFixed(4)}°)`; // Calculate visibility (NEW) const isAboveHorizon = altazCoords.altitude > 0; const visibility = isAboveHorizon ? altazCoords.altitude > 30 ? "Excellent visibility" : "Above horizon" : "Below horizon (not visible)"; // Format the response const response: any = { object: params.objectName, ...(typeof equatorialCoords.magnitude === 'number' && { apparentMagnitude: equatorialCoords.magnitude }), observationTime: date.toLocaleString() + " (system local time)", location: locationName, coordinates: { equatorial: { rightAscension: equatorialCoords.rightAscension.toFixed(4) + "h", declination: equatorialCoords.declination.toFixed(4) + "°" }, // Added altitude and azimuth to response horizontal: { altitude: altazCoords.altitude.toFixed(4) + "°", azimuth: altazCoords.azimuth.toFixed(4) + "°" } }, // Added these fields aboveHorizon: isAboveHorizon ? "Yes" : "No", visibility: visibility }; // Add rise/set/transit times if available if (details) { const formatTime = (timeObj: Date | Astronomy.AstroTime | null | undefined): string => { if (!timeObj) return "N/A"; // AstroTime objects have a .date property which is a JS Date. // Fixed objects might return JS Date directly for riseTime/setTime. const date = timeObj instanceof Date ? timeObj : new Date((timeObj as Astronomy.AstroTime).date); return date.toLocaleTimeString(); }; let note = ""; if (details.isCircumpolar) { if (details.alwaysAboveHorizon) { note = "This object is circumpolar and remains above the horizon from this location."; } else if (details.alwaysBelowHorizon) { note = "This object is circumpolar and remains below the horizon from this location."; } else { note = "This object is circumpolar from this location."; } } else { // Not circumpolar. Check if it doesn't rise/set and transit is below horizon. if (!details.riseTime && !details.setTime && details.transitTime && details.transitTime.hor && details.transitTime.hor.altitude < 0) { note = "This object does not rise above the horizon on this date from this location."; } } const riseStr = formatTime(details.riseTime); // details.transitTime is an event object like { time: AstroTime | Date, hor: HorizontalCoordinates } const transitStr = formatTime(details.transitTime ? details.transitTime.time : null); const setStr = formatTime(details.setTime); if (riseStr === "N/A" && transitStr === "N/A" && setStr === "N/A" && !note) { note = "Rise, transit, and set times are not available for this object on this date at this location."; } response.visibilityTimes = { rise: riseStr, transit: transitStr, set: setStr }; if (note) response.visibilityTimes.note = note; } else { response.visibilityTimes = { note: "Astronomical details, including rise/set times, could not be determined for this object." }; } // Add distance information if available if (details && details.distance) { response.distance = { astronomicalUnits: details.distance.au.toFixed(6), kilometers: Math.round(details.distance.km).toLocaleString() }; } // Add phase information for solar system objects if (details && details.phaseInfo) { response.phase = { percentIlluminated: details.phaseInfo.phasePercent.toFixed(1) + "%", trend: details.phaseInfo.isWaxing ? "Waxing" : "Waning" }; } // Add moon phase information if this is the Moon if (details && details.moonPhases && params.objectName.toLowerCase() === 'moon') { response.upcomingPhases = { newMoon: new Date(details.moonPhases.nextNewMoon.date).toLocaleDateString(), firstQuarter: new Date(details.moonPhases.nextFirstQuarter.date).toLocaleDateString(), fullMoon: new Date(details.moonPhases.nextFullMoon.date).toLocaleDateString(), lastQuarter: new Date(details.moonPhases.nextLastQuarter.date).toLocaleDateString() }; } return response; } catch (error: any) { throw new Error(`Failed to get celestial details: ${error.message}`); } }