Brasil API MCP

Instructions

Implementation Reference

• src/tools/cambio/index.ts:49-83 (handler)

  The main execution logic for the 'cambio-rate' tool. Fetches exchange rate data from the Brasil API endpoint `/cambio/v1/cotacao/{currency}/{date}`, processes the response, formats quotations, and returns a structured text content response. Handles errors using formatErrorResponse.

      async ({ currency, date }) => {
        console.error(`Getting exchange rates for ${currency} on ${date}`);
        
        const result = await getBrasilApiData(`/cambio/v1/cotacao/${currency}/${date}`);
        
        if (!result.success) {
          return formatErrorResponse(`Error getting exchange rates: ${result.message}`);
        }
        
        // Format the response data
        const exchangeData = result.data;
        
        // Format the quotations
        const formattedQuotations = exchangeData.cotacoes.map((quotation: any) => 
          `Time: ${quotation.data_hora_cotacao} - Type: ${quotation.tipo_boletim}
    Buy Rate: ${quotation.cotacao_compra}
    Sell Rate: ${quotation.cotacao_venda}
    Buy Parity: ${quotation.paridade_compra}
    Sell Parity: ${quotation.paridade_venda}`
        ).join("\n\n");
        
        return {
          content: [{ 
            type: "text" as const, 
            text: `
  Exchange Rate Information:
  Currency: ${exchangeData.moeda}
  Date: ${exchangeData.data}
  
  Quotations:
  ${formattedQuotations}
  ` 
          }]
        };
      }

• src/tools/cambio/index.ts:43-48 (schema)

  Input schema using Zod for validating the tool parameters: currency (string, e.g., USD) and date (string, YYYY-MM-DD format).

  {
    currency: z.string()
      .describe("Currency symbol (e.g., USD, EUR, GBP)"),
    date: z.string()
      .describe("Date in YYYY-MM-DD format. For weekends and holidays, the returned date will be the last available business day.")
  },

• src/tools/cambio/index.ts:40-84 (registration)

  Direct registration of the 'cambio-rate' tool using McpServer.tool(), providing name, description, input schema, and handler function within registerCambioTools.

    server.tool(
      "cambio-rate",
      "Get exchange rates for a specific currency on a specific date",
      {
        currency: z.string()
          .describe("Currency symbol (e.g., USD, EUR, GBP)"),
        date: z.string()
          .describe("Date in YYYY-MM-DD format. For weekends and holidays, the returned date will be the last available business day.")
      },
      async ({ currency, date }) => {
        console.error(`Getting exchange rates for ${currency} on ${date}`);
        
        const result = await getBrasilApiData(`/cambio/v1/cotacao/${currency}/${date}`);
        
        if (!result.success) {
          return formatErrorResponse(`Error getting exchange rates: ${result.message}`);
        }
        
        // Format the response data
        const exchangeData = result.data;
        
        // Format the quotations
        const formattedQuotations = exchangeData.cotacoes.map((quotation: any) => 
          `Time: ${quotation.data_hora_cotacao} - Type: ${quotation.tipo_boletim}
    Buy Rate: ${quotation.cotacao_compra}
    Sell Rate: ${quotation.cotacao_venda}
    Buy Parity: ${quotation.paridade_compra}
    Sell Parity: ${quotation.paridade_venda}`
        ).join("\n\n");
        
        return {
          content: [{ 
            type: "text" as const, 
            text: `
  Exchange Rate Information:
  Currency: ${exchangeData.moeda}
  Date: ${exchangeData.data}
  
  Quotations:
  ${formattedQuotations}
  ` 
          }]
        };
      }
    );

• src/index.ts:30-30 (registration)

  Top-level call to registerCambioTools on the main McpServer instance, which in turn registers the 'cambio-rate' tool.

  registerCambioTools(server);

• src/utils/api.ts:11-40 (helper)

  Shared helper utility for making API requests to brasilapi.com.br, returning structured success/error responses. Used by the 'cambio-rate' handler to fetch data.

  export async function getBrasilApiData(endpoint: string, params: Record<string, any> = {}) {
    try {
      const url = `${BASE_URL}${endpoint}`;
      console.error(`Making request to: ${url}`);
      
      const response = await axios.get(url, { params });
      return { 
        data: response.data,
        success: true
      };
    } catch (error: any) {
      console.error(`Error in API request: ${error.message}`);
      
      // Handle API errors in a structured format
      if (error.response) {
        return {
          success: false,
          statusCode: error.response.status,
          message: error.response.data?.message || error.message,
          error: error.response.data
        };
      }
      
      return {
        success: false,
        message: error.message,
        error
      };
    }
  }