weather-agent-mcp 0.1.4 → 0.1.5

package/.env.example

@@ -9,6 +9,7 @@ ANTHROPIC_MODEL=claude-3-5-haiku-latest
 
 # Open-Meteo base URLs (override in tests with fake server)
 OPEN_METEO_FORECAST_URL=https://api.open-meteo.com
+OPEN_METEO_ARCHIVE_URL=https://archive-api.open-meteo.com
 OPEN_METEO_GEOCODING_URL=https://geocoding-api.open-meteo.com
 
 # Agent defaults

package/README.md

@@ -58,7 +58,7 @@ sudo launchctl config user path "$HOME/.volta/bin:/usr/bin:/bin:/usr/sbin:/sbin"
 
 Без `sudo`: можно `launchctl setenv PATH "$HOME/.volta/bin:/usr/bin:/bin:/usr/sbin:/sbin"` и перезапустить Cursor (сбросится после reboot).
 
-Reload MCP. Tools: `geocode`, `getCurrentWeather`, `getForecast`, `compareWeather`.
+Reload MCP. Tools: `geocode`, `getCurrentWeather`, `getForecast`, `getHistoricalWeather`, `compareWeather`.
 
 ### GitHub Copilot / VS Code
 

package/dist/weather-mcp.js

@@ -34548,6 +34548,7 @@ async function httpJson(url2, options = {}) {
 function defaultConfig(overrides = {}) {
   return {
     forecastBaseUrl: process.env.OPEN_METEO_FORECAST_URL ?? "https://api.open-meteo.com",
+    archiveBaseUrl: process.env.OPEN_METEO_ARCHIVE_URL ?? "https://archive-api.open-meteo.com",
     geocodingBaseUrl: process.env.OPEN_METEO_GEOCODING_URL ?? "https://geocoding-api.open-meteo.com",
     timeoutMs: 1e4,
     retries: 1,
@@ -34728,8 +34729,198 @@ async function getForecast(latitude, longitude, startDate, endDate, config2 = {}
   };
 }
 
+// src/weather/history.ts
+var MAX_HISTORICAL_YEARS = 20;
+var ARCHIVE_FIRST_YEAR = 1940;
+var DAYS_IN_MONTH = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+function assertHistoricalSpan(month, day, startYear, endYear) {
+  if (!Number.isInteger(month) || month < 1 || month > 12) {
+    throw new ToolError("INVALID_DATE_RANGE", `month must be 1-12. Got ${month}`, false);
+  }
+  const maxDay = DAYS_IN_MONTH[month - 1];
+  if (!Number.isInteger(day) || day < 1 || day > maxDay) {
+    throw new ToolError(
+      "INVALID_DATE_RANGE",
+      `day must be 1-${maxDay} for month ${month}. Got ${day}`,
+      false
+    );
+  }
+  if (!Number.isInteger(startYear) || !Number.isInteger(endYear)) {
+    throw new ToolError(
+      "INVALID_DATE_RANGE",
+      `startYear and endYear must be integers. Got ${startYear}..${endYear}`,
+      false
+    );
+  }
+  if (startYear < ARCHIVE_FIRST_YEAR) {
+    throw new ToolError(
+      "INVALID_DATE_RANGE",
+      `startYear must be >= ${ARCHIVE_FIRST_YEAR}. Got ${startYear}`,
+      false
+    );
+  }
+  const thisYear = (/* @__PURE__ */ new Date()).getUTCFullYear();
+  if (endYear > thisYear) {
+    throw new ToolError(
+      "INVALID_DATE_RANGE",
+      `endYear must be <= ${thisYear}. Got ${endYear}`,
+      false
+    );
+  }
+  if (startYear > endYear) {
+    throw new ToolError(
+      "INVALID_DATE_RANGE",
+      `startYear (${startYear}) must be <= endYear (${endYear})`,
+      false
+    );
+  }
+  const span = endYear - startYear + 1;
+  if (span > MAX_HISTORICAL_YEARS) {
+    throw new ToolError(
+      "INVALID_DATE_RANGE",
+      `At most ${MAX_HISTORICAL_YEARS} years per call. Got ${span} (${startYear}..${endYear})`,
+      false
+    );
+  }
+}
+function isoDate(year, month, day) {
+  const m = String(month).padStart(2, "0");
+  const d = String(day).padStart(2, "0");
+  return `${year}-${m}-${d}`;
+}
+function isRealCalendarDate(year, month, day) {
+  const dt = new Date(Date.UTC(year, month - 1, day));
+  return dt.getUTCFullYear() === year && dt.getUTCMonth() === month - 1 && dt.getUTCDate() === day;
+}
+function num(value, label) {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    throw new ToolError("MALFORMED_RESPONSE", `Archive field ${label} is missing`, false);
+  }
+  return value;
+}
+function round1(n) {
+  return Math.round(n * 10) / 10;
+}
+async function mapPool(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  async function worker() {
+    for (; ; ) {
+      const i = next;
+      next += 1;
+      if (i >= items.length) return;
+      out[i] = await fn(items[i]);
+    }
+  }
+  const workers = Math.min(limit, items.length);
+  await Promise.all(Array.from({ length: workers }, () => worker()));
+  return out;
+}
+async function fetchYear(year, month, day, latitude, longitude, cfg) {
+  const date5 = isoDate(year, month, day);
+  if (!isRealCalendarDate(year, month, day)) {
+    return { ok: false, unavailable: { year, reason: `${date5} is not a calendar date` } };
+  }
+  try {
+    const data = await meteoGet(
+      cfg.archiveBaseUrl,
+      "/v1/archive",
+      {
+        latitude,
+        longitude,
+        daily: "temperature_2m_max,temperature_2m_min,temperature_2m_mean,precipitation_sum,snowfall_sum,weather_code,wind_speed_10m_max",
+        timezone: "auto",
+        start_date: date5,
+        end_date: date5
+      },
+      cfg
+    );
+    const daily = data.daily;
+    const time3 = daily?.time?.[0];
+    if (!daily || !time3) {
+      return { ok: false, unavailable: { year, reason: `No archive data for ${date5}` } };
+    }
+    const code = num(daily.weather_code?.[0], "weather_code");
+    return {
+      ok: true,
+      timezone: data.timezone,
+      latitude: data.latitude,
+      longitude: data.longitude,
+      row: {
+        year,
+        date: time3,
+        tempMaxC: num(daily.temperature_2m_max?.[0], "temperature_2m_max"),
+        tempMinC: num(daily.temperature_2m_min?.[0], "temperature_2m_min"),
+        tempMeanC: num(daily.temperature_2m_mean?.[0], "temperature_2m_mean"),
+        precipitationMm: num(daily.precipitation_sum?.[0], "precipitation_sum"),
+        snowfallCm: num(daily.snowfall_sum?.[0], "snowfall_sum"),
+        windSpeedMaxKmh: num(daily.wind_speed_10m_max?.[0], "wind_speed_10m_max"),
+        weatherCode: code,
+        weatherDescription: describeWmo(code)
+      }
+    };
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return { ok: false, unavailable: { year, reason } };
+  }
+}
+function summarize(years) {
+  const n = years.length;
+  const avg = (pick2) => round1(years.reduce((sum, y) => sum + pick2(y), 0) / n);
+  const wettest = years.reduce((best, y) => y.precipitationMm > best.precipitationMm ? y : best);
+  const warmest = years.reduce((best, y) => y.tempMaxC > best.tempMaxC ? y : best);
+  const coldest = years.reduce((best, y) => y.tempMinC < best.tempMinC ? y : best);
+  return {
+    avgTempMeanC: avg((y) => y.tempMeanC),
+    avgTempMaxC: avg((y) => y.tempMaxC),
+    avgTempMinC: avg((y) => y.tempMinC),
+    rainyDays: years.filter((y) => y.precipitationMm > 0).length,
+    wettestYear: wettest.year,
+    wettestPrecipitationMm: wettest.precipitationMm,
+    warmestYear: warmest.year,
+    warmestTempMaxC: warmest.tempMaxC,
+    coldestYear: coldest.year,
+    coldestTempMinC: coldest.tempMinC
+  };
+}
+async function getHistoricalWeather(latitude, longitude, month, day, startYear, endYear, config2 = {}) {
+  assertHistoricalSpan(month, day, startYear, endYear);
+  const cfg = defaultConfig(config2);
+  const years = Array.from({ length: endYear - startYear + 1 }, (_, i) => startYear + i);
+  const outcomes = await mapPool(
+    years,
+    5,
+    (year) => fetchYear(year, month, day, latitude, longitude, cfg)
+  );
+  const rows = outcomes.flatMap((o) => o.ok ? [o.row] : []);
+  const unavailable = outcomes.flatMap((o) => o.ok ? [] : [o.unavailable]);
+  if (rows.length === 0) {
+    const first = unavailable[0]?.reason ?? "no data";
+    throw new ToolError(
+      "INVALID_DATE_RANGE",
+      `Archive returned no days for ${month}/${day} in ${startYear}..${endYear}: ${first}`,
+      false,
+      { unavailable }
+    );
+  }
+  const sample = outcomes.find((o) => o.ok);
+  return {
+    latitude: sample && sample.ok ? sample.latitude : latitude,
+    longitude: sample && sample.ok ? sample.longitude : longitude,
+    timezone: sample && sample.ok ? sample.timezone : "UTC",
+    month,
+    day,
+    startYear,
+    endYear,
+    source: "open-meteo-archive",
+    years: rows,
+    unavailable,
+    summary: summarize(rows)
+  };
+}
+
 // src/weather/compare.ts
-function summarize(forecast) {
+function summarize2(forecast) {
   const n = forecast.days.length || 1;
   const avgTempMaxC = forecast.days.reduce((s, d) => s + d.tempMaxC, 0) / n;
   const avgTempMinC = forecast.days.reduce((s, d) => s + d.tempMinC, 0) / n;
@@ -34758,7 +34949,7 @@ async function compareWeather(locations, startDate, endDate, config2 = {}) {
       return {
         name: loc.name,
         forecast,
-        summary: summarize(forecast)
+        summary: summarize2(forecast)
       };
     })
   );
@@ -34844,6 +35035,55 @@ var ForecastOutputSchema = external_exports.object({
   endDate: external_exports.string(),
   days: external_exports.array(DailyForecastSchema)
 });
+var HistoricalWeatherInputSchema = external_exports.object({
+  latitude: external_exports.number().min(-90).max(90),
+  longitude: external_exports.number().min(-180).max(180),
+  month: external_exports.number().int().min(1).max(12).describe("Calendar month, 1-12"),
+  day: external_exports.number().int().min(1).max(31).describe("Day of month"),
+  startYear: external_exports.number().int().describe("First year, inclusive"),
+  endYear: external_exports.number().int().describe("Last year, inclusive")
+});
+var HistoricalYearSchema = external_exports.object({
+  year: external_exports.number(),
+  date: external_exports.string(),
+  tempMaxC: external_exports.number(),
+  tempMinC: external_exports.number(),
+  tempMeanC: external_exports.number(),
+  precipitationMm: external_exports.number(),
+  snowfallCm: external_exports.number(),
+  windSpeedMaxKmh: external_exports.number(),
+  weatherCode: external_exports.number(),
+  weatherDescription: external_exports.string()
+});
+var HistoricalWeatherOutputSchema = external_exports.object({
+  latitude: external_exports.number(),
+  longitude: external_exports.number(),
+  timezone: external_exports.string(),
+  month: external_exports.number(),
+  day: external_exports.number(),
+  startYear: external_exports.number(),
+  endYear: external_exports.number(),
+  source: external_exports.literal("open-meteo-archive"),
+  years: external_exports.array(HistoricalYearSchema),
+  unavailable: external_exports.array(
+    external_exports.object({
+      year: external_exports.number(),
+      reason: external_exports.string()
+    })
+  ),
+  summary: external_exports.object({
+    avgTempMeanC: external_exports.number(),
+    avgTempMaxC: external_exports.number(),
+    avgTempMinC: external_exports.number(),
+    rainyDays: external_exports.number(),
+    wettestYear: external_exports.number(),
+    wettestPrecipitationMm: external_exports.number(),
+    warmestYear: external_exports.number(),
+    warmestTempMaxC: external_exports.number(),
+    coldestYear: external_exports.number(),
+    coldestTempMinC: external_exports.number()
+  })
+});
 var CompareWeatherInputSchema = external_exports.object({
   locations: external_exports.array(LocationSchema).min(2).describe("Locations to compare"),
   startDate: external_exports.string().describe("Start date YYYY-MM-DD"),
@@ -34923,6 +35163,30 @@ function createWeatherMcpServer() {
       }
     }
   );
+  server.registerTool(
+    "getHistoricalWeather",
+    {
+      title: "Historical weather on a calendar day",
+      description: "Get historical daily weather for the same calendar day across startYear..endYear (inclusive, at most 20 years) from the Open-Meteo archive (ERA5 reanalysis, not a single weather station). Use for questions like 'what was the weather on 28 September for the last 10 years'. Returns per-year min/mean/max temperature (\xB0C), precipitation (mm), snowfall (cm), max wind (km/h), WMO description, plus summary stats. Years that are not a real date (e.g. 29 Feb) or not yet in the archive (about a 5-day delay) are listed in unavailable. Do not use getForecast for dates older than the forecast window.",
+      inputSchema: HistoricalWeatherInputSchema,
+      outputSchema: HistoricalWeatherOutputSchema
+    },
+    async ({ latitude, longitude, month, day, startYear, endYear }) => {
+      try {
+        const result = await getHistoricalWeather(
+          latitude,
+          longitude,
+          month,
+          day,
+          startYear,
+          endYear
+        );
+        return okResult(result);
+      } catch (err) {
+        return errResult(err);
+      }
+    }
+  );
   server.registerTool(
     "compareWeather",
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weather-agent-mcp",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Model-agnostic AI agent with MCP tools over Open-Meteo",
   "type": "module",
   "engines": {