get_next_sun_event
Retrieve the next occurrence(s) of sun events like sunrise, sunset, or dawn for a specific location and date. Supports custom time zones and outputs in JSON or text formats.
Instructions
Get the next occurrence(s) of a specific sun event
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of occurrences to return. Defaults to 1. | |
| date | No | Starting date (YYYY-MM-DD format). Defaults to current date. | |
| event | Yes | Sun event to find | |
| format | No | Output format (json or text) | |
| latitude | Yes | Latitude for location-specific calculations | |
| longitude | Yes | Longitude for location-specific calculations | |
| timezone | No | Timezone for the results. Defaults to UTC. |
Implementation Reference
- src/tools/sun-tools.ts:99-119 (registration)Registration of the get_next_sun_event MCP tool, including name, description, parameters schema reference, and execute handler function.server.addTool({ name: 'get_next_sun_event', description: 'Get the next occurrence(s) of a specific sun event', parameters: NextSunEventParamsSchema, 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:103-118 (handler)MCP tool handler (execute function): delegates to SunService.getNextSunEvent(params), then formats results as text list or JSON based on params.format.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/interfaces/sun.ts:47-55 (schema)Zod input schema (NextSunEventParamsSchema) defining parameters for the tool: event type, optional start date/count/format/timezone, required lat/lng.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.') });
- src/services/sun-service.ts:143-188 (helper)SunService.getNextSunEvent helper method: loops from start date, uses SunCalc.getTimes to find future occurrences of specified event (sunrise/sunset/etc.), formats with timezone, returns up to 'count' results.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; }