# 한국 공휴일 MCP

**커넥터 URL**: `https://korea-holiday-mcp.vercel.app/api/mcp`
**소개 페이지**: https://korea-holiday-mcp.vercel.app

Claude에 URL 하나만 등록하면 **한국 공휴일·대체공휴일·영업일 계산**을 정확하게 처리하는 MCP 서버입니다.
인증이 없는 공개 커넥터라서 설치·로그인·API 키가 필요 없습니다.

## 왜 필요한가

LLM은 날짜 산수에 약합니다. 한국 공휴일은 **음력 명절**(설날·추석·부처님오신날)과 **대체공휴일 규칙**이
얽혀 있어서 모델이 그럴듯한 오답을 내기 쉽습니다. 실제로 자주 틀리는 지점:

- **현충일은 대체공휴일이 없습니다.** 2027년 6월 6일은 일요일이지만 6월 7일은 정상 근무일입니다.
  현충일은 국경일이 아니라서 「관공서의 공휴일에 관한 규정」 제3조 적용 대상이 아닙니다.
- **설날·추석은 일요일과 겹칠 때만** 대체공휴일이 생깁니다. 토요일과 겹쳐도 늘어나지 않습니다.
- **제헌절이 2026년부터 다시 공휴일**입니다. 2008년 제외 후 18년 만의 복귀라 학습 데이터에 거의 없습니다.

이 서버는 날짜 표를 외워둔 게 아니라 **법령을 코드로 구현**해서, 매번 결정적으로 같은 답을 냅니다.

## 연결 방법

### Claude 웹 · 데스크톱 앱

1. **설정 → 커넥터**로 이동
2. **커스텀 커넥터 추가** 클릭
3. 이름 `한국 공휴일`, URL에 `https://korea-holiday-mcp.vercel.app/api/mcp` 입력
4. 대화창의 도구 메뉴에서 켜기

인증이 없는 공개 서버라 로그인 단계가 나오지 않습니다.
조직 관리자용 커넥터로 등록하면 OAuth를 기대하는 화면이 나올 수 있으니 개인 커넥터로 추가하세요.

### Claude Code

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

### 설정 파일을 직접 쓸 때

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

## 도구

| 도구 | 하는 일 | 이렇게 물어보면 됩니다 |
|------|---------|----------------------|
| `check_holiday` | 특정 날짜가 공휴일·영업일인지 확인 | "2026년 2월 17일 쉬는 날이야?" |
| `list_holidays` | 연도·월별 공휴일 전체 목록 | "2027년 공휴일 다 알려줘" |
| `next_holidays` | 다가오는 공휴일과 남은 일수 | "다음 공휴일 언제야?" |
| `count_business_days` | 두 날짜 사이 영업일 수 | "9월 1일부터 10월 15일까지 영업일 며칠?" |
| `add_business_days` | 기준일 + N영업일 날짜 | "오늘부터 7영업일 뒤가 며칠이야?" |
| `list_long_weekends` | 연휴 구간과 길이 | "2027년 3일 이상 연휴 정리해줘" |

공통 옵션:

- `includeLaborDay` (기본 `false`) — 근로자의 날(5/1)을 휴일로 계산할지.
  근로자의 날은 관공서 공휴일이 아니라 근로기준법상 유급휴일이라 기본값에서는 영업일로 봅니다.
- `saturdayIsBusinessDay` (기본 `false`) — 토요일을 영업일로 계산할지.

## 데이터 근거와 한계

**근거 법령**: 「관공서의 공휴일에 관한 규정」 제2조(공휴일)·제3조(대체공휴일)

대체공휴일 규칙은 시행일을 반영해서 연도별로 다르게 적용됩니다.

| 대상 | 발동 조건 | 적용 시작 |
|------|-----------|-----------|
| 설날·추석 연휴 | 연휴 중 **일요일**과 겹치는 날 수만큼 | 2014년 |
| 어린이날 | 토요일 또는 다른 공휴일과 겹칠 때 | 2014년 |
| 광복절·개천절·한글날 | 토요일 또는 일요일과 겹칠 때 | 2021년 |
| 삼일절 | 토요일 또는 일요일과 겹칠 때 | 2022년 |
| 부처님오신날·성탄절 | 토요일 또는 일요일과 겹칠 때 | 2023년 |
| 제헌절 | 토요일 또는 일요일과 겹칠 때 | 2026년 (공휴일 재지정) |
| 신정·현충일 | **없음** | — |

**조회 범위**: 2015~2050년. 음력 데이터가 2050년까지만 있어서 그 이후는 오류를 반환합니다.

**포함하지 않는 것**

- 회사별 창립기념일, 업종별 휴무일
- 확정되지 않은 미래의 임시공휴일·선거일

**임시공휴일과 선거일**은 규칙으로 예측할 수 없어 확정·공포된 것만 [`lib/overrides.ts`](lib/overrides.ts)에
수동 등재합니다. 새로 지정되면 한 줄 추가하고 `npm run verify`를 돌리면 됩니다.

**민간 달력 사이트와 다를 수 있는 지점**

일부 공휴일 정리 사이트는 2027년 6월 6일(일) 현충일에 대해 6월 7일을 대체공휴일로 표시합니다.
이 서버는 법령을 따라 **대체공휴일 없음**으로 계산합니다. 2021년 인사혁신처 개정 당시 대체공휴일
대상에서 신정·현충일이 명시적으로 제외됐고, 이후 2023년 개정으로 추가된 것은 부처님오신날과
성탄절뿐입니다. 실제로 2021년 6월 6일(일)에도 대체공휴일은 없었습니다.

> 중요한 의사결정에는 관보나 인사혁신처 공고로 한 번 더 확인하세요.
> 계산 결과에 이상이 있으면 이슈로 알려주세요.

## 검증

규칙 엔진 결과를 공개 자료(2024~2027년)와 대조합니다.

```bash
npm run verify
```

타임존에 관계없이 같은 결과가 나오는지도 확인합니다. 모든 날짜 연산은 UTC 자정 기준으로만 처리하고,
"오늘"은 KST로 계산합니다.

## 개발

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

MCP Inspector로 도구를 직접 찔러볼 수도 있습니다.

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

## 구조

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

## 배포

Vercel에 이 저장소를 연결하면 그대로 배포됩니다. 환경 변수는 필요 없습니다.
커넥터 URL은 배포 도메인 뒤에 `/api/mcp`를 붙인 주소이고, 랜딩 페이지가 자기 도메인을 읽어
자동으로 올바른 URL을 보여줍니다.

## 개인정보

날짜 문자열만 받아서 계산 결과를 돌려줍니다. 사용자 데이터를 저장하거나 외부로 보내지 않습니다.

## 라이선스

MIT