get_historical_exchange_rates

Instructions

Implementation Reference

• src/frankfurtermcp/server.py:253-322 (handler)

  Main async handler for the get_historical_exchange_rates tool. Accepts base_currency, optional symbols, and either specific_date, start_date, or a date range (start_date + end_date). Calls the cached internal helper _get_historical_exchange_rates and wraps the result with response metadata.

  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:128-166 (helper)

  Internal cached helper that builds the Frankfurter API URL with date range (start_date..end_date, start_date.., or /specific_date), adds optional base_currency and symbols query params, performs the HTTP GET request, and returns the JSON result along with the HTTP response.

  @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:55-62 (registration)

  Registration metadata for the get_historical_exchange_rates tool in the FrankfurterMCP.tools class variable. The MCPMixin.register_features method uses this list to dynamically register each tool with the FastMCP instance.

  {
      "fn": "get_historical_exchange_rates",
      "tags": ["currency-rates", "historical-exchange-rates"],
      "annotations": {
          "readOnlyHint": True,
          "openWorldHint": True,
      },
  },