@cyanheads/exchange-rates-mcp-server 0.1.1

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

@@ -0,0 +1,229 @@
+/**
+ * @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 { tool, z } from '@cyanheads/mcp-ts-core';
+import { spillover } from '@cyanheads/mcp-ts-core/canvas';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getServerConfig } from '../../../config/server-config.js';
+import { getCanvas } from '../../../services/canvas/canvas-accessor.js';
+import { ECB_START_DATE, getFrankfurterService, } from '../../../services/frankfurter/frankfurter-service.js';
+export const fxGetTimeseries = tool('fx_get_timeseries', {
+    description: 'Get historical daily exchange rates for a currency pair over a date range. ' +
+        'ECB publishes on business days only — weekends and holidays produce no entry (not snapped). ' +
+        'Short ranges (≤90 days by default) are returned inline as a date→rate map. ' +
+        'Long ranges spill to DataCanvas: the response carries spilled=true, a canvas_id, and a table_name. ' +
+        'Call fx_dataframe_describe to inspect the staged table, then fx_dataframe_query to run SQL against it.',
+    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). Call fx_list_currencies to get valid codes.'),
+        start_date: z
+            .string()
+            .describe('ISO 8601 start date (YYYY-MM-DD). ECB data starts 1999-01-04. ' +
+            'The actual first data point may be later if start_date falls on a weekend/holiday.'),
+        end_date: z
+            .string()
+            .describe('ISO 8601 end date (YYYY-MM-DD). Must be >= start_date. Future dates are not supported.'),
+        canvas_id: z
+            .string()
+            .optional()
+            .describe('Optional canvas ID from a prior call. Omit on the first call to start a fresh canvas; ' +
+            'pass the returned canvas_id to append tables to an existing canvas.'),
+    }),
+    output: z.object({
+        base_currency: z.string().describe('Base currency code.'),
+        quote_currency: z.string().describe('Quote currency code.'),
+        start_date: z
+            .string()
+            .describe('Actual first date in the returned series (may differ from requested if that date had no ECB fix).'),
+        end_date: z
+            .string()
+            .describe('Actual last date in the returned series (may differ from requested if that date had no ECB fix).'),
+        rates: z
+            .record(z.string(), z.number())
+            .describe('Date → rate map for the inline result. Business days only. ' +
+            'Empty when the result was spilled to canvas.'),
+        rate_count: z.number().describe('Total number of data points (business days) in the range.'),
+        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.'),
+        spilled: z
+            .boolean()
+            .describe('True when the full result was staged on the DataCanvas (range exceeded threshold).'),
+        canvas_id: z
+            .string()
+            .optional()
+            .describe('Canvas ID — present when spilled is true. Pass to fx_dataframe_query.'),
+        table_name: z
+            .string()
+            .optional()
+            .describe('Canvas table name — present when spilled is true. Use in fx_dataframe_query SQL.'),
+    }),
+    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: 'start_date is before 1999-01-04 or end_date is in the future.',
+            recovery: "ECB data starts 1999-01-04; omit end_date or use today's date.",
+        },
+        {
+            reason: 'invalid_range',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'start_date is after end_date.',
+            recovery: 'Ensure start_date is before or equal to end_date.',
+        },
+    ],
+    async handler(input, ctx) {
+        const service = getFrankfurterService();
+        const config = getServerConfig();
+        const today = new Date().toISOString().slice(0, 10);
+        // Validate dates
+        if (input.start_date < ECB_START_DATE) {
+            throw ctx.fail('date_out_of_range', `start_date ${input.start_date} is before ECB data start ${ECB_START_DATE}.`, {
+                ...ctx.recoveryFor('date_out_of_range'),
+            });
+        }
+        if (input.end_date > today) {
+            throw ctx.fail('date_out_of_range', `end_date ${input.end_date} is in the future.`, {
+                ...ctx.recoveryFor('date_out_of_range'),
+            });
+        }
+        if (input.start_date > input.end_date) {
+            throw ctx.fail('invalid_range', `start_date ${input.start_date} is after end_date ${input.end_date}.`, {
+                ...ctx.recoveryFor('invalid_range'),
+            });
+        }
+        // Compute calendar days to decide inline vs spillover
+        const msPerDay = 86_400_000;
+        const dayCount = (new Date(input.end_date).getTime() - new Date(input.start_date).getTime()) / msPerDay + 1;
+        let raw;
+        let rows;
+        try {
+            ({ raw, rows } = await service.getTimeSeries(input.base_currency, input.quote_currency, input.start_date, input.end_date));
+        }
+        catch (err) {
+            const msg = err.message ?? '';
+            if (msg.includes('not found')) {
+                throw ctx.fail('unsupported_currency', `Currency "${input.base_currency}" or "${input.quote_currency}" not available from ECB.`, { ...ctx.recoveryFor('unsupported_currency') });
+            }
+            throw err;
+        }
+        const actualStart = raw.start_date;
+        const actualEnd = raw.end_date;
+        ctx.log.info('Fetched timeseries', {
+            base: input.base_currency,
+            quote: input.quote_currency,
+            start: actualStart,
+            end: actualEnd,
+            points: rows.length,
+            dayCount,
+        });
+        // Inline path — short range
+        const canvas = getCanvas();
+        const shouldSpill = canvas != null && dayCount > config.timeseriesCanvasThresholdDays;
+        if (!shouldSpill) {
+            const rateMap = {};
+            for (const row of rows)
+                rateMap[row.date] = row.rate;
+            return {
+                base_currency: input.base_currency.toUpperCase(),
+                quote_currency: input.quote_currency.toUpperCase(),
+                start_date: actualStart,
+                end_date: actualEnd,
+                rates: rateMap,
+                rate_count: rows.length,
+                rate_type: 'ECB reference (mid-market)',
+                source: 'ECB via Frankfurter',
+                spilled: false,
+            };
+        }
+        // Canvas spillover path
+        const instance = await canvas.acquire(input.canvas_id, ctx);
+        const tableName = `fx_${input.base_currency.toLowerCase()}_${input.quote_currency.toLowerCase()}`;
+        const spillResult = await spillover({
+            canvas: instance,
+            source: rows,
+            tableName,
+            previewChars: 40_000, // ~10k tokens preview
+            signal: ctx.signal,
+        });
+        ctx.log.info('Spilled to canvas', {
+            canvasId: instance.canvasId,
+            tableName,
+            rowCount: rows.length,
+            spilled: spillResult.spilled,
+        });
+        // Build inline rate map from preview rows for the response
+        const previewRates = {};
+        for (const row of spillResult.previewRows) {
+            const r = row;
+            previewRates[r.date] = r.rate;
+        }
+        if (spillResult.spilled) {
+            return {
+                base_currency: input.base_currency.toUpperCase(),
+                quote_currency: input.quote_currency.toUpperCase(),
+                start_date: actualStart,
+                end_date: actualEnd,
+                rates: previewRates,
+                rate_count: spillResult.handle.rowCount,
+                rate_type: 'ECB reference (mid-market)',
+                source: 'ECB via Frankfurter',
+                spilled: true,
+                canvas_id: instance.canvasId,
+                table_name: spillResult.handle.tableName,
+            };
+        }
+        // Fell under budget even at canvas threshold — return inline
+        return {
+            base_currency: input.base_currency.toUpperCase(),
+            quote_currency: input.quote_currency.toUpperCase(),
+            start_date: actualStart,
+            end_date: actualEnd,
+            rates: previewRates,
+            rate_count: spillResult.previewRows.length,
+            rate_type: 'ECB reference (mid-market)',
+            source: 'ECB via Frankfurter',
+            spilled: false,
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `**${result.base_currency}/${result.quote_currency} time series** — ${result.start_date} to ${result.end_date}`,
+            `*${result.rate_count} business-day data points · ${result.rate_type} · ${result.source} · spilled: ${result.spilled}*`,
+        ];
+        if (result.spilled) {
+            lines.push(`\n📊 **Result staged on DataCanvas** (large range)`, `Canvas ID: \`${result.canvas_id}\``, `Table: \`${result.table_name}\``, `Use \`fx_dataframe_query\` with this canvas_id to run SQL. Preview (first entries below):`);
+        }
+        const rateEntries = Object.entries(result.rates)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .slice(0, 20);
+        if (rateEntries.length > 0) {
+            lines.push('');
+            for (const [date, rate] of rateEntries) {
+                lines.push(`${date}: ${rate}`);
+            }
+            if (Object.keys(result.rates).length > 20) {
+                lines.push(`... (${Object.keys(result.rates).length - 20} more entries)`);
+            }
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=fx-get-timeseries.tool.js.map

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

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

package/dist/mcp-server/tools/definitions/fx-list-currencies.tool.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview fx_list_currencies — lists all supported ISO 4217 currency codes.
+ * @module mcp-server/tools/definitions/fx-list-currencies.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const fxListCurrencies: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+    currencies: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+    count: z.ZodNumber;
+    source: z.ZodString;
+}, z.core.$strip>, undefined, undefined>;
+//# sourceMappingURL=fx-list-currencies.tool.d.ts.map

package/dist/mcp-server/tools/definitions/fx-list-currencies.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx-list-currencies.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fx-list-currencies.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAGjD,eAAO,MAAM,gBAAgB;;;;;;;wCA4C3B,CAAC"}

package/dist/mcp-server/tools/definitions/fx-list-currencies.tool.js

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview fx_list_currencies — lists all supported ISO 4217 currency codes.
+ * @module mcp-server/tools/definitions/fx-list-currencies.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { getFrankfurterService } from '../../../services/frankfurter/frankfurter-service.js';
+export const fxListCurrencies = tool('fx_list_currencies', {
+    description: 'List all supported ISO 4217 currency codes with their full names. ' +
+        'Call this before converting to disambiguate "dollars" (USD vs AUD vs CAD vs HKD vs SGD) ' +
+        'or to validate a user-supplied currency code. Covers the ~30 ECB reference currencies.',
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    input: z.object({}),
+    output: z.object({
+        currencies: z
+            .array(z
+            .object({
+            code: z.string().describe('ISO 4217 currency code (e.g. USD, EUR, JPY).'),
+            name: z.string().describe('Full currency name (e.g. "United States Dollar").'),
+        })
+            .describe('A single supported currency.'))
+            .describe('All supported currencies, sorted alphabetically by code.'),
+        count: z.number().describe('Total number of supported currencies.'),
+        source: z.string().describe('Always "ECB via Frankfurter" — the upstream data provider.'),
+    }),
+    async handler(_input, ctx) {
+        const service = getFrankfurterService();
+        const currencies = await service.listCurrencies();
+        ctx.log.info('Listed currencies', { count: currencies.length });
+        return {
+            currencies,
+            count: currencies.length,
+            source: 'ECB via Frankfurter',
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `**${result.count} supported currencies** (${result.source})\n`,
+            ...result.currencies.map((c) => `**${c.code}** — ${c.name}`),
+        ];
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=fx-list-currencies.tool.js.map

package/dist/mcp-server/tools/definitions/fx-list-currencies.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx-list-currencies.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fx-list-currencies.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,+CAA+C,CAAC;AAEtF,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC,oBAAoB,EAAE;IACzD,WAAW,EACT,oEAAoE;QACpE,0FAA0F;QAC1F,wFAAwF;IAC1F,WAAW,EAAE;QACX,YAAY,EAAE,IAAI;QAClB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,IAAI;KACpB;IACD,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;IACnB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,UAAU,EAAE,CAAC;aACV,KAAK,CACJ,CAAC;aACE,MAAM,CAAC;YACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;YACzE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;SAC/E,CAAC;aACD,QAAQ,CAAC,8BAA8B,CAAC,CAC5C;aACA,QAAQ,CAAC,0DAA0D,CAAC;QACvE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;QACnE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4DAA4D,CAAC;KAC1F,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG;QACvB,MAAM,OAAO,GAAG,qBAAqB,EAAE,CAAC;QACxC,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,cAAc,EAAE,CAAC;QAClD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,KAAK,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;QAChE,OAAO;YACL,UAAU;YACV,KAAK,EAAE,UAAU,CAAC,MAAM;YACxB,MAAM,EAAE,qBAAqB;SAC9B,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;QACjB,MAAM,KAAK,GAAG;YACZ,KAAK,MAAM,CAAC,KAAK,4BAA4B,MAAM,CAAC,MAAM,KAAK;YAC/D,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;SAC7D,CAAC;QACF,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;CACF,CAAC,CAAC"}

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

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Barrel export for all tool definitions.
+ * @module mcp-server/tools/definitions/index
+ */
+export { fxConvertCurrency } from './fx-convert-currency.tool.js';
+export { fxDataframeDescribe } from './fx-dataframe-describe.tool.js';
+export { fxDataframeQuery } from './fx-dataframe-query.tool.js';
+export { fxGetRate } from './fx-get-rate.tool.js';
+export { fxGetRates } from './fx-get-rates.tool.js';
+export { fxGetTimeseries } from './fx-get-timeseries.tool.js';
+export { fxListCurrencies } from './fx-list-currencies.tool.js';
+//# 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,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC"}

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

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Barrel export for all tool definitions.
+ * @module mcp-server/tools/definitions/index
+ */
+export { fxConvertCurrency } from './fx-convert-currency.tool.js';
+export { fxDataframeDescribe } from './fx-dataframe-describe.tool.js';
+export { fxDataframeQuery } from './fx-dataframe-query.tool.js';
+export { fxGetRate } from './fx-get-rate.tool.js';
+export { fxGetRates } from './fx-get-rates.tool.js';
+export { fxGetTimeseries } from './fx-get-timeseries.tool.js';
+export { fxListCurrencies } from './fx-list-currencies.tool.js';
+//# 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,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC"}

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

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview DataCanvas accessor — module-level singleton for the canvas service.
+ * @module services/canvas/canvas-accessor
+ */
+import type { DataCanvas } from '@cyanheads/mcp-ts-core/canvas';
+/** Set the canvas instance (called from createApp setup callback). */
+export declare const setCanvas: (c: DataCanvas | undefined) => void;
+/** Get the canvas instance, or undefined if canvas is not enabled. */
+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;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAIhE,sEAAsE;AACtE,eAAO,MAAM,SAAS,GAAI,GAAG,UAAU,GAAG,SAAS,KAAG,IAErD,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,SAAS,QAAO,UAAU,GAAG,SAAoB,CAAC"}

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

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview DataCanvas accessor — module-level singleton for the canvas service.
+ * @module services/canvas/canvas-accessor
+ */
+let _canvas;
+/** Set the canvas instance (called from createApp setup callback). */
+export const setCanvas = (c) => {
+    _canvas = c;
+};
+/** Get the canvas instance, or undefined if canvas is not enabled. */
+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;;;GAGG;AAIH,IAAI,OAA+B,CAAC;AAEpC,sEAAsE;AACtE,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAyB,EAAQ,EAAE;IAC3D,OAAO,GAAG,CAAC,CAAC;AACd,CAAC,CAAC;AAEF,sEAAsE;AACtE,MAAM,CAAC,MAAM,SAAS,GAAG,GAA2B,EAAE,CAAC,OAAO,CAAC"}

package/dist/services/frankfurter/frankfurter-service.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Frankfurter API service — wraps ECB rate data from api.frankfurter.dev.
+ * @module services/frankfurter/frankfurter-service
+ */
+import type { Currency, FrankfurterRateResponse, FrankfurterSeriesResponse, ResolvedRate, SeriesRow } from './types.js';
+/** ECB data start date. Requests before this return 404 from Frankfurter. */
+declare const ECB_START_DATE = "1999-01-04";
+/** Retrieve the singleton FrankfurterService (lazy-init). */
+export declare function getFrankfurterService(): FrankfurterService;
+/** @internal — exposed for testing only */
+export declare function resetFrankfurterService(): void;
+declare class FrankfurterService {
+    private readonly baseUrl;
+    constructor();
+    /** Fetch all supported currencies as a sorted array. */
+    listCurrencies(): Promise<Currency[]>;
+    /**
+     * Get the exchange rate for a currency pair on a given date.
+     * Handles cross-rate triangulation through EUR automatically.
+     *
+     * Frankfurter's base must be EUR for ECB data — but it also supports
+     * arbitrary base via its own math. We just set base={upper_base} and
+     * symbols={upper_quote} and let Frankfurter handle the triangulation.
+     *
+     * @param base - ISO 4217 base currency code
+     * @param quote - ISO 4217 quote currency code
+     * @param date - ISO 8601 date string, or 'latest'
+     */
+    getRate(base: string, quote: string, date: string): Promise<ResolvedRate>;
+    /**
+     * Fetch all rates for a base currency at latest or historical date.
+     * Optionally filter to a specific set of symbols.
+     */
+    getRates(base: string, date: string, symbols?: string[]): Promise<FrankfurterRateResponse>;
+    /**
+     * Fetch a historical rate series for a currency pair.
+     * Returns raw API response plus derived rows suitable for canvas registration.
+     */
+    getTimeSeries(base: string, quote: string, startDate: string, endDate: string): Promise<{
+        raw: FrankfurterSeriesResponse;
+        rows: SeriesRow[];
+    }>;
+    private fetchJson;
+}
+export { ECB_START_DATE };
+//# sourceMappingURL=frankfurter-service.d.ts.map

package/dist/services/frankfurter/frankfurter-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frankfurter-service.d.ts","sourceRoot":"","sources":["../../../src/services/frankfurter/frankfurter-service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EACV,QAAQ,EAER,uBAAuB,EACvB,yBAAyB,EACzB,YAAY,EACZ,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB,6EAA6E;AAC7E,QAAA,MAAM,cAAc,eAAe,CAAC;AAuBpC,6DAA6D;AAC7D,wBAAgB,qBAAqB,IAAI,kBAAkB,CAG1D;AAED,2CAA2C;AAC3C,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED,cAAM,kBAAkB;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;;IAQjC,wDAAwD;IAClD,cAAc,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAS3C;;;;;;;;;;;OAWG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAgD/E;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAiB1F;;;OAGG;IACG,aAAa,CACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QAAE,GAAG,EAAE,yBAAyB,CAAC;QAAC,IAAI,EAAE,SAAS,EAAE,CAAA;KAAE,CAAC;IA0BjE,OAAO,CAAC,SAAS;CAqClB;AAED,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/services/frankfurter/frankfurter-service.js

@@ -0,0 +1,181 @@
+/**
+ * @fileoverview Frankfurter API service — wraps ECB rate data from api.frankfurter.dev.
+ * @module services/frankfurter/frankfurter-service
+ */
+import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { withRetry } from '@cyanheads/mcp-ts-core/utils';
+import { getServerConfig } from '../../config/server-config.js';
+/** ECB data start date. Requests before this return 404 from Frankfurter. */
+const ECB_START_DATE = '1999-01-04';
+/** YYYY-MM-DD format guard. */
+const DATE_FORMAT_RE = /^\d{4}-\d{2}-\d{2}$/;
+/** ISO 4217 currency code guard: 1-4 uppercase letters (covers standard 3-letter codes + rare 4-letter ones). */
+const CURRENCY_CODE_RE = /^[A-Za-z]{1,4}$/;
+/** Validate a date string is YYYY-MM-DD. Throws on bad format. */
+function assertDateFormat(date, label) {
+    if (!DATE_FORMAT_RE.test(date)) {
+        throw new Error(`not found: ${label} "${date}" is not a valid YYYY-MM-DD date`);
+    }
+}
+/** Validate a currency code is safe to embed in a URL. Throws on bad format. */
+function assertCurrencyFormat(code, label) {
+    if (!CURRENCY_CODE_RE.test(code)) {
+        throw new Error(`not found: ${label} "${code}" is not a valid ISO 4217 currency code`);
+    }
+}
+let _service;
+/** Retrieve the singleton FrankfurterService (lazy-init). */
+export function getFrankfurterService() {
+    _service ??= new FrankfurterService();
+    return _service;
+}
+/** @internal — exposed for testing only */
+export function resetFrankfurterService() {
+    _service = undefined;
+}
+class FrankfurterService {
+    baseUrl;
+    constructor() {
+        this.baseUrl = getServerConfig().frankfurterBaseUrl;
+    }
+    // ── Currencies ──────────────────────────────────────────────────────────────
+    /** Fetch all supported currencies as a sorted array. */
+    async listCurrencies() {
+        const map = await this.fetchJson('/currencies');
+        return Object.entries(map)
+            .map(([code, name]) => ({ code, name }))
+            .sort((a, b) => a.code.localeCompare(b.code));
+    }
+    // ── Rate (point-in-time) ────────────────────────────────────────────────────
+    /**
+     * Get the exchange rate for a currency pair on a given date.
+     * Handles cross-rate triangulation through EUR automatically.
+     *
+     * Frankfurter's base must be EUR for ECB data — but it also supports
+     * arbitrary base via its own math. We just set base={upper_base} and
+     * symbols={upper_quote} and let Frankfurter handle the triangulation.
+     *
+     * @param base - ISO 4217 base currency code
+     * @param quote - ISO 4217 quote currency code
+     * @param date - ISO 8601 date string, or 'latest'
+     */
+    async getRate(base, quote, date) {
+        const upper_base = base.toUpperCase();
+        const upper_quote = quote.toUpperCase();
+        assertCurrencyFormat(upper_base, 'base_currency');
+        assertCurrencyFormat(upper_quote, 'quote_currency');
+        if (date !== 'latest')
+            assertDateFormat(date, 'date');
+        if (upper_base === upper_quote) {
+            // Identity rate — no API call needed
+            const today = new Date().toISOString().slice(0, 10);
+            return {
+                baseCurrency: upper_base,
+                quoteCurrency: upper_quote,
+                rate: 1,
+                rateDate: date === 'latest' ? today : date,
+                dateSnapped: false,
+                rateType: 'ECB reference (mid-market)',
+                source: 'ECB via Frankfurter',
+            };
+        }
+        // Frankfurter supports arbitrary base — it triangulates through EUR internally.
+        // Single call: base={upper_base}&symbols={upper_quote}
+        const endpoint = date === 'latest' ? '/latest' : `/${encodeURIComponent(date)}`;
+        const params = new URLSearchParams({ base: upper_base, symbols: upper_quote });
+        const url = `${endpoint}?${params}`;
+        const raw = await this.fetchJson(url);
+        const rate = raw.rates[upper_quote];
+        if (rate === undefined) {
+            throw new Error(`not found: ${upper_quote} not in response rates`);
+        }
+        const dateSnapped = date !== 'latest' && raw.date !== date;
+        return {
+            baseCurrency: upper_base,
+            quoteCurrency: upper_quote,
+            rate,
+            rateDate: raw.date,
+            dateSnapped,
+            rateType: 'ECB reference (mid-market)',
+            source: 'ECB via Frankfurter',
+        };
+    }
+    // ── Bulk rates snapshot ─────────────────────────────────────────────────────
+    /**
+     * Fetch all rates for a base currency at latest or historical date.
+     * Optionally filter to a specific set of symbols.
+     */
+    getRates(base, date, symbols) {
+        const upper_base = base.toUpperCase();
+        assertCurrencyFormat(upper_base, 'base_currency');
+        if (date !== 'latest')
+            assertDateFormat(date, 'date');
+        if (symbols) {
+            for (const sym of symbols)
+                assertCurrencyFormat(sym.toUpperCase(), 'symbol');
+        }
+        const endpoint = date === 'latest' ? '/latest' : `/${encodeURIComponent(date)}`;
+        const params = new URLSearchParams({ base: upper_base });
+        if (symbols && symbols.length > 0)
+            params.set('symbols', symbols.map((s) => s.toUpperCase()).join(','));
+        const url = `${endpoint}?${params}`;
+        return this.fetchJson(url);
+    }
+    // ── Time-series ─────────────────────────────────────────────────────────────
+    /**
+     * Fetch a historical rate series for a currency pair.
+     * Returns raw API response plus derived rows suitable for canvas registration.
+     */
+    async getTimeSeries(base, quote, startDate, endDate) {
+        const upper_base = base.toUpperCase();
+        const upper_quote = quote.toUpperCase();
+        assertCurrencyFormat(upper_base, 'base_currency');
+        assertCurrencyFormat(upper_quote, 'quote_currency');
+        assertDateFormat(startDate, 'start_date');
+        assertDateFormat(endDate, 'end_date');
+        const params = new URLSearchParams({ base: upper_base, symbols: upper_quote });
+        const url = `/${encodeURIComponent(startDate)}..${encodeURIComponent(endDate)}?${params}`;
+        const raw = await this.fetchJson(url);
+        const rows = Object.entries(raw.rates)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([date, rateMap]) => ({
+            date,
+            rate: rateMap[upper_quote] ?? 0,
+            base_currency: upper_base,
+            quote_currency: upper_quote,
+        }));
+        return { raw, rows };
+    }
+    // ── HTTP helpers ────────────────────────────────────────────────────────────
+    fetchJson(path) {
+        const url = `${this.baseUrl}${path}`;
+        return withRetry(async () => {
+            let response;
+            try {
+                response = await fetch(url, {
+                    headers: {
+                        Accept: 'application/json',
+                        'User-Agent': 'exchange-rates-mcp-server/0.1.1',
+                    },
+                    signal: AbortSignal.timeout(10_000),
+                });
+            }
+            catch (err) {
+                throw serviceUnavailable(`Frankfurter API unreachable: ${err.message}`, { url }, { cause: err });
+            }
+            if (!response.ok) {
+                if (response.status === 404) {
+                    const body = await response.text().catch(() => '');
+                    throw new Error(`not found: ${body || 'date out of range or unknown currency'}`);
+                }
+                throw serviceUnavailable(`Frankfurter API error ${response.status}`, {
+                    url,
+                    status: response.status,
+                });
+            }
+            return response.json();
+        }, { maxRetries: 2, baseDelayMs: 500 });
+    }
+}
+export { ECB_START_DATE };
+//# sourceMappingURL=frankfurter-service.js.map

package/dist/services/frankfurter/frankfurter-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frankfurter-service.js","sourceRoot":"","sources":["../../../src/services/frankfurter/frankfurter-service.ts"],"names":[],"mappings":"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"}