FrankfurterMCP

Instructions

Implementation Reference

• src/frankfurtermcp/server.py:244-313 (handler)

  Main handler function that implements the get_historical_exchange_rates tool logic, including parameter validation via Pydantic annotations, caching checks, API call via helper, and response formatting.
  async def get_historical_exchange_rates( self, ctx: Context, base_currency: Annotated[ ISO4217, Field(description="A base currency ISO4217 code for which rates are to be requested."), ], symbols: Annotated[ list[ISO4217] | ISO4217 | None, Field( description="A list of target currency ISO4217 codes for which rates against the base currency will be provided. If not provided, all supported currencies will be shown." ), ] = None, specific_date: Annotated[ date | None, Field( default=None, description="The specific date for which the historical rates are requested in the YYYY-MM-DD format.", ), ] = None, start_date: Annotated[ date | None, Field( default=None, description="The start date, of a date range, for which the historical rates are requested in the YYYY-MM-DD format.", ), ] = None, end_date: Annotated[ date | None, Field( default=None, description="The end date, of a date range, for which the historical rates are requested in the YYYY-MM-DD format.", ), ] = None, ): """Returns historical exchange rates for a specific date or date range. If the exchange rates for a specified date is not available, the rates available for the closest date before the specified date will be provided. Either a specific date, a start date, or a date range must be provided. The symbols can be used to filter the results to specific currencies. If symbols are not provided, all supported currencies will be returned. """ await ctx.info(f"Fetching historical exchange rates from Frankfurter API at {self.frankfurter_api_url}") # Some LLMs make this mistake of passing just one currency but not as a list! if type(symbols) is str: symbols = [symbols] cache_key = hashkey( self, specific_date=specific_date.isoformat() if specific_date else None, start_date=start_date.isoformat() if start_date else None, end_date=end_date.isoformat() if end_date else None, base_currency=base_currency, symbols=tuple(symbols) if symbols else None, ) cache_hit = cache_key in lru_cache result, http_response = self._get_historical_exchange_rates( specific_date=specific_date.isoformat() if specific_date else None, start_date=start_date.isoformat() if start_date else None, end_date=end_date.isoformat() if end_date else None, base_currency=base_currency, symbols=tuple(symbols) if symbols else None, ) if cache_hit: await ctx.info( f"Historical exchange rates fetched for {len(result.get('rates', []))} dates from least-recently used (LRU) cache." ) else: await ctx.info(f"Historical exchange rates fetched for {len(result.get('rates', []))} dates.") return self.get_response_content(response=result, http_response=http_response, cached_response=cache_hit)
• src/frankfurtermcp/server.py:54-61 (registration)

  Tool registration entry in the tools list of the FrankfurterMCP class, defining the tool name, tags, and annotations.
  { "fn": "get_historical_exchange_rates", "tags": ["currency-rates", "historical-exchange-rates"], "annotations": { "readOnlyHint": True, "openWorldHint": True, }, },
• src/frankfurtermcp/server.py:119-157 (helper)

  Cached internal helper function that performs the actual HTTP request to the Frankfurter API for historical exchange rates, constructing the URL based on date parameters.
  @cached(cache=lru_cache, lock=threading.Lock(), key=hashkey) def _get_historical_exchange_rates( self, specific_date: str | None = None, start_date: str | None = None, end_date: str | None = None, base_currency: str | None = None, symbols: tuple[str, ...] | None = None, ): """Internal function to get historical exchange rates. This is a helper function for the main tool.""" try: params = {} if base_currency: params["base"] = base_currency if symbols: params["symbols"] = ",".join(symbols) frankfurter_url = self.frankfurter_api_url if start_date and end_date: frankfurter_url += f"/{start_date}..{end_date}" elif start_date: # If only start_date is provided, we assume the end date is the latest available date frankfurter_url += f"/{start_date}.." elif specific_date: # If only specific_date is provided, we assume it is the date for which we want the rates frankfurter_url += f"/{specific_date}" else: raise ValueError("You must provide either a specific date, a start date, or a date range.") with self.get_httpx_client() as client: http_response = client.get( frankfurter_url, params=params, ) http_response.raise_for_status() result = http_response.json() return result, http_response except httpx.RequestError as e: raise ValueError(f"Failed to fetch historical exchange rates from {self.frankfurter_api_url}. {e}")
• src/frankfurtermcp/server.py:247-278 (schema)

  Input schema defined via Pydantic Annotated types and Field descriptions in the handler function signature.
  base_currency: Annotated[ ISO4217, Field(description="A base currency ISO4217 code for which rates are to be requested."), ], symbols: Annotated[ list[ISO4217] | ISO4217 | None, Field( description="A list of target currency ISO4217 codes for which rates against the base currency will be provided. If not provided, all supported currencies will be shown." ), ] = None, specific_date: Annotated[ date | None, Field( default=None, description="The specific date for which the historical rates are requested in the YYYY-MM-DD format.", ), ] = None, start_date: Annotated[ date | None, Field( default=None, description="The start date, of a date range, for which the historical rates are requested in the YYYY-MM-DD format.", ), ] = None, end_date: Annotated[ date | None, Field( default=None, description="The end date, of a date range, for which the historical rates are requested in the YYYY-MM-DD format.", ), ] = None, ):