dolar-mcp

Instructions

Implementation Reference

• src/actions.ts:44-93 (handler)

  The main convert handler function that converts amounts between ARS and currencies/dollar types. It fetches rates from the API, determines whether to use buy or sell rates, and performs multiplication or division based on the conversion direction.

  export async function convert(
    client: DolarApiClient,
    params: ConvertParams
  ): Promise<unknown> {
    const fromUpper = params.from.toUpperCase();
    const toUpper = (params.to ?? "ARS").toUpperCase();
  
    // Determine which rate to fetch
    let rate: number;
  
    if (fromUpper === "ARS" || toUpper === "ARS") {
      // One side is ARS — fetch the other side's rate
      const nonArs = fromUpper === "ARS" ? toUpper : fromUpper;
  
      // Check if it's a dollar type (blue, oficial, etc.) or a currency (EUR, BRL)
      const dollarTypes = ["blue", "oficial", "bolsa", "contadoconliqui", "cripto", "mayorista", "tarjeta"];
      const isDollarType = dollarTypes.includes(nonArs.toLowerCase());
  
      if (isDollarType) {
        const data = await client.get<DollarRate>(`/v1/dolares/${nonArs.toLowerCase()}`);
        rate = params.use_buy ? data.compra : data.venta;
      } else {
        const data = await client.get<CurrencyRate>(`/v1/cotizaciones/${nonArs}`);
        rate = params.use_buy ? data.compra : data.venta;
      }
  
      // Convert
      if (fromUpper === "ARS") {
        // ARS → other: divide by rate
        return {
          from: fromUpper,
          to: nonArs,
          rate,
          amount: params.amount,
          converted: Number((params.amount / rate).toFixed(2)),
        };
      } else {
        // other → ARS: multiply by rate
        return {
          from: nonArs,
          to: "ARS",
          rate,
          amount: params.amount,
          converted: Number((params.amount * rate).toFixed(2)),
        };
      }
    }
  
    throw new Error("At least one side of the conversion must be ARS. Use 'from' or 'to' as ARS.");
  }

• src/schemas.ts:9-14 (schema)

  TypeScript interface defining the input parameters for the convert tool: amount, from, to (optional, defaults to ARS), and use_buy (optional, defaults to false).

  export interface ConvertParams {
    amount: number;
    from: string;
    to?: string;
    use_buy?: boolean;
  }

• src/mcp-server.ts:77-95 (registration)

  MCP server tool registration with Zod schema validation. Registers the 'convert' tool with description and parameter definitions, then calls the tools.convert handler.

  server.tool(
    "convert",
    "Convert an amount between ARS and any currency or dollar type. At least one side must be ARS.",
    {
      amount: z.number().describe("Amount to convert"),
      from: z.string().describe("Source currency/dollar type (e.g. USD, blue, EUR, ARS)"),
      to: z.string().optional().describe("Target currency (default: ARS)"),
      use_buy: z.boolean().optional().describe("Use buy rate instead of sell rate (default: false)"),
    },
    async (params) => {
      try {
        const result = await tools.convert(params);
        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
      } catch (error) {
        const message = error instanceof Error ? error.message : String(error);
        return { content: [{ type: "text", text: message }], isError: true };
      }
    },
  );

• src/index.ts:26-26 (helper)

  Tool wrapper function that binds the DolarApiClient to the convert handler in the createDolarTools factory.

  convert: (params: ConvertParams) => convert(client, params),

• src/index.ts:38-38 (helper)

  Re-export of the convert function from actions.ts for external use.

  convert,