get_next_sun_event

Instructions

Implementation Reference

• src/tools/sun-tools.ts:103-118 (handler)

  The handler function that executes the tool logic: calls SunService.getNextSunEvent and returns formatted text or JSON output.

  execute: async (params) => {
    try {
      const results = sunService.getNextSunEvent(params);
      if (params.format === 'text') {
        return results.map(result => 
          `Next ${result.event}: ${result.date} at ${result.time}`
        ).join('\n');
      }
      return JSON.stringify(results);
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`Failed to get next sun event: ${error.message}`);
      }
      throw new Error('Failed to get next sun event');
    }
  }

• src/tools/sun-tools.ts:98-102 (registration)

  Registration of the get_next_sun_event tool with MCP server, specifying name, description, and input schema.

  // Add next sun event tool
  server.addTool({
    name: 'get_next_sun_event',
    description: 'Get the next occurrence(s) of a specific sun event',
    parameters: NextSunEventParamsSchema,

• src/interfaces/sun.ts:47-57 (schema)

  Zod schema for validating the tool's input parameters, including event type, optional date, location coordinates, count, format, and timezone.

  export const NextSunEventParamsSchema = z.object({
    event: z.nativeEnum(SunEventType).describe('Sun event to find'),
    date: z.string().optional().describe('Starting date (YYYY-MM-DD format). Defaults to current date.'),
    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'),
    count: z.number().positive().optional().describe('Number of occurrences to return. Defaults to 1.'),
    format: z.enum(['json', 'text']).optional().describe('Output format (json or text)'),
    timezone: z.string().optional().describe('Timezone for the results. Defaults to UTC.')
  });
  
  export type NextSunEventParams = z.infer<typeof NextSunEventParamsSchema>; 

• src/services/sun-service.ts:143-188 (helper)

  Supporting utility in SunService that implements the core algorithm for finding the next sun events using SunCalc.getTimes in a loop until required count is reached.

  getNextSunEvent(params: NextSunEventParams): { date: string, time: string, event: string }[] {
    const startDate = params.date ? new Date(params.date) : new Date();
    const count = params.count !== undefined ? params.count : 1;
    const { latitude, longitude } = params;
    const timezone = params.timezone !== undefined ? params.timezone : 'UTC';
    
    const results: { date: string, time: string, event: string }[] = [];
    let currentDate = new Date(startDate);
    
    // Find the next occurrences
    while (results.length < count) {
      const sunTimes = SunCalc.getTimes(currentDate, latitude, longitude);
      const eventTime = sunTimes[params.event as keyof typeof sunTimes];
      
      if (eventTime && !isNaN(eventTime.getTime()) && eventTime > startDate) {
        let formattedTime: string;
        
        try {
          formattedTime = eventTime.toLocaleTimeString('en-US', { timeZone: timezone });
        } catch (error) {
          // If timezone is invalid, fall back to ISO string
          console.warn(`Invalid timezone: ${timezone}. Using UTC.`);
          formattedTime = eventTime.toISOString().split('T')[1].split('.')[0];
        }
        
        results.push({
          date: eventTime.toISOString().split('T')[0],
          time: formattedTime,
          event: params.event as string
        });
        
        // Move to next day to find the next occurrence
        currentDate.setDate(currentDate.getDate() + 1);
      } else {
        // Event not found for this day, try next day
        currentDate.setDate(currentDate.getDate() + 1);
      }
      
      // Safety check to prevent infinite loops
      if (results.length === 0 && currentDate.getTime() - startDate.getTime() > 366 * 24 * 60 * 60 * 1000) {
        throw new Error('Could not find the specified sun event within a year.');
      }
    }
    
    return results;
  }