Buscar Feriados

Instructions

Implementation Reference

• lib/tools/feriados.ts:25-95 (handler)

  The 'buscar_feriados' tool registration and handler function. It registers the tool with an inputSchema (zod) and an async handler that calls the feriadosApi to /feriados, formats results, and returns text content. Lines 25-95 contain the full tool definition including the schema (lines 29-68) and the handler callback (lines 70-94).

  export function registerFeriadosTools(server: McpServer) {
      // 1. buscar_feriados
      server.registerTool(
          "buscar_feriados",
          {
              title: "Buscar Feriados",
              description: `Busca feriados brasileiros com filtros flexíveis.
  Use esta tool para consultas gerais quando precisar filtrar por múltiplos critérios ao mesmo tempo.
  Pode filtrar por data, tipo (NACIONAL/ESTADUAL/MUNICIPAL/FACULTATIVO), estado (UF), cidade (código IBGE), ano e mês.
  Para buscas mais específicas, prefira usar as tools especializadas (feriados_nacionais, feriados_por_estado, etc.).
  Retorna lista paginada de feriados com nome, data (DD/MM/YYYY), tipo, descrição e indicador bancário (FEBRABAN).`,
              inputSchema: z.object({
                  date: z
                      .string()
                      .optional()
                      .describe("Data no formato YYYY-MM-DD (ex: 2026-12-25)"),
                  type: z
                      .enum(["NACIONAL", "ESTADUAL", "MUNICIPAL", "FACULTATIVO"])
                      .optional()
                      .describe("Tipo do feriado"),
                  uf: z
                      .string()
                      .length(2)
                      .optional()
                      .describe("Sigla do estado em maiúsculas (ex: SP, RJ, MG)"),
                  ibge: z
                      .string()
                      .optional()
                      .describe(
                          "Código IBGE do município (ex: 3550308 para São Paulo)"
                      ),
                  ano: z
                      .string()
                      .optional()
                      .describe("Ano com 4 dígitos (ex: 2026)"),
                  month: z
                      .string()
                      .optional()
                      .describe("Mês de 1 a 12 (requer que 'ano' também seja informado)"),
                  bancarios: z
                      .boolean()
                      .optional()
                      .describe("Se true, retorna apenas feriados bancários (calendário FEBRABAN)"),
              }),
          },
          async ({ date, type, uf, ibge, ano, month, bancarios }) => {
              try {
                  const data = await feriadosApi<{
                      feriados: unknown[];
                      meta: unknown;
                  }>({
                      path: "/feriados",
                      params: { date, type, uf, ibge, ano, month, bancarios: bancarios ? "true" : undefined },
                  });
  
                  const text =
                      formatHolidayList(data.feriados) + formatMeta(data.meta);
                  return { content: [{ type: "text" as const, text }] };
              } catch (error) {
                  return {
                      content: [
                          {
                              type: "text" as const,
                              text: `❌ Erro: ${error instanceof Error ? error.message : String(error)}`,
                          },
                      ],
                      isError: true,
                  };
              }
          }
      );

• lib/register-tools.ts:1-10 (registration)

  Registration entry point. The registerFeriadosTools function (exported from lib/tools/feriados.ts) is imported and called inside registerAllTools, which wires it into the MCP server.

  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  import { registerFeriadosTools } from "./tools/feriados";
  import { registerEstadosTools } from "./tools/estados";
  import { registerMunicipiosTools } from "./tools/municipios";
  
  export function registerAllTools(server: McpServer) {
      registerFeriadosTools(server);
      registerEstadosTools(server);
      registerMunicipiosTools(server);
  }

• lib/tools/feriados.ts:29-68 (schema)

  The input schema for 'buscar_feriados' defined using Zod. It defines optional parameters: date (string YYYY-MM-DD), type (enum: NACIONAL/ESTADUAL/MUNICIPAL/FACULTATIVO), uf (2-letter string), ibge (string), ano (4-digit string), month (1-12 string), and bancarios (boolean).

          {
              title: "Buscar Feriados",
              description: `Busca feriados brasileiros com filtros flexíveis.
  Use esta tool para consultas gerais quando precisar filtrar por múltiplos critérios ao mesmo tempo.
  Pode filtrar por data, tipo (NACIONAL/ESTADUAL/MUNICIPAL/FACULTATIVO), estado (UF), cidade (código IBGE), ano e mês.
  Para buscas mais específicas, prefira usar as tools especializadas (feriados_nacionais, feriados_por_estado, etc.).
  Retorna lista paginada de feriados com nome, data (DD/MM/YYYY), tipo, descrição e indicador bancário (FEBRABAN).`,
              inputSchema: z.object({
                  date: z
                      .string()
                      .optional()
                      .describe("Data no formato YYYY-MM-DD (ex: 2026-12-25)"),
                  type: z
                      .enum(["NACIONAL", "ESTADUAL", "MUNICIPAL", "FACULTATIVO"])
                      .optional()
                      .describe("Tipo do feriado"),
                  uf: z
                      .string()
                      .length(2)
                      .optional()
                      .describe("Sigla do estado em maiúsculas (ex: SP, RJ, MG)"),
                  ibge: z
                      .string()
                      .optional()
                      .describe(
                          "Código IBGE do município (ex: 3550308 para São Paulo)"
                      ),
                  ano: z
                      .string()
                      .optional()
                      .describe("Ano com 4 dígitos (ex: 2026)"),
                  month: z
                      .string()
                      .optional()
                      .describe("Mês de 1 a 12 (requer que 'ano' também seja informado)"),
                  bancarios: z
                      .boolean()
                      .optional()
                      .describe("Se true, retorna apenas feriados bancários (calendário FEBRABAN)"),
              }),

• lib/tools/feriados.ts:6-17 (helper)

  The formatHolidayList helper used by the handler to format the array of feriados into a readable text output with emoji, date, name, type, banking indicator, and description.

  function formatHolidayList(feriados: any[]): string {
      if (!feriados || feriados.length === 0) {
          return "Nenhum feriado encontrado para os critérios informados.";
      }
  
      return feriados
          .map(
              (f) =>
                  `📅 ${f.data} — ${f.nome} (${f.tipo})${f.bancario ? " 🏦" : ""}${f.descricao ? `\n   ${f.descricao}` : ""}`
          )
          .join("\n\n");
  }

• lib/tools/feriados.ts:19-23 (helper)

  The formatMeta helper used by the handler to format pagination metadata (total count and page info) into a text footer.

  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  function formatMeta(meta: any): string {
      if (!meta) return "";
      return `\n\n📊 Total: ${meta.total} | Página ${meta.page}/${meta.total_pages}`;
  }