Feriados por Estado

Instructions

Implementation Reference

• lib/tools/feriados.ts:164-227 (registration)

  Registration of the 'feriados_por_estado' tool on the MCP server using server.registerTool().

      // 3. feriados_por_estado
      server.registerTool(
          "feriados_por_estado",
          {
              title: "Feriados por Estado",
              description: `Lista todos os feriados de um estado brasileiro (feriados nacionais + estaduais daquele UF).
  Use quando o usuário perguntar sobre feriados em um estado específico, como "feriados em São Paulo" ou "feriados do RJ".
  As siglas dos estados (UF) são: AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO.`,
              inputSchema: z.object({
                  uf: z
                      .string()
                      .length(2)
                      .describe("Sigla do estado em maiúsculas (ex: SP, RJ, MG, BA)"),
                  ano: z
                      .string()
                      .optional()
                      .describe("Ano com 4 dígitos (ex: 2026)"),
                  facultativos: z
                      .boolean()
                      .optional()
                      .describe("Se true, inclui feriados facultativos do estado"),
                  bancarios: z
                      .boolean()
                      .optional()
                      .describe("Se true, retorna apenas feriados bancários (calendário FEBRABAN)"),
              }),
          },
          async ({ uf, ano, facultativos, bancarios }) => {
              try {
                  const data = await feriadosApi<{
                      uf: string;
                      feriados: unknown[];
                      meta: unknown;
                  }>({
                      path: `/feriados/estado/${uf.toUpperCase()}`,
                      params: {
                          ano,
                          facultativos: facultativos ? "true" : undefined,
                          bancarios: bancarios ? "true" : undefined,
                      },
                  });
  
                  let header = `📍 Feriados — ${data.uf}`;
                  if (ano) header += ` — ${ano}`;
  
                  const text =
                      header +
                      "\n\n" +
                      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/tools/feriados.ts:172-189 (schema)

  Input schema definition for 'feriados_por_estado' using Zod: requires 'uf' (2-letter string), optional 'ano', 'facultativos', 'bancarios'.

  inputSchema: z.object({
      uf: z
          .string()
          .length(2)
          .describe("Sigla do estado em maiúsculas (ex: SP, RJ, MG, BA)"),
      ano: z
          .string()
          .optional()
          .describe("Ano com 4 dígitos (ex: 2026)"),
      facultativos: z
          .boolean()
          .optional()
          .describe("Se true, inclui feriados facultativos do estado"),
      bancarios: z
          .boolean()
          .optional()
          .describe("Se true, retorna apenas feriados bancários (calendário FEBRABAN)"),
  }),

• lib/tools/feriados.ts:191-227 (handler)

  Handler function that calls feriadosApi at path /feriados/estado/{uf}, formats the response with header, holiday list, and metadata.

      async ({ uf, ano, facultativos, bancarios }) => {
          try {
              const data = await feriadosApi<{
                  uf: string;
                  feriados: unknown[];
                  meta: unknown;
              }>({
                  path: `/feriados/estado/${uf.toUpperCase()}`,
                  params: {
                      ano,
                      facultativos: facultativos ? "true" : undefined,
                      bancarios: bancarios ? "true" : undefined,
                  },
              });
  
              let header = `📍 Feriados — ${data.uf}`;
              if (ano) header += ` — ${ano}`;
  
              const text =
                  header +
                  "\n\n" +
                  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/api-client.ts:18-69 (helper)

  Generic API client (feriadosApi) used by the handler to make HTTP requests to the Feriados API.

  export async function feriadosApi<T>(options: ApiRequestOptions): Promise<T> {
      const apiKey = options.apiKey || process.env.FERIADOS_API_KEY;
  
      if (!apiKey) {
          throw new Error(
              "API Key não fornecida. Passe sua chave via parâmetro apiKey na URL ou configure FERIADOS_API_KEY. Obtenha uma gratuita em https://feriadosapi.com/dashboard"
          );
      }
  
      const url = new URL(`${BASE_URL}/api/v1${options.path}`);
  
      // Adiciona query params (ignora undefined)
      if (options.params) {
          Object.entries(options.params).forEach(([key, value]) => {
              if (value !== undefined) {
                  url.searchParams.set(key, value);
              }
          });
      }
  
      const response = await fetch(url.toString(), {
          headers: {
              "X-API-Key": apiKey,
              "Content-Type": "application/json",
          },
      });
  
      if (!response.ok) {
          const errorBody = await response.json().catch(() => ({}));
          const errorMessage =
              errorBody.error || errorBody.message || response.statusText;
  
          switch (response.status) {
              case 401:
                  throw new Error(
                      "API Key inválida ou ausente. Verifique sua chave em https://feriadosapi.com/dashboard"
                  );
              case 403:
                  throw new Error(`Acesso negado: ${errorMessage}`);
              case 429:
                  throw new Error(
                      "Limite de requisições excedido. Plano Gratuito: 60 req/min. Para aumentar o limite, faça upgrade em https://feriadosapi.com/dashboard"
                  );
              case 404:
                  throw new Error(`Recurso não encontrado: ${errorMessage}`);
              default:
                  throw new Error(`Erro na API (${response.status}): ${errorMessage}`);
          }
      }
  
      return response.json() as Promise<T>;
  }

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

  Helper function formatHolidayList used to format the holiday list for display.

  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");
  }