euparliamentmonitor 0.9.3 → 0.9.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euparliamentmonitor",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "type": "module",
   "description": "European Parliament Intelligence Platform - Monitor political activity with systematic transparency",
   "main": "scripts/index.js",

package/scripts/mcp/fetch-proxy-server.d.ts

@@ -32,7 +32,7 @@ export interface McpToolResult {
 /**
  * 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.
@@ -63,18 +63,6 @@ export declare function handleInitialize(id: number | string | null): JsonRpcSuc
  * @returns JSON-RPC success with the tool descriptor array.
  */
 export declare function handleToolsList(id: number | string | null): JsonRpcSuccess;
-/**
- * Execute the `fetch_url` tool call.
- *
- * 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.
- *
- * @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.
- */
 export declare function handleFetchUrl(id: number | string | null, url: string | undefined, fetchImpl?: typeof fetch): Promise<JsonRpcSuccess | JsonRpcError>;
 /**
  * Run the fetch-proxy MCP server, reading JSON-RPC messages from `input` and

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.

package/scripts/mcp/imf-mcp-client.js

@@ -1,21 +1,192 @@
 // SPDX-FileCopyrightText: 2024-2026 Hack23 AB
 // SPDX-License-Identifier: Apache-2.0
 // ─── Defaults ────────────────────────────────────────────────────────────────
-/** Default base URL for the IMF SDMX 3.0 REST API. */
-const DEFAULT_IMF_API_BASE_URL = 'https://dataservices.imf.org/REST/SDMX_3.0';
+/** Default base URL for the IMF Data Portal SDMX 3.0 REST API. */
+const DEFAULT_IMF_API_BASE_URL = 'https://api.imf.org/external/sdmx/3.0';
 /** Default per-request timeout (milliseconds). */
 const DEFAULT_IMF_API_TIMEOUT_MS = 90_000;
 /** Product identifier sent to IMF SDMX endpoints. */
 const IMF_USER_AGENT = 'euparliamentmonitor/0.9.0 (+https://github.com/Hack23/euparliamentmonitor)';
 /** IMF SDMX accepts JSON data; keep a fallback for proxy/content negotiation. */
 const IMF_ACCEPT_HEADER = 'application/json, application/vnd.sdmx.data+json, */*;q=0.8';
-/** Common unauthenticated headers for direct IMF SDMX REST requests. */
+/** Common headers for direct IMF SDMX REST requests (auth header added per-request). */
 const IMF_REQUEST_HEADERS = Object.freeze({
     Accept: IMF_ACCEPT_HEADER,
     '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';
+/**
+ * Per-dataflow → maintainer agency map for the post-September-2025 IMF
+ * Data Portal, where the umbrella `IMF` agency was retired in favour of
+ * sub-departmental agency IDs (`IMF.RES`, `IMF.STA`, `IMF.FAD`, `IMF.WHD`,
+ * `IMF.MCM`, …). Discovered live against
+ * `GET /structure/dataflow` on `api.imf.org/external/sdmx/3.0`.
+ *
+ * Keys are uppercased dataflow IDs; values are the canonical agency that
+ * publishes them. Unknown / vintage-suffixed IDs (e.g. `WEO_2025_OCT_VINTAGE`)
+ * fall through to {@link DEFAULT_IMF_AGENCY}.
+ */
+const IMF_DATAFLOW_AGENCY = Object.freeze({
+    // IMF.RES — Research Department (forecasts + commodity prices)
+    WEO: 'IMF.RES',
+    PCPS: 'IMF.RES',
+    ITS: 'IMF.RES',
+    // IMF.FAD — Fiscal Affairs Department
+    FM: 'IMF.FAD',
+    // IMF.STA — Statistics Department (everything else editorial)
+    CPI: 'IMF.STA',
+    CPI_WCA: 'IMF.STA',
+    BOP: 'IMF.STA',
+    BOP_AGG: 'IMF.STA',
+    ER: 'IMF.STA',
+    IFS: 'IMF.STA',
+    DOT: 'IMF.STA',
+    CDIS: 'IMF.STA',
+    CPIS: 'IMF.STA',
+    GFS: 'IMF.STA',
+    GFS_SOO: 'IMF.STA',
+    GFS_BS: 'IMF.STA',
+    GFS_COFOG: 'IMF.STA',
+    GFS_SSUC: 'IMF.STA',
+    GFS_SOEF: 'IMF.STA',
+    GFS_SFCP: 'IMF.STA',
+    FSI: 'IMF.STA',
+    MFS: 'IMF.STA',
+    MFS_FC: 'IMF.STA',
+    FA: 'IMF.STA',
+    GFSR: 'IMF.STA',
+});
+/** Fallback agency when {@link IMF_DATAFLOW_AGENCY} has no entry — most editorial dataflows are STA-published. */
+const DEFAULT_IMF_AGENCY = 'IMF.STA';
+/**
+ * Parse an SDMX URN into its three salient parts:
+ * agency (optional), id, and concept-id (only present for Concept URNs).
+ *
+ * Examples handled:
+ *   - `urn:sdmx:org.sdmx.infomodel.codelist.Codelist=IMF.RES:CL_WEO_INDICATOR(2.0+.0)`
+ *     → `{ agency: 'IMF.RES', id: 'CL_WEO_INDICATOR', conceptId: '' }`
+ *   - `urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=IMF.RES:CS_WEO(4.0+.0).INDICATOR`
+ *     → `{ agency: 'IMF.RES', id: 'CS_WEO', conceptId: 'INDICATOR' }`
+ *
+ * Pure string-split parsing (no regex) so the static-analysis "unsafe regex"
+ * detector has nothing to object to and the extraction stays linear.
+ *
+ * Assumption: IMF SDMX 3.0 always emits a `(version)` block on every
+ * URN we encounter, so the concept-id extraction relies on the closing
+ * `)`. If the version block is missing or malformed (no `)`) we treat
+ * the URN as having no concept-id rather than fall back to slicing
+ * from the start of the body — which would silently leak the codelist
+ * id into the conceptId field.
+ *
+ * @param urn - SDMX URN to parse.
+ * @returns Parsed parts (any field may be empty if absent in the URN).
+ * @internal
+ */
+function parseSDMXUrn(urn) {
+    const eqIdx = urn.indexOf('=');
+    const body = eqIdx >= 0 ? urn.slice(eqIdx + 1) : urn;
+    const parenIdx = body.indexOf('(');
+    const head = parenIdx >= 0 ? body.slice(0, parenIdx) : body;
+    // Concept URNs have a trailing `.CONCEPT_ID` after the closing paren.
+    // Guard the missing-`)` case explicitly: `indexOf(')', n)` returns -1
+    // when absent, and `body.slice(-1 + 1) = body.slice(0)` would echo
+    // the whole URN body into `tail` — yielding a bogus conceptId.
+    let tail = '';
+    if (parenIdx >= 0) {
+        const closeIdx = body.indexOf(')', parenIdx);
+        if (closeIdx >= 0)
+            tail = body.slice(closeIdx + 1);
+    }
+    const conceptId = tail.startsWith('.') ? tail.slice(1) : '';
+    const colonIdx = head.indexOf(':');
+    const agency = colonIdx >= 0 ? head.slice(0, colonIdx) : '';
+    const id = colonIdx >= 0 ? head.slice(colonIdx + 1) : head;
+    return { agency, id, conceptId };
+}
+/**
+ * Resolve the codelist URN for a single dimension by walking the SDMX
+ * 3.0 dimension → concept → codelist binding chain.
+ *
+ * Tries the legacy SDMX 2.1 shape first (`localRepresentation.enumeration`
+ * directly on the dimension) before falling back to the SDMX 3.0 shape
+ * where the binding lives on the concept (`coreRepresentation.enumeration`).
+ *
+ * @param dim - DSD dimension entry.
+ * @param conceptSchemes - Inlined conceptSchemes from the same payload.
+ * @returns Codelist URN, or `undefined` when no binding is declared.
+ * @internal
+ */
+function resolveCodelistUrn(dim, conceptSchemes) {
+    const direct = dim.localRepresentation?.enumeration;
+    if (direct)
+        return direct;
+    if (!dim.conceptIdentity)
+        return undefined;
+    const { agency, id, conceptId } = parseSDMXUrn(dim.conceptIdentity);
+    if (!conceptId)
+        return undefined;
+    const cs = conceptSchemes.find((s) => s.id === id && (agency === '' || s.agencyID === agency));
+    const concept = cs?.concepts?.find((c) => c.id === conceptId);
+    return concept?.coreRepresentation?.enumeration;
+}
+/**
+ * Resolve the actual list of codes for a single dimension by looking up
+ * the bound codelist in the inlined codelists payload. Falls back to
+ * any inlined `dim.values` array when present.
+ *
+ * @param dim - DSD dimension entry.
+ * @param payload - The `data` block of an SDMX `references=all` response
+ *   (must contain `conceptSchemes` and `codelists`).
+ * @returns Ordered list of `{ id, name }` codes; empty when the
+ *   dimension has neither inlined values nor a resolvable codelist.
+ * @internal
+ */
+function resolveCodelistCodes(dim, payload) {
+    if (dim.values && dim.values.length > 0)
+        return dim.values;
+    const urn = resolveCodelistUrn(dim, payload.conceptSchemes ?? []);
+    if (!urn)
+        return [];
+    const { agency, id } = parseSDMXUrn(urn);
+    if (!id)
+        return [];
+    const cls = payload.codelists ?? [];
+    const exact = cls.find((c) => c.id === id && (!agency || c.agencyID === agency));
+    const cl = exact ?? cls.find((c) => c.id === id);
+    return cl?.codes ?? [];
+}
+/**
+ * Resolve the SDMX agency for a dataflow.
+ *
+ * Strips any `_YYYY_MMM_VINTAGE` suffix before lookup so monthly vintage
+ * IDs (`WEO_2025_OCT_VINTAGE`) inherit the same agency as their
+ * canonical "latest" sibling (`WEO`).
+ *
+ * @param databaseId - IMF dataflow identifier.
+ * @returns Agency code (e.g. `"IMF.RES"`).
+ * @internal
+ */
+function resolveAgency(databaseId) {
+    const upper = databaseId.toUpperCase();
+    // Avoid dynamic object indexing so the security lint does not flag user input as a sink.
+    const direct = Object.entries(IMF_DATAFLOW_AGENCY).find(([k]) => k === upper)?.[1];
+    if (direct)
+        return direct;
+    // Vintage suffix: WEO_2025_OCT_VINTAGE → WEO
+    const vintageIdx = upper.indexOf('_VINTAGE');
+    if (vintageIdx > 0) {
+        const trimmed = upper.slice(0, vintageIdx).split('_').slice(0, -2).join('_');
+        if (trimmed) {
+            const fromBase = Object.entries(IMF_DATAFLOW_AGENCY).find(([k]) => k === trimmed)?.[1];
+            if (fromBase)
+                return fromBase;
+        }
+    }
+    return DEFAULT_IMF_AGENCY;
+}
 /** Fallback payload shape when an IMF call fails or the server is offline. */
 const IMF_FALLBACK = {
     content: [{ type: 'text', text: '' }],
@@ -130,8 +301,15 @@ export function countIMFSDMXObservations(payload) {
  * avoid collisions with user-supplied codes that happen to contain
  * those characters.
  *
- * @param codes - Ordered code values for a single dimension (may be empty = wildcard).
- * @returns URL-safe dimension component (`""` for wildcard, `"A+B"` for union).
+ * Callers must NOT pass an empty array. The post-Sept-2025 IMF Data
+ * Portal rejects bare empty positions (`DEU..A` returns 0 series); the
+ * SDMX 3.0 wildcard for "match every code in this dimension" is the
+ * literal `*` and is emitted by {@link buildSDMXKey} directly when a
+ * dimension has no caller-supplied codes — never by passing `[]` here.
+ *
+ * @param codes - Ordered, non-empty code values for a single dimension.
+ * @returns URL-safe dimension component (`"A"` for a single code,
+ *   `"A+B"` for a union; never `""` — see note above).
  * @internal
  */
 function encodeSDMXDimension(codes) {
@@ -140,23 +318,33 @@ function encodeSDMXDimension(codes) {
 /**
  * Build an SDMX key from a filters map + declared dimension order.
  *
- * If a declared dimension is absent from `filters`, the slot is left as
- * the wildcard (empty string). Extra filter keys not present in the
- * declared order are ignored — the caller is expected to have discovered
- * the correct dimension names via {@link IMFMCPClient.getParameterDefs}.
+ * If a declared dimension is absent from `filters`, the slot is filled
+ * with the SDMX 3.0 wildcard `*` (the post-Sept-2025 IMF Data Portal
+ * rejects bare empty positions — `DEU..A` returns 0 series, `DEU.*.A`
+ * returns the full set). Extra filter keys not present in the declared
+ * order are ignored — the caller is expected to have discovered the
+ * correct dimension names via {@link IMFMCPClient.getParameterDefs}.
  *
- * @param dimensions - Declared dimension order (e.g. `["frequency","country","indicator"]`).
+ * Filter keys are matched case-insensitively against declared dimension
+ * names so callers can keep using the legacy lowercase aliases
+ * (`country`, `indicator`, `frequency`) even though the IMF SDMX 3.0
+ * DSDs use uppercase (`COUNTRY`, `INDICATOR`, `FREQUENCY`).
+ *
+ * @param dimensions - Declared dimension order (e.g. `["COUNTRY","INDICATOR","FREQUENCY"]`).
  * @param filters - Map of dimension → selected codes.
- * @returns SDMX key (e.g. `"A.DEU.NGDP_RPCH"`).
+ * @returns SDMX key (e.g. `"DEU.NGDP_RPCH.A"` or `"DEU.*.A"` for wildcard indicator).
  * @internal
  */
 function buildSDMXKey(dimensions, filters) {
+    const lowercasedFilters = Object.entries(filters).map(([key, value]) => [key.toLowerCase(), value]);
     return dimensions
         .map((dim) => {
-        // Avoid direct dynamic object indexing here so the security lint rule
-        // does not flag caller-supplied SDMX dimension names as an injection sink.
-        const codes = Object.entries(filters).find(([key]) => key === dim)?.[1];
-        return Array.isArray(codes) ? encodeSDMXDimension(codes) : '';
+        const dimLc = dim.toLowerCase();
+        const codes = lowercasedFilters.find(([key]) => key === dimLc)?.[1];
+        // SDMX 3.0 wildcard for "match every code in this dimension" is `*`.
+        // The legacy SDMX 2.1 convention of leaving the segment bare is
+        // rejected by `api.imf.org` post-Sept-2025 (returns 0 series).
+        return Array.isArray(codes) && codes.length > 0 ? encodeSDMXDimension(codes) : '*';
     })
         .join('.');
 }
@@ -166,8 +354,12 @@ function buildSDMXKey(dimensions, filters) {
  * fallback because the WEO datastructure in particular is so widely used
  * that encoding a well-known default eliminates one round-trip per fetch.
  *
- * Order mirrors the IMF SDMX 3.0 DSDs catalogued in
- * `analysis/imf/sdmx-dimensions-reference.md`.
+ * Order mirrors the IMF SDMX 3.0 DSDs catalogued live against
+ * `api.imf.org/external/sdmx/3.0/structure/dataflow/{agency}/{id}/+?references=datastructure`
+ * (post-Sept-2025 Data Portal migration). All dimension names are
+ * UPPERCASE and `FREQUENCY` is the **last** series-level dimension —
+ * the legacy SDMX 2.1 convention of leading with `FREQ` no longer
+ * applies on `api.imf.org`.
  *
  * @param databaseId - Dataflow identifier (case-insensitive).
  * @returns Default dimension order used when the caller omits it.
@@ -178,25 +370,37 @@ function defaultDimensionOrder(databaseId) {
         case 'WEO':
         case 'FM':
         case 'IFS':
-        case 'CPI':
         case 'BOP_AGG':
+            return ['COUNTRY', 'INDICATOR', 'FREQUENCY'];
+        case 'CPI':
+        case 'CPI_WCA':
+            return ['COUNTRY', 'INDEX_TYPE', 'COICOP_1999', 'TYPE_OF_TRANSFORMATION', 'FREQUENCY'];
+        case 'BOP':
+            return ['COUNTRY', 'BOP_ACCOUNTING_ENTRY', 'INDICATOR', 'UNIT', 'FREQUENCY'];
         case 'ER':
-        case 'FSI':
-            return ['frequency', 'country', 'indicator'];
+            return ['COUNTRY', 'INDICATOR', 'TYPE_OF_TRANSFORMATION', 'FREQUENCY'];
+        case 'PCPS':
+            return ['COUNTRY', 'INDICATOR', 'DATA_TRANSFORMATION', 'FREQUENCY'];
         case 'DOT':
-            return ['frequency', 'country', 'counterpartArea', 'indicator'];
+            return ['COUNTRY', 'COUNTERPART_AREA', 'INDICATOR', 'FREQUENCY'];
         case 'CDIS':
-            return ['frequency', 'country', 'counterpartArea', 'sector', 'indicator'];
+            return ['COUNTRY', 'COUNTERPART_AREA', 'SECTOR', 'INDICATOR', 'FREQUENCY'];
         case 'CPIS':
-            return ['frequency', 'country', 'counterpartArea', 'instrument', 'indicator'];
-        case 'PCPS':
-            return ['frequency', 'indicator'];
+            return ['COUNTRY', 'COUNTERPART_AREA', 'INSTRUMENT', 'INDICATOR', 'FREQUENCY'];
+        case 'FSI':
+            return ['COUNTRY', 'INDICATOR', 'SECTOR', 'FREQUENCY'];
         case 'GFSR':
-            return ['frequency', 'country', 'indicator', 'sector'];
+            return ['COUNTRY', 'INDICATOR', 'SECTOR', 'FREQUENCY'];
         case 'GFS':
-            return ['frequency', 'country', 'sector', 'unit', 'indicator'];
+        case 'GFS_SOO':
+        case 'GFS_BS':
+        case 'GFS_COFOG':
+        case 'GFS_SSUC':
+        case 'GFS_SOEF':
+        case 'GFS_SFCP':
+            return ['COUNTRY', 'SECTOR', 'UNIT', 'INDICATOR', 'FREQUENCY'];
         default:
-            return ['frequency', 'country', 'indicator'];
+            return ['COUNTRY', 'INDICATOR', 'FREQUENCY'];
     }
 }
 /**
@@ -232,17 +436,102 @@ function defaultFrequency(databaseId) {
     }
 }
 /**
- * Add a dataflow-specific default frequency when the caller omitted one.
+ * Add a dataflow-specific default frequency when the caller omitted one,
+ * and normalise the legacy `freq` alias to the SDMX 3.0 `FREQUENCY`
+ * dimension name. {@link buildSDMXKey} matches dimension keys by name
+ * (`frequency`/`FREQUENCY`), so a caller that passes `freq: ['A']`
+ * would otherwise be silently dropped and the FREQUENCY slot filled
+ * with the `*` wildcard — pulling far more data than intended.
  *
  * @param databaseId - Dataflow identifier.
  * @param filters - Caller-supplied SDMX dimension filters.
- * @returns The original filters or a shallow copy with `frequency` populated.
+ * @returns The original filters or a shallow copy with `FREQUENCY` populated.
  * @internal
  */
 function withDefaultFrequency(databaseId, filters) {
-    const hasFrequency = Object.entries(filters).some(([key]) => key === 'frequency');
-    const frequency = defaultFrequency(databaseId);
-    return !hasFrequency && frequency ? { ...filters, frequency: [frequency] } : filters;
+    // Pull any caller-supplied frequency value out of the legacy `freq`
+    // alias (or any case variant of `frequency`) so we can re-emit it
+    // under the canonical uppercase `FREQUENCY` key that buildSDMXKey
+    // and defaultDimensionOrder both use.
+    let freqCodes;
+    const passthrough = {};
+    for (const [key, value] of Object.entries(filters)) {
+        const k = key.toLowerCase();
+        if (k === 'frequency' || k === 'freq') {
+            if (Array.isArray(value) && value.length > 0 && freqCodes === undefined) {
+                freqCodes = value;
+            }
+        }
+        else {
+            passthrough[key] = value;
+        }
+    }
+    const fallback = freqCodes ??
+        (() => {
+            const f = defaultFrequency(databaseId);
+            return f ? [f] : undefined;
+        })();
+    return fallback ? { ...passthrough, FREQUENCY: fallback } : filters;
+}
+/**
+ * Resolve the IMF base URL and per-request timeout from constructor options
+ * and environment variables. Extracted so the {@link IMFMCPClient}
+ * constructor stays under SonarJS's cognitive-complexity threshold.
+ *
+ * @param options - Caller-supplied options (take precedence over env).
+ * @returns Resolved `base` (raw, may have trailing slashes) and `timeout`.
+ * @internal
+ */
+function readBaseAndTimeout(options) {
+    const envBase = process.env['IMF_API_BASE_URL'];
+    const envTimeout = process.env['IMF_API_TIMEOUT_MS'];
+    const parsedEnvTimeout = envTimeout !== undefined && envTimeout !== '' ? Number.parseInt(envTimeout, 10) : Number.NaN;
+    const base = options.apiBaseUrl ?? (envBase && envBase !== '' ? envBase : DEFAULT_IMF_API_BASE_URL);
+    let timeout;
+    if (options.timeoutMs !== undefined &&
+        Number.isFinite(options.timeoutMs) &&
+        options.timeoutMs > 0) {
+        timeout = options.timeoutMs;
+    }
+    else if (Number.isFinite(parsedEnvTimeout) && parsedEnvTimeout > 0) {
+        timeout = parsedEnvTimeout;
+    }
+    else {
+        timeout = DEFAULT_IMF_API_TIMEOUT_MS;
+    }
+    return { base, timeout };
+}
+/**
+ * Strip trailing slashes without using a regex, so the CodeQL polynomial-
+ * ReDoS detector has nothing to flag. Single linear pass from the right.
+ *
+ * @param s - Input string.
+ * @returns The input with all trailing `/` characters removed.
+ * @internal
+ */
+function stripTrailingSlashes(s) {
+    let end = s.length;
+    while (end > 0 && s.charCodeAt(end - 1) === 47 /* '/' */) {
+        end -= 1;
+    }
+    return end === s.length ? s : s.slice(0, end);
+}
+/**
+ * Read IMF Azure-APIM subscription keys from the environment, in priority
+ * order (primary, then secondary). Empty / unset / duplicate keys are
+ * filtered out so the returned array is `[]` only when no key is set at all.
+ *
+ * @returns Ordered list of candidate API keys (length 0–2).
+ * @internal
+ */
+function readImfSubscriptionKeysFromEnv() {
+    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;
 }
 // ─── Client ──────────────────────────────────────────────────────────────────
 /**
@@ -259,31 +548,22 @@ export class IMFMCPClient {
     _fetchImpl;
     _fetchProxyGatewayUrl;
     _fetchProxyApiKey;
+    _imfSubscriptionKeys;
     _connected = false;
     constructor(options = {}) {
-        const envBase = process.env['IMF_API_BASE_URL'];
-        const envTimeout = process.env['IMF_API_TIMEOUT_MS'];
-        const parsedEnvTimeout = envTimeout !== undefined && envTimeout !== '' ? Number.parseInt(envTimeout, 10) : Number.NaN;
-        const base = options.apiBaseUrl ?? (envBase && envBase !== '' ? envBase : DEFAULT_IMF_API_BASE_URL);
-        // Strip trailing slashes without a regex so the CodeQL polynomial-ReDoS
-        // detector has nothing to flag. Single linear pass from the right.
-        let end = base.length;
-        while (end > 0 && base.charCodeAt(end - 1) === 47 /* '/' */) {
-            end -= 1;
-        }
-        this._apiBaseUrl = end === base.length ? base : base.slice(0, end);
-        this._timeoutMs =
-            options.timeoutMs !== undefined && Number.isFinite(options.timeoutMs) && options.timeoutMs > 0
-                ? options.timeoutMs
-                : Number.isFinite(parsedEnvTimeout) && parsedEnvTimeout > 0
-                    ? parsedEnvTimeout
-                    : DEFAULT_IMF_API_TIMEOUT_MS;
+        const { base, timeout } = readBaseAndTimeout(options);
+        this._apiBaseUrl = stripTrailingSlashes(base);
+        this._timeoutMs = timeout;
         this._fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
         // MCP fetch-proxy gateway for AWF sandbox (bypasses Squid proxy)
         this._fetchProxyGatewayUrl =
             options.fetchProxyGatewayUrl ?? process.env['FETCH_MCP_GATEWAY_URL'] ?? undefined;
         this._fetchProxyApiKey =
             options.fetchProxyApiKey ?? process.env['EP_MCP_GATEWAY_API_KEY'] ?? undefined;
+        // IMF Azure-APIM subscription keys (primary + secondary). The fetch-proxy
+        // server already injects the same header when it is the transport, so this
+        // is mainly for the direct-fetch fallback used outside the AWF sandbox.
+        this._imfSubscriptionKeys = readImfSubscriptionKeysFromEnv();
     }
     /**
      * Base URL currently in use (read-only — set at construction time).
@@ -338,19 +618,27 @@ export 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.
      */
     async listDatabases() {
         try {
-            const json = await this._getJSON('/dataflow/IMF');
+            const json = await this._getJSON('/structure/dataflow');
             const flows = json?.data?.dataflows ?? [];
             const rows = flows.map((f) => ({
                 id: f.id ?? '',
                 name: unwrapLocalisedLabel(f.name),
                 description: unwrapLocalisedLabel(f.description),
+                agency: f.agencyID ?? '',
+                version: f.version ?? '',
             }));
             return wrapAsMCPResult(rows);
         }
@@ -377,7 +665,7 @@ export class IMFMCPClient {
             return IMF_FALLBACK;
         }
         try {
-            const json = await this._getJSON('/dataflow/IMF');
+            const json = await this._getJSON('/structure/dataflow');
             const flows = json?.data?.dataflows ?? [];
             const needle = keyword.toLowerCase();
             const rows = flows
@@ -385,6 +673,8 @@ export class IMFMCPClient {
                 id: f.id ?? '',
                 name: unwrapLocalisedLabel(f.name),
                 description: unwrapLocalisedLabel(f.description),
+                agency: f.agencyID ?? '',
+                version: f.version ?? '',
             }))
                 .filter((r) => {
                 const hay = `${r.id} ${r.name} ${r.description}`.toLowerCase();
@@ -403,19 +693,25 @@ export 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.
      */
-    async getParameterDefs(databaseId) {
+    async getParameterDefs(databaseId, agencyId) {
         if (!databaseId) {
             console.warn('imf-get-parameter-defs called without databaseId');
             return IMF_FALLBACK;
         }
         try {
-            const json = await this._getJSON(`/datastructure/${encodeURIComponent(databaseId)}`);
+            const agency = agencyId ?? resolveAgency(databaseId);
+            const json = await this._getJSON(`/structure/dataflow/${encodeURIComponent(agency)}/${encodeURIComponent(databaseId)}/+?references=datastructure`);
             const ds = json?.data?.dataStructures?.[0];
             const dims = ds?.dataStructureComponents?.dimensionList?.dimensions ?? [];
             const rows = dims.map((d) => ({ id: d.id, name: unwrapLocalisedLabel(d.name) }));
@@ -431,58 +727,46 @@ export class IMFMCPClient {
      * 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.
      */
-    async getParameterCodes(databaseId, parameter, search) {
+    async getParameterCodes(databaseId, parameter, search, agencyId) {
         if (!databaseId || !parameter) {
             console.warn('imf-get-parameter-codes requires databaseId and parameter');
             return IMF_FALLBACK;
         }
         try {
-            // 1. Discover the codelist id for the requested dimension.
-            const structure = await this._getJSON(`/datastructure/${encodeURIComponent(databaseId)}?references=codelist`);
+            const agency = agencyId ?? resolveAgency(databaseId);
+            // `references=all` returns DSD + conceptSchemes + codelists in one
+            // round-trip. The IMF SDMX 3.0 DSDs put the codelist binding on
+            // the *concept* (`coreRepresentation.enumeration`), not on the
+            // dimension itself, so we need both the DSD (for the dimension →
+            // concept link) and the conceptScheme (for the concept → codelist
+            // link). The payload is large (~2-3 MB for WEO) — it's fetched
+            // once per workflow run by gh-aw and cached upstream.
+            const structure = await this._getJSON(`/structure/dataflow/${encodeURIComponent(agency)}/${encodeURIComponent(databaseId)}/+?references=all`);
             const ds = structure?.data?.dataStructures?.[0];
             const dims = ds?.dataStructureComponents?.dimensionList?.dimensions ?? [];
             const dim = dims.find((d) => d.id.toLowerCase() === parameter.toLowerCase());
             if (!dim) {
                 return wrapAsMCPResult([]);
             }
-            // The SDMX codelist reference URN looks like
-            //   "urn:sdmx:org.sdmx.infomodel.codelist.Codelist=IMF:CL_AREA(1.0)"
-            // We only need the codelist id — use string-split parsing
-            // (no regex) so the static-analysis "unsafe regex" detector has
-            // nothing to object to and the extraction stays obviously linear.
-            let codelistId = dim.localRepresentation?.enumeration;
-            if (codelistId) {
-                const afterEquals = codelistId.includes('=')
-                    ? (codelistId.split('=')[1] ?? '')
-                    : codelistId;
-                const beforeParen = afterEquals.split('(')[0] ?? '';
-                const parts = beforeParen.split(':');
-                codelistId = (parts[parts.length - 1] ?? beforeParen).trim() || codelistId;
-            }
-            // Some payloads inline the values directly; prefer those when present.
-            let codes = dim.values ?? [];
-            if (codes.length === 0 && codelistId) {
-                const cl = structure?.data?.codelists?.find((c) => c.id === codelistId);
-                codes = cl?.codes ?? [];
-            }
+            const codes = resolveCodelistCodes(dim, structure?.data ?? {});
             const needle = (search ?? '').toLowerCase();
             const rows = codes
                 .map((c) => ({ id: c.id, name: unwrapLocalisedLabel(c.name) }))
-                .filter((r) => {
-                if (!needle)
-                    return true;
-                return `${r.id} ${r.name}`.toLowerCase().includes(needle);
-            });
+                .filter((r) => !needle || `${r.id} ${r.name}`.toLowerCase().includes(needle));
             return wrapAsMCPResult(rows);
         }
         catch (error) {
@@ -501,18 +785,22 @@ export 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.
      */
     async fetchData(options) {
-        const { databaseId, startYear, endYear, filters, dimensionOrder } = options;
+        const { databaseId, startYear, endYear, filters, dimensionOrder, agencyId } = options;
         if (!databaseId || !filters || Object.keys(filters).length === 0) {
             console.warn('imf-fetch-data requires databaseId and a non-empty filters map');
             return IMF_FALLBACK;
@@ -522,14 +810,32 @@ export class IMFMCPClient {
             return IMF_FALLBACK;
         }
         try {
+            const agency = agencyId ?? resolveAgency(databaseId);
             const dims = dimensionOrder ?? defaultDimensionOrder(databaseId);
-            const key = buildSDMXKey(dims, withDefaultFrequency(databaseId, filters));
+            const normalisedFilters = withDefaultFrequency(databaseId, filters);
+            const key = buildSDMXKey(dims, normalisedFilters);
+            // Guard against accidentally unbounded downloads: at least one
+            // *non-FREQUENCY* slot must be concrete (not `*`). FREQUENCY
+            // auto-injects via withDefaultFrequency, so requiring it would
+            // not prove the caller intended a bounded query — a typo'd
+            // filter key (e.g. `region` instead of `country` for WEO) would
+            // otherwise yield `*.*.A`, downloading the full WEO cross-product.
+            // Callers wanting a single wildcard slot (e.g. `DEU.*.A`) still
+            // pass because `DEU` pins the COUNTRY dimension.
+            const slots = key.split('.');
+            const hasConcreteNonFreqSlot = dims.some((dim, i) => dim.toUpperCase() !== 'FREQUENCY' && slots[i] !== '*');
+            if (!hasConcreteNonFreqSlot) {
+                console.warn(`imf-fetch-data refusing unbounded request for ${databaseId} (${dims.join('.')}=${key}): ` +
+                    `at least one non-FREQUENCY dimension must have a concrete filter value. ` +
+                    `Filter keys received: ${Object.keys(filters).join(', ') || '<none>'}`);
+                return IMF_FALLBACK;
+            }
             const qs = new URLSearchParams({
                 startPeriod: String(startYear),
                 endPeriod: String(endYear),
                 format: 'jsondata',
             });
-            const url = `/data/${encodeURIComponent(databaseId)}/${key}?${qs.toString()}`;
+            const url = `/data/dataflow/${encodeURIComponent(agency)}/${encodeURIComponent(databaseId)}/+/${key}?${qs.toString()}`;
             const text = await this._getText(url);
             return wrapAsMCPResult(text);
         }
@@ -570,18 +876,83 @@ export class IMFMCPClient {
             }
         }
         // Strategy 2: Direct fetch (works outside AWF sandbox)
+        // Tries the primary subscription key first, falling back to the secondary
+        // on 401/403 so live IMF key rotation never breaks an in-flight run.
+        return this._fetchDirectWithKeyRotation(url);
+    }
+    /**
+     * 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
+     */
+    async _fetchDirectWithKeyRotation(url) {
+        const attempts = this._imfSubscriptionKeys.length > 0 ? [...this._imfSubscriptionKeys] : [undefined];
+        let lastError;
+        for (let i = 0; i < attempts.length; i += 1) {
+            const isLast = i + 1 >= attempts.length;
+            const outcome = await this._fetchOnceWithKey(url, attempts[i]);
+            if (outcome.kind === 'ok')
+                return outcome.text;
+            lastError = outcome.error;
+            if (outcome.kind === 'auth' && !isLast)
+                continue;
+            throw outcome.error;
+        }
+        if (lastError !== undefined)
+            throw lastError;
+        throw new Error(`IMF request to ${url} failed without producing a response`);
+    }
+    /**
+     * 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
+     */
+    async _fetchOnceWithKey(url, key) {
+        const headers = { ...IMF_REQUEST_HEADERS };
+        if (key !== undefined && key.length > 0) {
+            headers[IMF_SUBSCRIPTION_KEY_HEADER] = key;
+        }
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this._timeoutMs);
         try {
             const response = await this._fetchImpl(url, {
                 method: 'GET',
-                headers: IMF_REQUEST_HEADERS,
+                headers,
                 signal: controller.signal,
             });
-            if (!response.ok) {
-                throw new Error(`HTTP ${response.status} ${response.statusText} for ${url}`);
+            if (response.ok) {
+                // `api.imf.org` returns 204 when the request reached Azure APIM
+                // but no Ocp-Apim-Subscription-Key matched. 204 is technically
+                // 2xx, so without this explicit branch the empty body would be
+                // returned as a successful SDMX-JSON envelope and downstream
+                // parsers would silently produce empty series. Treat 204 as an
+                // error so missing/invalid keys are caught at Stage A.
+                if (response.status === 204) {
+                    return {
+                        kind: 'error',
+                        error: new Error(`HTTP 204 No Content for ${url} — likely missing or invalid ${IMF_SUBSCRIPTION_KEY_HEADER} (set IMF_API_PRIMARY_KEY)`),
+                    };
+                }
+                return { kind: 'ok', text: await response.text() };
             }
-            return await response.text();
+            const error = new Error(`HTTP ${response.status} ${response.statusText} for ${url}`);
+            const isAuthFailure = response.status === 401 || response.status === 403;
+            return { kind: isAuthFailure ? 'auth' : 'error', error };
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            return { kind: 'error', error };
         }
         finally {
             clearTimeout(timer);

package/scripts/types/imf.d.ts

@@ -3,7 +3,7 @@
  * @description Types for IMF (International Monetary Fund) economic data
  * integration via the native TypeScript SDMX 3.0 REST client
  * (`src/mcp/imf-mcp-client.ts`), which calls
- * `https://dataservices.imf.org/REST/SDMX_3.0/` directly.
+ * `https://api.imf.org/external/sdmx/3.0/` directly.
  *
  * Used to enrich EU Parliament articles with **fresher** macroeconomic context
  * than the World Bank WDI provides (IMF WEO ships 2025 actuals + 2026-2030
@@ -28,7 +28,7 @@
  * (parsers, indicator/country maps, HTML builders) was purged in the
  * April-2026 aggregator-pipeline migration.
  *
- * @see {@link https://dataservices.imf.org/REST/SDMX_3.0 | IMF SDMX 3.0 REST API}
+ * @see {@link https://api.imf.org/external/sdmx/3.0 | IMF SDMX 3.0 REST API}
  * @see {@link https://github.com/Hack23/euparliamentmonitor/blob/main/analysis/methodologies/imf-indicator-mapping.md | IMF Indicator Mapping methodology} for the committee →
  *   IMF indicator mapping enforced at Stage-C editorial review.
  */
@@ -42,7 +42,7 @@ import type { MCPClientOptions } from './mcp.js';
  * actually consumed by the native HTTP transport:
  *
  * - `apiBaseUrl` — override the IMF REST base URL (default
- *   `https://dataservices.imf.org/REST/SDMX_3.0`).
+ *   `https://api.imf.org/external/sdmx/3.0`).
  * - `timeoutMs` — per-request timeout in milliseconds.
  * - `fetchImpl` — optional `fetch` injection for tests.
  *