@cyanheads/exchange-rates-mcp-server 0.1.1

package/dist/mcp-server/tools/definitions/fx-dataframe-describe.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx-dataframe-describe.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fx-dataframe-describe.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAsB,MAAM,+BAA+B,CAAC;AAGrF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;cAkH9B,CAAC"}

package/dist/mcp-server/tools/definitions/fx-dataframe-describe.tool.js

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview fx_dataframe_describe — list tables and columns on a DataCanvas.
+ * @module mcp-server/tools/definitions/fx-dataframe-describe.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { getCanvas } from '../../../services/canvas/canvas-accessor.js';
+export const fxDataframeDescribe = tool('fx_dataframe_describe', {
+    description: 'List tables and columns staged on a DataCanvas from a prior fx_get_timeseries call. ' +
+        'Required first step before fx_dataframe_query — use it to discover table names and column schemas.',
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    input: z.object({
+        canvas_id: z
+            .string()
+            .describe('Canvas ID returned by fx_get_timeseries. ' +
+            'Re-run fx_get_timeseries to obtain a fresh canvas_id if this one has expired.'),
+    }),
+    output: z.object({
+        canvas_id: z.string().describe('The canvas ID echoed back — use this in fx_dataframe_query.'),
+        tables: z
+            .array(z
+            .object({
+            name: z.string().describe('Table or view name.'),
+            kind: z.string().describe('Either "table" or "view".'),
+            row_count: z.number().describe('Number of rows in this table or view.'),
+            columns: z
+                .array(z
+                .object({
+                name: z.string().describe('Column name.'),
+                type: z.string().describe('DuckDB column type (e.g. VARCHAR, DOUBLE, BIGINT).'),
+                nullable: z.boolean().describe('Whether the column accepts NULL values.'),
+            })
+                .describe('A single column descriptor.'))
+                .describe('Column schema for this table.'),
+        })
+            .describe('A single table or view staged on the canvas.'))
+            .describe('All tables and views currently staged on this canvas.'),
+        expires_at: z.string().describe('ISO 8601 timestamp when this canvas will be evicted.'),
+    }),
+    errors: [
+        {
+            reason: 'canvas_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'canvas_id does not exist or has been evicted.',
+            recovery: 'Re-run fx_get_timeseries to obtain a fresh canvas_id.',
+        },
+    ],
+    async handler(input, ctx) {
+        const canvas = getCanvas();
+        if (!canvas) {
+            throw serviceUnavailable('DataCanvas is not enabled. Set CANVAS_PROVIDER_TYPE=duckdb.');
+        }
+        let instance;
+        try {
+            instance = await canvas.acquire(input.canvas_id, ctx);
+        }
+        catch (err) {
+            const msg = err.message ?? '';
+            if (msg.includes('not found') || msg.includes('NotFound')) {
+                throw ctx.fail('canvas_not_found', `Canvas "${input.canvas_id}" not found or has expired.`, {
+                    ...ctx.recoveryFor('canvas_not_found'),
+                });
+            }
+            throw err;
+        }
+        const tableInfos = await instance.describe();
+        ctx.log.info('Described canvas', {
+            canvasId: input.canvas_id,
+            tableCount: tableInfos.length,
+        });
+        const tables = tableInfos.map((t) => ({
+            name: t.name,
+            kind: t.kind,
+            row_count: t.rowCount,
+            columns: t.columns.map((c) => ({
+                name: c.name,
+                type: c.type,
+                nullable: c.nullable ?? false,
+            })),
+        }));
+        return {
+            canvas_id: input.canvas_id,
+            tables,
+            expires_at: instance.expiresAt,
+        };
+    },
+    format: (result) => {
+        if (result.tables.length === 0) {
+            return [{ type: 'text', text: `Canvas \`${result.canvas_id}\` has no staged tables.` }];
+        }
+        const lines = [`**Canvas \`${result.canvas_id}\`** — expires ${result.expires_at}\n`];
+        for (const t of result.tables) {
+            lines.push(`### ${t.name} (${t.kind}, ${t.row_count} rows)`);
+            for (const col of t.columns) {
+                lines.push(`- \`${col.name}\` ${col.type}${col.nullable ? ' (nullable)' : ''}`);
+            }
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=fx-dataframe-describe.tool.js.map

package/dist/mcp-server/tools/definitions/fx-dataframe-describe.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx-dataframe-describe.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fx-dataframe-describe.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/fx-dataframe-query.tool.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview fx_dataframe_query — run SQL against DataCanvas tables from fx_get_timeseries.
+ * @module mcp-server/tools/definitions/fx-dataframe-query.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const fxDataframeQuery: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    canvas_id: z.ZodString;
+    query: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    row_count: z.ZodNumber;
+    canvas_id: z.ZodString;
+}, z.core.$strip>, readonly [{
+    readonly reason: "canvas_not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "canvas_id does not exist or has been evicted.";
+    readonly recovery: "Re-run fx_get_timeseries to obtain a fresh canvas_id.";
+}, {
+    readonly reason: "invalid_query";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "SQL is not a SELECT, references unknown tables/columns, or has a syntax error.";
+    readonly recovery: "Run fx_dataframe_describe first to verify table and column names.";
+}], undefined>;
+//# sourceMappingURL=fx-dataframe-query.tool.d.ts.map

package/dist/mcp-server/tools/definitions/fx-dataframe-query.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx-dataframe-query.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fx-dataframe-query.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAsB,MAAM,+BAA+B,CAAC;AAGrF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;cA2I3B,CAAC"}

package/dist/mcp-server/tools/definitions/fx-dataframe-query.tool.js

@@ -0,0 +1,125 @@
+/**
+ * @fileoverview fx_dataframe_query — run SQL against DataCanvas tables from fx_get_timeseries.
+ * @module mcp-server/tools/definitions/fx-dataframe-query.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { getCanvas } from '../../../services/canvas/canvas-accessor.js';
+export const fxDataframeQuery = tool('fx_dataframe_query', {
+    description: 'Run a read-only SQL SELECT against DataCanvas tables staged by fx_get_timeseries. ' +
+        'Supports aggregations, GROUP BY, window functions, and JOINs across multiple registered tables. ' +
+        'Run fx_dataframe_describe first to discover table names and column schemas.',
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    input: z.object({
+        canvas_id: z
+            .string()
+            .describe('Canvas ID returned by fx_get_timeseries. ' +
+            'Re-run fx_get_timeseries to obtain a fresh canvas_id if this one has expired.'),
+        query: z
+            .string()
+            .describe('Read-only SQL SELECT statement. Reference tables by the names returned by fx_dataframe_describe ' +
+            'or the table_name field from fx_get_timeseries. ' +
+            "Example: SELECT date, rate FROM fx_usd_eur WHERE date > '2024-01-01' ORDER BY date"),
+    }),
+    output: z.object({
+        rows: z
+            .array(z
+            .record(z.string(), z.unknown())
+            .describe('One result row — column-name → value pairs matching the SELECT columns.'))
+            .describe('Result rows, capped at the canvas row limit (default 10 000). Each key is a column name from the query.'),
+        row_count: z
+            .number()
+            .describe('Total rows in the full result set before the row cap was applied.'),
+        canvas_id: z
+            .string()
+            .describe('The canvas ID used — pass to a subsequent fx_dataframe_query or fx_dataframe_describe call.'),
+    }),
+    errors: [
+        {
+            reason: 'canvas_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'canvas_id does not exist or has been evicted.',
+            recovery: 'Re-run fx_get_timeseries to obtain a fresh canvas_id.',
+        },
+        {
+            reason: 'invalid_query',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'SQL is not a SELECT, references unknown tables/columns, or has a syntax error.',
+            recovery: 'Run fx_dataframe_describe first to verify table and column names.',
+        },
+    ],
+    async handler(input, ctx) {
+        const canvas = getCanvas();
+        if (!canvas) {
+            throw serviceUnavailable('DataCanvas is not enabled. Set CANVAS_PROVIDER_TYPE=duckdb.');
+        }
+        let instance;
+        try {
+            instance = await canvas.acquire(input.canvas_id, ctx);
+        }
+        catch (err) {
+            const msg = err.message ?? '';
+            if (msg.includes('not found') || msg.includes('NotFound')) {
+                throw ctx.fail('canvas_not_found', `Canvas "${input.canvas_id}" not found or has expired.`, {
+                    ...ctx.recoveryFor('canvas_not_found'),
+                });
+            }
+            throw err;
+        }
+        let result;
+        try {
+            result = await instance.query(input.query, { signal: ctx.signal });
+        }
+        catch (err) {
+            const msg = err.message ?? '';
+            // ValidationError from the four-layer gate, or DuckDB parse errors
+            if (msg.includes('ValidationError') ||
+                msg.includes('SELECT') ||
+                msg.includes('syntax') ||
+                msg.includes('not found') ||
+                msg.includes('does not exist') ||
+                msg.includes('read_csv') ||
+                msg.includes('register_as_clash') ||
+                err.code === 'ValidationError') {
+                throw ctx.fail('invalid_query', `SQL query rejected: ${msg}`, {
+                    ...ctx.recoveryFor('invalid_query'),
+                });
+            }
+            throw err;
+        }
+        ctx.log.info('Executed dataframe query', {
+            canvasId: input.canvas_id,
+            rowCount: result.rowCount,
+        });
+        return {
+            rows: result.rows,
+            row_count: result.rowCount,
+            canvas_id: input.canvas_id,
+        };
+    },
+    format: (result) => {
+        if (result.rows.length === 0) {
+            return [{ type: 'text', text: `Query returned 0 rows (canvas \`${result.canvas_id}\`).` }];
+        }
+        const cols = Object.keys(result.rows[0] ?? {});
+        const header = `| ${cols.join(' | ')} |`;
+        const sep = `| ${cols.map(() => '---').join(' | ')} |`;
+        const rowLines = result.rows
+            .slice(0, 50)
+            .map((r) => `| ${cols.map((c) => String(r[c] ?? '')).join(' | ')} |`);
+        const note = result.row_count > 50
+            ? `\n*Showing 50 of ${result.row_count} rows*`
+            : `\n*${result.row_count} rows*`;
+        return [
+            {
+                type: 'text',
+                text: [header, sep, ...rowLines].join('\n') + note + ` · canvas \`${result.canvas_id}\``,
+            },
+        ];
+    },
+});
+//# sourceMappingURL=fx-dataframe-query.tool.js.map

package/dist/mcp-server/tools/definitions/fx-dataframe-query.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx-dataframe-query.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fx-dataframe-query.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/fx-get-rate.tool.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview fx_get_rate — get the exchange rate for a single currency pair.
+ * @module mcp-server/tools/definitions/fx-get-rate.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const fxGetRate: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    base_currency: z.ZodString;
+    quote_currency: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    base_currency: z.ZodString;
+    quote_currency: z.ZodString;
+    rate: z.ZodNumber;
+    rate_date: z.ZodString;
+    date_snapped: z.ZodBoolean;
+    rate_type: z.ZodString;
+    source: z.ZodString;
+}, z.core.$strip>, readonly [{
+    readonly reason: "unsupported_currency";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "base_currency or quote_currency is not in the ECB currency set.";
+    readonly recovery: "Call fx_list_currencies to get the list of valid currency codes.";
+}, {
+    readonly reason: "date_out_of_range";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "date is before 1999-01-04 or in the future.";
+    readonly recovery: "ECB data starts 1999-01-04; omit date for the latest available rate.";
+}], undefined>;
+//# sourceMappingURL=fx-get-rate.tool.d.ts.map

package/dist/mcp-server/tools/definitions/fx-get-rate.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx-get-rate.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fx-get-rate.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAOjE,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;cA0IpB,CAAC"}

package/dist/mcp-server/tools/definitions/fx-get-rate.tool.js

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview fx_get_rate — get the exchange rate for a single currency pair.
+ * @module mcp-server/tools/definitions/fx-get-rate.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { ECB_START_DATE, getFrankfurterService, } from '../../../services/frankfurter/frankfurter-service.js';
+export const fxGetRate = tool('fx_get_rate', {
+    description: 'Get the exchange rate for a currency pair on a given date (default: latest). ' +
+        'Returns the rate, the actual rate date (which may differ from the requested date on ' +
+        'weekends/holidays — ECB publishes business days only), and source provenance. ' +
+        'Cross-rates are triangulated through EUR automatically. ' +
+        'Use fx_convert_currency when you want the converted amount; use this tool when you only need the rate number.',
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    input: z.object({
+        base_currency: z
+            .string()
+            .describe('ISO 4217 base currency code (e.g. USD). Call fx_list_currencies to get valid codes.'),
+        quote_currency: z
+            .string()
+            .describe('ISO 4217 quote currency code (e.g. EUR). The rate is expressed as "how many quote units per 1 base unit".'),
+        date: z
+            .string()
+            .optional()
+            .describe('ISO 8601 date (YYYY-MM-DD). Omit for the latest available rate. ' +
+            'ECB data starts 1999-01-04. Future dates are not supported.'),
+    }),
+    output: z.object({
+        base_currency: z.string().describe('The base currency code.'),
+        quote_currency: z.string().describe('The quote currency code.'),
+        rate: z
+            .number()
+            .describe('Exchange rate: units of quote currency per 1 unit of base currency.'),
+        rate_date: z.string().describe('Actual date of the rate returned.'),
+        date_snapped: z
+            .boolean()
+            .describe('True when the API returned a different date than requested — ' +
+            'ECB silently snaps weekend/holiday requests to the prior business day.'),
+        rate_type: z
+            .string()
+            .describe('Always "ECB reference (mid-market)" — these are reference rates, not tradeable bid/ask.'),
+        source: z.string().describe('Always "ECB via Frankfurter" — the upstream data provider.'),
+    }),
+    errors: [
+        {
+            reason: 'unsupported_currency',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'base_currency or quote_currency is not in the ECB currency set.',
+            recovery: 'Call fx_list_currencies to get the list of valid currency codes.',
+        },
+        {
+            reason: 'date_out_of_range',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'date is before 1999-01-04 or in the future.',
+            recovery: 'ECB data starts 1999-01-04; omit date for the latest available rate.',
+        },
+    ],
+    async handler(input, ctx) {
+        const service = getFrankfurterService();
+        const date = input.date ?? 'latest';
+        if (date !== 'latest') {
+            if (date < ECB_START_DATE) {
+                throw ctx.fail('date_out_of_range', `Date ${date} is before ECB data start ${ECB_START_DATE}.`, {
+                    ...ctx.recoveryFor('date_out_of_range'),
+                });
+            }
+            const today = new Date().toISOString().slice(0, 10);
+            if (date > today) {
+                throw ctx.fail('date_out_of_range', `Date ${date} is in the future.`, {
+                    ...ctx.recoveryFor('date_out_of_range'),
+                });
+            }
+        }
+        let resolved;
+        try {
+            resolved = await service.getRate(input.base_currency, input.quote_currency, date);
+        }
+        catch (err) {
+            const msg = err.message ?? '';
+            if (msg.includes('not found')) {
+                throw ctx.fail('unsupported_currency', `Currency pair "${input.base_currency}/${input.quote_currency}" not available from ECB.`, { ...ctx.recoveryFor('unsupported_currency') });
+            }
+            throw err;
+        }
+        ctx.log.info('Fetched rate', {
+            base: resolved.baseCurrency,
+            quote: resolved.quoteCurrency,
+            rate: resolved.rate,
+            date: resolved.rateDate,
+            snapped: resolved.dateSnapped,
+        });
+        return {
+            base_currency: resolved.baseCurrency,
+            quote_currency: resolved.quoteCurrency,
+            rate: resolved.rate,
+            rate_date: resolved.rateDate,
+            date_snapped: resolved.dateSnapped,
+            rate_type: resolved.rateType,
+            source: resolved.source,
+        };
+    },
+    format: (result) => {
+        const snapNote = result.date_snapped
+            ? `\n⚠️ *Requested date snapped to ${result.rate_date} (weekend/holiday — ECB publishes business days only)*`
+            : '';
+        return [
+            {
+                type: 'text',
+                text: `**${result.base_currency}/${result.quote_currency}** — ${result.rate_date}\n` +
+                    `Rate: **${result.rate}** (${result.quote_currency} per ${result.base_currency})` +
+                    snapNote +
+                    `\n*${result.rate_type} · ${result.source}*`,
+            },
+        ];
+    },
+});
+//# sourceMappingURL=fx-get-rate.tool.js.map

package/dist/mcp-server/tools/definitions/fx-get-rate.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx-get-rate.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fx-get-rate.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/fx-get-rates.tool.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview fx_get_rates — bulk snapshot of all rates for one base currency.
+ * @module mcp-server/tools/definitions/fx-get-rates.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const fxGetRates: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    base_currency: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+    symbols: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    base_currency: z.ZodString;
+    rate_date: z.ZodString;
+    rates: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    rate_type: z.ZodString;
+    source: z.ZodString;
+}, z.core.$strip>, readonly [{
+    readonly reason: "unsupported_currency";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "base_currency is not in the ECB currency set.";
+    readonly recovery: "Call fx_list_currencies to get the list of valid currency codes.";
+}, {
+    readonly reason: "date_out_of_range";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "date is before 1999-01-04 or in the future.";
+    readonly recovery: "ECB data starts 1999-01-04; omit date for the latest available rate.";
+}], undefined>;
+//# sourceMappingURL=fx-get-rates.tool.d.ts.map

package/dist/mcp-server/tools/definitions/fx-get-rates.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx-get-rates.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fx-get-rates.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAOjE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;cAoIrB,CAAC"}

package/dist/mcp-server/tools/definitions/fx-get-rates.tool.js

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview fx_get_rates — bulk snapshot of all rates for one base currency.
+ * @module mcp-server/tools/definitions/fx-get-rates.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { ECB_START_DATE, getFrankfurterService, } from '../../../services/frankfurter/frankfurter-service.js';
+export const fxGetRates = tool('fx_get_rates', {
+    description: 'Get all available exchange rates for one base currency in a single snapshot. ' +
+        'Useful for bulk comparison and seeding downstream tools. ' +
+        'Returns a map of quote currency → rate plus the snapshot date. ' +
+        'Optionally filter to a subset of quote currencies via symbols.',
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    input: z.object({
+        base_currency: z
+            .string()
+            .describe('ISO 4217 base currency code (e.g. USD). Call fx_list_currencies to get valid codes.'),
+        date: z
+            .string()
+            .optional()
+            .describe('ISO 8601 date (YYYY-MM-DD). Omit for the latest available rate. ' +
+            'ECB data starts 1999-01-04. Future dates are not supported.'),
+        symbols: z
+            .array(z.string().describe('ISO 4217 currency code to include in the response.'))
+            .optional()
+            .describe('Optional list of quote currency codes to filter the response. ' +
+            'Omit to return all ~30 supported currencies.'),
+    }),
+    output: z.object({
+        base_currency: z.string().describe('The base currency code.'),
+        rate_date: z
+            .string()
+            .describe('Actual date of the rates. May differ from requested date on weekends/holidays — ' +
+            'ECB publishes business days only; the API silently snaps to the prior business day.'),
+        rates: z
+            .record(z.string(), z.number())
+            .describe('Map of quote currency code → exchange rate (units of quote per 1 base).'),
+        rate_type: z
+            .string()
+            .describe('Always "ECB reference (mid-market)" — these are reference rates, not tradeable bid/ask.'),
+        source: z.string().describe('Always "ECB via Frankfurter" — the upstream data provider.'),
+    }),
+    errors: [
+        {
+            reason: 'unsupported_currency',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'base_currency is not in the ECB currency set.',
+            recovery: 'Call fx_list_currencies to get the list of valid currency codes.',
+        },
+        {
+            reason: 'date_out_of_range',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'date is before 1999-01-04 or in the future.',
+            recovery: 'ECB data starts 1999-01-04; omit date for the latest available rate.',
+        },
+    ],
+    async handler(input, ctx) {
+        const service = getFrankfurterService();
+        const date = input.date ?? 'latest';
+        if (date !== 'latest') {
+            if (date < ECB_START_DATE) {
+                throw ctx.fail('date_out_of_range', `Date ${date} is before ECB data start ${ECB_START_DATE}.`, {
+                    ...ctx.recoveryFor('date_out_of_range'),
+                });
+            }
+            const today = new Date().toISOString().slice(0, 10);
+            if (date > today) {
+                throw ctx.fail('date_out_of_range', `Date ${date} is in the future.`, {
+                    ...ctx.recoveryFor('date_out_of_range'),
+                });
+            }
+        }
+        let raw;
+        try {
+            raw = await service.getRates(input.base_currency, date, input.symbols);
+        }
+        catch (err) {
+            const msg = err.message ?? '';
+            if (msg.includes('not found')) {
+                throw ctx.fail('unsupported_currency', `Currency "${input.base_currency}" is not supported by the ECB.`, { ...ctx.recoveryFor('unsupported_currency') });
+            }
+            throw err;
+        }
+        ctx.log.info('Fetched rates snapshot', {
+            base: input.base_currency,
+            date: raw.date,
+            count: Object.keys(raw.rates).length,
+        });
+        return {
+            base_currency: raw.base,
+            rate_date: raw.date,
+            rates: raw.rates,
+            rate_type: 'ECB reference (mid-market)',
+            source: 'ECB via Frankfurter',
+        };
+    },
+    format: (result) => {
+        const rateLines = Object.entries(result.rates)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([code, rate]) => `**${code}**: ${rate}`);
+        return [
+            {
+                type: 'text',
+                text: `**${result.base_currency} exchange rates** — ${result.rate_date}\n` +
+                    `*${result.rate_type} · ${result.source}*\n\n` +
+                    rateLines.join('\n'),
+            },
+        ];
+    },
+});
+//# sourceMappingURL=fx-get-rates.tool.js.map

package/dist/mcp-server/tools/definitions/fx-get-rates.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx-get-rates.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fx-get-rates.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/fx-get-timeseries.tool.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview fx_get_timeseries — historical daily rates for a currency pair over a date range.
+ * @module mcp-server/tools/definitions/fx-get-timeseries.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const fxGetTimeseries: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    base_currency: z.ZodString;
+    quote_currency: z.ZodString;
+    start_date: z.ZodString;
+    end_date: z.ZodString;
+    canvas_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    base_currency: z.ZodString;
+    quote_currency: z.ZodString;
+    start_date: z.ZodString;
+    end_date: z.ZodString;
+    rates: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    rate_count: z.ZodNumber;
+    rate_type: z.ZodString;
+    source: z.ZodString;
+    spilled: z.ZodBoolean;
+    canvas_id: z.ZodOptional<z.ZodString>;
+    table_name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "unsupported_currency";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "base_currency or quote_currency is not in the ECB currency set.";
+    readonly recovery: "Call fx_list_currencies to get the list of valid currency codes.";
+}, {
+    readonly reason: "date_out_of_range";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "start_date is before 1999-01-04 or end_date is in the future.";
+    readonly recovery: "ECB data starts 1999-01-04; omit end_date or use today's date.";
+}, {
+    readonly reason: "invalid_range";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "start_date is after end_date.";
+    readonly recovery: "Ensure start_date is before or equal to end_date.";
+}], undefined>;
+//# sourceMappingURL=fx-get-timeseries.tool.d.ts.map

package/dist/mcp-server/tools/definitions/fx-get-timeseries.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx-get-timeseries.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fx-get-timeseries.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AASjE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAsR1B,CAAC"}