Taiwan Holiday

Proporciona información sobre los días festivos nacionales de Taiwán y los días laborables compensatorios. Los datos se obtienen y almacenan en caché automáticamente.

GitHub
27

Documentación

Servidor MCP de Taiwan Holiday

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

Un servidor de consulta de días festivos de Taiwán basado en el Model Context Protocol (MCP), que proporciona información precisa sobre días festivos nacionales y días de trabajo compensatorio de Taiwán.

✨ Características

  • 🇹🇼 Datos precisos de días festivos de Taiwán: Basado en la información oficial de días festivos proporcionada por TaiwanCalendar
  • 🚀 Consulta en tiempo real: Compatible con consultas de un solo día, consultas por rango y consultas estadísticas
  • 📅 Múltiples formatos de fecha: Compatible con formatos YYYY-MM-DD y YYYYMMDD
  • 🔄 Caché inteligente: Caché automática de datos para mejorar el rendimiento de las consultas
  • 🛠️ Estándar MCP: Totalmente compatible con la especificación del Model Context Protocol
  • 🎯 Amigable con IA: Diseñado específicamente para herramientas de IA como Claude Desktop y Cursor
  • 📊 Estadísticas enriquecidas: Proporciona funciones de estadísticas y análisis de días festivos
  • 🌐 Multiplataforma: Compatible con Windows, macOS y Linux

🚀 Inicio rápido

Uso directo con NPX (recomendado)

La forma más sencilla de uso, sin necesidad de instalación:

npx taiwan-holiday-mcp

Instalación local

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

Instalación en entorno de desarrollo

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

🔧 Configuración del cliente

Configuración de Claude Desktop

Añade lo siguiente en el archivo de configuración de Claude Desktop:

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

Ubicación del archivo de configuración:

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

Configuración de Cursor

Haz clic en el siguiente botón para instalar directamente.

Install MCP Server

Configuración de Windsurf

Añade lo siguiente en el archivo .cursorrules del proyecto o en el archivo de configuración:

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

📖 Ejemplos de uso

Después de la instalación, puedes conversar directamente con la IA en Claude Desktop usando lenguaje natural para consultar sobre días festivos de Taiwán:

Consultas básicas

Puedes preguntar así:

"¿El 10 de octubre de 2025 es día festivo?"

"Ayúdame a consultar qué días festivos hay en enero de 2025"

"¿Cuántos días festivos hay en total en 2025?"

Claude llamará automáticamente a las herramientas correspondientes y responderá:

  • ✅ El 10 de octubre de 2025 es el Día Nacional, es día festivo
  • 📅 Enero de 2025 tiene 14 días festivos en total, incluido el feriado del Año Nuevo Chino
  • 📊 2025 tiene 115 días festivos en total

Ejemplos de conversación práctica

🏖️ Planificación de vacaciones

Tú: "Quiero planificar un viaje para el primer trimestre de 2025, ayúdame a encontrar qué feriados largos puedo aprovechar"

Claude: Consultará automáticamente los días festivos de enero a marzo, analizará los feriados consecutivos y te dirá:

  • Feriado del Año Nuevo Chino: 27-31 de enero (5 días)
  • Feriado del 228: 28 de febrero - 2 de marzo (3 días)
  • Sugerencias para otros fines de semana

💼 Planificación laboral

Tú: "¿Necesito trabajar el próximo lunes (6 de octubre de 2025)?"

Claude: Verificará esa fecha y responderá si es día laborable; si es día festivo, también explicará el motivo.

📈 Estadísticas de días festivos

Tú: "¿Cuántos días festivos hay en octubre de 2025? ¿Hay algún día festivo importante?"

Claude: Proporcionará las estadísticas de días festivos de ese mes, incluidos los días festivos nacionales y la información de celebraciones importantes.

Aplicaciones avanzadas

🎯 Análisis inteligente de días festivos

Tú: "Ayúdame a analizar qué mes de 2025 es el mejor para tomar vacaciones"

Claude: Analizará la distribución de días festivos en cada mes, considerando la duración y frecuencia de los feriados consecutivos, y dará la mejor recomendación.

📅 Planificación anual de vacaciones

Tú: "Quiero ver todos los feriados largos de 2025, ayúdame a organizar una lista"

Claude: Encontrará automáticamente todos los feriados consecutivos de más de 3 días y los organizará en una lista por orden cronológico.

🛠️ Documentación de la API

Herramientas MCP

check_holiday

Verifica si una fecha específica es día festivo en Taiwán.

Parámetros:

  • date (string): Fecha, en formato YYYY-MM-DD o YYYYMMDD

Retorno:

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

get_holidays_in_range

Obtiene todos los días festivos de Taiwán dentro de un rango de fechas específico.

Parámetros:

  • start_date (string): Fecha de inicio
  • end_date (string): Fecha de fin

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

Obtiene información estadística de días festivos de Taiwán para un año o año-mes específico.

Parámetros:

  • year (number): Año, desde 2017 (los años realmente consultables dependen de los datos de la fuente)
  • month (number, opcional): Mes (1-12)

Retorno:

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

Recursos MCP

El servidor proporciona los siguientes recursos:

  • taiwan-holidays://years - Lista de años compatibles
  • taiwan-holidays://holidays/{year} - Datos completos de días festivos para un año específico
  • taiwan-holidays://stats/{year} - Información estadística para un año específico

🔍 Solución de problemas

Problemas comunes

1. No se puede conectar al servidor

Problema: Claude Desktop muestra "No se puede conectar al servidor MCP"

Solución:

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

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

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

2. Error de formato de fecha

Problema: Se recibe el error "Formato de fecha no válido"

Solución:

  • Asegúrate de usar el formato correcto: YYYY-MM-DD o YYYYMMDD
  • Verifica que la fecha sea válida (por ejemplo: 2025-02-30 es una fecha no válida)

3. Problemas de conexión de red

Problema: No se pueden obtener los datos de días festivos

Solución:

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

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

Modo de depuración

Activa los registros detallados:

taiwan-holiday-mcp --debug

Ajuste de rendimiento

Si las consultas son lentas:

  1. Verifica la conexión de red
  2. Confirma que el mecanismo de caché funciona correctamente
  3. Considera usar una fuente de datos local

🧪 Desarrollo y pruebas

Para instrucciones detalladas de desarrollo, consulta DEVELOPMENT.md.

Desarrollo 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 pruebas

npm run test:coverage

Cobertura de pruebas actual: 92.27% (446 casos de prueba, 100% aprobados)

Cobertura de módulos principales:

  • SmartCache: 98.97% ✅
  • HealthMonitor: 98.78% ✅
  • DateParser: 97.77% ✅
  • CircuitBreaker: 100% ✅
  • GracefulShutdown: 88.34% ✅

📊 Métricas de rendimiento

  • Primera llamada a la API: < 2 segundos
  • Llamadas a la API con caché: < 100ms
  • Procesamiento concurrente: Compatible con 10+ solicitudes concurrentes
  • Uso de memoria: < 50MB
  • Estabilidad de pruebas: 100% de tasa de aprobación, estándar de calidad empresarial
  • Cobertura de código: 92.34% (muy por encima del estándar de la industria del 80%)

🤝 Guía de contribución

¡Las contribuciones son bienvenidas! Sigue estos pasos:

  1. Haz un fork del proyecto
  2. Crea una rama de funcionalidad (git checkout -b feature/amazing-feature)
  3. Realiza los cambios (git commit -m 'Add amazing feature')
  4. Haz push a la rama (git push origin feature/amazing-feature)
  5. Abre un Pull Request

⚠️ Aviso legal

Fuente de datos y precisión

Los datos de días festivos de Taiwán de este proyecto provienen del proyecto de código abierto TaiwanCalendar, que se basa en la información oficial de días festivos anunciada por el gobierno de la República de China.

Declaración importante:

  1. Precisión de los datos: Aunque nos esforzamos por garantizar la precisión de los datos, este proyecto no garantiza que la información de días festivos proporcionada sea completamente correcta o esté actualizada en tiempo real.
  2. Datos oficiales: Para obtener la información más precisa sobre días festivos, consulta los anuncios oficiales de los departamentos gubernamentales correspondientes de la República de China.
  3. Actualización de datos: Los datos de días festivos pueden cambiar debido a ajustes en las políticas gubernamentales. Este proyecto hará todo lo posible por mantenerse actualizado, pero puede haber retrasos.
  4. Responsabilidad del usuario: Los usuarios deben verificar por sí mismos el estado de los días festivos para fechas importantes, especialmente cuando se utilizan con fines comerciales o legales.

Disponibilidad del servicio

  • Este servicio depende de fuentes de datos externas y puede no estar disponible temporalmente debido a problemas de red o anomalías en las fuentes de datos
  • No garantizamos una disponibilidad del 100% ni tiempos de respuesta específicos
  • Se recomienda implementar mecanismos adecuados de manejo de errores y respaldo en aplicaciones críticas

Limitación de responsabilidad

En la máxima medida permitida por la ley, los autores y colaboradores de este proyecto no serán responsables de ningún daño directo, indirecto, incidental, especial o consecuente que surja del uso de este software.

🔗 Proyectos relacionados

  • taiwan-holiday-cli —— Herramienta de línea de comandos con la misma fuente de datos, adecuada para terminales y scripts
  • taiwan-holiday-skills —— Skill empaquetado para Claude Agent (funciona mediante llamadas CLI en segundo plano)

Los tres proyectos comparten el número de versión MAJOR, actualmente en la generación 2.x.

📄 Términos de licencia

Este proyecto está bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.

🙏 Agradecimientos

📞 Soporte

Años compatibles: Desde 2017, el límite superior sigue a los datos de la fuente (los nuevos años se admiten automáticamente cuando se publican)
MCP SDK: @modelcontextprotocol/sdk ^1.13.0
Requisito de Node.js: ≥ 18.0.0
Estado de calidad: Listo para producción a nivel empresarial ✅