@pipeworx/mcp-aviationstack 0.1.2 → 0.1.4

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 1847+ 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 1847+ 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.4",
   "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-eec8b23dd927b0fad41b15aba49607560f3a3da5c7fbcab4175b92ef7d403733",
+    "sourceCommit": "54bf7d1c06a0775508a65d0c388dd10ba75174c3"
   }
 }

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.4",
   "websiteUrl": "https://pipeworx.io/packs/aviationstack",
   "repository": {
     "url": "https://github.com/pipeworx-io/mcp-aviationstack",

package/src/index.ts

@@ -670,6 +670,254 @@ function pickMessage(node: unknown, depth: number): string | null {
 function collapse(s: string): string {
   return s.replace(/\s+/g, ' ').trim();
 }
+
+// ── Bounded readers — peak memory, not just wall time (fleet #3322) ──────
+//
+// `parseJson` above does `await res.text()` then `JSON.parse(raw)`, so a
+// multi-megabyte upstream body is held TWICE at peak: once as the raw string
+// and once as the object graph (which for an array of small objects runs
+// several times the byte size). Nothing in `workers/gateway` can see that
+// peak — it happens inside the pack, before any gateway code holds a payload —
+// which is why the gateway-side payload caps of #3293 and #3320 did not move
+// the 503/1102 rate at all.
+//
+// Measured on the live gateway, 2026-10-19, sha fa5de5c34, direct tools/call:
+//   statcan_list_cubes  8,049,566 B   <- one upstream array, no limit argument
+//   gnomad_gene BRCA1   2,732,706 B
+// Five of those in flight at the quality runner's width is ~40 MB of parse
+// peak against a 128 MB isolate; Cloudflare kills the isolate and every
+// request in flight returns 503/1102, which is why the victims look random.
+//
+// `readJsonArrayPrefix` is the fix for the dominant shape: an upstream that
+// returns one enormous top-level JSON array with no server-side paging. It
+// parses elements off the stream and DISCARDS the consumed bytes, so peak
+// retained memory is one element plus one chunk rather than the whole body,
+// and it cancels the body as soon as it has what it was asked for.
+
+/** Default ceiling for a single upstream JSON body read into an isolate.
+ *  Chosen so the known tail (statcan 8.0 MB, gnomad 2.7 MB) is bounded well
+ *  below the point where a handful of concurrent reads exhausts 128 MB. */
+const DEFAULT_MAX_JSON_BYTES = 1_500_000;
+
+interface JsonArrayPrefix<T> {
+  /** The decoded elements, at most `maxItems` of them. */
+  items: T[];
+  /** True when the upstream array had more elements than we read. */
+  truncated: boolean;
+  /** Bytes actually pulled off the socket — the number that bounds memory. */
+  bytesRead: number;
+  /** `Content-Length` if the upstream declared one, else null. */
+  declaredBytes: number | null;
+}
+
+/**
+ * Read the FIRST `maxItems` elements of a top-level JSON array off a response
+ * stream without ever materialising the whole body.
+ *
+ * Use this instead of `parseJson` when the upstream returns one big array and
+ * offers no `limit`/`offset` of its own. Peak retained memory is one element
+ * plus the current chunk; the body is cancelled as soon as `maxItems` is
+ * reached, so the remaining megabytes are never transferred at all.
+ *
+ *     const { items, truncated } = await readJsonArrayPrefix<Cube>(
+ *       res, 'StatCan WDS', { maxItems: limit + offset });
+ *
+ * `maxBytes` is a second, independent backstop for a pathological element (a
+ * single 50 MB object): hitting it stops the read and sets `truncated`, rather
+ * than throwing, because a partial answer plus an explicit truncated flag is
+ * more useful to a caller than an error.
+ */
+async function readJsonArrayPrefix<T>(
+  res: Response,
+  name: string,
+  opts: { maxItems: number; maxBytes?: number },
+): Promise<JsonArrayPrefix<T>> {
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_JSON_BYTES;
+  const declaredRaw = Number(res.headers.get('content-length'));
+  const declaredBytes = Number.isFinite(declaredRaw) && declaredRaw > 0 ? declaredRaw : null;
+
+  // No streaming body available (a mock, or an already-buffered response):
+  // fall back to the whole-text path so behaviour stays correct, just unbounded.
+  if (!res.body) {
+    const all = await parseJson<T[]>(res, name);
+    if (!Array.isArray(all)) throw new Error(`upstream_down: ${name} returned ${typeof all} where a JSON array was expected.`);
+    return {
+      items: all.slice(0, opts.maxItems),
+      truncated: all.length > opts.maxItems,
+      bytesRead: declaredBytes ?? 0,
+      declaredBytes,
+    };
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  const items: T[] = [];
+
+  let buf = '';
+  let scan = 0;
+  let bytesRead = 0;
+  let started = false; // consumed the opening '['
+  let arrayEnded = false;
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  let elemStart = -1;
+  let truncated = false;
+
+  const push = (text: string) => {
+    const t = text.trim();
+    if (!t) return;
+    items.push(JSON.parse(t) as T);
+  };
+
+  try {
+    outer: while (items.length < opts.maxItems && !arrayEnded) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      bytesRead += value.byteLength;
+      buf += decoder.decode(value, { stream: true });
+      if (bytesRead > maxBytes) { truncated = true; break; }
+
+      for (; scan < buf.length; scan++) {
+        const ch = buf[scan];
+
+        if (inStr) {
+          if (esc) { esc = false; continue; }
+          if (ch === '\\') { esc = true; continue; }
+          if (ch === '"') inStr = false;
+          continue;
+        }
+
+        if (!started) {
+          if (ch === '[') { started = true; continue; }
+          if (ch.trim() === '') continue;
+          throw new Error(
+            `upstream_down: ${name} returned a body that does not begin with a JSON array (saw ${JSON.stringify(ch)}). ` +
+              'This reader is only for upstreams that answer with one top-level array.',
+          );
+        }
+
+        if (ch === '"') { if (depth === 0 && elemStart < 0) elemStart = scan; inStr = true; continue; }
+
+        if (ch === '{' || ch === '[') {
+          if (depth === 0 && elemStart < 0) elemStart = scan;
+          depth++;
+          continue;
+        }
+
+        if (ch === '}' || ch === ']') {
+          if (depth > 0) {
+            depth--;
+            if (depth === 0 && elemStart >= 0) {
+              push(buf.slice(elemStart, scan + 1));
+              elemStart = -1;
+              if (items.length >= opts.maxItems) { truncated = true; scan++; break outer; }
+            }
+            continue;
+          }
+          // depth 0 and a closing bracket: the end of the top-level array.
+          if (elemStart >= 0) { push(buf.slice(elemStart, scan)); elemStart = -1; }
+          arrayEnded = true;
+          break outer;
+        }
+
+        if (ch === ',' && depth === 0) {
+          if (elemStart >= 0) {
+            push(buf.slice(elemStart, scan));
+            elemStart = -1;
+            if (items.length >= opts.maxItems) { truncated = true; scan++; break outer; }
+          }
+          continue;
+        }
+
+        // A bare scalar element (number / true / false / null).
+        if (depth === 0 && elemStart < 0 && ch.trim() !== '') elemStart = scan;
+      }
+
+      // Drop everything already consumed. THIS is what bounds memory: without
+      // it `buf` grows to the full body and the reader is streaming in name only.
+      if (elemStart >= 0) {
+        buf = buf.slice(elemStart);
+        scan -= elemStart;
+        elemStart = 0;
+      } else {
+        buf = buf.slice(scan);
+        scan = 0;
+      }
+    }
+  } finally {
+    // Cancel rather than drain: the point is that the remaining megabytes are
+    // never transferred. A cancel on an already-finished body is a no-op.
+    await reader.cancel().catch(() => {});
+  }
+
+  return { items, truncated, bytesRead, declaredBytes };
+}
+
+/**
+ * `parseJson`, with a hard ceiling on how many bytes are read.
+ *
+ * For an upstream whose body is not a single array (so `readJsonArrayPrefix`
+ * does not apply) but which can still answer with megabytes. Unlike the array
+ * reader this one THROWS when the cap is hit, because a truncated prefix of an
+ * arbitrary JSON document is not parseable and there is no partial answer to
+ * hand back. A declared `Content-Length` over the cap is refused before a
+ * single chunk is read.
+ */
+async function parseJsonBounded<T>(
+  res: Response,
+  name: string,
+  maxBytes: number = DEFAULT_MAX_JSON_BYTES,
+): Promise<T> {
+  const declaredRaw = Number(res.headers.get('content-length'));
+  const declared = Number.isFinite(declaredRaw) && declaredRaw > 0 ? declaredRaw : null;
+
+  const tooBig = (n: number) =>
+    new Error(
+      `upstream_down: ${name} answered with ${n.toLocaleString()} bytes, over this pack's ${maxBytes.toLocaleString()}-byte ceiling. ` +
+        'The body is not read past the ceiling on purpose — a few concurrent reads of a body that size exhaust the ' +
+        'Worker isolate and take every other in-flight request down with them. Narrow the request (a smaller range, ' +
+        'a specific id, or a lower limit) and retry.',
+    );
+
+  if (declared !== null && declared > maxBytes) {
+    await res.body?.cancel().catch(() => {});
+    throw tooBig(declared);
+  }
+  if (!res.body) return parseJson<T>(res, name);
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let raw = '';
+  let bytesRead = 0;
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      bytesRead += value.byteLength;
+      if (bytesRead > maxBytes) throw tooBig(bytesRead);
+      raw += decoder.decode(value, { stream: true });
+    }
+    raw += decoder.decode();
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+
+  if (!raw.trim()) {
+    throw new Error(
+      `upstream_down: ${name} answered HTTP ${res.status} with an EMPTY body where JSON was expected. ` +
+        'Nothing about the request can cause this — it is an upstream fault, and the same call may well work on retry.',
+    );
+  }
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    throw new Error(
+      `upstream_down: ${name} answered HTTP ${res.status} with a body that is not valid JSON. ` +
+        `It begins: ${stripMarkup(raw).slice(0, 120) || '(unreadable)'}`,
+    );
+  }
+}
 /**
  * Aviationstack MCP — global flight + airport + airline data
  *
@@ -777,6 +1025,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 +1137,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 +1151,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

@@ -8,8 +8,9 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import pack from './index.js';
 
+
 const server = new Server(
-  { name: '@pipeworx/mcp-aviationstack', version: '0.1.2' },
+  { name: '@pipeworx/mcp-aviationstack', version: '0.1.4' },
   { capabilities: { tools: {} } },
 );
 
@@ -24,7 +25,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
   try {
-    const result = await pack.callTool(name, (args ?? {}) as Record<string, unknown>);
+    const callArgs = { ...((args ?? {}) as Record<string, unknown>) };
+    
+    const result = await pack.callTool(name, callArgs);
     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
   } catch (err) {
     return {