noaa-tidesandcurrents-mcp

Instructions

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