Taiwan Holiday

Fornece informações sobre feriados nacionais de Taiwan e dias úteis compensatórios. Os dados são obtidos e armazenados em cache automaticamente.

GitHub
27
Experimente este MCPPatrocinado

Documentação

Taiwan Holiday MCP Server

Node.js Version npm version License: MIT Install MCP Server

Um servidor de consulta de feriados de Taiwan baseado no Model Context Protocol (MCP), fornecendo informações precisas sobre feriados nacionais e dias de compensação de Taiwan.

✨ Recursos

  • 🇹🇼 Dados precisos de feriados de Taiwan: baseado nas informações de feriados oficiais divulgadas pelo governo, fornecidas pelo TaiwanCalendar
  • 🚀 Consulta em tempo real: suporte a consulta de dia único, consulta por intervalo e consulta estatística
  • 📅 Múltiplos formatos de data: suporte aos formatos YYYY-MM-DD e YYYYMMDD
  • 🔄 Cache inteligente: cache automático de dados para melhorar o desempenho das consultas
  • 🛠️ Padrão MCP: totalmente compatível com a especificação do Model Context Protocol
  • 🎯 Amigável para IA: projetado para ferramentas de IA como Claude Desktop, Cursor, entre outras
  • 📊 Estatísticas completas: fornece funções de estatísticas e análise de feriados
  • 🌐 Multiplataforma: suporte a Windows, macOS e Linux

🚀 Início Rápido

Uso direto via NPX (recomendado)

A maneira mais simples de usar, sem necessidade de instalação:

npx taiwan-holiday-mcp

Instalação local

npm install -g taiwan-holiday-mcp
taiwan-holiday-mcp

Instalação em ambiente de desenvolvimento

git clone https://github.com/lis186/taiwan-holiday-mcp.git
cd taiwan-holiday-mcp
npm install
npm run build
npm start

🔧 Configuração do Cliente

Configuração do Claude Desktop

Adicione no arquivo de configuração do Claude Desktop:

{
  "mcpServers": {
    "taiwan-holiday": {
      "command": "npx",
      "args": ["taiwan-holiday-mcp"]
    }
  }
}

Localização do arquivo de configuração:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuração do Cursor

Clique no botão abaixo para instalar diretamente.

Install MCP Server

Configuração do Windsurf

Adicione no .cursorrules do projeto ou no arquivo de configuração:

{
  "mcp": {
    "servers": {
      "taiwan-holiday": {
        "command": "npx",
        "args": ["taiwan-holiday-mcp"]
      }
    }
  }
}

📖 Exemplos de Uso

Após a instalação, você pode conversar diretamente com a IA em linguagem natural no Claude Desktop para perguntar sobre feriados de Taiwan:

Consultas Básicas

Você pode perguntar assim:

"O dia 10 de outubro de 2025 é feriado?"

"Me ajude a verificar quais feriados existem em janeiro de 2025"

"Quantos feriados existem no total em 2025?"

O Claude chamará automaticamente as ferramentas correspondentes e responderá:

  • ✅ 10 de outubro de 2025 é o Dia Nacional, é feriado
  • 📅 Janeiro de 2025 tem 14 feriados no total, incluindo o feriado prolongado do Ano Novo Chinês
  • 📊 2025 tem 115 feriados no total

Exemplos de Conversas Úteis

🏖️ Planejamento de Feriados

Você: "Quero planejar uma viagem no primeiro trimestre de 2025, me ajude a encontrar quais feriados prolongados posso aproveitar?"

Claude: Consultará automaticamente os feriados de janeiro a março, analisará os feriados prolongados e informará:

  • Feriado prolongado do Ano Novo Chinês: 27 a 31 de janeiro (5 dias)
  • Feriado prolongado do 228: 28 de fevereiro a 2 de março (3 dias)
  • Sugestões de outros feriados de fim de semana

💼 Planejamento de Trabalho

Você: "Preciso trabalhar na próxima segunda-feira (6 de outubro de 2025)?"

Claude: Verificará a data e responderá se é um dia útil; se for feriado, também explicará o motivo.

📈 Estatísticas de Feriados

Você: "Quantos feriados existem em outubro de 2025? Há alguma data importante?"

Claude: Fornecerá as estatísticas de feriados do mês, incluindo feriados nacionais e informações sobre datas comemorativas importantes.

Aplicações Avançadas

🎯 Análise Inteligente de Feriados

Você: "Me ajude a analisar qual mês de 2025 é o melhor para tirar folga e viajar?"

Claude: Analisará a distribuição de feriados em cada mês, considerando a duração e a frequência dos feriados prolongados, e dará a melhor recomendação.

📅 Planejamento Anual de Feriados

Você: "Quero ver todos os feriados prolongados de 2025, me ajude a organizar uma lista"

Claude: Encontrará automaticamente todos os feriados prolongados com mais de 3 dias e os organizará em uma lista em ordem cronológica.

🛠️ Documentação da API

Ferramentas MCP

check_holiday

Verifica se uma data específica é feriado em Taiwan.

Parâmetros:

  • date (string): data, no formato YYYY-MM-DD ou YYYYMMDD

Retorno:

{
  "success": true,
  "data": {
    "date": "2025-10-10",
    "isHoliday": true,
    "description": "國慶日",
    "week": "五",
    "normalizedDate": "20251010"
  }
}

get_holidays_in_range

Obtém todos os feriados de Taiwan dentro de um intervalo de datas especificado.

Parâmetros:

  • start_date (string): data de início
  • end_date (string): data de término

Retorno:

{
  "success": true,
  "data": {
    "startDate": "2025-01-01",
    "endDate": "2025-01-31",
    "holidays": [...],
    "totalCount": 14,
    "summary": "在 2025-01-01 到 2025-01-31 期間共有 14 個假期"
  }
}

get_holiday_stats

Obtém informações estatísticas de feriados de Taiwan para um ano ou mês específico.

Parâmetros:

  • year (number): ano, a partir de 2017 (os anos realmente disponíveis dependem dos dados de origem)
  • month (number, opcional): mês (1-12)

Retorno:

{
  "success": true,
  "data": {
    "year": 2025,
    "statistics": {
      "year": 2025,
      "totalHolidays": 115,
      "nationalHolidays": 113,
      "compensatoryDays": 2,
      "holidayTypes": {...}
    },
    "summary": "2025 年共有 115 個假期"
  }
}

Recursos MCP

O servidor fornece os seguintes recursos:

  • taiwan-holidays://years - lista de anos suportados
  • taiwan-holidays://holidays/{year} - dados completos de feriados para um ano específico
  • taiwan-holidays://stats/{year} - informações estatísticas para um ano específico

🔍 Solução de Problemas

Problemas Comuns

1. Não é possível conectar ao servidor

Problema: o Claude Desktop exibe "Não foi possível conectar ao servidor MCP"

Solução:

# 檢查 Node.js 版本（需要 18+）
node --version

# 重新安裝套件
npm uninstall -g taiwan-holiday-mcp
npm install -g taiwan-holiday-mcp

# 測試伺服器
taiwan-holiday-mcp --version

2. Erro de formato de data

Problema: erro "Formato de data inválido"

Solução:

  • Certifique-se de usar o formato correto: YYYY-MM-DD ou YYYYMMDD
  • Verifique se a data é válida (por exemplo: 2025-02-30 é uma data inválida)

3. Problemas de conexão de rede

Problema: não é possível obter dados de feriados

Solução:

# 檢查網路連接
curl -I https://cdn.jsdelivr.net/gh/ruyut/TaiwanCalendar/data/2025.json

# 清除快取（如果有問題）
rm -rf ~/.taiwan-holiday-mcp-cache

Modo de Depuração

Ative os logs detalhados:

taiwan-holiday-mcp --debug

Ajuste de Desempenho

Se as consultas estiverem lentas:

  1. Verifique a conexão de rede
  2. Confirme se o mecanismo de cache está funcionando corretamente
  3. Considere usar uma fonte de dados local

🧪 Desenvolvimento e Testes

Consulte DEVELOPMENT.md para instruções detalhadas de desenvolvimento.

Desenvolvimento Local

# 複製專案
git clone https://github.com/lis186/taiwan-holiday-mcp.git
cd taiwan-holiday-mcp

# 安裝依賴
npm install

# 執行測試
npm test

# 建置專案
npm run build

# 啟動開發模式
npm run dev

Cobertura de Testes

npm run test:coverage

Cobertura de testes atual: 92,27% (446 casos de teste, 100% aprovados)

Cobertura dos módulos principais:

  • SmartCache: 98,97% ✅
  • HealthMonitor: 98,78% ✅
  • DateParser: 97,77% ✅
  • CircuitBreaker: 100% ✅
  • GracefulShutdown: 88,34% ✅

📊 Métricas de Desempenho

  • Primeira chamada de API: < 2 segundos
  • Chamada de API com cache: < 100ms
  • Processamento concorrente: suporte a 10+ solicitações simultâneas
  • Uso de memória: < 50MB
  • Estabilidade dos testes: 100% de taxa de aprovação, padrão de qualidade empresarial
  • Cobertura de código: 92,34% (muito acima do padrão de 80% do setor)

🤝 Guia de Contribuição

Contribuições são bem-vindas! Siga os passos abaixo:

  1. Faça um fork do projeto
  2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
  3. Faça commit das alterações (git commit -m 'Add amazing feature')
  4. Envie para o branch (git push origin feature/amazing-feature)
  5. Abra um Pull Request

⚠️ Aviso Legal

Fonte de Dados e Precisão

Os dados de feriados de Taiwan deste projeto são originados do projeto de código aberto TaiwanCalendar, que se baseia nas informações oficiais de feriados divulgadas pelo governo da República da China (Taiwan).

Declaração importante:

  1. Precisão dos dados: embora nos esforcemos para garantir a precisão dos dados, este projeto não garante que as informações de feriados fornecidas estejam totalmente corretas ou atualizadas em tempo real.
  2. Dados oficiais: para obter as informações mais precisas sobre feriados, consulte os anúncios oficiais dos departamentos relevantes do governo da República da China (Taiwan).
  3. Atualização de dados: os dados de feriados podem mudar devido a ajustes nas políticas governamentais; este projeto fará o possível para acompanhar as atualizações, mas pode haver atrasos.
  4. Responsabilidade de uso: os usuários devem verificar por conta própria o status de feriados em datas importantes, especialmente para fins comerciais ou legais.

Disponibilidade do Serviço

  • Este serviço depende de fontes de dados externas e pode ficar temporariamente indisponível devido a problemas de rede ou anomalias na fonte de dados
  • Não garantimos 100% de disponibilidade do serviço ou tempos de resposta
  • Recomenda-se implementar tratamento de erros e mecanismos de redundância adequados em aplicações críticas

Limitação de Responsabilidade

Na máxima extensão permitida por lei, os autores e contribuidores deste projeto não serão responsáveis por quaisquer danos diretos, indiretos, incidentais, especiais ou consequenciais decorrentes do uso deste software.

🔗 Projetos Relacionados

  • taiwan-holiday-cli — ferramenta de linha de comando com a mesma fonte de dados, adequada para terminais e scripts
  • taiwan-holiday-skills — Claude Agent Skill empacotado (chamado internamente via CLI)

Os três projetos compartilham o mesmo número de versão MAJOR, atualmente na geração 2.x.

📄 Termos de Licença

Este projeto é licenciado sob a licença MIT. Consulte o arquivo LICENSE para mais detalhes.

🙏 Agradecimentos

📞 Suporte

Anos suportados: a partir de 2017, o limite superior segue os dados de origem (novos anos são suportados automaticamente quando publicados)
MCP SDK: @modelcontextprotocol/sdk ^1.13.0
Requisito Node.js: ≥ 18.0.0
Status de qualidade: pronto para produção em nível empresarial ✅