LocalTides MCP Server

Instructions

Implementation Reference

• src/tools/sun-tools.ts:19-39 (handler)

  The execute handler function for the 'get_sun_times' tool. It invokes the sun service's getSunTimes method and handles text or JSON formatting of the response.

  execute: async (params) => {
    try {
      const result = sunService.getSunTimes(params);
      if (params.format === 'text') {
        let text = `Sun times for ${result.date} at latitude ${params.latitude}, longitude ${params.longitude}:\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`;
        text += `Solar noon: ${result.solarNoon || 'N/A'}\n`;
        text += `Dawn: ${result.dawn || 'N/A'}\n`;
        text += `Dusk: ${result.dusk || 'N/A'}\n`;
        return text;
      }
      return JSON.stringify(result);
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`Failed to get sun times: ${error.message}`);
      }
      throw new Error('Failed to get sun times');
    }
  }

• src/interfaces/sun.ts:7-13 (schema)

  Zod schema defining the input parameters for the get_sun_times tool.

  export const SunTimesParamsSchema = z.object({
    date: z.string().optional().describe('Date to get sun times for (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'),
    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/tools/sun-tools.ts:15-40 (registration)

  Registration of the 'get_sun_times' tool using server.addTool within the registerSunTools function.

  server.addTool({
    name: 'get_sun_times',
    description: 'Get sun rise/set and other sun event times for a specific date and location',
    parameters: SunTimesParamsSchema,
    execute: async (params) => {
      try {
        const result = sunService.getSunTimes(params);
        if (params.format === 'text') {
          let text = `Sun times for ${result.date} at latitude ${params.latitude}, longitude ${params.longitude}:\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`;
          text += `Solar noon: ${result.solarNoon || 'N/A'}\n`;
          text += `Dawn: ${result.dawn || 'N/A'}\n`;
          text += `Dusk: ${result.dusk || 'N/A'}\n`;
          return text;
        }
        return JSON.stringify(result);
      } catch (error) {
        if (error instanceof Error) {
          throw new Error(`Failed to get sun times: ${error.message}`);
        }
        throw new Error('Failed to get sun times');
      }
    }
  });

• src/services/sun-service.ts:14-63 (helper)

  Core helper function implementing sun times calculation using the SunCalc library, handling date, location, timezone, and formatting.

  getSunTimes(params: SunTimesParams): SunTimesInfo {
    const date = params.date ? new Date(params.date) : new Date();
    const { latitude, longitude } = params;
    
    // Get sun times data
    const sunTimes = SunCalc.getTimes(date, latitude, longitude);
    
    // Format times or return null if not available
    const formatTime = (time: Date | null): string | null => {
      if (!time || isNaN(time.getTime())) return null;
      
      if (params.timezone) {
        try {
          return time.toLocaleTimeString('en-US', { timeZone: params.timezone });
        } catch (error) {
          // If timezone is invalid, fall back to ISO string
          console.warn(`Invalid timezone: ${params.timezone}. Using UTC.`);
        }
      }
      
      return time.toISOString();
    };
    
    // Calculate day length in minutes
    const sunrise = sunTimes.sunrise;
    const sunset = sunTimes.sunset;
    let dayLength = 0;
    
    if (sunrise && sunset && !isNaN(sunrise.getTime()) && !isNaN(sunset.getTime())) {
      dayLength = (sunset.getTime() - sunrise.getTime()) / (60 * 1000);
    }
    
    return {
      date: date.toISOString().split('T')[0],
      sunrise: formatTime(sunTimes.sunrise),
      sunset: formatTime(sunTimes.sunset),
      solarNoon: formatTime(sunTimes.solarNoon),
      dawn: formatTime(sunTimes.dawn),
      dusk: formatTime(sunTimes.dusk),
      nightStart: formatTime(sunTimes.night),
      nightEnd: formatTime(sunTimes.nightEnd),
      goldenHourStart: formatTime(sunTimes.goldenHour),
      goldenHourEnd: formatTime(sunTimes.goldenHourEnd),
      nauticalDawn: formatTime(sunTimes.nauticalDawn),
      nauticalDusk: formatTime(sunTimes.nauticalDusk),
      astronomicalDawn: formatTime(sunTimes.astronomicalDawn),
      astronomicalDusk: formatTime(sunTimes.astronomicalDusk),
      dayLength
    };
  }