get_sun_position

Instructions

Implementation Reference

• src/tools/sun-tools.ts:73-96 (handler)

  The MCP tool handler for 'get_sun_position', which calls the sun service and handles text/JSON output formatting and error handling.

  server.addTool({
    name: 'get_sun_position',
    description: 'Get sun position information for a specific date, time, and location',
    parameters: SunPositionParamsSchema,
    execute: async (params) => {
      try {
        const result = sunService.getSunPosition(params);
        if (params.format === 'text') {
          let text = `Sun position for ${result.date} ${result.time} at latitude ${params.latitude}, longitude ${params.longitude}:\n`;
          text += `Azimuth: ${result.azimuth.toFixed(2)}°\n`;
          text += `Altitude: ${result.altitude.toFixed(2)}°\n`;
          text += `Declination: ${result.declination.toFixed(2)}°\n`;
          text += `Right Ascension: ${result.rightAscension.toFixed(2)}h\n`;
          return text;
        }
        return JSON.stringify(result);
      } catch (error) {
        if (error instanceof Error) {
          throw new Error(`Failed to get sun position: ${error.message}`);
        }
        throw new Error('Failed to get sun position');
      }
    }
  });

• src/interfaces/sun.ts:34-42 (schema)

  Zod schema defining input parameters for the get_sun_position tool, including date, time, location, and format.

  export const SunPositionParamsSchema = z.object({
    date: z.string().optional().describe('Date to get sun position for (YYYY-MM-DD format). Defaults to current date.'),
    time: z.string().optional().describe('Time to get sun position for (HH:MM:SS format). Defaults to current time.'),
    latitude: z.number().min(-90).max(90).describe('Latitude for location-specific calculations'),
    longitude: z.number().min(-180).max(180).describe('Longitude for location-specific calculations'),
    format: z.enum(['json', 'text']).optional().describe('Output format (json or text)')
  });
  
  export type SunPositionParams = z.infer<typeof SunPositionParamsSchema>;

• src/tools/index.ts:29-29 (registration)

  Calls registerSunTools to register sun tools including get_sun_position to the MCP server.

  registerSunTools(server, sunService);

• src/services/sun-service.ts:105-136 (helper)

  Core implementation of sun position calculation using SunCalc library, including position retrieval and approximate equatorial coordinates computation.

  getSunPosition(params: SunPositionParams): SunPositionInfo {
    const date = params.date ? new Date(params.date) : new Date();
    const time = params.time;
    const { latitude, longitude } = params;
    
    // Set the time if provided
    if (time) {
      const [hours, minutes, seconds] = time.split(':').map(Number);
      
      if (!isNaN(hours) && !isNaN(minutes) && (!seconds || !isNaN(seconds))) {
        date.setHours(hours, minutes, seconds || 0, 0);
      } else {
        throw new Error('Invalid time format. Please use HH:MM:SS format.');
      }
    }
    
    // Get sun position data
    const position = SunCalc.getPosition(date, latitude, longitude);
    
    // Calculate right ascension and declination (approximate values)
    // Note: These are approximate calculations and may not be precise
    const equatorialCoords = this.calculateEquatorialCoordinates(date, position.azimuth, position.altitude, latitude, longitude);
    
    return {
      date: date.toISOString().split('T')[0],
      time: date.toISOString().split('T')[1].split('.')[0],
      azimuth: position.azimuth * (180 / Math.PI),
      altitude: position.altitude * (180 / Math.PI),
      declination: equatorialCoords.declination,
      rightAscension: equatorialCoords.rightAscension
    };
  }