get_sun_times_range
Retrieve sunrise, sunset, and other sun event times for a specific date range and location using latitude, longitude, and optional timezone, with output in JSON or text format.
Instructions
Get sun rise/set and other sun event times for a date range and location
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | End date (YYYY-MM-DD format) | |
| format | No | Output format (json or text) | |
| latitude | Yes | Latitude for location-specific calculations | |
| longitude | Yes | Longitude for location-specific calculations | |
| start_date | Yes | Start date (YYYY-MM-DD format) | |
| timezone | No | Timezone for the results. Defaults to UTC. |
Implementation Reference
- src/services/sun-service.ts:70-98 (handler)Core handler function that computes sun times for a range of dates by iterating over each day and calling getSunTimes.getSunTimesRange(params: SunTimesRangeParams): SunTimesInfo[] { const startDate = new Date(params.start_date); const endDate = new Date(params.end_date); if (isNaN(startDate.getTime()) || isNaN(endDate.getTime())) { throw new Error('Invalid date format. Please use YYYY-MM-DD format.'); } if (startDate > endDate) { throw new Error('Start date must be before end date.'); } const result: SunTimesInfo[] = []; const currentDate = new Date(startDate); while (currentDate <= endDate) { result.push(this.getSunTimes({ date: currentDate.toISOString().split('T')[0], latitude: params.latitude, longitude: params.longitude, timezone: params.timezone })); // Move to next day currentDate.setDate(currentDate.getDate() + 1); } return result; }
- src/tools/sun-tools.ts:43-70 (registration)MCP tool registration: defines name, description, input schema, and execute function that calls the sun service handler and formats output.server.addTool({ name: 'get_sun_times_range', description: 'Get sun rise/set and other sun event times for a date range and location', parameters: SunTimesRangeParamsSchema, execute: async (params) => { try { const results = sunService.getSunTimesRange(params); if (params.format === 'text') { let text = `Sun times from ${params.start_date} to ${params.end_date} at latitude ${params.latitude}, longitude ${params.longitude}:\n\n`; results.forEach(result => { text += `Date: ${result.date}\n`; text += `Sunrise: ${result.sunrise || 'N/A'}\n`; text += `Sunset: ${result.sunset || 'N/A'}\n`; text += `Day length: ${Math.floor(result.dayLength / 60)}h ${Math.round(result.dayLength % 60)}m\n\n`; }); return text; } return JSON.stringify(results); } catch (error) { if (error instanceof Error) { throw new Error(`Failed to get sun times range: ${error.message}`); } throw new Error('Failed to get sun times range'); } } });
- src/interfaces/sun.ts:20-27 (schema)Zod schema defining input parameters for the get_sun_times_range tool.export const SunTimesRangeParamsSchema = z.object({ start_date: z.string().describe('Start date (YYYY-MM-DD format)'), end_date: z.string().describe('End date (YYYY-MM-DD format)'), 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)'), timezone: z.string().optional().describe('Timezone for the results. Defaults to UTC.') });
- src/types/sun.ts:23-39 (schema)TypeScript interface defining the structure of sun times information returned by the tool.export interface SunTimesInfo { date: string; sunrise: string | null; sunset: string | null; solarNoon: string | null; dawn: string | null; dusk: string | null; nightStart: string | null; nightEnd: string | null; goldenHourStart: string | null; goldenHourEnd: string | null; nauticalDawn: string | null; nauticalDusk: string | null; astronomicalDawn: string | null; astronomicalDusk: string | null; dayLength: number; // in minutes }
- src/tools/index.ts:29-29 (registration)Top-level registration call that invokes the sun tools registration function, instantiating SunService.registerSunTools(server, sunService);