Get historical exchange rate (Pro plan required)

Instructions

Implementation Reference

• src/client.ts:187-195 (handler)

  The actual API call function that fetches the historical exchange rate from the /api/historical/rates endpoint. Called by the MCP tool handler.

  async getHistoricalRate(date: string, from: string, to: string): Promise<number> {
    const data = await this.request<{ rate?: string; result?: string }>(
      "/api/historical/rates",
      { date, from: from.toUpperCase(), to: to.toUpperCase(), amount: 1 },
    );
    if (data.rate !== undefined) return parseFloat(data.rate);
    if (data.result !== undefined) return parseFloat(data.result);
    throw new APIError("Unexpected historical rate response shape", 500);
  }

• src/client.ts:197-210 (handler)

  Helper function that converts an amount at a historical rate (used when amount != 1).

  async convertHistorical(
    date: string,
    from: string,
    to: string,
    amount: number,
  ): Promise<number> {
    const data = await this.request<{ rate?: string; result?: string }>(
      "/api/historical/rates",
      { date, from: from.toUpperCase(), to: to.toUpperCase(), amount },
    );
    if (data.result !== undefined) return parseFloat(data.result);
    if (data.rate !== undefined) return parseFloat(data.rate) * amount;
    throw new APIError("Unexpected historical rate response shape", 500);
  }

• src/index.ts:116-157 (registration)

  Registration of the 'historical_rate' tool with the MCP server, including input schema (date, from, to, amount) and the handler callback that dispatches to getHistoricalRate or convertHistorical.

  server.registerTool(
    "historical_rate",
    {
      title: "Get historical exchange rate (Pro plan required)",
      description:
        "Fetch the exchange rate that was in effect on a specific date. Date format YYYY-MM-DD. " +
        "Coverage goes back to 1999-01-04 for major fiat pairs. **Requires UniRate Pro** — " +
        "free-tier keys will receive a clear upgrade-required error.",
      inputSchema: {
        date: z
          .string()
          .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD")
          .describe("Date in YYYY-MM-DD format, e.g. '2020-03-15'"),
        from: z.string().min(3).max(10).describe("Source currency code"),
        to: z.string().min(3).max(10).describe("Target currency code"),
        amount: z
          .number()
          .positive()
          .optional()
          .describe("Optional amount to convert at the historical rate. Defaults to 1."),
      },
      annotations: { readOnlyHint: true, openWorldHint: true },
    },
    async ({ date, from, to, amount }) => {
      try {
        if (amount !== undefined && amount !== 1) {
          const result = await client.convertHistorical(date, from, to, amount);
          return ok(
            `On ${date}, ${amount} ${from.toUpperCase()} = ${result} ${to.toUpperCase()}`,
            { date, from: from.toUpperCase(), to: to.toUpperCase(), amount, result },
          );
        }
        const rate = await client.getHistoricalRate(date, from, to);
        return ok(
          `On ${date}, 1 ${from.toUpperCase()} = ${rate} ${to.toUpperCase()}`,
          { date, from: from.toUpperCase(), to: to.toUpperCase(), rate },
        );
      } catch (err) {
        return fail(err);
      }
    },
  );

• src/index.ts:124-136 (schema)

  Input schema for the historical_rate tool defining date (YYYY-MM-DD format), from, to, and optional amount parameters with Zod validation.

  inputSchema: {
    date: z
      .string()
      .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD")
      .describe("Date in YYYY-MM-DD format, e.g. '2020-03-15'"),
    from: z.string().min(3).max(10).describe("Source currency code"),
    to: z.string().min(3).max(10).describe("Target currency code"),
    amount: z
      .number()
      .positive()
      .optional()
      .describe("Optional amount to convert at the historical rate. Defaults to 1."),
  },