FrankfurterMCP

Exposes the Frankfurter API (European Central Bank currency data) as MCP tools via FastMCP framework, enabling LLM agents to fetch current and historical exchange rates through a standardized Model Context Protocol interface. Implements async tool registration with readOnlyHint and openWorldHint annotations, allowing Claude Desktop, VS Code, and HTTP-based clients to invoke currency operations without direct API knowledge.

Implements get_latest_exchange_rates tool that queries Frankfurter API for current exchange rates and caches results for 15 minutes using a TTL (time-to-live) cache strategy. Accepts base currency and target currencies as parameters, returning structured JSON with rates, timestamp, and metadata. Cache is transparent to the caller and automatically expires stale data.

Implements convert_currency_latest tool that performs real-time currency conversion by fetching current exchange rates and applying them to a specified amount. Accepts amount, source currency, and target currency as parameters. Internally calls get_latest_exchange_rates and applies the rate to compute the converted amount, returning both the result and the rate used.

Implements get_historical_exchange_rates tool that fetches exchange rates for a specific date or date range from the Frankfurter API. Uses an LRU (Least Recently Used) cache with 1024-item capacity to cache historical queries, enabling efficient repeated lookups of the same historical periods without redundant API calls. Accepts base currency, target currencies, and date/date range parameters.

Implements convert_currency_specific_date tool that performs currency conversion using historical exchange rates for a specified date. Accepts amount, source currency, target currency, and date parameters. Internally calls get_historical_exchange_rates and applies the rate from that date, returning the converted amount and the historical rate used. Results are cached using the same LRU strategy as get_historical_exchange_rates.

Implements get_supported_currencies tool that returns a list of all ISO 4217 currency codes supported by the Frankfurter API. This is a lightweight, read-only operation that queries the Frankfurter API's /currencies endpoint and returns a structured list of currency codes and names. No caching is applied since the supported currency set changes infrequently.

Implements a hybrid caching architecture that uses TTL (time-to-live) caching for recent exchange rates (15-minute expiry) and LRU (least-recently-used) caching for historical queries (1024-item capacity). This design recognizes that recent rates need freshness guarantees while historical data is immutable and benefits from long-term caching. Caching is transparent to tool callers and automatically managed by the FrankfurterMCP class.

Implements FrankfurterMCP as a FastMCP-based server that supports multiple transport protocols: stdio (for local desktop integrations like Claude Desktop and VS Code) and HTTP-based transports (SSE and streamable-http for cloud and browser-based clients). Transport selection is configured at deployment time, allowing the same server code to run in different environments without modification.

Implements all five currency tools as async methods registered with FastMCP framework using MCP tool annotations. Each tool is decorated with readOnlyHint: True (indicating read-only operations) and openWorldHint: True (indicating external API access). This enables MCP clients to understand tool semantics and make informed decisions about tool invocation, error handling, and caching.