Brazil Holidays & Business Days MCP (Feriados e Dias Úteis) MCP Server

Consulta os feriados nacionais e estaduais válidos para uma Unidade Federativa (UF) brasileira em determinado ano, excluindo feriados estritamente municipais. QUANDO UTILIZAR ESTA FERRAMENTA: - Quando o agente precisa avaliar calendários estaduais amplos (ex: malha rodoviária estadual, recessos de órgãos estaduais como SEFAZ/Tribunais de Justiça Estaduais) ou quando o município específico de destino ainda não foi definido. - ATENÇÃO: Para liquidação de títulos (boletos) ou SLA de entrega Last-Mile em uma cidade específica, prefira SEMPRE `consultar_feriados_municipio`, pois feriados municipais (como aniversário da cidade ou padroeiro) também suspendem o expediente bancário local. Args: estado: Sigla da Unidade Federativa (UF) com 2 letras (ex: "SP", "RJ", "MG", "BA", "TO"). ano: Ano de referência com 4 dígitos (ex: 2026). Returns: Dicionário contendo a lista de feriados nacionais e estaduais da UF informada.

Consulta todos os feriados (nacionais, estaduais e municipais), pontos facultativos e dias comemorativos vigentes em um município brasileiro específico para um determinado ano. CONTEXTO JURÍDICO E OPERACIONAL PARA O AGENTE (BRASIL): No Brasil, a paralisação de atividades bancárias, comerciais e logísticas depende de três esferas cumulativas de feriados que esta ferramenta consolida automaticamente: 1. Feriados Nacionais (Lei Federal nº 662/1949 e Lei nº 6.802/1980): Válidos em todo o território nacional (ex: 01/01 Confraternização Universal, Tiradentes, Independência, Dia da Consciência Negra, Natal). Bancos, B3 e repartições públicas fecham obrigatoriamente. 2. Feriados Estaduais (Lei Federal nº 9.093/1995, art. 1º, II): Data magna de cada Unidade Federativa (ex: 09/07 Revolução Constitucionalista em SP; 23/04 São Jorge no RJ). Paralisa operações bancárias e prazos em todas as cidades daquele estado. 3. Feriados Municipais (Lei Federal nº 9.093/1995, art. 1º, III e art. 2º): Aniversário da cidade, padroeiro local e Sexta-Feira da Paixão (até 4 feriados religiosos municipais). Ex: 25/01 (Aniversário de São Paulo). Um boleto pagável em uma praça com feriado municipal tem seu vencimento prorrogado, e entregas locais sofrem restrição operacional. CLASSIFICAÇÃO DO CAMPO `tipo` RETORNADO: - "feriado": Feriado oficial (civil ou religioso) previsto em lei federal, estadual ou municipal. NÃO é dia útil bancário nem comercial padrão. - "facultativo": Ponto facultativo (ex: Segunda e Terça de Carnaval, Quarta-Feira de Cinzas, Corpus Christi, Dia do Servidor Público). Repartições públicas fecham; a FEBRABAN costuma suspender atendimento bancário no Carnaval e Corpus Christi, mas empresas privadas e transportadoras frequentemente operam normalmente. - "dia comemorativo": Data apenas histórica ou profissional (ex: Dia do Professor, Dia do Comerciário). É um DIA ÚTIL NORMAL, salvo convenção coletiva específica da categoria. Args: cidade: Nome do município brasileiro (pode conter ou não acentos, ex: "sao paulo", "São Paulo", "araguaina", "curitiba", "belo horizonte"). estado: Sigla da Unidade Federativa (UF) com 2 letras (ex: "SP", "RJ", "MG", "TO"). ano: Ano de referência com 4 dígitos (ex: 2026). Returns: Dicionário estruturado contendo metadados da localidade, resumo quantitativo por tipo e a lista cronológica de eventos no formato {"data": "DD/MM/YYYY", "feriado": "...", "tipo": "..."}.

Calcula a data final exata somando `dias_uteis` a partir de `data_inicial`, descontando automaticamente sábados, domingos e feriados vigentes na UF/município. CASOS DE USO CORPORATIVOS PARA AGENTES: 1. Logística, Frete e SLA de Entrega (E-commerce / Transportadoras): Calcular a data prometida de entrega (ETA) quando o prazo do frete é expresso em dias úteis (ex: "Entrega em 5 dias úteis para São Paulo/SP"). No setor logístico privado, pontos facultativos geralmente têm operação normal (`incluir_ponto_facultativo_como_nao_util=False`). 2. Prazos Contratuais, Jurídicos e Bancários (D+N): Liquidação em D+1, D+2 ou prazos administrativos onde pontos facultativos também suspendem a contagem (`incluir_ponto_facultativo_como_nao_util=True`). METODOLOGIA DE CONTAGEM: - Segue a regra padrão brasileira (Código Civil art. 132 / prazos D+N): exclui-se o dia do começo (`data_inicial`) e contam-se exatamente `dias_uteis` dias úteis completos seguintes. - Se `dias_uteis == 0`, retorna o próprio `data_inicial` caso seja útil, ou o próximo dia útil subsequente. Args: data_inicial: Data base de início da contagem ('YYYY-MM-DD' ou 'DD/MM/YYYY'). dias_uteis: Quantidade de dias úteis a adicionar (inteiro >= 0 e <= 365). estado: Sigla da UF com 2 letras (ex: 'SP', 'PR', 'TO'). cidade: (Opcional) Nome do município para descontar também feriados municipais locais. incluir_ponto_facultativo_como_nao_util: Se False (padrão logístico/comercial), apenas 'feriado' oficial suspende a contagem de dias úteis. Se True (padrão público/bancário), 'facultativo' também suspende a contagem. Returns: Dicionário contendo a data final em formato ISO e BR, total de dias corridos, quantidade de fins de semana e a lista nominal de feriados que impactaram o prazo.

Verifica de forma determinística se uma data específica é dia útil bancário/comercial em um município ou estado brasileiro e calcula a data efetiva de liquidação/vencimento (próximo dia útil subsequente, caso a data original caia em fim de semana ou feriado). CASOS DE USO CORPORATIVOS PARA AGENTES: 1. Vencimento de Boletos e Contas a Pagar (Lei nº 7.089/1983 e normas FEBRABAN/BACEN): Títulos de cobrança com vencimento em sábado, domingo ou feriado (nacional, estadual ou municipal da praça de pagamento) podem ser pagos no primeiro dia útil subsequente sem incidência de juros ou multa. 2. Liquidação Financeira (STR / TED / Câmbio / B3): Identificar se haverá compensação bancária na data consultada. 3. Corte de Folha de Pagamento (CLT, art. 459, § 1º): Verificar se o 5º dia útil ou data de pagamento salarial coincide com feriado local. REGRA SOBRE PONTOS FACULTATIVOS (`incluir_ponto_facultativo_como_nao_util`): - No sistema bancário brasileiro (FEBRABAN), datas classificadas como `facultativo` no calendário oficial (como Segunda e Terça-feira de Carnaval e Corpus Christi) NÃO têm compensação bancária tradicional (boletos prorrogam para o dia útil seguinte). Por isso, o padrão é `incluir_ponto_facultativo_como_nao_util=True`. - Caso o agente esteja avaliando comércio varejista ou operação privada que trabalha em pontos facultativos, defina `incluir_ponto_facultativo_como_nao_util=False`. Args: data_consulta: Data a ser verificada nos formatos 'YYYY-MM-DD' (ex: '2026-01-25') ou 'DD/MM/YYYY' (ex: '25/01/2026'). estado: Sigla da UF com 2 letras (ex: 'SP', 'RJ'). cidade: (Opcional, mas altamente recomendado) Nome do município para considerar também os feriados municipais da praça (ex: 'sao paulo'). Se omitido, avalia apenas feriados nacionais e estaduais da UF. incluir_ponto_facultativo_como_nao_util: Se True (padrão bancário), trata eventos do tipo 'facultativo' como dias não úteis. Se False, apenas 'feriado' oficial bloqueia o dia. Returns: Objeto detalhando se a data original é dia útil, o motivo de eventual bloqueio (sábado, domingo, feriado ou ponto facultativo), a data do próximo dia útil (`data_vencimento_efetivo`) e quantos dias corridos de prorrogação ocorreram.