@pipeworx/mcp-aviationstack 0.1.2 → 0.1.3

package/README.md

@@ -1,8 +1,8 @@
 # @pipeworx/aviationstack
 
-Aviationstack MCP — global flight tracking + airport / airline / route reference data. Free tier: 100 req/month.
+Aviationstack MCP — global flight tracking + airport / airline / route reference data.
 
-Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1683+ live data sources.
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1689+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.
 
 ## Tools
 
@@ -12,19 +12,29 @@ Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents
 - `cities(search?, iata_code?, country_iso2?, limit?)` — city → primary airport mapping
 - `countries(search?, country_iso2?, limit?)` — country reference
 - `routes(dep_iata?, arr_iata?, airline_iata?, flight_number?, limit?)` — scheduled routes
+- `aviationstack_future_flights(iataCode, type, date, airline_iata?, airline_icao?, flight_number?, limit?, offset?)` — scheduled future flights at one airport for a specific date (`type`: `departure` or `arrival`). Backed by Aviationstack's `/flightsFuture` endpoint, which apilayer's 2026-10-06 notice opened only for the **next 7 days** — `date` must be `tomorrow..today+7` (UTC); the pack refuses out-of-window dates itself before calling upstream (fleet #2700).
 
 ## Auth
 
 - **Platform key:** gateway env `PLATFORM_AVIATIONSTACK_KEY`
 - **BYO:** `?_apiKey=<key>` after registering at https://aviationstack.com/signup/free
 
-### Free-plan limits
+### Plan tier
 
-Only the `flights` endpoint works on the free tier. `airports`, `airlines`, `cities`, `countries`, `routes` return HTTP 403 `function_access_restricted`. Upgrade to Basic (~$50/mo) to unlock them. Free plan is HTTP-only (no https) — the pack already uses `http://`.
+As of 2026-10-06 the shared platform key is on a plan that reaches `flights`, `airports`,
+`airlines`, `cities`, `countries` and `routes` live (verified: `airports`/JFK and
+`routes`/JFK→LAX both returned non-empty data — neither is free-tier-only any more; an
+earlier version of this README, written 2026-08-28, said otherwise and was stale).
+`aviationstack_future_flights` was added the same day the vendor emailed that they opened
+`/flightsFuture` more broadly; whether our specific plan reaches *that* endpoint was not
+independently confirmed before this tool shipped (the platform key's raw value is a
+Cloudflare/Supabase secret, not available to a pack-authoring session) — if a live call
+answers HTTP 403 `function_access_restricted`, that means the plan doesn't cover this
+endpoint yet and is a money/plan decision, not a pack bug.
 
-The free plan is also capped at **100 requests per month**, and once that is spent every
-endpoint answers 429 — including the ones the tier would otherwise allow. As of 2026-08-28
-the shared key is in that state (`routes` and `airports`, zero successes in seven days).
+The free plan (if the platform key ever reverts to it) is capped at **100 requests per
+month**, and once that is spent every endpoint answers 429 — including ones the tier would
+otherwise allow. Free plan is also HTTP-only (no https) — the pack already uses `http://`.
 
 **Reading a 429 here:** Aviationstack labels the monthly-allowance refusal with the code
 `rate_limit_reached` and only says "monthly" in the message text, so the code name argues
@@ -33,7 +43,8 @@ renews. The pack branches on the message, not the code. Fleet #577.
 
 ## Data source
 
-`http://api.aviationstack.com/v1/` — `access_key` query param.
+`http://api.aviationstack.com/v1/` — `access_key` query param. `/flightsFuture` spec:
+https://api.swaggerhub.com/apis/apilayer-863/AviationstackAPI/1.0.0/swagger.json
 
 ## Quick Start
 
@@ -79,7 +90,7 @@ directly, instead of just this one's:
 }
 ```
 
-Both URLs reach the same gateway and the same 1683+ data sources. The
+Both URLs reach the same gateway and the same 1689+ data sources. The
 only difference is which pack's tools are listed **directly**; `ask_pipeworx`
 reaches all of them from either one.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipeworx/mcp-aviationstack",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Aviationstack MCP — global flight + airport + airline data",
   "type": "module",
   "main": "src/index.ts",
@@ -26,7 +26,7 @@
     "@cloudflare/workers-types": "^4.20260405.1"
   },
   "pipeworx": {
-    "sourceHash": "v1-17d9a3d7acdd3fb0a4f2e81daafc56c2e3068f281d2a5e064fece8a70284b339",
-    "sourceCommit": "454041882179fae560c06e770b6b7a2f33970015"
+    "sourceHash": "v1-935ef0d23982e69db2037243fd0cba3475b438663a5b5a288b9f7e2189c770fe",
+    "sourceCommit": "211a6d307878cf994dd13cc72b7c2921b47759a7"
   }
 }

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.pipeworx-io/aviationstack",
   "title": "Aviationstack",
   "description": "Aviationstack MCP — global flight + airport + airline data",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "websiteUrl": "https://pipeworx.io/packs/aviationstack",
   "repository": {
     "url": "https://github.com/pipeworx-io/mcp-aviationstack",

package/src/index.ts

@@ -777,6 +777,109 @@ const tools: McpToolExport['tools'] = [
       },
     },
   },
+  {
+    // apilayer emailed developer@mojibake.ai on 2026-10-06 ("What the new
+    // /flightsFuture range changes for your app"): they opened this endpoint
+    // to cover the next 7 days for itinerary/booking views. Vendor spec:
+    // https://api.swaggerhub.com/apis/apilayer-863/AviationstackAPI/1.0.0/swagger.json
+    // (paths./v1/flightsFuture — iataCode + type + date all required; date
+    // format YYYY-MM-DD). The 7-day window is the vendor's own notice, not a
+    // field the swagger spec encodes, so it is enforced here rather than left
+    // to a far-future call failing late and unexplained (fleet #2700).
+    name: 'aviationstack_future_flights',
+    description:
+      "Scheduled future flights at one airport, from Aviationstack's /flightsFuture endpoint — what flies a route on a day next week. Requires an IATA airport code, a direction (departure or arrival), and a date; returns each flight's number, airline, aircraft model, and scheduled terminal/gate/time. Aviationstack's booking-view window for this endpoint currently covers only the next 7 days (apilayer notice, 2026-10-06): date must be between tomorrow and 7 days from today — a date outside that window is refused before the call is made, not after a wasted round trip.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        iataCode: { type: 'string', description: '3-letter IATA airport code whose schedule to look up (e.g. "JFK")' },
+        type: {
+          type: 'string',
+          enum: ['departure', 'arrival'],
+          description: 'Whether to return flights scheduled to depart or arrive at iataCode',
+        },
+        date: {
+          type: 'string',
+          description:
+            'Future date, format YYYY-MM-DD, must fall within tomorrow through 7 days from today (UTC) — Aviationstack\'s current flightsFuture window.',
+        },
+        airline_iata: { type: 'string', description: 'Filter by airline IATA code' },
+        airline_icao: { type: 'string', description: 'Filter by airline ICAO code' },
+        flight_number: { type: 'string', description: 'Filter by flight number' },
+        limit: { type: 'number', description: '1-100 (default 100)' },
+        offset: { type: 'number', description: '0-based offset' },
+      },
+      required: ['iataCode', 'type', 'date'],
+    },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        pagination: {
+          type: 'object',
+          properties: {
+            limit: { type: 'number' },
+            offset: { type: 'number' },
+            count: { type: 'number' },
+            total: { type: 'number' },
+          },
+        },
+        data: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              weekday: { type: ['string', 'null'], description: 'ISO weekday number 1-7 as a string' },
+              departure: {
+                type: 'object',
+                properties: {
+                  iataCode: { type: ['string', 'null'] },
+                  icaoCode: { type: ['string', 'null'] },
+                  terminal: { type: ['string', 'null'] },
+                  gate: { type: ['string', 'null'] },
+                  scheduledTime: { type: ['string', 'null'], description: 'Local time, HH:MM' },
+                },
+              },
+              arrival: {
+                type: 'object',
+                properties: {
+                  iataCode: { type: ['string', 'null'] },
+                  icaoCode: { type: ['string', 'null'] },
+                  terminal: { type: ['string', 'null'] },
+                  gate: { type: ['string', 'null'] },
+                  scheduledTime: { type: ['string', 'null'], description: 'Local time, HH:MM' },
+                },
+              },
+              aircraft: {
+                type: ['object', 'null'],
+                properties: {
+                  modelCode: { type: ['string', 'null'] },
+                  modelText: { type: ['string', 'null'] },
+                },
+              },
+              airline: {
+                type: 'object',
+                properties: {
+                  name: { type: ['string', 'null'] },
+                  iataCode: { type: ['string', 'null'] },
+                  icaoCode: { type: ['string', 'null'] },
+                },
+              },
+              flight: {
+                type: 'object',
+                properties: {
+                  number: { type: ['string', 'null'] },
+                  iataNumber: { type: ['string', 'null'] },
+                  icaoNumber: { type: ['string', 'null'] },
+                },
+              },
+              codeshared: { type: ['object', 'null'] },
+            },
+          },
+        },
+        data_as_of: { type: 'string', description: 'ISO timestamp when this response was fetched live from Aviationstack' },
+      },
+    },
+  },
 ];
 
 async function callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
@@ -786,6 +889,11 @@ async function callTool(name: string, args: Record<string, unknown>): Promise<un
       'Aviationstack requires an API key. Contact the operator about platform credentials, or BYO via ?_apiKey=<key> after registering at https://aviationstack.com/signup/free.',
     );
   }
+
+  if (name === 'aviationstack_future_flights') {
+    return getFutureFlights(apiKey, args);
+  }
+
   const path = `/${name}`;
   const params = new URLSearchParams({ access_key: apiKey });
   for (const [k, v] of Object.entries(args)) {
@@ -795,6 +903,56 @@ async function callTool(name: string, args: Record<string, unknown>): Promise<un
   return avsGet(`${path}?${params}`);
 }
 
+/**
+ * Validate the date is inside Aviationstack's current flightsFuture window
+ * (tomorrow through 7 days from today, UTC — apilayer notice, 2026-10-06)
+ * BEFORE spending a call on it. Refusing early and by name beats a vendor
+ * 200-with-empty-data or a late 4xx for a date the caller had no way to know
+ * was out of range.
+ */
+function assertWithinFutureWindow(date: string): void {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+    throw new Error(`Aviationstack future_flights: date must be YYYY-MM-DD, got "${date}".`);
+  }
+  const requested = Date.parse(`${date}T00:00:00Z`);
+  if (Number.isNaN(requested)) {
+    throw new Error(`Aviationstack future_flights: "${date}" is not a valid calendar date.`);
+  }
+  const now = new Date();
+  const todayUtc = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+  const DAY_MS = 86_400_000;
+  const minDate = todayUtc + DAY_MS; // tomorrow
+  const maxDate = todayUtc + 7 * DAY_MS; // today + 7
+  if (requested < minDate || requested > maxDate) {
+    const min = new Date(minDate).toISOString().slice(0, 10);
+    const max = new Date(maxDate).toISOString().slice(0, 10);
+    throw new Error(
+      `Aviationstack future_flights: "${date}" is outside the vendor's current flightsFuture window. Aviationstack opened this endpoint to only the next 7 days (apilayer notice, 2026-10-06) — valid range today is ${min} through ${max}. Pass a date inside that range.`,
+    );
+  }
+}
+
+async function getFutureFlights(apiKey: string, args: Record<string, unknown>): Promise<unknown> {
+  const iataCode = (args.iataCode as string | undefined)?.trim();
+  const type = args.type as string | undefined;
+  const date = (args.date as string | undefined)?.trim();
+  if (!iataCode) throw new Error('Aviationstack future_flights: iataCode is required (3-letter airport code, e.g. "JFK").');
+  if (type !== 'departure' && type !== 'arrival') {
+    throw new Error(`Aviationstack future_flights: type must be "departure" or "arrival", got "${type ?? ''}".`);
+  }
+  if (!date) throw new Error('Aviationstack future_flights: date is required (YYYY-MM-DD).');
+  assertWithinFutureWindow(date);
+
+  const params = new URLSearchParams({ access_key: apiKey, iataCode, type, date });
+  for (const k of ['airline_iata', 'airline_icao', 'flight_number', 'limit', 'offset'] as const) {
+    const v = args[k];
+    if (v === undefined || v === null || v === '') continue;
+    params.set(k, String(v));
+  }
+  const data = (await avsGet(`/flightsFuture?${params}`)) as Record<string, unknown>;
+  return { ...data, data_as_of: new Date().toISOString() };
+}
+
 /**
  * Turn an Aviationstack limit refusal into a sentence that says which limit.
  *

package/src/server.ts

@@ -9,7 +9,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import pack from './index.js';
 
 const server = new Server(
-  { name: '@pipeworx/mcp-aviationstack', version: '0.1.2' },
+  { name: '@pipeworx/mcp-aviationstack', version: '0.1.3' },
   { capabilities: { tools: {} } },
 );