[English](README.en.md) | [繁體中文](README.md)

# Taiwan Holiday MCP Server

[![Node.js Version](https://img.shields.io/node/v/taiwan-holiday-mcp.svg)](https://nodejs.org/)
[![npm version](https://badge.fury.io/js/taiwan-holiday-mcp.svg)](https://badge.fury.io/js/taiwan-holiday-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=taiwan-holiday&config=eyJjb21tYW5kIjoibnB4IHRhaXdhbi1ob2xpZGF5LW1jcCJ9)

一個基於 Model Context Protocol (MCP) 的台灣假期查詢伺服器，提供準確的台灣國定假日和補班日資訊，以及颱風假（天然災害停止上班上課）查詢。

## ✨ 特色功能

- 🇹🇼 **準確的台灣假期資料**：基於 [TaiwanCalendar](https://github.com/ruyut/TaiwanCalendar) 提供的政府公告假期資訊
- 🚀 **即時查詢**：支援單日查詢、範圍查詢、接下來的假期、工作天（含補班日）與統計查詢
- 🌀 **颱風假查詢**：今天、明天讀人事行政總處即時頁，其他日期讀 2001-07-30 起的歸檔
- 📅 **多種日期格式**：支援 `YYYY-MM-DD` 和 `YYYYMMDD` 格式
- 🔄 **智慧快取**：自動快取資料，提升查詢效能
- 🛠️ **MCP 標準**：完全相容 Model Context Protocol 規範
- 🎯 **AI 友善**：專為 Claude Desktop、Cursor 等 AI 工具設計
- 📊 **豐富統計**：提供假期統計和分析功能
- 🌐 **跨平台**：支援 Windows、macOS 和 Linux

## 🚀 快速開始

### NPX 直接使用（推薦）

最簡單的使用方式，無需安裝：

```bash
npx taiwan-holiday-mcp
```

### 本地安裝

```bash
npm install -g taiwan-holiday-mcp
taiwan-holiday-mcp
```

### 開發環境安裝

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



## 🔧 客戶端設定

### Claude Desktop 設定

在 Claude Desktop 的設定檔中新增：

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

**設定檔位置：**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

### Cursor 設定

點擊以下按鈕直接安裝。

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=taiwan-holiday&config=eyJjb21tYW5kIjoibnB4IHRhaXdhbi1ob2xpZGF5LW1jcCJ9)

### Windsurf 設定

在專案的 `.cursorrules` 或設定檔中新增：

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

## 📖 使用範例

安裝完成後，你可以直接在 Claude Desktop 中用自然語言與 AI 對話，詢問台灣假期相關問題：

### 基本查詢

**你可以這樣問：**
> "2025年10月10日是假期嗎？"
> 
> "幫我查一下2025年1月有哪些假期"
> 
> "2025年總共有多少個假期？"

**Claude 會自動呼叫相應的工具並回答：**
- ✅ 2025年10月10日是國慶日，是假期
- 📅 2025年1月共有14個假期，包含春節連假
- 📊 2025年總共有115個假期

### 實用對話範例

#### 🏖️ 假期規劃

**你：** "我想規劃2025年第一季的旅遊，幫我找出有哪些連假可以安排？"

**Claude：** 會自動查詢1-3月的假期，分析連續假期，並告訴你：
- 春節連假：1月27日-31日（5天）
- 228連假：2月28日-3月2日（3天）
- 其他週末假期安排建議

#### 💼 工作安排

**你：** "下週一（2025年10月6日）需要上班嗎？"

**Claude：** 會檢查該日期並回答是否為工作日，如果是假期還會說明原因。

#### 📈 假期統計

**你：** "2025年10月份有幾個假期？有什麼重要節日嗎？"

**Claude：** 會提供該月份的假期統計，包含國定假日和重要節慶資訊。

#### 🌀 颱風假

**你：** "颱風要來了，明天臺北市要上班嗎？"

**Claude：** 會查詢明天臺北市的停班停課公告並回答：
- 已公告停止上班上課時，說明時段（全天、下午、幾點起）
- 只有部分區域或學制停止時，列出受影響的區域
- 人事行政總處尚未公告時，說明「目前無法確認」，不會當成照常上班，並提醒以縣市政府公告為準

### 進階應用

#### 🎯 智慧假期分析

**你：** "幫我分析2025年哪個月份最適合請假旅遊？"

**Claude：** 會分析各月份的假期分布，考慮連假長度和頻率，給出最佳建議。

#### 📅 年度假期規劃

**你：** "我想看2025年所有的長假期，幫我整理一個清單"

**Claude：** 會自動找出所有3天以上的連假，並按時間順序整理成清單。

## 🛠️ API 文件

### MCP 工具

#### `check_holiday`

檢查指定日期是否為台灣假期。

**參數：**
- `date` (string): 日期，格式為 `YYYY-MM-DD` 或 `YYYYMMDD`

**回傳：**
```json
{
  "success": true,
  "data": {
    "date": "2025-10-10",
    "isHoliday": true,
    "description": "國慶日",
    "week": "五",
    "normalizedDate": "20251010"
  }
}
```

#### `get_holidays_in_range`

獲取指定日期範圍內的所有台灣假期。

**參數：**
- `start_date` (string): 開始日期
- `end_date` (string): 結束日期

**回傳：**
```json
{
  "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`

獲取指定年份或年月的台灣假期統計資訊。

**參數：**
- `year` (number): 年份，2017 年起（實際可查年份由上游資料決定）
- `month` (number, 可選): 月份 (1-12)

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

#### `get_next_holidays`

取得起算日之後的接下來 N 個台灣假期。語意對齊 [`taiwan-holiday-cli`](https://github.com/lis186/taiwan-holiday-cli) 的 `holiday next`：起算日當天即使放假也不算，搜尋範圍是起算日後 365 天（且不超過上游已發布的最後一年）。

**參數：**
- `date` (string, 可選): 起算日，`YYYY-MM-DD` 或 `YYYYMMDD`。省略時為台北時區的今天
- `count` (integer, 可選): 要取得的數量，預設 `1`，最大 `366`
- `skip_weekends` (boolean, 可選): 略過一般週末（週六日且說明為空或「週末」），仍保留落在週末的具名假日。預設 `false`

**回傳：**
```json
{
  "success": true,
  "data": {
    "found": true,
    "count": 2,
    "fromDate": "2026-01-01",
    "searchedThrough": "2026-12-31",
    "truncatedByData": false,
    "holidays": [
      { "date": "2026-01-03", "week": "六", "description": "週末" },
      { "date": "2026-01-04", "week": "日", "description": "週末" }
    ]
  },
  "tool": "get_next_holidays"
}
```

`searchedThrough` 是這次實際搜到的最後一天。`truncatedByData` 為 `true` 時，365 天視窗被上游最後一個已發布年度截斷，回傳筆數少於 `count` 不代表後面沒有假期。

找不到、而且搜尋窗裡真的沒有假期時，`found` 為 `false`、`holidays` 為 `[]`，並帶 `message: "查無假期"`。起算日晚於已發布資料時，訊息改為 `上游最新資料只到 N 年`。一般週末的空說明會顯示為「週末」。補班日不是假期，不會出現在這份清單。

#### `get_workdays`

計算工作天數。可查整月，或查一段日期（含起迄日）。請擇一，不要同時指定。語意對齊 CLI 的 `holiday workdays` 與 `holiday between`：

- 週末與 `isHoliday: true` 的日子計入 `holidays`，不計入 `workdays`
- `workdays = totalDays - holidays`
- 補班日（說明含「補行上班」）不是假期，因此算工作天；`makeupWorkdays` 是這些日子的筆數，`makeupWorkdayDates` 列出日期

**整月參數：**
- `year` (integer): 年份
- `month` (integer): 月份 1-12

**區間參數：**
- `start_date` (string): 起日，`YYYY-MM-DD` 或 `YYYYMMDD`
- `end_date` (string): 迄日，同一格式

**整月回傳：**
```json
{
  "success": true,
  "data": {
    "year": 2024,
    "month": 1,
    "totalDays": 31,
    "workdays": 22,
    "holidays": 9,
    "makeupWorkdays": 1,
    "makeupWorkdayDates": [
      { "date": "2024-01-06", "week": "六", "description": "補行上班" }
    ]
  },
  "tool": "get_workdays"
}
```

**區間回傳：**
```json
{
  "success": true,
  "data": {
    "startDate": "2024-01-06",
    "endDate": "2024-01-07",
    "totalDays": 2,
    "workdays": 1,
    "holidays": 1,
    "makeupWorkdays": 1,
    "makeupWorkdayDates": [
      { "date": "2024-01-06", "week": "六", "description": "補行上班" }
    ]
  },
  "tool": "get_workdays"
}
```

`totalDays` 在整月查詢是該月的日曆天數（閏年二月為 29）。上游該範圍的筆數必須剛好等於日曆天數；少一天或多一天都會回錯誤（例如 `上游 2024 年 2 月 資料不完整（預期 29 筆，實得 2 筆）`），不會把缺的日子當成工作天。
#### `check_typhoon_closure`

查詢颱風假（天然災害停止上班上課）。判斷規則與即時頁解析由 [`taiwan-holiday-cli`](https://github.com/lis186/taiwan-holiday-cli) 提供，
欄位語意見該專案 README 的「颱風假查詢」一節。

**資料來源：** 今天、明天讀 [DGPA 天然災害停止上班及上課情形](https://www.dgpa.gov.tw/typh/daily/nds.html) 即時頁；
其他日期讀 [TaiwanTyphoonDays](https://github.com/lis186/TaiwanTyphoonDays) 歸檔（2001-07-30 起）。

**參數：**
- `date` (string, 可選): `today`、`tomorrow`、`YYYY-MM-DD` 或 `YYYYMMDD`，省略為今天（臺灣時間）
- `city` (string, 可選): 縣市名稱，台／臺視為相同；省略為全國

**回傳：** `summary` 為一行結論，`data` 為完整的 `TyphoonQueryResult`。

```json
{
  "success": true,
  "summary": "2024-10-31 臺北市：停止上班（全天）、停止上課（全天）〔已定案〕",
  "data": {
    "date": "20241031",
    "city": "臺北市",
    "work": { "status": "stopped", "period": "allDay", "from": "" },
    "school": { "status": "stopped", "period": "allDay", "from": "" },
    "basis": "own",
    "reason": null,
    "source": {...},
    "cities": [...],
    "notes": [...]
  }
}
```

**判讀重點：**
- `status` 為 `unknown` 時代表無法判斷，**不可當成照常上班上課**。
- `conditional` 表示只有部分地區、學制或時段停止，要看 `cities[].rows`。
- `reason` 不是 `null` 時結果仍可能改變（`live` 為即時頁，當天仍可能更新）。
- 昨天到 21 天前常是 `unknown`／`pending`：即時頁只有今天與明天，歸檔通常延遲數天才收錄。
- 請以各縣市政府公告為準。

### MCP 資源

伺服器提供以下資源：

- `taiwan-holidays://years` - 支援的年份列表
- `taiwan-holidays://holidays/{year}` - 指定年份的完整假期資料
- `taiwan-holidays://stats/{year}` - 指定年份的統計資訊

## 🔍 故障排除

### 常見問題

#### 1. 無法連接到伺服器

**問題**：Claude Desktop 顯示 "無法連接到 MCP 伺服器"

**解決方案**：
```bash
# 檢查 Node.js 版本（需要 22+）
node --version

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

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

#### 2. 日期格式錯誤

**問題**：收到 "無效的日期格式" 錯誤

**解決方案**：
- 確保使用正確格式：`YYYY-MM-DD` 或 `YYYYMMDD`
- 檢查日期是否有效（例如：2025-02-30 是無效日期）

#### 3. 網路連接問題

**問題**：無法獲取假期資料

**解決方案**：
```bash
# 檢查網路連接
curl -I https://cdn.jsdelivr.net/gh/ruyut/TaiwanCalendar/data/2025.json

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

### 除錯模式

啟用詳細日誌：

```bash
taiwan-holiday-mcp --debug
```

### 效能調整

如果查詢速度較慢：

1. 檢查網路連接
2. 確認快取機制正常運作
3. 考慮使用本地資料來源

## 🧪 開發與測試

詳細的開發說明請參考 [DEVELOPMENT.md](DEVELOPMENT.md)。

### 本地開發

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

# 安裝依賴
npm install

# 執行測試
npm test

# 建置專案
npm run build

# 啟動開發模式
npm run dev
```

### 測試覆蓋率

```bash
npm run test:coverage
```

目前測試覆蓋率：**93.68%** statements（522 個測試通過，另有 8 個因環境略過）

**核心模組覆蓋率**（statements）：
- SmartCache: 98.97% ✅
- HealthMonitor: 98.78% ✅
- DateParser: 98.97% ✅
- CircuitBreaker: 100% ✅
- GracefulShutdown: 89.42% ✅

變異測試為選用，不在 CI。執行 `npm run test:mutation`（Stryker），目前分數 **98.51%**。

## 📊 效能指標

- **首次 API 呼叫**：< 2 秒
- **快取 API 呼叫**：< 100ms
- **併發處理**：支援 10+ 併發請求
- **記憶體使用**：< 50MB
- **測試穩定性**：522 個測試通過（另有 8 個因環境略過）
- **程式碼覆蓋率**：93.68% statements（遠超業界 80% 標準）

## 🤝 貢獻指南

歡迎貢獻！請遵循以下步驟：

1. Fork 專案
2. 建立功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交變更 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 開啟 Pull Request

## ⚠️ 免責聲明

### 資料來源與準確性

本專案的台灣假期資料來源於 [TaiwanCalendar](https://github.com/ruyut/TaiwanCalendar) 開源專案，該專案基於中華民國政府公告的官方假期資訊。

颱風假（天然災害停止上班上課）資料來源：今天、明天讀行政院人事行政總處的
[天然災害停止上班及上課情形](https://www.dgpa.gov.tw/typh/daily/nds.html) 即時頁，其他日期讀
[TaiwanTyphoonDays](https://github.com/lis186/TaiwanTyphoonDays) 歸檔。即時頁格式並非官方承諾，
可能隨時改變而導致無法解析；歸檔通常在事件後數天才收錄。**停班停課請以各縣市政府的正式公告為準**，
本專案回報「無法判斷」時，不代表照常上班上課。

**重要聲明：**

1. **資料準確性**：雖然我們努力確保資料的準確性，但本專案不保證所提供的假期資訊完全正確或即時更新。
2. **官方資料**：如需最準確的假期資訊，請以中華民國政府相關部門的官方公告為準。
3. **資料更新**：假期資料可能因政府政策調整而變更，本專案會盡力跟進更新，但可能存在延遲。
4. **使用責任**：使用者應自行驗證重要日期的假期狀態，特別是用於商業或法律用途時。

### 服務可用性

- 本服務依賴外部資料來源，可能因網路問題或資料來源異常而暫時無法使用
- 我們不保證服務的 100% 可用性或回應時間
- 建議在關鍵應用中實作適當的錯誤處理和備援機制

### 責任限制

在法律允許的最大範圍內，本專案的作者和貢獻者不對因使用本軟體而產生的任何直接、間接、偶然、特殊或後果性損害承擔責任。

## 🔗 相關專案

- [`taiwan-holiday-cli`](https://github.com/lis186/taiwan-holiday-cli) —— 同一資料來源的命令列工具，適合終端機與腳本使用
- [`taiwan-holiday-skills`](https://github.com/lis186/taiwan-holiday-skills) —— 打包好的 Claude Agent Skill（底層透過 CLI 呼叫）

三個專案共享 MAJOR 版號，目前為 3.x 世代。

## 📄 授權條款

本專案採用 MIT 授權條款。詳見 [LICENSE](LICENSE) 檔案。

## 🙏 致謝

- [TaiwanCalendar](https://github.com/ruyut/TaiwanCalendar) - 提供準確的台灣假期資料
- [Model Context Protocol](https://modelcontextprotocol.io/) - 提供標準化的 AI 工具協議

## 📞 支援

- **GitHub Issues**: [回報問題](https://github.com/lis186/taiwan-holiday-mcp/issues)
- **文件**: [完整文件](https://github.com/lis186/taiwan-holiday-mcp/docs)

---

**支援年份**: 2017 年起，上限跟隨上游資料（新年度發布即自動支援）  
**MCP SDK**: @modelcontextprotocol/sdk ^1.13.0  
**Node.js 需求**: ≥ 22.0.0  
**品質狀態**: 企業級生產就緒 ✅