Get Hourly Forecast

Instructions

Implementation Reference

• src/weather/tools.ts:87-93 (handler)

  The async handler that executes the 'get_hourly_forecast' tool logic. It receives {latitude, longitude, hours}, calls fetchHourlyForecast, and returns the result via okUntrusted.

  async ({ latitude, longitude, hours }) => {
    try {
      return okUntrusted(await fetchHourlyForecast(latitude, longitude, hours));
    } catch (e) {
      return errUpstreamFor("get hourly forecast", e, { retryable: true });
    }
  },

• src/weather/tools.ts:70-84 (schema)

  Input schema and tool definition for 'get_hourly_forecast'. Defines latitude, longitude (required), and hours (optional, default 24, max 168).

  {
    title: "Get Hourly Forecast",
    description: "Get hourly weather forecast for a location.",
    inputSchema: {
      latitude: z.number().min(-90).max(90).describe("Latitude coordinate"),
      longitude: z.number().min(-180).max(180).describe("Longitude coordinate"),
      hours: z
        .number()
        .int()
        .min(1)
        .max(168)
        .optional()
        .default(24)
        .describe("Number of forecast hours (default: 24)"),
    },

• src/weather/tools.ts:68-94 (registration)

  Registration of the 'get_hourly_forecast' tool via server.registerTool() inside registerWeatherTools().

  server.registerTool(
    "get_hourly_forecast",
    {
      title: "Get Hourly Forecast",
      description: "Get hourly weather forecast for a location.",
      inputSchema: {
        latitude: z.number().min(-90).max(90).describe("Latitude coordinate"),
        longitude: z.number().min(-180).max(180).describe("Longitude coordinate"),
        hours: z
          .number()
          .int()
          .min(1)
          .max(168)
          .optional()
          .default(24)
          .describe("Number of forecast hours (default: 24)"),
      },
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
    },
    async ({ latitude, longitude, hours }) => {
      try {
        return okUntrusted(await fetchHourlyForecast(latitude, longitude, hours));
      } catch (e) {
        return errUpstreamFor("get hourly forecast", e, { retryable: true });
      }
    },
  );

• src/weather/api.ts:105-124 (helper)

  The fetchHourlyForecast helper function that calls the Open-Meteo API with hourly parameters and maps the response to an array of hourly forecast objects.

  export async function fetchHourlyForecast(latitude: number, longitude: number, hours: number) {
    const data = await fetchOpenMeteo(latitude, longitude, {
      hourly:
        "temperature_2m,relative_humidity_2m,apparent_temperature,weather_code,precipitation,precipitation_probability,wind_speed_10m,cloud_cover",
      forecast_hours: String(hours),
    });
    const h = data.hourly;
    return h.time.map((time: string, i: number) => ({
      time,
      temperature: h.temperature_2m[i],
      feelsLike: h.apparent_temperature[i],
      humidity: h.relative_humidity_2m[i],
      weatherCode: h.weather_code[i],
      weatherDescription: describeWeatherCode(h.weather_code[i]),
      precipitation: h.precipitation[i],
      precipitationProbability: h.precipitation_probability[i],
      windSpeed: h.wind_speed_10m[i],
      cloudCover: h.cloud_cover[i],
    }));
  }

• src/weather/api.ts:46-62 (helper)

  Low-level fetchOpenMeteo helper that builds the URL, calls the Open-Meteo API, and returns the JSON response. Used by fetchHourlyForecast.

  async function fetchOpenMeteo(
    latitude: number,
    longitude: number,
    extra: Record<string, string>,
  ): Promise<OpenMeteoResponse> {
    const params = new URLSearchParams({
      latitude: String(latitude),
      longitude: String(longitude),
      timezone: "auto",
      ...extra,
    });
    const res = await fetch(`${BASE_URL}?${params}`, {
      signal: AbortSignal.timeout(TIMEOUT.GEOCODE),
    });
    if (!res.ok) throw new Error(`Open-Meteo API error: ${res.status} ${res.statusText}`);
    return (await res.json()) as OpenMeteoResponse;
  }