MCP de días festivos de Corea

URL del conector: https://korea-holiday-mcp.vercel.app/api/mcp Página de presentación: https://korea-holiday-mcp.vercel.app

Es un servidor MCP que procesa con precisión el cálculo de días festivos, días festivos sustitutivos y días laborables de Corea con solo registrar una URL en Claude. Al ser un conector público sin autenticación, no requiere instalación, inicio de sesión ni clave de API.

Por qué es necesario

Los LLM son débiles en aritmética de fechas. Los días festivos de Corea combinan festividades del calendario lunar (Seollal, Chuseok y el cumpleaños de Buda) y reglas de días festivos sustitutivos, por lo que los modelos tienden a dar respuestas erróneas pero plausibles. Puntos donde fallan con frecuencia:

• El Día de los Caídos no tiene día festivo sustitutivo. El 6 de junio de 2027 es domingo, pero el 7 de junio es un día laborable normal. El Día de los Caídos no es una fiesta nacional, por lo que no está sujeto al artículo 3 del «Reglamento sobre los días festivos de las oficinas públicas».

• Seollal y Chuseok solo generan día festivo sustitutivo cuando coinciden con domingo. Aunque coincidan con sábado, no se añade ningún día.

• El Día de la Constitución vuelve a ser festivo a partir de 2026. Es su regreso 18 años después de su exclusión en 2008, por lo que apenas aparece en los datos de entrenamiento.

Este servidor no memoriza tablas de fechas, sino que implementa la legislación en código, por lo que siempre da la misma respuesta de forma determinista.

Cómo conectarse

Claude Web · aplicación de escritorio

1. Ve a Configuración → Conectores

2. Haz clic en Añadir conector personalizado

3. Introduce el nombre 한국 공휴일 y la URL https://korea-holiday-mcp.vercel.app/api/mcp

4. Actívalo en el menú de herramientas de la ventana de chat

Al ser un servidor público sin autenticación, no aparece ningún paso de inicio de sesión. Si lo registras como conector para administradores de organización, puede aparecer una pantalla que espera OAuth, así que añádelo como conector personal.

Claude Code

claude mcp add --transport http korea-holiday https://korea-holiday-mcp.vercel.app/api/mcp

Al escribir el archivo de configuración manualmente

{
  "mcpServers": {
    "korea-holiday": {
      "type": "http",
      "url": "https://korea-holiday-mcp.vercel.app/api/mcp"
    }
  }
}

Herramientas

Opciones comunes:

• includeLaborDay (por defecto false) — si se calcula el Día del Trabajador (1/5) como festivo. El Día del Trabajador no es un día festivo de oficinas públicas, sino un día retribuido según la Ley de Normas Laborales, por lo que por defecto se considera día laborable.

• saturdayIsBusinessDay (por defecto false) — si se calcula el sábado como día laborable.

Fundamento de los datos y limitaciones

Legislación de referencia: artículo 2 (días festivos) y artículo 3 (días festivos sustitutivos) del «Reglamento sobre los días festivos de las oficinas públicas»

Las reglas de días festivos sustitutivos se aplican de forma distinta según el año, reflejando su fecha de entrada en vigor.

Rango de consulta: 2015~2050. Como los datos del calendario lunar solo llegan hasta 2050, a partir de esa fecha se devuelve un error.

Lo que no incluye

• Aniversarios de fundación por empresa, días de cierre por sector

• Días festivos temporales y días de elecciones futuros no confirmados

Los días festivos temporales y los días de elecciones no se pueden predecir mediante reglas, por lo que solo se registran manualmente en lib/overrides.ts aquellos que han sido confirmados y publicados oficialmente. Cuando se designe uno nuevo, basta con añadir una línea y ejecutar npm run verify.

Posibles diferencias con los sitios de calendarios privados

Algunos sitios que recopilan días festivos muestran el 7 de junio como día festivo sustitutivo del Día de los Caídos del 6 de junio de 2027 (domingo). Este servidor, siguiendo la legislación, calcula que no hay día festivo sustitutivo. Cuando el Ministerio de Gestión de Personal revisó la norma en 2021, el Año Nuevo y el Día de los Caídos quedaron explícitamente excluidos de los días festivos sustitutivos, y la revisión de 2023 solo añadió el Cumpleaños de Buda y la Navidad. De hecho, el 6 de junio de 2021 (domingo) tampoco tuvo día festivo sustitutivo.

Para decisiones importantes, verifica una vez más en el Boletín Oficial o en los anuncios del Ministerio de Gestión de Personal. Si encuentras algún error en los resultados, repórtalo como issue.

Verificación

Los resultados del motor de reglas se contrastan con fuentes públicas (2024~2027).

npm run verify

También se comprueba que los resultados sean los mismos independientemente de la zona horaria. Todas las operaciones de fechas se procesan únicamente con referencia a la medianoche UTC, y el "hoy" se calcula en KST.

Desarrollo

npm install
npm run dev        # http://localhost:3000
npm run verify     # 공휴일 규칙 검증
npm run typecheck
npm run build

También puedes probar las herramientas directamente con MCP Inspector.

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP / URL: http://localhost:3000/api/mcp

Estructura

app/
  api/mcp/route.ts   MCP 서버 (도구 6개 등록)
  page.tsx           랜딩 + 연결 가이드
lib/
  date.ts            타임존 안전 날짜 유틸
  holidays.ts        공휴일 규칙 엔진 (법령 구현)
  overrides.ts       임시공휴일·선거일 수동 테이블
  format.ts          응답 텍스트 포맷터
scripts/
  verify.ts          공개 자료 대조 검증

Despliegue

Si conectas este repositorio a Vercel, se desplegará tal cual. No se necesitan variables de entorno. La URL del conector es la dirección del dominio de despliegue seguida de /api/mcp, y la página de aterrizaje lee su propio dominio para mostrar automáticamente la URL correcta.

Privacidad

Solo recibe cadenas de fecha y devuelve el resultado del cálculo. No almacena ni envía datos de los usuarios a terceros.

Licencia

MIT