@pipeworx/mcp-bts-ontime 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mojibake Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,209 @@
-# Temporary Holding Version
+# @pipeworx/bts-ontime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+US domestic airline on-time performance and delay causes: monthly on-time %,
+average arrival delay, cancellations, diversions, and delay minutes broken
+down by cause (carrier, weather, air-traffic-control/NAS, security, late
+aircraft) — by route, by carrier, and by arrival airport. Fleet #2953.
+
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1856+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.
+
+## Tools
+
+- `route_ontime(origin, dest, carrier?, months?)` — monthly on-time
+  performance for one origin->destination route, optionally scoped to one
+  carrier. Each month carries flights, completed flights, on-time arrivals
+  and on-time %, average arrival delay, cancellations, diversions, and delay
+  minutes by cause.
+- `carrier_ontime(carrier, airport?, months?)` — the same monthly shape,
+  aggregated across one airline's whole network (or just the flights
+  touching one airport).
+- `bts_airport_delays(airport, year?, month?, limit?, offset?)` —
+  delay-cause breakdown by carrier for flights ARRIVING at one airport,
+  optionally scoped to a year and/or month. `limit` defaults to 50 (max
+  200); a response with more matching rows than returned carries
+  `truncated: true` and `total_matching` rather than silently dropping them.
+- `delay_causes(year, carrier?, airport?, limit?, offset?)` — the same
+  delay-cause rows, organized by year first, for scanning a whole year
+  across carriers or airports. Same `limit`/`truncated`/`total_matching`
+  pagination as `bts_airport_delays`.
+- `list_coverage()` — the earliest/latest month actually loaded, and when.
+  Call this first if you're not sure a given period is covered.
+
+Carrier accepts either the 2-letter reporting-carrier code (`"DL"`) or a
+common airline name (`"Delta"`). Airport codes are validated against what is
+actually loaded (not a static list) — an unrecognized code is refused with a
+clear error, never an empty success.
+
+## Auth
+
+Keyless. The tools answer only through the Pipeworx gateway, which holds the
+data; a standalone `npm install` has no data to read, and every tool throws
+a clear "not bound in this runtime" error there instead of returning an
+empty list.
+
+## Data sources
+
+- US DOT Bureau of Transportation Statistics (BTS), TranStats — "Reporting
+  Carrier On-Time Performance" monthly bulk data. US federal government
+  work: public domain (17 U.S.C. §105). The agency publishes bulk files
+  only (no live query API for this dataset), so this pack builds a copy
+  (`scripts/bts-ontime/load-data.mjs`) rather than proxying — raw
+  flight-level rows (~600k/month) are never stored; the loader aggregates
+  each month down to two small tables and discards the raw file before
+  moving to the next one.
+
+### What `delay_cause` is, and is not
+
+BTS separately publishes its own "Airline Delay Cause" product, which
+apportions each delayed flight's minutes into fractional per-cause *counts*
+via a methodology this pack does not reimplement. The `delay_cause` table
+here is derived from the same underlying per-flight delay-minute fields
+(carrier/weather/NAS/security/late-aircraft) as `route_month`, rolled up by
+carrier x arrival-airport x month, and reported as **minute sums**, not
+fractional counts. It will be consistent with BTS's own published cause
+breakdown but is not guaranteed to match it row-for-row — this is one
+pipeline over one raw source, not a second download of BTS's own aggregate.
+
+### Known gaps — read before extending this pack
+
+**Coverage is the most recent months as of the load, not full history.**
+BTS's bulk-file server throttles hard per connection — one file download
+measured ~170 seconds regardless of a modest concurrency increase helping
+(3 concurrent downloads of this upstream finished in about the same wall
+time as 1 serial one, measured 2026-10-12), so pulling the full 1987-present
+archive (400+ monthly files) in one sitting is a multi-hour job, not a
+pack-build step. This first load covers the most recent 12 months as of
+2026-10-12 (call `list_coverage` for the exact range) for BOTH tables —
+there is no separate 2003-onward backfill for `delay_cause` in this
+commit; it is derived from the same months as `route_month`.
+
+**Extending coverage is mechanical, not research** — see "Refreshing or
+extending the data" below. Re-running the loader with a larger `--months`
+(and a `--concurrency` tuned to be polite to the upstream) pulls further
+back; nothing about the schema or the tools changes.
+
+### Refreshing or extending the data
+
+```bash
+node scripts/bts-ontime/load-data.mjs --months 12                 # default: most recent 12 months
+node scripts/bts-ontime/load-data.mjs --months 36 --concurrency 4 # extend further back
+node scripts/bts-ontime/load-data.mjs --through 2026-7            # pin the "latest" month instead of probing
+```
+
+Needs `wrangler` logged in to the Pipeworx Cloudflare account. Each run
+**replaces** `route_month`, `delay_cause` and `bts_ontime_meta` (DROP +
+reload) rather than appending — BTS's own monthly files are themselves
+revised occasionally, so a clean reload is the only way to be sure stale
+rows from a withdrawn/corrected file don't linger. A monthly refresh (BTS
+publishes with a roughly 2-month lag) should re-run this with a `--months`
+large enough to cover the gap since the last load, not just `12`, or the
+oldest previously-loaded months will quietly drop off the window.
+
+## Quick Start
+
+Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
+
+```json
+{
+  "mcpServers": {
+    "bts-ontime": {
+      "url": "https://gateway.pipeworx.io/bts-ontime/mcp"
+    }
+  }
+}
+```
+
+### What this endpoint actually serves
+
+`tools/list` at `https://gateway.pipeworx.io/bts-ontime/mcp` returns the tools in the table
+above **plus the shared Pipeworx meta-tools** — `ask_pipeworx`,
+`discover_tools`, `search_within`, `remember`/`recall` and the rest of the
+gateway-wide set. So the tool count you see is larger than this table: a
+single-pack endpoint currently lists roughly 30 shared tools alongside the
+pack's own. The connection's `initialize` response states its exact scope, and
+is the authoritative answer for a given day.
+
+This is deliberate, not multiplexing by accident. The meta-tools are what let a
+scoped connection answer a question this pack does not cover — via
+`ask_pipeworx`, which routes across the whole catalog — without you adding a
+second MCP server. There is currently no way to mount a pack endpoint without
+them; if the extra schemas cost you more context than the routing is worth,
+connect to the full gateway once rather than to several pack endpoints.
+
+Or connect to the full Pipeworx gateway to get every pack's tools listed
+directly, instead of just this one's:
+
+```json
+{
+  "mcpServers": {
+    "pipeworx": {
+      "url": "https://gateway.pipeworx.io/mcp"
+    }
+  }
+}
+```
+
+Both URLs reach the same gateway and the same 1856+ data sources. The
+only difference is which pack's tools are listed **directly**; `ask_pipeworx`
+reaches all of them from either one.
+
+## No MCP client? Call it over HTTP
+
+```bash
+curl -X POST https://gateway.pipeworx.io/v1/tools/route_ontime \
+  -H 'Content-Type: application/json' \
+  -d '{"origin":"JFK","dest":"LAX","months":3}'
+```
+
+No account needed for the first calls. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/route_ontime`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.
+
+## Run it from npm
+
+`@pipeworx/mcp-bts-ontime` is a local stdio bridge to the Pipeworx gateway: your MCP client
+starts it with `npx`, and it forwards every call to the same
+`https://gateway.pipeworx.io/bts-ontime/mcp` endpoint shown above. It needs network access;
+there is no offline mode.
+
+```json
+{
+  "mcpServers": {
+    "bts-ontime": {
+      "command": "npx",
+      "args": ["-y", "@pipeworx/mcp-bts-ontime"]
+    }
+  }
+}
+```
+
+Without a key it calls anonymously, capped at 50 calls a day. A free account
+raises that to 200 a day: get a key at https://pipeworx.io/signup and add
+`"env": { "PIPEWORX_API_KEY": "<your key>" }` to the server entry.
+The key is sent as a Bearer token, the same way a hosted connection sends it,
+so calls are metered and billed exactly as they are there.
+
+It lists **only** this pack's tools by default. Set `PIPEWORX_META_TOOLS=1` to
+also list `ask_pipeworx` and the other gateway-wide tools.
+
+Behind an HTTPS proxy: Node's built-in `fetch` does not read `HTTPS_PROXY` by
+default. Newer Node releases honour it when `NODE_USE_ENV_PROXY=1` is set; check
+your Node version's documentation.
+
+## Using with ask_pipeworx
+
+Instead of calling tools directly, you can ask questions in plain English —
+this works on the pack endpoint above as well as on the full gateway:
+
+```
+ask_pipeworx({ question: "your question about Bts Ontime data" })
+```
+
+The gateway picks the right tool and fills the arguments automatically.
+
+## More
+
+- [Docs and guides](https://pipeworx.io/docs)
+- [pipeworx.io](https://pipeworx.io)
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Entry point for `npx @pipeworx/mcp-<slug>` in gateway mode (bin/cli.js).
+//
+// A stdio MCP server that relays every message to the Pipeworx gateway's
+// /<slug>/mcp endpoint -- fleet #3759, docs/standalone-via-gateway-plan.md.
+// It carries no pack code and has no local mode. The relay itself lives in
+// ../lib/index.js (copied from scripts/templates/standalone-gateway-lib.js);
+// this file only owns stdin/stdout.
+//
+// Copied VERBATIM into every gateway-mode package by scripts/publish-pack.sh.
+// Edit scripts/templates/standalone-gateway-cli.js in the monorepo, never a
+// per-pack copy. Zero dependencies, Node 18+.
+//
+// stdout carries newline-delimited JSON-RPC and nothing else; every diagnostic
+// goes to stderr, because a single stray line on stdout breaks the host's
+// parser.
+import { createInterface } from 'node:readline';
+import { relay, bridgeConfig } from '../lib/index.js';
+
+const cfg = bridgeConfig();
+const warn = (line) => process.stderr.write(`${line}\n`);
+const write = (msg) => { if (msg) process.stdout.write(`${JSON.stringify(msg)}\n`); };
+
+const pending = new Set();
+function track(p) {
+  pending.add(p);
+  p.finally(() => pending.delete(p));
+}
+
+async function handleLine(line) {
+  const text = line.trim();
+  if (!text) return;
+  let message;
+  try {
+    message = JSON.parse(text);
+  } catch {
+    write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+    return;
+  }
+  // A JSON-RPC batch: relay each member, answer with the non-notification replies.
+  if (Array.isArray(message)) {
+    const replies = (await Promise.all(message.map((m) => relay(m, { cfg, warn })))).filter(Boolean);
+    if (replies.length) write(replies);
+    return;
+  }
+  write(await relay(message, { cfg, warn }));
+}
+
+// Requests are handled concurrently and answered as they finish: JSON-RPC ids
+// let the host match them, and a slow tool call must not hold up a ping.
+const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on('line', (line) => {
+  track(handleLine(line).catch((err) => warn(`pipeworx-standalone: ${err && err.stack ? err.stack : err}`)));
+});
+rl.on('close', async () => {
+  // stdin closed: finish what is in flight, then exit.
+  while (pending.size) await Promise.allSettled([...pending]);
+  // Exit only once stdout has flushed: on a pipe that is not synchronous
+  // everywhere, and a bare exit can drop the last reply.
+  process.stdout.write('', () => process.exit(0));
+});

package/lib/index.js

@@ -0,0 +1,333 @@
+// @pipeworx/mcp-<slug> -- library half of the gateway bridge (lib/index.js).
+//
+// Copied VERBATIM into every gateway-mode pack package by scripts/publish-pack.sh
+// (fleet #3759, docs/standalone-via-gateway-plan.md section 1). There is no
+// per-pack templating: the slug and version are read from this package's own
+// package.json (`pipeworx.slug`, `version`) at load time, so the same bytes
+// ship in every package and the source hash can cover them once. Edit this
+// file in the monorepo (scripts/templates/standalone-gateway-lib.js), never a
+// per-pack copy.
+//
+// What it is: a relay. Every JSON-RPC message goes to
+// ${PIPEWORX_GATEWAY_URL:-https://gateway.pipeworx.io}/<slug>/mcp, the same
+// endpoint a hosted MCP client uses, so tiers, rate limits and credits apply
+// exactly as they do there. There is no local mode: the pack's code is not in
+// this package.
+//
+// Zero dependencies, plain ESM, Node 18+ (global fetch). Nothing here writes
+// to stdout -- bin/cli.js owns stdout and it carries JSON-RPC only.
+//
+// Environment:
+//   PIPEWORX_API_KEY      sent as `Authorization: Bearer <key>`. Never as
+//                         X-API-Key: the gateway reads a pwx_ key sent that way
+//                         as an unvalidated BYO string with no account.
+//   PIPEWORX_GATEWAY_URL  gateway base URL (no path), default the public gateway.
+//   PIPEWORX_META_TOOLS=1 list the gateway-wide tools (ask_pipeworx, ...) too.
+//   PIPEWORX_TIMEOUT_MS   per-request timeout, default 120000.
+
+import { readFileSync } from 'node:fs';
+
+const readJson = (rel) => JSON.parse(readFileSync(new URL(rel, import.meta.url), 'utf8'));
+
+const PKG = readJson('../package.json');
+export const SLUG = PKG.pipeworx && PKG.pipeworx.slug;
+if (typeof SLUG !== 'string' || !/^[a-z0-9][a-z0-9_-]*$/.test(SLUG)) {
+  throw new Error(`${PKG.name}: package.json carries no valid pipeworx.slug -- this package was built wrong`);
+}
+/**
+ * The pack's slug on the GATEWAY: the /<slug>/mcp route and the `_meta.pack`
+ * every listed tool carries. Usually the same as `slug` (the npm/directory
+ * name), but 14 packs differ -- `hex-pm` is `hex_pm` on the gateway -- and
+ * filtering tools/list on the npm slug would match none of their tools
+ * (fleet #3761). publish-pack.sh stamps it from the gateway manifest.
+ */
+export const GATEWAY_SLUG = (PKG.pipeworx && PKG.pipeworx.gatewaySlug) || SLUG;
+if (typeof GATEWAY_SLUG !== 'string' || !/^[a-z0-9][a-z0-9_-]*$/.test(GATEWAY_SLUG)) {
+  throw new Error(`${PKG.name}: package.json carries an invalid pipeworx.gatewaySlug -- this package was built wrong`);
+}
+export const PACKAGE_NAME = PKG.name;
+export const VERSION = PKG.version;
+
+/** The pack's own tool definitions at publish time (the offline tools/list answer). */
+export const tools = readJson('../tools.json');
+
+const DEFAULT_GATEWAY = 'https://gateway.pipeworx.io';
+const DEFAULT_TIMEOUT_MS = 120_000;
+const SIGNUP_URL = 'https://pipeworx.io/signup';
+const VIA = '(via pipeworx-standalone)';
+
+/** Resolve the bridge's settings. Exported for the tests and for callTool. */
+export function bridgeConfig(env = process.env, overrides = {}) {
+  const base = String(overrides.gatewayUrl || env.PIPEWORX_GATEWAY_URL || DEFAULT_GATEWAY).trim().replace(/\/+$/, '');
+  const apiKey = String(overrides.apiKey ?? env.PIPEWORX_API_KEY ?? '').trim();
+  const t = Number(overrides.timeoutMs ?? env.PIPEWORX_TIMEOUT_MS);
+  return {
+    endpoint: `${base}/${GATEWAY_SLUG}/mcp`,
+    apiKey,
+    timeoutMs: Number.isFinite(t) && t > 0 ? t : DEFAULT_TIMEOUT_MS,
+    metaTools: (overrides.metaTools ?? env.PIPEWORX_META_TOOLS) === '1' || overrides.metaTools === true,
+  };
+}
+
+function requestHeaders(cfg) {
+  const h = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+    // Stable per package version: the gateway remembers a client's name by
+    // identifier + User-Agent (workers/gateway/src/client-identity.ts).
+    'User-Agent': `pipeworx-standalone/${VERSION} (${PACKAGE_NAME})`,
+    // Analytics label only (blob11 = 'standalone'). It never changes tier,
+    // limits or price -- anyone can send it.
+    'X-Pipeworx-Surface': 'standalone',
+  };
+  if (cfg.apiKey) h.Authorization = `Bearer ${cfg.apiKey}`;
+  return h;
+}
+
+/** Parse a gateway body: JSON, or the last JSON `data:` frame of an SSE stream. */
+function parseBody(text, contentType) {
+  if (/text\/event-stream/i.test(contentType || '')) {
+    let last = null;
+    for (const line of text.split(/\r?\n/)) {
+      if (!line.startsWith('data:')) continue;
+      try { last = JSON.parse(line.slice(5).trim()); } catch { /* keep-alive or partial frame */ }
+    }
+    return last;
+  }
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+/**
+ * POST one JSON-RPC message. Never throws: the outcome is one of
+ *   { kind: 'http', status, headers, body, text }   the gateway answered
+ *   { kind: 'network', detail }                      DNS, TLS, refused, reset
+ *   { kind: 'timeout' }                              no answer in cfg.timeoutMs
+ */
+export async function postToGateway(message, cfg) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), cfg.timeoutMs);
+  try {
+    const res = await fetch(cfg.endpoint, {
+      method: 'POST',
+      headers: requestHeaders(cfg),
+      body: JSON.stringify(message),
+      signal: ac.signal,
+    });
+    const text = await res.text();
+    return { kind: 'http', status: res.status, headers: res.headers, body: parseBody(text, res.headers.get('content-type')), text };
+  } catch (err) {
+    if (ac.signal.aborted || (err && (err.name === 'AbortError' || err.name === 'TimeoutError'))) return { kind: 'timeout' };
+    const cause = err && err.cause;
+    const detail = (cause && (cause.code || cause.message)) || (err && err.message) || String(err);
+    return { kind: 'network', detail };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ── The key-not-accepted warning (one per process) ──────────────────
+
+let warnedKeyIgnored = false;
+const KEY_IGNORED = 'PIPEWORX_API_KEY was not accepted, calling anonymously.';
+
+/** True when a key was sent but the gateway still served the call as anonymous. */
+function keyIgnored(out, cfg) {
+  return !!cfg.apiKey && out.kind === 'http' && (out.headers.get('x-ratelimit-tier') || '').toLowerCase() === 'anonymous';
+}
+
+function noteTier(out, cfg, warn) {
+  if (!keyIgnored(out, cfg) || warnedKeyIgnored) return;
+  warnedKeyIgnored = true;
+  warn(`${PACKAGE_NAME}: ${KEY_IGNORED} Check the key at ${SIGNUP_URL}.`);
+}
+
+/** Test hook: forget that the warning was printed. */
+export function _resetWarnings() { warnedKeyIgnored = false; }
+
+// ── Results the host shows to the model ─────────────────────────────
+
+function errorResult(text, detail) {
+  const result = { content: [{ type: 'text', text }], isError: true };
+  if (detail) result._meta = { pipeworx_standalone: detail };
+  return result;
+}
+
+const rpcResult = (id, result) => ({ jsonrpc: '2.0', id, result });
+const rpcError = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+function firstLine(text) {
+  const line = String(text || '').split(/\r?\n/).map((l) => l.trim()).find(Boolean) || '(empty body)';
+  return line.length > 200 ? `${line.slice(0, 200)}...` : line;
+}
+
+function unreachableText(cfg, out) {
+  if (out.kind === 'timeout') {
+    return `The Pipeworx gateway at ${cfg.endpoint} did not answer within ${Math.round(cfg.timeoutMs / 1000)}s, so this call timed out. `
+      + `${PACKAGE_NAME} forwards every call to the Pipeworx gateway and has no local mode. Try again; a call that keeps timing out is worth reporting.`;
+  }
+  return `Could not reach the Pipeworx gateway at ${cfg.endpoint} (${out.detail}). `
+    + `${PACKAGE_NAME} forwards every call to the Pipeworx gateway and has no local mode, so it needs network access.`;
+}
+
+function isAuthRequired(body) {
+  return !!body && (body.error_code === 'authentication_required'
+    || (body.error && body.error.data && body.error.data.reason === 'authentication_required'));
+}
+
+/** Map a tools/call outcome to the JSON-RPC response the host gets. */
+function toolsCallResponse(id, out, cfg) {
+  if (out.kind !== 'http') return rpcResult(id, errorResult(unreachableText(cfg, out), { reason: out.kind }));
+  const { status, body } = out;
+
+  // Anonymous daily cap: the gateway answers 401 with a JSON-RPC error whose
+  // message is the offer. Hosts often swallow protocol errors, so hand it over
+  // as a tool result the model actually reads.
+  if (status === 401 && isAuthRequired(body)) {
+    const data = (body.error && body.error.data) || {};
+    const parts = [body.error && body.error.message ? body.error.message : 'The anonymous daily allowance is used up.'];
+    if (data.resets_at) parts.push(`The anonymous allowance resets at ${data.resets_at}.`);
+    parts.push(cfg.apiKey
+      ? `${KEY_IGNORED} Check the key, or get a free one at ${SIGNUP_URL}.`
+      : `To keep going now, set PIPEWORX_API_KEY in this MCP server's environment; a free key is at ${SIGNUP_URL}.`);
+    return rpcResult(id, errorResult(parts.join('\n\n'), { status, reason: 'authentication_required', resets_at: data.resets_at ?? null }));
+  }
+
+  // A keyed tier over its cap: today the gateway answers 429 with a RESULT
+  // that has no isError, which reads as a success (fleet #3760). Mark it.
+  if (status === 429 && body && body.result && typeof body.result === 'object') {
+    const result = { ...body.result, isError: true };
+    if (cfg.apiKey && keyIgnored(out, cfg)) {
+      result.content = [...(Array.isArray(result.content) ? result.content : []), { type: 'text', text: KEY_IGNORED }];
+    }
+    return rpcResult(id, result);
+  }
+  if ((status === 401 || status === 429) && body && body.error) {
+    const extra = keyIgnored(out, cfg) ? ` ${KEY_IGNORED}` : '';
+    return rpcResult(id, errorResult(`${body.error.message || `HTTP ${status}`}${extra}`, { status }));
+  }
+
+  // A real JSON-RPC answer (result or protocol error): relay it verbatim,
+  // structuredContent and _meta (cost, tier, provenance) included.
+  if (body && body.jsonrpc === '2.0' && (body.result !== undefined || body.error !== undefined) && status < 500) {
+    return { ...body, id };
+  }
+
+  // 5xx, an HTML edge page, or anything else that is not JSON-RPC.
+  return rpcResult(id, errorResult(`The Pipeworx gateway returned HTTP ${status}: ${firstLine(out.text)}`, { status }));
+}
+
+function localInitialize(params) {
+  return {
+    protocolVersion: (params && params.protocolVersion) || '2025-06-18',
+    capabilities: { tools: {} },
+    serverInfo: { name: PACKAGE_NAME, version: VERSION },
+  };
+}
+
+const scopedInstructions = () =>
+  `${PACKAGE_NAME} forwards to the Pipeworx gateway and lists only the ${SLUG} pack's tools. `
+  + 'Set PIPEWORX_META_TOOLS=1 to also list ask_pipeworx and the other gateway-wide tools.';
+
+/** `<host name> (via pipeworx-standalone)`. The slug stays OUT of the name: the
+ *  gateway's scanner-name check substring-matches words like poll/watch/index. */
+export function bridgedClientName(name) {
+  const n = typeof name === 'string' && name.trim() ? name.trim() : 'unknown';
+  return n.includes(VIA) ? n : `${n} ${VIA}`;
+}
+
+/**
+ * Relay one JSON-RPC message to the gateway and return the response to write
+ * back, or null for a notification. Never throws.
+ *
+ * @param {object} message  a parsed JSON-RPC request or notification
+ * @param {{cfg?: object, warn?: (line: string) => void}} [opts]
+ */
+export async function relay(message, opts = {}) {
+  const cfg = opts.cfg || bridgeConfig();
+  const warn = opts.warn || ((line) => process.stderr.write(`${line}\n`));
+  if (!message || typeof message !== 'object' || message.jsonrpc !== '2.0' || typeof message.method !== 'string') {
+    const id = message && typeof message === 'object' && 'id' in message ? message.id : null;
+    return rpcError(id ?? null, -32600, 'Invalid Request');
+  }
+  const isNotification = !('id' in message) || message.id === undefined;
+  const id = message.id;
+
+  if (isNotification) {
+    const out = await postToGateway(message, cfg);
+    if (out.kind !== 'http') warn(`${PACKAGE_NAME}: notification ${message.method} not delivered: ${unreachableText(cfg, out)}`);
+    return null;
+  }
+
+  if (message.method === 'initialize') {
+    const params = { ...(message.params || {}) };
+    params.clientInfo = { ...(params.clientInfo || {}), name: bridgedClientName(params.clientInfo && params.clientInfo.name) };
+    if (!params.clientInfo.version) params.clientInfo.version = '0';
+    const out = await postToGateway({ ...message, params }, cfg);
+    noteTier(out, cfg, warn);
+    if (out.kind === 'http' && out.body && out.body.result && typeof out.body.result === 'object') {
+      const result = { ...out.body.result, serverInfo: { name: PACKAGE_NAME, version: VERSION } };
+      if (!cfg.metaTools) result.instructions = scopedInstructions();
+      return rpcResult(id, result);
+    }
+    // The host must still start: answer locally and let the calls report the
+    // gateway problem when they happen.
+    warn(`${PACKAGE_NAME}: initialize answered locally -- ${out.kind === 'http' ? `gateway HTTP ${out.status}` : unreachableText(cfg, out)}`);
+    return rpcResult(id, { ...localInitialize(message.params), instructions: scopedInstructions() });
+  }
+
+  if (message.method === 'tools/list') {
+    const out = await postToGateway(message, cfg);
+    noteTier(out, cfg, warn);
+    const listed = out.kind === 'http' && out.body && out.body.result && Array.isArray(out.body.result.tools)
+      ? out.body.result : null;
+    if (listed) {
+      if (cfg.metaTools) return rpcResult(id, listed);
+      const own = listed.tools.filter((t) => t && t._meta && (t._meta.pack === GATEWAY_SLUG || t._meta.pack === SLUG));
+      if (own.length > 0) return rpcResult(id, { ...listed, tools: own });
+      warn(`${PACKAGE_NAME}: the gateway listed no ${SLUG} tools; serving the tool list bundled with this package`);
+    } else {
+      warn(`${PACKAGE_NAME}: tools/list served from the snapshot bundled with this package -- ${out.kind === 'http' ? `gateway HTTP ${out.status}` : unreachableText(cfg, out)}`);
+    }
+    return rpcResult(id, { tools });
+  }
+
+  if (message.method === 'tools/call') {
+    const out = await postToGateway(message, cfg);
+    noteTier(out, cfg, warn);
+    return toolsCallResponse(id, out, cfg);
+  }
+
+  // Everything else (ping, resources/*, prompts/*, ...): relay as-is.
+  const out = await postToGateway(message, cfg);
+  noteTier(out, cfg, warn);
+  if (out.kind === 'http' && out.body && out.body.jsonrpc === '2.0') return { ...out.body, id };
+  if (message.method === 'ping') return rpcResult(id, {});
+  return rpcError(id, -32603, out.kind === 'http'
+    ? `The Pipeworx gateway returned HTTP ${out.status}: ${firstLine(out.text)}`
+    : unreachableText(cfg, out));
+}
+
+/**
+ * Call one of this pack's tools through the gateway -- the `{tools, callTool}`
+ * shape earlier versions of this package exported. Resolves with the tool's
+ * structured result; rejects with the gateway's message on any error.
+ *
+ * @param {string} name
+ * @param {Record<string, unknown>} [args]
+ * @param {{apiKey?: string, gatewayUrl?: string, timeoutMs?: number}} [opts]
+ *        apiKey defaults to process.env.PIPEWORX_API_KEY.
+ */
+export async function callTool(name, args = {}, opts = {}) {
+  const cfg = bridgeConfig(process.env, opts);
+  const res = await relay({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } }, { cfg });
+  if (res.error) throw new Error(res.error.message);
+  const result = res.result || {};
+  const text = Array.isArray(result.content)
+    ? result.content.filter((c) => c && c.type === 'text').map((c) => c.text).join('\n')
+    : '';
+  if (result.isError) throw new Error(text || `${name} failed`);
+  if (result.structuredContent !== undefined) return result.structuredContent;
+  try { return JSON.parse(text); } catch { return text; }
+}
+
+export default { tools, callTool };

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@pipeworx/mcp-bts-ontime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "bts-ontime -- US airline on-time performance and delay causes (fleet #2953).",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./tools.json": "./tools.json",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "mcp-bts-ontime": "bin/cli.js"
+  },
+  "files": ["bin/", "lib/", "tools.json", "server.json"],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "bts-ontime"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pipeworx-io/mcp-bts-ontime.git"
+  },
+  "mcpName": "io.github.pipeworx-io/bts-ontime",
+  "pipeworx": {
+    "mode": "gateway",
+    "slug": "bts-ontime",
+    "gatewaySlug": "bts-ontime",
+    "sourceHash": "v1-fd4a19e805e686a943ca36cc516dfb47db8ff6c651537f3cee5c269c763b6ca2",
+    "sourceCommit": "4277282d72f9bf55e548b3799aaf737baf22152f"
+  }
+}

package/server.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.pipeworx-io/bts-ontime",
+  "title": "Bts Ontime",
+  "description": "bts-ontime -- US airline on-time performance and delay causes (fleet #2953).",
+  "version": "0.2.0",
+  "websiteUrl": "https://pipeworx.io/packs/bts-ontime",
+  "repository": {
+    "url": "https://github.com/pipeworx-io/mcp-bts-ontime",
+    "source": "github"
+  },
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://gateway.pipeworx.io/bts-ontime/mcp"
+    }
+  ]
+}

package/tools.json

@@ -0,0 +1,127 @@
+[
+  {
+    "name": "route_ontime",
+    "description": "Monthly on-time performance for one US domestic flight route (origin airport -> destination airport), from BTS TranStats Reporting Carrier On-Time Performance. Returns, per month (and per carrier if more than one serves the route): flights, completed flights, on-time arrivals and on-time %, average arrival delay in minutes, cancellations, diversions, and delay minutes broken down by cause (carrier, weather, NAS/air-traffic-control, security, late aircraft). Pass carrier (2-letter code like \"DL\", or a common name like \"Delta\") to scope to one airline; omit it to see every carrier that flew the route. months caps how many of the most recently loaded months to return (default 12). Covers the most recent months loaded (see data_as_of and the earliest/latest fields), not full history. Unknown origin/destination airport codes are refused with a clear error, never an empty success.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "origin": {
+          "type": "string",
+          "description": "Origin airport code, e.g. \"JFK\"."
+        },
+        "dest": {
+          "type": "string",
+          "description": "Destination airport code, e.g. \"LAX\"."
+        },
+        "carrier": {
+          "type": "string",
+          "description": "Optional: 2-letter carrier code (\"DL\") or common name (\"Delta\") to scope to one airline."
+        },
+        "months": {
+          "type": "number",
+          "description": "How many of the most recently loaded months to return, most recent first. Default 12."
+        }
+      },
+      "required": [
+        "origin",
+        "dest"
+      ]
+    }
+  },
+  {
+    "name": "carrier_ontime",
+    "description": "Monthly on-time performance for one airline, aggregated across all its routes (or just the routes touching one airport), from BTS TranStats Reporting Carrier On-Time Performance. Pass carrier as a 2-letter code (\"WN\") or common name (\"Southwest\"). Pass airport to scope to flights where that airport is the origin or destination. Returns the same per-month shape as route_ontime (flights, on-time %, average arrival delay, cancellations, diversions, delay minutes by cause). months caps how many of the most recently loaded months to return (default 12). Unknown carrier codes are refused with a clear error, never an empty success.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "carrier": {
+          "type": "string",
+          "description": "2-letter carrier code (\"WN\") or common name (\"Southwest\")."
+        },
+        "airport": {
+          "type": "string",
+          "description": "Optional: scope to flights where this airport is the origin or destination."
+        },
+        "months": {
+          "type": "number",
+          "description": "How many of the most recently loaded months to return, most recent first. Default 12."
+        }
+      },
+      "required": [
+        "carrier"
+      ]
+    }
+  },
+  {
+    "name": "bts_airport_delays",
+    "description": "Delay-cause breakdown at one US airport (as the ARRIVAL airport), by carrier, from BTS TranStats on-time data: arriving flights, how many arrived 15+ minutes late, cancellations, diversions, and delay minutes attributed to carrier, weather, NAS (air-traffic-control/system), security, and late-aircraft causes. Pass year and/or month to scope to a specific period; omit both to get every loaded month, most recent first. Rows beyond `limit` are reported via truncated/total_matching rather than silently dropped -- narrow with year/month or page with limit/offset to see the rest. Unknown airport codes are refused with a clear error, never an empty success.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "airport": {
+          "type": "string",
+          "description": "Airport code, e.g. \"ORD\"."
+        },
+        "year": {
+          "type": "number",
+          "description": "Optional: scope to one calendar year."
+        },
+        "month": {
+          "type": "number",
+          "description": "Optional: scope to one month (1-12). Requires year to be meaningful alongside it, but works alone too (matches that month in any loaded year)."
+        },
+        "limit": {
+          "type": "number",
+          "description": "Max rows to return, 1-200. Default 50. A truncated response carries truncated:true and total_matching."
+        },
+        "offset": {
+          "type": "number",
+          "description": "Pagination offset. Default 0."
+        }
+      },
+      "required": [
+        "airport"
+      ]
+    }
+  },
+  {
+    "name": "delay_causes",
+    "description": "Delay-cause rows for a given year, optionally scoped to one carrier and/or one (arrival) airport, from BTS TranStats on-time data. Same fields as bts_airport_delays (arriving flights, 15+ minute-late arrivals, cancellations, diversions, delay minutes by cause) but organized by year first rather than by airport first -- use this to scan a whole year across carriers/airports, or to compare one carrier's delay profile across the airports it serves. Rows beyond `limit` are reported via truncated/total_matching rather than silently dropped -- narrow with carrier/airport or page with limit/offset to see the rest. Unknown carrier or airport codes are refused with a clear error, never an empty success.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "year": {
+          "type": "number",
+          "description": "Calendar year, e.g. 2026."
+        },
+        "carrier": {
+          "type": "string",
+          "description": "Optional: 2-letter carrier code (\"AA\") or common name (\"American\")."
+        },
+        "airport": {
+          "type": "string",
+          "description": "Optional: arrival-airport code, e.g. \"DFW\"."
+        },
+        "limit": {
+          "type": "number",
+          "description": "Max rows to return, 1-200. Default 50. A truncated response carries truncated:true and total_matching."
+        },
+        "offset": {
+          "type": "number",
+          "description": "Pagination offset. Default 0."
+        }
+      },
+      "required": [
+        "year"
+      ]
+    }
+  },
+  {
+    "name": "list_coverage",
+    "description": "What this pack actually has loaded right now: the earliest and latest BTS month covered, how many months, and when it was last loaded. Call this before route_ontime/carrier_ontime/bts_airport_delays/delay_causes if you are not sure a given month or year is covered.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    }
+  }
+]