convert_currency

Instructions

Implementation Reference

• src/frankfurter_forex_mcp/tools/convert_currency.py:9-38 (handler)

  The main handler function that executes the currency conversion logic. It calls the FrankfurterClient.convert method, validates the response payload, extracts the conversion rate, and returns a ConvertCurrencyOutput with the original amount, currencies, converted amount, and date.

  async def execute(
      input_data: ConvertCurrencyInput,
      client: FrankfurterClient,
  ) -> ConvertCurrencyOutput:
      payload = await client.convert(
          amount=float(input_data.amount),
          source_currency=input_data.from_currency,
          destination_currency=input_data.to_currency,
      )
      rates = payload.get("rates", {})
      payload_date = payload.get("date")
  
      if not isinstance(rates, dict):
          raise FrankfurterClientError("Frankfurter API returned malformed rates payload")
      if not isinstance(payload_date, str):
          raise FrankfurterClientError("Frankfurter API returned malformed date payload")
  
      converted_amount = rates.get(input_data.to_currency)
      if converted_amount is None:
          raise FrankfurterClientError(
              "Frankfurter API returned no conversion rate for target currency"
          )
  
      return ConvertCurrencyOutput(
          original_amount=float(input_data.amount),
          source_currency=input_data.from_currency,
          destination_currency=input_data.to_currency,
          converted_amount=float(converted_amount),
          date=date.fromisoformat(payload_date),
      )

• src/frankfurter_forex_mcp/models/schemas.py:54-75 (schema)

  Pydantic schema definitions for convert_currency. ConvertCurrencyInput (lines 54-67) validates amount (PositiveFloat), from_currency, and to_currency (3-letter ISO 4217 codes with normalization). ConvertCurrencyOutput (lines 70-75) defines the response structure with original_amount, source_currency, destination_currency, converted_amount, and date.

  class ConvertCurrencyInput(BaseModel):
      model_config = ConfigDict(populate_by_name=True, str_strip_whitespace=True)
  
      amount: PositiveFloat
      from_currency: str = Field(alias="from", min_length=3, max_length=3)
      to_currency: str = Field(alias="to", min_length=3, max_length=3)
  
      @field_validator("from_currency", "to_currency")
      @classmethod
      def normalize_currency(cls, value: str) -> str:
          value = _normalize_currency(value)
          if len(value) != 3 or not value.isalpha():
              raise ValueError("currency must be a 3-letter ISO 4217 code")
          return value
  
  
  class ConvertCurrencyOutput(BaseModel):
      original_amount: float
      source_currency: str
      destination_currency: str
      converted_amount: float
      date: date

• src/frankfurter_forex_mcp/server.py:48-69 (registration)

  The tool registration function decorated with @mcp.tool(name="convert_currency"). It creates a ConvertCurrencyInput from the raw parameters, creates a FrankfurterClient, calls convert_currency.execute, and handles ValidationError, FrankfurterClientError, and unexpected exceptions with appropriate error responses.

  @mcp.tool(name="convert_currency")
  async def convert_currency_tool(amount: float, from_currency: str, to_currency: str) -> dict:
      """Convert a monetary amount from one currency to another."""
      try:
          input_data = ConvertCurrencyInput(
              amount=amount,
              from_currency=from_currency,
              to_currency=to_currency,
          )
          async with FrankfurterClient.from_env() as client:
              output = await convert_currency.execute(input_data, client)
          return output.model_dump(mode="json")
      except ValidationError as exc:
          return _to_error(str(exc), tool="convert_currency", error_code="validation_error")
      except FrankfurterClientError as exc:
          return _to_error(str(exc), tool="convert_currency", error_code="upstream_error")
      except Exception:
          return _to_error(
              "Unexpected internal error",
              tool="convert_currency",
              error_code="internal_error",
          )

• src/frankfurter_forex_mcp/client/frankfurter.py:57-68 (helper)

  The FrankfurterClient.convert helper method that makes the actual HTTP request to the Frankfurter API's /latest endpoint with amount, from, and to parameters. It returns the JSON response payload containing the conversion rates and date.

  async def convert(
      self,
      amount: float,
      source_currency: str,
      destination_currency: str,
  ) -> dict[str, Any]:
      params = {
          "amount": amount,
          "from": source_currency,
          "to": destination_currency,
      }
      return await self._request_json("/latest", params=params)