LocalTides MCP Server

Instructions

Implementation Reference

• src/services/sun-service.ts:105-136 (handler)

  The main handler function in SunService that computes the sun's position (azimuth, altitude, declination, right ascension) for given date, time, latitude, and longitude using SunCalc.getPosition and custom calculations for equatorial coordinates.

  getSunPosition(params: SunPositionParams): SunPositionInfo {
    const date = params.date ? new Date(params.date) : new Date();
    const time = params.time;
    const { latitude, longitude } = params;
    
    // Set the time if provided
    if (time) {
      const [hours, minutes, seconds] = time.split(':').map(Number);
      
      if (!isNaN(hours) && !isNaN(minutes) && (!seconds || !isNaN(seconds))) {
        date.setHours(hours, minutes, seconds || 0, 0);
      } else {
        throw new Error('Invalid time format. Please use HH:MM:SS format.');
      }
    }
    
    // Get sun position data
    const position = SunCalc.getPosition(date, latitude, longitude);
    
    // Calculate right ascension and declination (approximate values)
    // Note: These are approximate calculations and may not be precise
    const equatorialCoords = this.calculateEquatorialCoordinates(date, position.azimuth, position.altitude, latitude, longitude);
    
    return {
      date: date.toISOString().split('T')[0],
      time: date.toISOString().split('T')[1].split('.')[0],
      azimuth: position.azimuth * (180 / Math.PI),
      altitude: position.altitude * (180 / Math.PI),
      declination: equatorialCoords.declination,
      rightAscension: equatorialCoords.rightAscension
    };
  }

• src/interfaces/sun.ts:34-40 (schema)

  Zod schema defining the input parameters (date, time, latitude, longitude, format) for the get_sun_position tool.

  export const SunPositionParamsSchema = z.object({
    date: z.string().optional().describe('Date to get sun position for (YYYY-MM-DD format). Defaults to current date.'),
    time: z.string().optional().describe('Time to get sun position for (HH:MM:SS format). Defaults to current time.'),
    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)')
  });

• src/tools/sun-tools.ts:73-96 (registration)

  Registers the 'get_sun_position' tool with the FastMCP server, providing description, input schema, and an execute handler that calls the SunService method and handles text/JSON output formatting.

  server.addTool({
    name: 'get_sun_position',
    description: 'Get sun position information for a specific date, time, and location',
    parameters: SunPositionParamsSchema,
    execute: async (params) => {
      try {
        const result = sunService.getSunPosition(params);
        if (params.format === 'text') {
          let text = `Sun position for ${result.date} ${result.time} at latitude ${params.latitude}, longitude ${params.longitude}:\n`;
          text += `Azimuth: ${result.azimuth.toFixed(2)}°\n`;
          text += `Altitude: ${result.altitude.toFixed(2)}°\n`;
          text += `Declination: ${result.declination.toFixed(2)}°\n`;
          text += `Right Ascension: ${result.rightAscension.toFixed(2)}h\n`;
          return text;
        }
        return JSON.stringify(result);
      } catch (error) {
        if (error instanceof Error) {
          throw new Error(`Failed to get sun position: ${error.message}`);
        }
        throw new Error('Failed to get sun position');
      }
    }
  });