consultar_banco

Instructions

Implementation Reference

• src/tools/banco.ts:53-89 (handler)

  Handler function for the 'consultar_banco' tool. Validates the numeric bank code input, calls the BrasilAPI endpoint /banks/v1/{code}, and returns the bank info as formatted JSON. On error, translates API errors to user-friendly Portuguese messages.

  export async function consultarBancoHandler(
    input: ConsultarBancoInput,
  ): Promise<CallToolResult> {
    const codigo = normalizarCodigo(input.codigo);
  
    if (!codigo) {
      return {
        content: [
          {
            type: "text",
            text: `Código de banco inválido: '${input.codigo}'. Deve ser numérico, de 1 a 4 dígitos.`,
          },
        ],
        isError: true,
      };
    }
  
    try {
      const dados = await brasilApi.get<unknown>(`/banks/v1/${codigo}`);
      return {
        content: [{ type: "text", text: JSON.stringify(dados, null, 2) }],
      };
    } catch (err) {
      return {
        content: [
          {
            type: "text",
            text: traduzirErroBrasilApi(err, {
              notFound: `Banco com código ${codigo} não encontrado no cadastro do BACEN.`,
              contextoErro: "Erro ao consultar banco",
            }),
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/banco.ts:21-27 (schema)

  Zod schema for 'consultar_banco' input. Accepts a 'codigo' field as string or number (1-4 digit COMPE/Febraban bank code).

  export const consultarBancoSchema = z.object({
    codigo: z
      .union([z.string(), z.number()])
      .describe(
        "Código COMPE/Febraban do banco (1 a 4 dígitos). Aceita string ou número. Ex: 341 (Itaú), 260 (Nubank), 237 (Bradesco).",
      ),
  });

• src/index.ts:99-106 (registration)

  Registration of the 'consultar_banco' tool with the MCP server via server.registerTool(), using the tool name, description, input schema, and a wrapped handler.

  server.registerTool(
    consultarBancoTool.name,
    {
      description: consultarBancoTool.description,
      inputSchema: consultarBancoSchema.shape,
    },
    wrapHandler(consultarBancoTool.name, consultarBancoHandler),
  );

• src/tools/banco.ts:45-51 (helper)

  Helper function 'normalizarCodigo' that validates and normalizes a bank code (1-4 digits), stripping leading zeros and returning an empty string if invalid.

  function normalizarCodigo(codigo: string | number): string {
    const s = String(codigo).trim();
    // Códigos COMPE têm de 1 a 4 dígitos. Normaliza removendo zeros à esquerda
    // só pra validar — a BrasilAPI aceita tanto "1" quanto "001".
    if (!/^\d{1,4}$/.test(s)) return "";
    return s;
  }

• src/utils/errors.ts:23-49 (helper)

  Helper function 'traduzirErroBrasilApi' used by the handler to translate BrasilApiError exceptions into user-friendly Portuguese messages based on HTTP status codes.

  export function traduzirErroBrasilApi(
    err: unknown,
    mapa: MapeamentoErro,
  ): string {
    const ctx = mapa.contextoErro ?? "Erro ao consultar dados";
  
    if (err instanceof BrasilApiError) {
      if (err.status === 404) return mapa.notFound;
      if (err.status === 400) {
        return `${ctx}: dados inválidos enviados ao serviço.`;
      }
      if (err.status === 429) {
        return `${ctx}: limite de requisições temporariamente atingido. Tente novamente em alguns segundos.`;
      }
      if (err.status >= 500) {
        return `${ctx}: serviço temporariamente indisponível. Tente novamente em alguns instantes.`;
      }
      // status === 0 é o sinal que usamos no cliente pra erro de rede / abort.
      if (err.status === 0) {
        return `${ctx}: falha de rede ao alcançar o serviço.`;
      }
      return `${ctx}: o serviço retornou erro inesperado (${err.status}).`;
    }
  
    const msg = err instanceof Error ? err.message : String(err);
    return `${ctx}: ${msg}`;
  }