get_currency_rates

Instructions

Implementation Reference

• src/index.ts:22-39 (registration)

  The 'get_currency_rates' tool is registered on the MCP server using server.tool(). The handler is inline: it calls the Monobank /bank/currency endpoint, parses the JSON response, validates it against CurrencyRatesResponseSchema, and returns the result via createSuccessResponse.

  server.tool(
      "get_currency_rates",
      "Get a basic list of currency rates from Monobank. The information can be refreshed once per 5 minutes, otherwise an error will be thrown.",
      {},
      async () => {
          try {
              const { baseUrl } = getConfig();
              const response = await fetchWithErrorHandling(
                  `${baseUrl}/bank/currency`,
              );
              const result = await parseJsonResponse<CurrencyRate[]>(response);
              const currencyRates = CurrencyRatesResponseSchema.parse(result);
              return createSuccessResponse(currencyRates);
          } catch (error) {
              return formatErrorAsToolResponse(error, "get currency rates");
          }
      },
  );

• src/schemas.ts:1-13 (schema)

  Defines CurrencyRateSchema (zod object with fields: currencyCodeA, currencyCodeB, date, rateBuy?, rateSell?, rateCross?) and CurrencyRatesResponseSchema (z.array of CurrencyRateSchema) used to validate the currency rates API response.

  import { z } from "zod";
  
  export const CurrencyRateSchema = z.object({
      currencyCodeA: z.number(),
      currencyCodeB: z.number(),
      date: z.number(),
      rateBuy: z.number().optional(),
      rateSell: z.number().optional(),
      rateCross: z.number().optional(),
  });
  
  export const CurrencyRatesResponseSchema = z.array(CurrencyRateSchema);

• src/interfaces.ts:1-8 (schema)

  Defines the CurrencyRate TypeScript interface used for typing the parsed JSON response from the /bank/currency endpoint.

  export interface CurrencyRate {
      currencyCodeA: number;
      currencyCodeB: number;
      date: number;
      rateBuy?: number;
      rateSell?: number;
      rateCross?: number;
  }

• src/helpers.ts:43-57 (helper)

  fetchWithErrorHandling helper used to make the HTTP request to the /bank/currency endpoint.

  export async function fetchWithErrorHandling(
      url: string,
      options?: RequestInit,
  ): Promise<Response> {
      const response = await fetch(url, options);
  
      if (!response.ok) {
          const errorText = await response
              .text()
              .catch(() => response.statusText);
          throw new Error(`HTTP ${response.status} - ${errorText}`);
      }
  
      return response;
  }

• src/helpers.ts:59-69 (helper)

  parseJsonResponse helper used to parse the JSON body of the /bank/currency response.

  export async function parseJsonResponse<T>(response: Response): Promise<T> {
      try {
          return await response.json();
      } catch (error) {
          throw new Error(
              `Failed to parse response as JSON: ${
                  error instanceof Error ? error.message : "Unknown JSON error"
              }`,
          );
      }
  }