@cyanheads/imf-mcp-server 0.1.1

package/dist/mcp-server/tools/definitions/index.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview Barrel export for all IMF MCP tool definitions.
+ * @module mcp-server/tools/definitions/index
+ */
+export { imfDataframeDescribe } from './imf-dataframe-describe.tool.js';
+export { imfDataframeQuery } from './imf-dataframe-query.tool.js';
+export { imfGetDatabase } from './imf-get-database.tool.js';
+export { imfListDatabases } from './imf-list-databases.tool.js';
+export { imfQueryDataset } from './imf-query-dataset.tool.js';
+export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+    canvas_id: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    canvas_id: import("zod").ZodString;
+    tables: import("zod").ZodArray<import("zod").ZodObject<{
+        name: import("zod").ZodString;
+        row_count: import("zod").ZodNumber;
+        columns: import("zod").ZodArray<import("zod").ZodObject<{
+            name: import("zod").ZodString;
+            type: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>>;
+    table_count: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "canvas_not_found";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly when: "canvas_id does not match any registered DataCanvas table (expired, wrong session, or canvas disabled)";
+    readonly recovery: "Re-run imf_query_dataset to obtain a fresh canvas_id; ensure CANVAS_PROVIDER_TYPE=duckdb is set.";
+}], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+    canvas_id: import("zod").ZodString;
+    sql: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    rows: import("zod").ZodArray<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
+    row_count: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "canvas_not_found";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly when: "canvas_id does not match any registered DataCanvas table (expired, wrong session, or canvas disabled)";
+    readonly recovery: "Re-run imf_query_dataset to obtain a fresh canvas_id; ensure CANVAS_PROVIDER_TYPE=duckdb is set.";
+}, {
+    readonly reason: "invalid_sql";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidParams;
+    readonly when: "sql does not start with SELECT — DML and DDL statements are not permitted";
+    readonly recovery: "Rewrite the statement as a SELECT query referencing tables from imf_dataframe_describe.";
+}], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+    dataflow_id: import("zod").ZodString;
+    agency_id: import("zod").ZodOptional<import("zod").ZodString>;
+    version: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    dataflow_id: import("zod").ZodString;
+    agency_id: import("zod").ZodString;
+    version: import("zod").ZodString;
+    name: import("zod").ZodString;
+    description: import("zod").ZodOptional<import("zod").ZodString>;
+    key_format: import("zod").ZodString;
+    dimensions: import("zod").ZodArray<import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        name: import("zod").ZodString;
+        position: import("zod").ZodNumber;
+        codelist: import("zod").ZodArray<import("zod").ZodObject<{
+            id: import("zod").ZodString;
+            name: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>>;
+        codelist_truncated: import("zod").ZodBoolean;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "dataflow_not_found";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly when: "dataflow_id does not match any known dataflow on api.imf.org";
+    readonly recovery: "Call imf_list_databases to browse available dataflow IDs.";
+}, {
+    readonly reason: "structure_unavailable";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "api.imf.org returns non-200 on the DSD endpoint";
+    readonly recovery: "Retry after a short wait; the IMF SDMX 3.0 portal is occasionally slow.";
+}], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+    filter: import("zod").ZodOptional<import("zod").ZodString>;
+    include_vintages: import("zod").ZodDefault<import("zod").ZodBoolean>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    dataflows: import("zod").ZodArray<import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        agency_id: import("zod").ZodString;
+        version: import("zod").ZodString;
+        name: import("zod").ZodString;
+        description: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>>;
+    total_count: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>, undefined, undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+    dataflow_id: import("zod").ZodString;
+    agency_id: import("zod").ZodOptional<import("zod").ZodString>;
+    version: import("zod").ZodOptional<import("zod").ZodString>;
+    key: import("zod").ZodString;
+    start_period: import("zod").ZodOptional<import("zod").ZodString>;
+    end_period: import("zod").ZodOptional<import("zod").ZodString>;
+    canvas_id: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    dataflow_id: import("zod").ZodString;
+    key: import("zod").ZodString;
+    start_period: import("zod").ZodOptional<import("zod").ZodString>;
+    end_period: import("zod").ZodOptional<import("zod").ZodString>;
+    observations: import("zod").ZodArray<import("zod").ZodObject<{
+        series_key: import("zod").ZodString;
+        time_period: import("zod").ZodString;
+        value: import("zod").ZodNullable<import("zod").ZodNumber>;
+        status: import("zod").ZodNullable<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>>;
+    series_attributes: import("zod").ZodObject<{
+        unit: import("zod").ZodNullable<import("zod").ZodString>;
+        scale: import("zod").ZodNullable<import("zod").ZodString>;
+        decimals: import("zod").ZodNullable<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strip>;
+    observation_count: import("zod").ZodNumber;
+    truncated: import("zod").ZodBoolean;
+    canvas_id: import("zod").ZodOptional<import("zod").ZodString>;
+    table_name: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "dataflow_not_found";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly when: "dataflow_id does not match any known dataflow on api.imf.org";
+    readonly recovery: "Call imf_list_databases to browse available dataflow IDs.";
+}, {
+    readonly reason: "no_data";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly when: "Key is structurally valid but returns an empty dataset — typically an unknown dimension code or no data for the time range";
+    readonly recovery: "Verify dimension codes with imf_get_database; check that start_period/end_period overlap available data.";
+}, {
+    readonly reason: "key_dimension_mismatch";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidParams;
+    readonly when: "Number of dot-separated segments in key does not match the dataflow's DSD dimension count";
+    readonly recovery: "Call imf_get_database to get the correct key_format for this dataflow, then reconstruct the key.";
+}, {
+    readonly reason: "structure_unavailable";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "api.imf.org returns non-200 on the data endpoint";
+    readonly recovery: "Retry after a short wait.";
+}], undefined>)[];
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp-server/tools/definitions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAQ9D,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAM9B,CAAC"}

package/dist/mcp-server/tools/definitions/index.js

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Barrel export for all IMF MCP tool definitions.
+ * @module mcp-server/tools/definitions/index
+ */
+export { imfDataframeDescribe } from './imf-dataframe-describe.tool.js';
+export { imfDataframeQuery } from './imf-dataframe-query.tool.js';
+export { imfGetDatabase } from './imf-get-database.tool.js';
+export { imfListDatabases } from './imf-list-databases.tool.js';
+export { imfQueryDataset } from './imf-query-dataset.tool.js';
+import { imfDataframeDescribe } from './imf-dataframe-describe.tool.js';
+import { imfDataframeQuery } from './imf-dataframe-query.tool.js';
+import { imfGetDatabase } from './imf-get-database.tool.js';
+import { imfListDatabases } from './imf-list-databases.tool.js';
+import { imfQueryDataset } from './imf-query-dataset.tool.js';
+export const allToolDefinitions = [
+    imfListDatabases,
+    imfGetDatabase,
+    imfQueryDataset,
+    imfDataframeDescribe,
+    imfDataframeQuery,
+];
+//# sourceMappingURL=index.js.map

package/dist/mcp-server/tools/definitions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,gBAAgB;IAChB,cAAc;IACd,eAAe;IACf,oBAAoB;IACpB,iBAAiB;CAClB,CAAC"}

package/dist/services/canvas/canvas-accessor.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Module-level accessor for the DataCanvas instance.
+ * Wired in setup() from the createApp() entry point.
+ * @module services/canvas/canvas-accessor
+ */
+import type { DataCanvas } from '@cyanheads/mcp-ts-core/canvas';
+/** Store the DataCanvas instance from CoreServices. Call once in setup(). */
+export declare const setCanvas: (c: DataCanvas | undefined) => void;
+/** Returns the DataCanvas instance, or undefined when canvas is disabled. */
+export declare const getCanvas: () => DataCanvas | undefined;
+//# sourceMappingURL=canvas-accessor.d.ts.map

package/dist/services/canvas/canvas-accessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-accessor.d.ts","sourceRoot":"","sources":["../../../src/services/canvas/canvas-accessor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAIhE,6EAA6E;AAC7E,eAAO,MAAM,SAAS,GAAI,GAAG,UAAU,GAAG,SAAS,KAAG,IAErD,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,SAAS,QAAO,UAAU,GAAG,SAAoB,CAAC"}

package/dist/services/canvas/canvas-accessor.js

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Module-level accessor for the DataCanvas instance.
+ * Wired in setup() from the createApp() entry point.
+ * @module services/canvas/canvas-accessor
+ */
+let _canvas;
+/** Store the DataCanvas instance from CoreServices. Call once in setup(). */
+export const setCanvas = (c) => {
+    _canvas = c;
+};
+/** Returns the DataCanvas instance, or undefined when canvas is disabled. */
+export const getCanvas = () => _canvas;
+//# sourceMappingURL=canvas-accessor.js.map

package/dist/services/canvas/canvas-accessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-accessor.js","sourceRoot":"","sources":["../../../src/services/canvas/canvas-accessor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,IAAI,OAA+B,CAAC;AAEpC,6EAA6E;AAC7E,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAyB,EAAQ,EAAE;IAC3D,OAAO,GAAG,CAAC,CAAC;AACd,CAAC,CAAC;AAEF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,SAAS,GAAG,GAA2B,EAAE,CAAC,OAAO,CAAC"}

package/dist/services/imf-sdmx/imf-sdmx-service.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview IMF SDMX 3.0 REST API service — fetches dataflows, data structures,
+ * and observations from api.imf.org. Implements caching via ctx.state and retry.
+ * @module services/imf-sdmx/imf-sdmx-service
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
+import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
+import type { Dataflow, DataflowStructure, DataQueryResult } from './types.js';
+export declare class ImfSdmxService {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(_config: AppConfig, _storage: StorageService, baseUrl: string, timeoutMs: number);
+    /** Fetch all dataflows, with 1-hour caching. */
+    fetchDataflows(ctx: Context): Promise<Dataflow[]>;
+    /** Find a dataflow by id, optionally constraining by agencyId/version. */
+    findDataflow(dataflowId: string, agencyId: string | undefined, version: string | undefined, ctx: Context): Promise<Dataflow | undefined>;
+    /** Fetch DSD with all codelists for a dataflow, with 24-hour caching. */
+    fetchDataStructure(agencyId: string, dsdId: string, version: string, ctx: Context): Promise<DataflowStructure | undefined>;
+    /**
+     * Fetch a dataflow's structure, resolving the DSD reference from the dataflow
+     * list if not provided.
+     */
+    fetchDataflowStructure(dataflowId: string, agencyId: string | undefined, version: string | undefined, ctx: Context): Promise<DataflowStructure>;
+    /** Fallback: fetch structure using the dataflow endpoint path directly. */
+    private fetchDataflowStructureFallback;
+    /** Fetch observations for a dataflow key over a time range. No cache — always live. */
+    fetchData(agencyId: string, dataflowId: string, version: string, key: string, startPeriod?: string, endPeriod?: string, ctx?: Context, signal?: AbortSignal): Promise<DataQueryResult>;
+    private normalizeDataflows;
+    private normalizeDsd;
+    private decodeObservations;
+    private resolveAttrValue;
+    private resolveDecimalsValue;
+    private parseJson;
+}
+export declare function initImfSdmxService(config: AppConfig, storage: StorageService, baseUrl: string, timeoutMs: number): void;
+export declare function getImfSdmxService(): ImfSdmxService;
+//# sourceMappingURL=imf-sdmx-service.d.ts.map

package/dist/services/imf-sdmx/imf-sdmx-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imf-sdmx-service.d.ts","sourceRoot":"","sources":["../../../src/services/imf-sdmx/imf-sdmx-service.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAGrE,OAAO,KAAK,EAEV,QAAQ,EACR,iBAAiB,EACjB,eAAe,EAMhB,MAAM,YAAY,CAAC;AAKpB,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IAS5F,gDAAgD;IAC1C,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAuCvD,0EAA0E;IACpE,YAAY,CAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAchC,yEAAyE;IACnE,kBAAkB,CACtB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAwCzC;;;OAGG;IACG,sBAAsB,CAC1B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,iBAAiB,CAAC;IAiD7B,2EAA2E;YAC7D,8BAA8B;IA8C5C,uFAAuF;IACjF,SAAS,CACb,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,MAAM,EACpB,SAAS,CAAC,EAAE,MAAM,EAClB,GAAG,CAAC,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;IAyC3B,OAAO,CAAC,kBAAkB;IAW1B,OAAO,CAAC,YAAY;IA6GpB,OAAO,CAAC,kBAAkB;IAyF1B,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,oBAAoB;IAQ5B,OAAO,CAAC,SAAS;CAUlB;AAQD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,IAAI,CAEN;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAKlD"}