get_ecb_rates

Instructions

Implementation Reference

• src/tools/ecb-rates.ts:77-111 (handler)

  The handler function that executes the get_ecb_rates tool logic. It checks cache, fetches three ECB key interest rates (deposit facility, main refinancing, marginal lending) via fetchEcbSeries, and returns the result as JSON.

  async () => {
    return withMcpMiddleware({ serverName: SERVER_NAME, toolName: 'get_ecb_rates' }, async () => {
      const cacheKey = `get_ecb_rates:${hashParams({})}`;
      const cached = await cacheGet<EcbRatesResult>(cacheKey);
      if (cached) {
        return { content: [{ type: 'text' as const, text: JSON.stringify(cached, null, 2) }] };
      }
  
      const [deposit, main, marginal] = await Promise.all([
        fetchEcbSeries(ECB_SERIES.deposit_facility),
        fetchEcbSeries(ECB_SERIES.main_refinancing),
        fetchEcbSeries(ECB_SERIES.marginal_lending),
      ]);
  
      if (!deposit || !main || !marginal) {
        return makeMcpError(
          'Failed to fetch ECB rates from data-api.ecb.europa.eu',
          'SOURCE_UNAVAILABLE',
        );
      }
  
      const result: EcbRatesResult = {
        rates: {
          deposit_facility: deposit,
          main_refinancing: main,
          marginal_lending: marginal,
        },
        source: 'European Central Bank Statistical Data Warehouse',
        retrieved_at: new Date().toISOString(),
      };
  
      await cacheSet(cacheKey, result, CACHE_TTL);
      return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
    });
  },

• src/tools/ecb-rates.ts:31-69 (handler)

  Helper function that fetches a single ECB series (SDMX-JSON) from the ECB Statistical Data Warehouse API and returns an EcbObservation with date and value.

  async function fetchEcbSeries(seriesKey: string): Promise<EcbObservation | null> {
    const url = `https://data-api.ecb.europa.eu/service/data/${seriesKey}?format=jsondata&detail=dataonly&lastNObservations=1`;
    const res = await fetch(url, {
      headers: { Accept: 'application/json' },
      signal: AbortSignal.timeout(10_000),
    });
  
    if (!res.ok) return null;
  
    // ECB returns SDMX-JSON format
    const json = (await res.json()) as {
      dataSets: Array<{
        series: Record<string, { observations: Record<string, [number | null]> }>;
      }>;
      structure: {
        dimensions: {
          observation: Array<{ values: Array<{ id: string }> }>;
        };
      };
    };
  
    const series = json.dataSets?.[0]?.series?.['0:0:0:0:0:0:0'];
    if (!series) return null;
  
    const observations = series.observations;
    const obsDimension = json.structure?.dimensions?.observation?.[0]?.values;
    if (!obsDimension) return null;
  
    // Get the last observation (we requested lastNObservations=1, so index is "0")
    const lastIdx = Object.keys(observations).sort().pop();
    if (lastIdx === undefined) return null;
  
    const value = observations[lastIdx]?.[0];
    const date = obsDimension[parseInt(lastIdx, 10)]?.id;
  
    if (value === null || value === undefined || !date) return null;
  
    return { date, value };
  }

• src/tools/ecb-rates.ts:16-29 (schema)

  TypeScript interfaces for the tool's input/output: EcbObservation (date/value), EcbRatesResult (rates with three keys, source, retrieved_at).

  interface EcbObservation {
    date: string;
    value: number;
  }
  
  interface EcbRatesResult {
    rates: {
      deposit_facility: EcbObservation;
      main_refinancing: EcbObservation;
      marginal_lending: EcbObservation;
    };
    source: string;
    retrieved_at: string;
  }

• src/tools/ecb-rates.ts:71-113 (registration)

  Registration function registerEcbRatesTool that calls server.tool('get_ecb_rates', ...) with description, empty schema, READ_ONLY_PUBLIC_API annotations, and the async handler.

  export function registerEcbRatesTool(server: McpServer): void {
    server.tool(
      'get_ecb_rates',
      'Fetches the three ECB key interest rates from the ECB Statistical Data Warehouse (SDMX). Returns a JSON object with `rates` containing three entries — `deposit_facility`, `main_refinancing`, and `marginal_lending` — each with `date` (YYYY-MM-DD of the last rate change) and `value` (percentage as a number). Also includes `source` and `retrieved_at` as ISO 8601. Results are cached for 1 hour. USAGE: These are ECB policy rates, not real-time market rates — they only change at Governing Council meetings (roughly every 6 weeks). The `date` field indicates when the current rate was set, not today\'s date. For currency conversion use get_euro_exchange; these rates are not applicable for forex calculations. Use get_eu_inflation alongside this tool to assess the real interest rate (nominal rate minus inflation).',
      {},
      READ_ONLY_PUBLIC_API,
      async () => {
        return withMcpMiddleware({ serverName: SERVER_NAME, toolName: 'get_ecb_rates' }, async () => {
          const cacheKey = `get_ecb_rates:${hashParams({})}`;
          const cached = await cacheGet<EcbRatesResult>(cacheKey);
          if (cached) {
            return { content: [{ type: 'text' as const, text: JSON.stringify(cached, null, 2) }] };
          }
  
          const [deposit, main, marginal] = await Promise.all([
            fetchEcbSeries(ECB_SERIES.deposit_facility),
            fetchEcbSeries(ECB_SERIES.main_refinancing),
            fetchEcbSeries(ECB_SERIES.marginal_lending),
          ]);
  
          if (!deposit || !main || !marginal) {
            return makeMcpError(
              'Failed to fetch ECB rates from data-api.ecb.europa.eu',
              'SOURCE_UNAVAILABLE',
            );
          }
  
          const result: EcbRatesResult = {
            rates: {
              deposit_facility: deposit,
              main_refinancing: main,
              marginal_lending: marginal,
            },
            source: 'European Central Bank Statistical Data Warehouse',
            retrieved_at: new Date().toISOString(),
          };
  
          await cacheSet(cacheKey, result, CACHE_TTL);
          return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
        });
      },
    );
  }

• src/http-entry.ts:24-31 (registration)

  Top-level registration: calls registerEcbRatesTool(server) from the main entry point to wire up the tool.

  const server = new McpServer({ name: NAME, version: VERSION });
  registerEcbRatesTool(server);
  registerEuroExchangeTool(server);
  registerEuInflationTool(server);
  registerEuGdpTool(server);
  registerEuUnemploymentTool(server);
  registerCompareEconomiesTool(server);
  return server;

• src/http-entry.ts:41-48 (registration)

  The tool name 'get_ecb_rates' is listed in the MCP_WELL_KNOWN.tools array for protocol discovery.

  tools: [
    'get_ecb_rates',
    'get_euro_exchange',
    'get_eu_inflation',
    'get_eu_gdp',
    'get_eu_unemployment',
    'compare_eu_economies'
  ]

• src/lib/annotations.ts:1-6 (helper)

  The READ_ONLY_PUBLIC_API annotation constant used in the tool registration to mark the tool as read-only, non-destructive, idempotent, and open-world.

  export const READ_ONLY_PUBLIC_API = {
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
    openWorldHint: true,
  } as const;