mcp-meteoblue 1.0.0 → 1.0.2

package/README.md

@@ -10,6 +10,20 @@ An MCP server for the [meteoblue Weather API](https://docs.meteoblue.com/en/weat
 
 Place names passed to forecast or image tools are always resolved through the official meteoblue Location Search API. Forecast package inputs are restricted to the packages listed in the Free Weather API documentation.
 
+`get_forecast` can restrict hourly output to a local time range. For example, tomorrow from 14:00 through 16:00 (inclusive):
+
+```json
+{
+  "location": "Paris",
+  "forecastDays": 2,
+  "dayOffset": 1,
+  "startHour": "14:00",
+  "endHour": "16:00"
+}
+```
+
+You can use an explicit `date` such as `2026-08-24` instead of `dayOffset`. An end time earlier than the start time represents an overnight range. When a range is specified, the server requests `basic-1h` automatically and returns only the hourly data inside that range.
+
 > [!NOTE]
 > meteoblue's current Free Weather API documentation says that images require a higher access level. The image tool is included for keys with an Image API entitlement and will return a clear authorization error otherwise.
 
@@ -46,6 +60,39 @@ METEOBLUE_API_KEY=your_api_key_here npx -y mcp-meteoblue
 
 The server uses stdio, so it intentionally produces no normal terminal output while it waits for an MCP client.
 
+## Docker
+
+Build the image locally:
+
+```sh
+docker build -t mcp-meteoblue .
+```
+
+Configure a Docker-based stdio server in your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "meteoblue": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "--env",
+        "METEOBLUE_API_KEY",
+        "mcp-meteoblue"
+      ],
+      "env": {
+        "METEOBLUE_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+The container runs as the unprivileged `node` user. Keep stdin open with `-i` because MCP communication uses stdio.
+
 ## Develop locally
 
 ```sh
@@ -58,9 +105,9 @@ Point an MCP client at `node /absolute/path/to/mcp-meteoblue/src/index.js` and s
 
 ## Releases
 
-GitHub Actions runs the test suite and validates the npm tarball on Node.js 20, 22, 24, and 26 for every push and pull request.
+GitHub Actions runs the test suite and validates the npm tarball on Node.js 20, 22, 24, and 26 for every push and pull request. Dependabot checks npm and GitHub Actions dependencies weekly.
 
-Publishing a GitHub release triggers `.github/workflows/publish.yml`. The workflow uses npm trusted publishing (OIDC) and automatically attaches provenance. Configure the npm trusted publisher with:
+Pushing a `v*` Git tag triggers `.github/workflows/publish.yml`. The workflow uses npm trusted publishing (OIDC) and automatically attaches provenance. Configure the npm trusted publisher with:
 
 - GitHub owner: `unixfox`
 - Repository: `mcp-meteoblue`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-meteoblue",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "MCP server for meteoblue forecast, forecast image, and location search APIs",
   "type": "module",
   "bin": {

package/src/meteoblue.js

@@ -93,7 +93,7 @@ export class MeteoblueClient {
   async #fetch(url) {
     try {
       return await this.fetch(url, {
-        headers: { "user-agent": "mcp-meteoblue/1.0.0" },
+        headers: { "user-agent": "mcp-meteoblue/1.0.2" },
         signal: AbortSignal.timeout(this.timeoutMs)
       });
     } catch (error) {

package/src/server.js

@@ -7,6 +7,7 @@ const latitude = z.number().min(-90).max(90).optional().describe("WGS84 latitude
 const longitude = z.number().min(-180).max(180).optional().describe("WGS84 longitude; required with latitude when location is omitted");
 const elevation = z.number().min(-500).max(9000).optional().describe("Elevation above sea level in metres");
 const location = z.string().min(2).optional().describe("Place name, postal code, IATA, or ICAO code; resolved with meteoblue Location Search");
+const hour = z.string().regex(/^(?:[01]\d|2[0-3]):[0-5]\d$/).optional();
 
 function textResult(value) {
   return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
@@ -35,9 +36,93 @@ async function coordinatesFor(client, input) {
   return { latitude: input.latitude, longitude: input.longitude, elevation: input.elevation };
 }
 
+function minutesSinceMidnight(value) {
+  const [hours, minutes] = value.split(":").map(Number);
+  return hours * 60 + minutes;
+}
+
+function datePart(value) {
+  return value.slice(0, 10);
+}
+
+function timePart(value) {
+  const match = value.match(/(?:T|\s)(\d{2}):(\d{2})/);
+  return match ? `${match[1]}:${match[2]}` : undefined;
+}
+
+function addDays(isoDate, days) {
+  const date = new Date(`${isoDate}T00:00:00Z`);
+  date.setUTCDate(date.getUTCDate() + days);
+  return date.toISOString().slice(0, 10);
+}
+
+export function filterHourlyForecast(forecast, { startHour, endHour, date, dayOffset }) {
+  const hourly = forecast.data_1h;
+  if (!hourly?.time?.length) {
+    throw new Error("meteoblue returned no hourly data for the requested range");
+  }
+
+  const availableDates = [...new Set(hourly.time.map(datePart))];
+  const targetDate = date ?? (dayOffset !== undefined ? availableDates[dayOffset] : undefined);
+  if ((date || dayOffset !== undefined) && !targetDate) {
+    throw new Error("The requested date is outside the returned forecast period");
+  }
+
+  const startMinutes = minutesSinceMidnight(startHour);
+  const endMinutes = minutesSinceMidnight(endHour);
+  const crossesMidnight = endMinutes < startMinutes;
+  const nextDate = targetDate && crossesMidnight ? addDays(targetDate, 1) : undefined;
+  const selectedIndices = [];
+
+  for (const [index, timestamp] of hourly.time.entries()) {
+    const rowDate = datePart(timestamp);
+    const rowTime = timePart(timestamp);
+    if (!rowTime) continue;
+    const rowMinutes = minutesSinceMidnight(rowTime);
+
+    let selected;
+    if (targetDate) {
+      selected = crossesMidnight
+        ? (rowDate === targetDate && rowMinutes >= startMinutes) || (rowDate === nextDate && rowMinutes <= endMinutes)
+        : rowDate === targetDate && rowMinutes >= startMinutes && rowMinutes <= endMinutes;
+    } else {
+      selected = crossesMidnight
+        ? rowMinutes >= startMinutes || rowMinutes <= endMinutes
+        : rowMinutes >= startMinutes && rowMinutes <= endMinutes;
+    }
+    if (selected) selectedIndices.push(index);
+  }
+
+  if (!selectedIndices.length) {
+    throw new Error("No hourly forecast data falls within the requested range");
+  }
+
+  const filteredHourly = Object.fromEntries(
+    Object.entries(hourly).map(([key, value]) => [
+      key,
+      Array.isArray(value) && value.length === hourly.time.length
+        ? selectedIndices.map((index) => value[index])
+        : value
+    ])
+  );
+
+  return {
+    metadata: forecast.metadata,
+    units: forecast.units,
+    requestedRange: {
+      startHour,
+      endHour,
+      ...(targetDate ? { date: targetDate } : {}),
+      inclusive: true,
+      crossesMidnight
+    },
+    data_1h: filteredHourly
+  };
+}
+
 export function createServer({ apiKey = process.env.METEOBLUE_API_KEY, client } = {}) {
   const meteoblue = client || new MeteoblueClient({ apiKey });
-  const server = new McpServer({ name: "mcp-meteoblue", version: "1.0.0" });
+  const server = new McpServer({ name: "mcp-meteoblue", version: "1.0.2" });
 
   server.registerTool(
     "search_locations",
@@ -65,7 +150,7 @@ export function createServer({ apiKey = process.env.METEOBLUE_API_KEY, client }
     "get_forecast",
     {
       title: "Get meteoblue weather forecast",
-      description: "Get meteoblue forecast JSON by place name or coordinates. Place names are resolved through the Location Search API. Only packages documented for the Free Weather API are accepted.",
+      description: "Get meteoblue forecast JSON by place name or coordinates. Place names are resolved through the Location Search API. For a specific time window, provide startHour and endHour plus either date or dayOffset; the tool then returns only inclusive basic-1h rows in that range.",
       inputSchema: {
         location,
         latitude,
@@ -79,13 +164,39 @@ export function createServer({ apiKey = process.env.METEOBLUE_API_KEY, client }
         timezone: z.string().optional().describe("IANA timezone such as Europe/Paris; auto-detected when omitted"),
         temperatureUnit: z.enum(["C", "K", "F"]).default("C"),
         windSpeedUnit: z.enum(["m/s", "km/h", "mph", "kn", "bft"]).default("km/h"),
-        precipitationUnit: z.enum(["metric", "imperial"]).default("metric")
+        precipitationUnit: z.enum(["metric", "imperial"]).default("metric"),
+        startHour: hour.describe("Inclusive local start time in HH:mm format, for example 14:00; must be used with endHour"),
+        endHour: hour.describe("Inclusive local end time in HH:mm format, for example 16:00; must be used with startHour"),
+        date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("Local forecast date in YYYY-MM-DD format for the hour range"),
+        dayOffset: z.number().int().min(0).max(6).optional().describe("Forecast day for the hour range: 0 is today/first returned day, 1 is tomorrow; use instead of date")
       }
     },
     async (input) => {
       try {
+        const hasHourRange = input.startHour !== undefined || input.endHour !== undefined;
+        if (hasHourRange && (!input.startHour || !input.endHour)) {
+          throw new Error("startHour and endHour must be provided together");
+        }
+        if (!hasHourRange && (input.date || input.dayOffset !== undefined)) {
+          throw new Error("date and dayOffset can only be used with startHour and endHour");
+        }
+        if (input.date && input.dayOffset !== undefined) {
+          throw new Error("Use either date or dayOffset, not both");
+        }
+
         const coords = await coordinatesFor(meteoblue, input);
-        const forecast = await meteoblue.getForecast({ ...input, ...coords });
+        const request = hasHourRange
+          ? {
+              ...input,
+              packages: ["basic-1h"],
+              forecastDays: input.dayOffset !== undefined
+                ? Math.max(input.forecastDays, input.dayOffset + 1)
+                : input.forecastDays,
+              ...coords
+            }
+          : { ...input, ...coords };
+        const rawForecast = await meteoblue.getForecast(request);
+        const forecast = hasHourRange ? filterHourlyForecast(rawForecast, input) : rawForecast;
         return textResult({ resolvedLocation: coords.resolvedLocation, forecast });
       } catch (error) {
         return errorResult(error);