euparliamentmonitor 0.9.2 → 0.9.4

package/scripts/mcp/fetch-proxy-server.js

@@ -6,18 +6,30 @@
  *
  * Implements the Model Context Protocol (JSON-RPC 2.0 over stdio) with a
  * single tool — `fetch_url` — that proxies HTTPS GET requests to the IMF
- * SDMX 3.0 REST API at `https://dataservices.imf.org/REST/SDMX_3.0/`.
+ * Data Portal SDMX 3.0 REST API at `https://api.imf.org/external/sdmx/3.0/`.
  *
  * ## Why this exists
  *
  * The Agent Workflow Firewall (AWF) runs a Squid proxy that blocks outbound
- * HTTPS even to allowlisted domains such as `dataservices.imf.org`. This
- * server is mounted as an MCP container in gh-aw workflows; because MCP
- * containers run in a Docker network with direct outbound access (bypassing
- * Squid), `fetch_url` can reach the IMF API while the main runner cannot.
+ * HTTPS even to allowlisted domains such as `api.imf.org`. This server is
+ * mounted as an MCP container in gh-aw workflows; because MCP containers
+ * run in a Docker network with direct outbound access (bypassing Squid),
+ * `fetch_url` can reach the IMF API while the main runner cannot.
  *
- * The server only allows calls to `https://dataservices.imf.org/REST/SDMX_3.0/`
- * — all other URLs are rejected with an error message.
+ * The server only allows calls to `https://api.imf.org/external/sdmx/3.0/`
+ * — SDMX 2.1 paths and any other URLs are rejected with an error message.
+ *
+ * ## Authentication
+ *
+ * The IMF Data Portal API is fronted by Azure API Management and requires
+ * a subscription key in the `Ocp-Apim-Subscription-Key` header for every
+ * request. The server reads the key from `IMF_API_PRIMARY_KEY` (with
+ * `IMF_API_SECONDARY_KEY` as a warm-standby fallback used on `401`/`403`
+ * responses to enable zero-downtime key rotation). When neither env var
+ * is set, the request is sent unauthenticated and IMF will return `204`
+ * (no subscription matched) — useful for diagnosing auth misconfiguration.
+ *
+ * The header is injected server-side; agent prompts never see the key.
  *
  * ## Usage
  *
@@ -37,25 +49,27 @@
  */
 import * as readline from 'node:readline';
 // ─── Constants ────────────────────────────────────────────────────────────────
-const IMF_ALLOWED_HOSTNAME = 'dataservices.imf.org';
-const IMF_ALLOWED_PATH_PREFIX = '/REST/SDMX_3.0/';
+const IMF_ALLOWED_HOSTNAME = 'api.imf.org';
+const IMF_ALLOWED_PATH_PREFIX = '/external/sdmx/3.0/';
 const IMF_ALLOWED_PROTOCOL = 'https:';
 /** Per-request fetch timeout (ms). */
 const FETCH_TIMEOUT_MS = 180_000;
 /** Product identifier sent to IMF SDMX endpoints. */
 const IMF_USER_AGENT = 'euparliamentmonitor/0.9.0 (+https://github.com/Hack23/euparliamentmonitor)';
-/** Common unauthenticated headers for IMF SDMX REST requests. */
+/** Common headers for IMF SDMX REST requests (auth header added per-request). */
 const IMF_REQUEST_HEADERS = Object.freeze({
     Accept: 'application/json, application/vnd.sdmx.data+json, */*;q=0.8',
     'User-Agent': IMF_USER_AGENT,
     'Accept-Language': 'en-US,en;q=0.9',
     'Cache-Control': 'no-cache',
 });
+/** Azure APIM subscription-key header expected by `api.imf.org`. */
+const IMF_SUBSCRIPTION_KEY_HEADER = 'Ocp-Apim-Subscription-Key';
 // ─── Allowlist check ─────────────────────────────────────────────────────────
 /**
  * Returns `true` when `url` is allowed by the IMF-only fetch-proxy policy.
  *
- * Allowed: `https://dataservices.imf.org/REST/SDMX_3.0/...`
+ * Allowed: `https://api.imf.org/external/sdmx/3.0/...` (SDMX 2.1 rejected).
  *
  * @param url - Raw URL string to validate.
  * @returns Whether the URL is permitted.
@@ -137,17 +151,83 @@ export function handleToolsList(id) {
     };
 }
 /**
- * Execute the `fetch_url` tool call.
+ * Read IMF subscription keys from the environment, in priority order.
  *
- * Only URLs matching the IMF SDMX 3.0 allowlist are permitted. Non-matching
- * or malformed URLs receive a JSON-RPC error response; HTTP errors and network
- * failures also surface as errors.
+ * Returns up to two keys: the primary (first attempt) and the secondary
+ * (used to retry on `401`/`403` so live key rotation never breaks a run).
+ * Empty / unset keys are filtered out so `[]` is returned only when no
+ * key is configured at all.
  *
- * @param id - Request id to echo.
- * @param url - URL to fetch.
- * @param fetchImpl - Injectable `fetch` implementation (defaults to global).
- * @returns JSON-RPC success or error.
+ * @returns Ordered list of candidate API keys (length 0–2).
+ * @internal
  */
+function readImfSubscriptionKeys() {
+    const candidates = [process.env['IMF_API_PRIMARY_KEY'], process.env['IMF_API_SECONDARY_KEY']];
+    const keys = [];
+    for (const k of candidates) {
+        if (typeof k === 'string' && k.length > 0 && !keys.includes(k)) {
+            keys.push(k);
+        }
+    }
+    return keys;
+}
+/**
+ * Build the request headers for an outbound IMF call. The `Ocp-Apim-Subscription-Key`
+ * header is added when a key is supplied; otherwise the request is sent
+ * unauthenticated (and IMF will return `204 No Content`).
+ *
+ * @param key - Subscription key, or `undefined` to send unauthenticated.
+ * @returns Plain object suitable for `fetch(..., { headers })`.
+ * @internal
+ */
+function buildImfHeaders(key) {
+    const headers = { ...IMF_REQUEST_HEADERS };
+    if (key !== undefined && key.length > 0) {
+        headers[IMF_SUBSCRIPTION_KEY_HEADER] = key;
+    }
+    return headers;
+}
+/**
+ * Classify a single `fetch()` response from `api.imf.org` so
+ * {@link handleFetchUrl} can decide whether to rotate keys, return
+ * success, or surface an explicit error.
+ *
+ * - `204 No Content` → explicit error (Azure APIM accepted the request
+ *   but no Ocp-Apim-Subscription-Key matched; without this guard the
+ *   empty body would be indistinguishable from a successful 200).
+ * - `401`/`403` with another key available → auth-retry signal.
+ * - Any other non-2xx → error with the HTTP status.
+ *
+ * @internal Exported for tests.
+ *
+ * @param response - The HTTP response returned by `fetch()`.
+ * @param hasNextAttempt - `true` when another subscription key is available for retry.
+ * @returns A classified outcome — `'ok'` with body text, `'auth-retry'` to rotate keys,
+ *   or `'error'` with a JSON-RPC error envelope.
+ */
+async function classifyFetchResponse(response, hasNextAttempt) {
+    if ((response.status === 401 || response.status === 403) && hasNextAttempt) {
+        return { kind: 'auth-retry', response };
+    }
+    if (response.status === 204) {
+        return {
+            kind: 'error',
+            rpcError: {
+                code: -1,
+                message: `HTTP 204 No Content from ${IMF_ALLOWED_HOSTNAME} — likely missing or invalid ${IMF_SUBSCRIPTION_KEY_HEADER} (set IMF_API_PRIMARY_KEY)`,
+            },
+            response,
+        };
+    }
+    if (!response.ok) {
+        return {
+            kind: 'error',
+            rpcError: { code: -1, message: `HTTP ${response.status} ${response.statusText}` },
+            response,
+        };
+    }
+    return { kind: 'ok', text: await response.text() };
+}
 export async function handleFetchUrl(id, url, fetchImpl = globalThis.fetch) {
     if (!url || !isAllowedImfUrl(url)) {
         return {
@@ -159,29 +239,65 @@ export async function handleFetchUrl(id, url, fetchImpl = globalThis.fetch) {
             },
         };
     }
-    try {
-        const response = await fetchImpl(url, {
-            headers: IMF_REQUEST_HEADERS,
-            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
-        });
-        if (!response.ok) {
+    // Try the primary key, then the secondary key on 401/403 (live rotation).
+    // When no keys are configured, fall through to a single unauthenticated
+    // attempt so the diagnostic surface (e.g. 204 No Content from IMF) is
+    // visible to the caller.
+    const keys = readImfSubscriptionKeys();
+    const attempts = keys.length > 0 ? [...keys] : [undefined];
+    let lastResponse;
+    let lastError;
+    for (let i = 0; i < attempts.length; i += 1) {
+        const key = attempts[i];
+        try {
+            const response = (await fetchImpl(url, {
+                headers: buildImfHeaders(key),
+                signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            }));
+            lastResponse = response;
+            const outcome = await classifyFetchResponse(response, i + 1 < attempts.length);
+            if (outcome.kind === 'auth-retry') {
+                continue;
+            }
+            if (outcome.kind === 'error') {
+                return { jsonrpc: '2.0', id, error: outcome.rpcError };
+            }
             return {
                 jsonrpc: '2.0',
                 id,
-                error: { code: -1, message: `HTTP ${response.status} ${response.statusText}` },
+                result: { content: [{ type: 'text', text: outcome.text }] },
             };
         }
-        const text = await response.text();
+        catch (err) {
+            lastError = err;
+            // Network errors are not auth-class — do not retry with the secondary
+            // key (the IMF endpoint is the same, only the header differs). Clear
+            // any HTTP response captured by an earlier attempt so the post-loop
+            // branch does not surface a stale 401/403 in place of this thrown
+            // error (the caller needs to see the real failure mode).
+            lastResponse = undefined;
+            break;
+        }
+    }
+    if (lastError !== undefined) {
+        const message = lastError instanceof Error ? lastError.message : String(lastError);
+        return { jsonrpc: '2.0', id, error: { code: -1, message } };
+    }
+    if (lastResponse !== undefined && !lastResponse.ok) {
         return {
             jsonrpc: '2.0',
             id,
-            result: { content: [{ type: 'text', text }] },
+            error: {
+                code: -1,
+                message: `HTTP ${lastResponse.status} ${lastResponse.statusText}`,
+            },
         };
     }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { jsonrpc: '2.0', id, error: { code: -1, message } };
-    }
+    return {
+        jsonrpc: '2.0',
+        id,
+        error: { code: -1, message: 'fetch_url failed without a response' },
+    };
 }
 // ─── Main server loop ─────────────────────────────────────────────────────────
 /**

package/scripts/mcp/imf-mcp-client.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module MCP/IMFMCPClient
  * @description Native TypeScript IMF Data client — calls the IMF SDMX 3.0
- * REST API at {@link https://dataservices.imf.org/REST/SDMX_3.0/} via the
+ * REST API at {@link https://api.imf.org/external/sdmx/3.0/} via the
  * shared IMF-only `fetch-proxy` MCP gateway in gh-aw/AWF runs and direct
  * `fetch()` in local/non-AWF contexts.
  *
@@ -34,7 +34,7 @@
  *
  * - Uses the native Node 25 `fetch()` — no extra runtime dependency.
  * - Every call has an independent `AbortController` with a configurable
- *   timeout (`IMF_API_TIMEOUT_MS`, default 30 s).
+ *   timeout (`IMF_API_TIMEOUT_MS`, default 90 s).
  * - Errors (HTTP 4xx/5xx, network faults, JSON parse failures, abort) are
  *   caught and converted to the {@link IMF_FALLBACK} envelope. Callers
  *   upstream can therefore treat "no IMF" as "empty data" without
@@ -42,12 +42,17 @@
  *
  * Environment variables:
  * - `IMF_API_BASE_URL` — override base URL (default
- *   `https://dataservices.imf.org/REST/SDMX_3.0`).
- * - `IMF_API_TIMEOUT_MS` — per-request timeout (default `30000`).
+ *   `https://api.imf.org/external/sdmx/3.0`).
+ * - `IMF_API_TIMEOUT_MS` — per-request timeout (default `90000`).
+ * - `IMF_API_PRIMARY_KEY` — Azure APIM subscription key for `api.imf.org`
+ *   (required since September 2025; sent as `Ocp-Apim-Subscription-Key`).
+ * - `IMF_API_SECONDARY_KEY` — warm-standby subscription key, used to retry
+ *   on `401`/`403` so live key rotation never breaks a run.
  *
  * Historic env vars (`IMF_MCP_GATEWAY_URL`, `IMF_MCP_GATEWAY_API_KEY`,
- * `IMF_MCP_SERVER_PATH`) are no longer consulted — no gateway is needed
- * because the IMF SDMX 3.0 API is an unauthenticated public endpoint.
+ * `IMF_MCP_SERVER_PATH`) are no longer consulted — the IMF SDMX surface
+ * runs over plain HTTPS (with subscription-key auth) via the AWF
+ * fetch-proxy MCP server when reached from a sandboxed agent.
  */
 import type { MCPToolResult, MCPClientOptions } from '../types/index.js';
 /**
@@ -113,6 +118,7 @@ export declare class IMFMCPClient {
     private readonly _fetchImpl;
     private readonly _fetchProxyGatewayUrl;
     private readonly _fetchProxyApiKey;
+    private readonly _imfSubscriptionKeys;
     private _connected;
     constructor(options?: IMFClientOptions);
     /**
@@ -147,10 +153,16 @@ export declare class IMFMCPClient {
     /**
      * List every IMF database (dataflow) exposed by the SDMX 3.0 API.
      *
-     * Virtual tool: `imf-list-databases`.
+     * Virtual tool: `imf-list-databases`. Hits the umbrella
+     * `/structure/dataflow` endpoint which returns every published
+     * dataflow across all IMF sub-agencies (`IMF.RES`, `IMF.STA`,
+     * `IMF.FAD`, `IMF.WHD`, `IMF.MCM`, …) — typically ~190 entries.
+     * Each row includes the publishing `agency` so callers know which
+     * agency to use when calling {@link getParameterDefs} or {@link fetchData}.
      *
      * @returns MCP-shaped result whose `content[0].text` carries a JSON
-     *   array of `{ id, name, description }` entries. Empty on error.
+     *   array of `{ id, name, description, agency, version }` entries.
+     *   Empty on error.
      */
     listDatabases(): Promise<MCPToolResult>;
     /**
@@ -170,28 +182,37 @@ export declare class IMFMCPClient {
      * dataflow. Essential before building an SDMX key for
      * {@link fetchData} because each database has its own dimension set.
      *
-     * Virtual tool: `imf-get-parameter-defs`.
+     * Virtual tool: `imf-get-parameter-defs`. Uses the
+     * `/structure/dataflow/{agency}/{id}/+?references=datastructure`
+     * endpoint because the legacy `/structure/datastructure/IMF/{id}/+`
+     * shape returns 204 on `api.imf.org` after the September-2025 IMF
+     * Data Portal migration retired the umbrella `IMF` agency.
      *
-     * @param databaseId - IMF dataflow identifier (e.g. `"WEO"`, `"IFS"`).
+     * @param databaseId - IMF dataflow identifier (e.g. `"WEO"`, `"FM"`).
+     * @param agencyId - Optional override; defaults to {@link resolveAgency}.
      * @returns MCP-shaped result whose `content[0].text` carries the
      *   ordered list of dimensions (`[{ id, name }]`). Empty on error.
      */
-    getParameterDefs(databaseId: string): Promise<MCPToolResult>;
+    getParameterDefs(databaseId: string, agencyId?: string): Promise<MCPToolResult>;
     /**
      * List valid codes for a single dimension of an IMF dataflow, with
      * an optional free-text filter to narrow the result.
      *
-     * Virtual tool: `imf-get-parameter-codes`. The underlying SDMX
-     * `/codelist/` endpoint is used, looked up from the datastructure so
-     * the caller does not need to know the codelist identifier ahead of
-     * time.
+     * Virtual tool: `imf-get-parameter-codes`. Uses
+     * `/structure/dataflow/{agency}/{id}/+?references=all` to fetch the
+     * DSD plus its referenced conceptSchemes and codelists in one
+     * round-trip — SDMX 3.0 binds the codelist on the *concept*
+     * (`coreRepresentation.enumeration`), so resolving codes requires
+     * walking dim → conceptIdentity → conceptScheme → concept → codelist.
      *
      * @param databaseId - IMF dataflow identifier.
-     * @param parameter - Dimension name (e.g. `"country"`, `"indicator"`).
+     * @param parameter - Dimension name (e.g. `"COUNTRY"`, `"INDICATOR"`;
+     *   matched case-insensitively).
      * @param search - Optional free-text search (case-insensitive substring).
+     * @param agencyId - Optional agency override; defaults to {@link resolveAgency}.
      * @returns MCP-shaped result with `[{ id, name }]` rows; empty on error.
      */
-    getParameterCodes(databaseId: string, parameter: string, search?: string): Promise<MCPToolResult>;
+    getParameterCodes(databaseId: string, parameter: string, search?: string, agencyId?: string): Promise<MCPToolResult>;
     /**
      * Fetch a time-series slice from an IMF dataflow as SDMX-JSON.
      *
@@ -202,13 +223,17 @@ export declare class IMFMCPClient {
      * April-2026 aggregator-pipeline migration.)
      *
      * @param options - Fetch parameters.
-     * @param options.databaseId - IMF dataflow ID (`"WEO"`, `"IFS"`, ...).
+     * @param options.databaseId - IMF dataflow ID (`"WEO"`, `"FM"`, ...).
      * @param options.startYear - Inclusive start year (e.g. `2015`).
      * @param options.endYear - Inclusive end year (e.g. `2030` for WEO forecasts).
-     * @param options.filters - Map of dimension → selected codes.
+     * @param options.filters - Map of dimension → selected codes. Filter
+     *   keys are matched case-insensitively against the DSD dimensions
+     *   (legacy lowercase `country`/`indicator`/`frequency` continue to work).
      * @param options.dimensionOrder - Optional override of the dimension order
      *   used to build the SDMX key. Defaults to
      *   {@link defaultDimensionOrder} for the database.
+     * @param options.agencyId - Optional SDMX agency override (e.g. `"IMF.RES"`,
+     *   `"IMF.STA"`). Defaults to {@link resolveAgency}.
      * @returns MCP-shaped result whose `content[0].text` carries the raw
      *   SDMX-JSON response. Empty on error or invalid inputs.
      */
@@ -218,6 +243,7 @@ export declare class IMFMCPClient {
         endYear: number;
         filters: Readonly<Record<string, readonly string[]>>;
         dimensionOrder?: readonly string[];
+        agencyId?: string;
     }): Promise<MCPToolResult>;
     /**
      * Build a full URL and GET it as text, enforcing the client-wide timeout.
@@ -231,6 +257,29 @@ export declare class IMFMCPClient {
      * @internal
      */
     private _getText;
+    /**
+     * Direct-fetch strategy with subscription-key rotation.
+     *
+     * Iterates configured `IMF_API_PRIMARY_KEY` → `IMF_API_SECONDARY_KEY`,
+     * retrying only on `401`/`403`. Network errors short-circuit immediately.
+     *
+     * @param url - Fully-qualified IMF SDMX URL.
+     * @returns Response body text on success.
+     * @throws The last HTTP/network error when all configured keys are exhausted.
+     * @internal
+     */
+    private _fetchDirectWithKeyRotation;
+    /**
+     * Single direct-fetch attempt with one subscription key. Classifies the
+     * outcome so {@link _fetchDirectWithKeyRotation} can decide whether to
+     * rotate keys or surface the error.
+     *
+     * @param url - Fully-qualified IMF SDMX URL.
+     * @param key - Subscription key for this attempt, or `undefined` to send unauthenticated.
+     * @returns `'ok'` with body text, `'auth'` with the 401/403 error, or `'error'` for everything else.
+     * @internal
+     */
+    private _fetchOnceWithKey;
     /**
      * Fetch a URL via the MCP fetch-proxy gateway (JSON-RPC 2.0 over HTTP).
      * The fetch-proxy server runs in a container that bypasses the AWF Squid proxy.