LocalTides MCP Server

Instructions

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;
  }