@pipeworx/mcp-ecb 0.1.2 → 0.1.4

package/README.md

@@ -2,7 +2,7 @@
 
 European Central Bank Data Portal MCP — exchange rates, interest rates, monetary aggregates, HICP, bank lending. No auth.
 
-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 1855+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.
 
 ## Tools
 
@@ -71,19 +71,19 @@ 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 1855+ 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/ecb_exchange_rate \
+curl -X POST https://gateway.pipeworx.io/v1/tools/ecb_policy_rate \
   -H 'Content-Type: application/json' \
-  -d '{"currency":"USD"}'
+  -d '{}'
 ```
 
-No account needed for the first calls. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/ecb_exchange_rate`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.
+No account needed for the first calls. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/ecb_policy_rate`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.
 
 ## Standalone (no gateway account)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipeworx/mcp-ecb",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "ECB Data Portal MCP — European Central Bank statistical data",
   "type": "module",
   "main": "src/index.ts",
@@ -26,7 +26,7 @@
     "@cloudflare/workers-types": "^4.20260405.1"
   },
   "pipeworx": {
-    "sourceHash": "v1-6da2a22652c47fe27e8653b84d0dd4934e8b20677f51818b817ca676fbd0a2e3",
-    "sourceCommit": "4fa4c64448be06f4a2ee4cee19f756f3558a7cad"
+    "sourceHash": "v1-ab883f34ae882027b585171d95c9b8c5f3467180a89e01691b2894af4f901431",
+    "sourceCommit": "5749f83c0ea115fab4c0c0ef04b66b05f2507d67"
   }
 }

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.pipeworx-io/ecb",
   "title": "Ecb",
   "description": "ECB Data Portal MCP — European Central Bank statistical data",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "websiteUrl": "https://pipeworx.io/packs/ecb",
   "repository": {
     "url": "https://github.com/pipeworx-io/mcp-ecb",

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)'}`,
+    );
+  }
+}
 /**
  * ECB Data Portal MCP — European Central Bank statistical data
  *
@@ -687,6 +935,10 @@ function collapse(s: string): string {
  * API docs: https://data.ecb.europa.eu/help/api/
  *
  * Tools:
+ * - ecb_policy_rate:   current deposit facility rate / main refinancing rate /
+ *                      marginal lending rate, each with effective_since,
+ *                      previous_rate and decision history (FM flow, the three
+ *                      official "key ECB interest rates" — fleet #3206)
  * - exchange_rate:     EUR → currency rate (convenience over EXR flow)
  * - hicp_inflation:    Harmonised CPI YoY change (convenience over ICP flow)
  * - get_data:          generic SDMX query against any flow
@@ -704,7 +956,27 @@ async function pwFetch(url: string | URL, init?: RequestInit): Promise<Response>
 
 const BASE = 'https://data-api.ecb.europa.eu/service';
 
+// The three official "key ECB interest rates", FM flow, confirmed against the
+// live series. DFR is the ECB's primary policy lever since the 2024 corridor
+// narrowing (deposits now drive short-term money-market rates); MRO and MLFR
+// are published alongside it and move on the same Governing Council dates.
+const POLICY_RATE_SERIES: { field: string; label: string; key: string }[] = [
+  { field: 'deposit_facility_rate', label: 'Deposit facility rate', key: 'D.U2.EUR.4F.KR.DFR.LEV' },
+  { field: 'main_refinancing_rate', label: 'Main refinancing operations rate (fixed-rate tenders)', key: 'D.U2.EUR.4F.KR.MRR_FR.LEV' },
+  { field: 'marginal_lending_facility_rate', label: 'Marginal lending facility rate', key: 'D.U2.EUR.4F.KR.MLFR.LEV' },
+];
+
 const tools: McpToolExport['tools'] = [
+  {
+    name: 'ecb_policy_rate',
+    description:
+      "The European Central Bank's three official key interest rates — the deposit facility rate (the ECB's " +
+      'primary policy rate since the 2024 operational-framework reform), the main refinancing operations rate, ' +
+      'and the marginal lending facility rate. For each: the current rate, the date it took effect, the previous ' +
+      'rate and when that one took effect, plus recent decision history (FM flow, series DFR/MRR_FR/MLFR). ' +
+      "Use this for \"ECB interest rate\" / \"ECB deposit rate\" / \"has the ECB cut rates\" instead of guessing an FM series key.",
+    inputSchema: { type: 'object', properties: {} },
+  },
   {
     name: 'ecb_exchange_rate',
     description:
@@ -777,6 +1049,8 @@ const tools: McpToolExport['tools'] = [
 
 async function callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
   switch (name) {
+    case 'ecb_policy_rate':
+      return policyRate();
     case 'ecb_exchange_rate':
       return exchangeRate(args);
     case 'ecb_hicp_inflation':
@@ -790,6 +1064,76 @@ async function callTool(name: string, args: Record<string, unknown>): Promise<un
   }
 }
 
+/** {rate, effective_since, previous_rate, previous_rate_effective_since, decision_history, data_as_of} from an ascending {period,value} series. */
+function computeRateChanges(obs: { period: string; value: number | null }[]) {
+  const pts = obs.filter((o) => o.value !== null) as { period: string; value: number }[];
+  if (pts.length === 0) return null;
+  const changes: { rate: number; effective_since: string }[] = [{ rate: pts[0].value, effective_since: pts[0].period }];
+  for (let i = 1; i < pts.length; i++) {
+    if (pts[i].value !== changes[changes.length - 1].rate) {
+      changes.push({ rate: pts[i].value, effective_since: pts[i].period });
+    }
+  }
+  const current = changes[changes.length - 1];
+  const previous = changes.length > 1 ? changes[changes.length - 2] : null;
+  return {
+    rate: current.rate,
+    effective_since: current.effective_since,
+    previous_rate: previous?.rate ?? null,
+    previous_rate_effective_since: previous?.effective_since ?? null,
+    decision_history: changes.slice(-5).reverse(),
+    data_as_of: pts[pts.length - 1].period,
+  };
+}
+
+async function policyRate() {
+  // ~6 years of daily observations — comfortably more than enough to see the
+  // last several Governing Council rate decisions.
+  const results = await Promise.all(
+    POLICY_RATE_SERIES.map(async (s) => {
+      try {
+        const data = await fetchData('FM', s.key, { start_period: '2020-01-01' });
+        const series = data.series[0]?.observations ?? [];
+        return { field: s.field, label: s.label, computed: computeRateChanges(series), fetchError: null as string | null };
+      } catch (err) {
+        // A fixed, verified-live key failing is an upstream fault, not a bad
+        // query — surface it per-field rather than failing the whole call,
+        // since the other two rates may well still be answerable.
+        return { field: s.field, label: s.label, computed: null, fetchError: err instanceof Error ? err.message : String(err) };
+      }
+    }),
+  );
+  const missing = results.filter((r) => r.computed === null);
+  if (missing.length === results.length) {
+    return {
+      error: 'no_data',
+      message:
+        'The ECB returned no observations for any of the key interest rate series (FM flow, DFR/MRR_FR/MLFR). ' +
+        'The series shape may have changed upstream; try get_data with flow_ref "FM" directly.',
+    };
+  }
+  const primary = results.find((r) => r.field === 'deposit_facility_rate')!;
+  const out: Record<string, unknown> = {
+    unit: 'percent',
+    // Aggregate fields first: the deposit facility rate is the ECB's primary
+    // policy lever since the 2024 corridor reform, so it carries the
+    // top-level {rate, effective_since, previous_rate, ...} shape directly —
+    // a caller asking "the ECB rate" does not have to know there are three.
+    ...(primary.computed ?? {}),
+  };
+  for (const r of results) {
+    out[r.field] = r.computed
+      ? { label: r.label, ...r.computed }
+      : { label: r.label, error: 'no_data', message: r.fetchError ?? `The ECB returned no observations for ${r.label}.` };
+  }
+  out.note =
+    "The ECB's three official key interest rates (deposit facility, main refinancing, marginal lending). " +
+    'The deposit facility rate has been the primary signal of the ECB monetary-policy stance since the ' +
+    "2024 operational-framework reform narrowed the corridor; top-level fields describe it. All three " +
+    'normally change together, on the same Governing Council decision date.';
+  return out;
+}
+
 async function exchangeRate(args: Record<string, unknown>) {
   const currency = reqStr(args, 'currency', '"USD"').toUpperCase();
   const freq = ((args.frequency as string) ?? 'D').toUpperCase();
@@ -836,9 +1180,23 @@ async function fetchData(
   if (opts.last_n) params.set('lastNObservations', String(opts.last_n));
   const url = `${BASE}/data/${encodeURIComponent(flow)}/${encodeURIComponent(key)}?${params}`;
   const res = await pwFetch(url, { headers: { Accept: 'application/json' } });
-  if (res.status === 404) throw new Error(`ECB: no data for flow=${flow} key=${key}`);
+  if (res.status === 404) {
+    throw new Error(
+      `not_found: the ECB has no series matching key "${key}" in flow "${flow}". The key does not exist at that ` +
+        'shape, not just empty for this period — check the dimension values, or call list_dataflows for valid flow_refs.',
+    );
+  }
   if (!res.ok) {
     const body = await res.text();
+    // A malformed key (wrong dimension count) gets ECB's generic error page —
+    // HTML, not SDMX JSON. Leaking it verbatim reads as a Pipeworx bug and
+    // buries the one useful fact (the request was malformed) under markup.
+    if (body.trimStart().startsWith('<')) {
+      throw new Error(
+        `user_error: the ECB rejected key "${key}" for flow "${flow}" as malformed (HTTP ${res.status}). ` +
+          'SDMX keys are dot-separated dimension values in a fixed order for that flow — check the dimension count.',
+      );
+    }
     throw new Error(`ECB error: ${res.status} ${body.slice(0, 200)}`);
   }
   // ECB answers a 200 with a ZERO-BYTE body during an outage, and res.json()

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-ecb', version: '0.1.2' },
+  { name: '@pipeworx/mcp-ecb', 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 {