Get latest exchange rate(s)

Instructions

Implementation Reference

• src/index.ts:91-113 (handler)

  The handler function for the 'latest_rate' tool. Accepts 'from' (base currency) and optional 'to' (target currency). If 'to' is provided, calls client.getRate(from, to) for a single rate. Otherwise, calls client.getRates(from) for all rates and returns a preview of the first 10.

  async ({ from, to }) => {
    try {
      if (to) {
        const rate = await client.getRate(from, to);
        return ok(
          `1 ${from.toUpperCase()} = ${rate} ${to.toUpperCase()}`,
          { from: from.toUpperCase(), to: to.toUpperCase(), rate },
        );
      }
      const rates = await client.getRates(from);
      const preview = Object.entries(rates)
        .slice(0, 10)
        .map(([k, v]) => `${k}: ${v}`)
        .join(", ");
      const total = Object.keys(rates).length;
      return ok(
        `${total} rates for base ${from.toUpperCase()}. First 10: ${preview}.`,
        { base: from.toUpperCase(), rates },
      );
    } catch (err) {
      return fail(err);
    }
  },

• src/index.ts:75-89 (schema)

  Input schema for the 'latest_rate' tool. Defines 'from' (required, ISO 4217 currency code) and 'to' (optional target currency). Uses Zod for validation.

  {
    title: "Get latest exchange rate(s)",
    description:
      "Fetch the latest exchange rate for a base currency. If 'to' is provided, returns a single rate; " +
      "otherwise returns rates for all supported currencies relative to the base.",
    inputSchema: {
      from: z.string().min(3).max(10).describe("Base currency code, e.g. 'USD'"),
      to: z
        .string()
        .min(3)
        .max(10)
        .optional()
        .describe("Optional target currency. Omit to get rates for all currencies."),
    },
    annotations: { readOnlyHint: true, openWorldHint: true },

• src/index.ts:73-114 (registration)

  Registration of the 'latest_rate' tool via server.registerTool() on the McpServer instance, binding the name, schema, annotations, and handler together.

  server.registerTool(
    "latest_rate",
    {
      title: "Get latest exchange rate(s)",
      description:
        "Fetch the latest exchange rate for a base currency. If 'to' is provided, returns a single rate; " +
        "otherwise returns rates for all supported currencies relative to the base.",
      inputSchema: {
        from: z.string().min(3).max(10).describe("Base currency code, e.g. 'USD'"),
        to: z
          .string()
          .min(3)
          .max(10)
          .optional()
          .describe("Optional target currency. Omit to get rates for all currencies."),
      },
      annotations: { readOnlyHint: true, openWorldHint: true },
    },
    async ({ from, to }) => {
      try {
        if (to) {
          const rate = await client.getRate(from, to);
          return ok(
            `1 ${from.toUpperCase()} = ${rate} ${to.toUpperCase()}`,
            { from: from.toUpperCase(), to: to.toUpperCase(), rate },
          );
        }
        const rates = await client.getRates(from);
        const preview = Object.entries(rates)
          .slice(0, 10)
          .map(([k, v]) => `${k}: ${v}`)
          .join(", ");
        const total = Object.keys(rates).length;
        return ok(
          `${total} rates for base ${from.toUpperCase()}. First 10: ${preview}.`,
          { base: from.toUpperCase(), rates },
        );
      } catch (err) {
        return fail(err);
      }
    },
  );

• src/client.ts:156-171 (helper)

  Client helper methods used by the latest_rate handler: getRate(from, to) returns a single rate, and getRates(from) returns all rates. Both call the /api/rates endpoint.

  async getRate(from: string, to: string): Promise<number> {
    const data = await this.request<{ rate: string }>("/api/rates", {
      from: from.toUpperCase(),
      to: to.toUpperCase(),
    });
    return parseFloat(data.rate);
  }
  
  async getRates(from: string): Promise<Record<string, number>> {
    const data = await this.request<{ rates: Record<string, string> }>("/api/rates", {
      from: from.toUpperCase(),
    });
    const out: Record<string, number> = {};
    for (const [k, v] of Object.entries(data.rates)) out[k] = parseFloat(v);
    return out;
  }