LocalTides MCP Server

Instructions

Implementation Reference

• src/tools/moon-tools.ts:18-31 (handler)

  The execute handler for the 'get_moon_phase' tool. It invokes the moon phase service, formats the output as text or JSON based on the 'format' parameter, and handles errors.

  execute: async (params) => {
    try {
      const result = moonPhaseService.getMoonPhase(params);
      if (params.format === 'text') {
        return `Moon phase for ${result.date}: ${result.phaseName} (${(result.illumination * 100).toFixed(1)}% illuminated)`;
      }
      return JSON.stringify(result);
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`Failed to get moon phase: ${error.message}`);
      }
      throw new Error('Failed to get moon phase');
    }
  }

• src/interfaces/moon.ts:7-12 (schema)

  Zod schema defining the input parameters for the 'get_moon_phase' tool.

  export const MoonPhaseParamsSchema = z.object({
    date: z.string().optional().describe('Date to get moon phase for (YYYY-MM-DD format). Defaults to current date.'),
    latitude: z.number().min(-90).max(90).optional().describe('Latitude for location-specific calculations'),
    longitude: z.number().min(-180).max(180).optional().describe('Longitude for location-specific calculations'),
    format: z.enum(['json', 'text']).optional().describe('Output format (json or text)')
  });

• src/tools/moon-tools.ts:14-32 (registration)

  Registration of the 'get_moon_phase' tool on the MCP server, specifying name, description, parameters schema, and execute handler.

  server.addTool({
    name: 'get_moon_phase',
    description: 'Get moon phase information for a specific date',
    parameters: MoonPhaseParamsSchema,
    execute: async (params) => {
      try {
        const result = moonPhaseService.getMoonPhase(params);
        if (params.format === 'text') {
          return `Moon phase for ${result.date}: ${result.phaseName} (${(result.illumination * 100).toFixed(1)}% illuminated)`;
        }
        return JSON.stringify(result);
      } catch (error) {
        if (error instanceof Error) {
          throw new Error(`Failed to get moon phase: ${error.message}`);
        }
        throw new Error('Failed to get moon phase');
      }
    }
  });

• src/services/moon-phase-service.ts:14-48 (helper)

  Core helper function in MoonPhaseService that computes detailed moon phase information using SunCalc library for illumination, position, phase name, age, distance, etc.

  getMoonPhase(params: MoonPhaseParams): MoonPhaseInfo {
    const date = params.date ? new Date(params.date) : new Date();
    
    // Get moon illumination data
    const illuminationData = SunCalc.getMoonIllumination(date);
    
    // Get moon position data (requires location)
    const latitude = params.latitude ?? 0;
    const longitude = params.longitude ?? 0;
    const positionData = SunCalc.getMoonPosition(date, latitude, longitude);
    
    // Calculate moon phase name
    const phaseName = this.getMoonPhaseName(illuminationData.phase);
    
    // Calculate if the moon is waxing (increasing illumination)
    const isWaxing = illuminationData.phase < 0.5;
    
    // Calculate approximate moon age (0-29.53 days)
    const lunarMonth = 29.53; // days
    const age = illuminationData.phase * lunarMonth;
    
    // Calculate apparent diameter (in degrees)
    const diameter = 0.5181 * (384400 / positionData.distance);
    
    return {
      date: date.toISOString().split('T')[0],
      phase: illuminationData.phase,
      phaseName,
      illumination: illuminationData.fraction,
      age,
      distance: positionData.distance,
      diameter,
      isWaxing
    };
  }