consultar_feriados

Instructions

Implementation Reference

• src/tools/feriados.ts:45-79 (handler)

  Handler function that validates the year (1900-2199), calls BrasilAPI /feriados/v1/{ano}, and returns the result with error translation.

  export async function consultarFeriadosHandler(
    input: ConsultarFeriadosInput,
  ): Promise<CallToolResult> {
    if (!validarAno(input.ano)) {
      return {
        content: [
          {
            type: "text",
            text: `Ano inválido: ${input.ano}. Deve ser inteiro entre 1900 e 2199.`,
          },
        ],
        isError: true,
      };
    }
  
    try {
      const dados = await brasilApi.get<unknown>(`/feriados/v1/${input.ano}`);
      return {
        content: [{ type: "text", text: JSON.stringify(dados, null, 2) }],
      };
    } catch (err) {
      return {
        content: [
          {
            type: "text",
            text: traduzirErroBrasilApi(err, {
              notFound: `Feriados de ${input.ano} não encontrados na base.`,
              contextoErro: "Erro ao consultar feriados",
            }),
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/feriados.ts:15-22 (schema)

  Zod schema defining the input: a single integer field 'ano' (year) with description.

  export const consultarFeriadosSchema = z.object({
    ano: z
      .number()
      .int()
      .describe(
        "Ano dos feriados, 4 dígitos. Faixa aceita: 1900 a 2199. Ex: 2026.",
      ),
  });

• src/index.ts:117-124 (registration)

  Registration of the tool with the MCP server, binding tool name, description, schema, and wrapped handler.

  server.registerTool(
    consultarFeriadosTool.name,
    {
      description: consultarFeriadosTool.description,
      inputSchema: consultarFeriadosSchema.shape,
    },
    wrapHandler(consultarFeriadosTool.name, consultarFeriadosHandler),
  );

• src/tools/feriados.ts:26-38 (registration)

  Tool definition object with name 'consultar_feriados', description, and schema reference.

  export const consultarFeriadosTool = {
    name: "consultar_feriados",
    description: [
      "Lista os feriados NACIONAIS brasileiros de um ano específico via BrasilAPI.",
      "",
      "Retorna em JSON um array com data (YYYY-MM-DD), nome do feriado e tipo (national/optional). Inclui feriados móveis calculados (Carnaval, Páscoa, Corpus Christi).",
      "",
      "Use quando o usuário perguntar quando cai um feriado, listar feriados do ano, planejar emendas/pontes, ou calcular dias úteis.",
      "",
      "NÃO use para: feriados estaduais ou municipais (a API só cobre nacionais), datas comemorativas sem dia de folga (Dia das Mães etc.), ou anos fora da faixa 1900-2199.",
    ].join(" "),
    inputSchema: consultarFeriadosSchema,
  };

• src/tools/feriados.ts:40-43 (helper)

  Helper function that validates the year is an integer between 1900 and 2199 (BrasilAPI range).

  function validarAno(ano: number): boolean {
    // Faixa que a BrasilAPI suporta. Validamos local pra evitar round-trip.
    return Number.isInteger(ano) && ano >= 1900 && ano <= 2199;
  }