noaa-tidesandcurrents-mcp

Instructions

Implementation Reference

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

  Registration of the 'get_moon_phase' tool, including its handler function that delegates to MoonPhaseService and handles text/json formatting

  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 (handler)

  Core handler logic for calculating moon phase information using SunCalc

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

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

  Zod schema defining 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/services/moon-phase-service.ts:144-166 (helper)

  Helper function to determine moon phase name from phase value (used by getMoonPhase)

  private getMoonPhaseName(phase: number): MoonPhaseName {
    // Normalize phase to 0-1 range
    const normalizedPhase = phase < 0 ? phase + 1 : phase > 1 ? phase - 1 : phase;
    
    // Determine moon phase based on the value
    if (normalizedPhase < 0.0625 || normalizedPhase >= 0.9375) {
      return MoonPhaseName.NEW_MOON;
    } else if (normalizedPhase < 0.1875) {
      return MoonPhaseName.WAXING_CRESCENT;
    } else if (normalizedPhase < 0.3125) {
      return MoonPhaseName.FIRST_QUARTER;
    } else if (normalizedPhase < 0.4375) {
      return MoonPhaseName.WAXING_GIBBOUS;
    } else if (normalizedPhase < 0.5625) {
      return MoonPhaseName.FULL_MOON;
    } else if (normalizedPhase < 0.6875) {
      return MoonPhaseName.WANING_GIBBOUS;
    } else if (normalizedPhase < 0.8125) {
      return MoonPhaseName.LAST_QUARTER;
    } else {
      return MoonPhaseName.WANING_CRESCENT;
    }
  }