{"_id":"@bachstudio/taiwan-holiday-mcp","name":"@bachstudio/taiwan-holiday-mcp","dist-tags":{"latest":"1.0.5"},"versions":{"1.0.5":{"name":"@bachstudio/taiwan-holiday-mcp","version":"1.0.5","mcpName":"io.github.bachstudio/taiwan-holiday-mcp","description":"MCP server for Taiwan holiday information","license":"MIT","author":{"name":"bachstudio"},"homepage":"https://github.com/BACH-AI-Tools/taiwan-holiday-mcp","repository":{"type":"git","url":"git+https://github.com/BACH-AI-Tools/taiwan-holiday-mcp.git"},"type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"taiwan-holiday-mcp":"dist/index.js"},"scripts":{"clean":"shx rm -rf dist","build":"npm run clean && tsc && shx chmod +x dist/*.js","build:watch":"tsc --watch","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","lint":"eslint src/**/*.ts","lint:fix":"eslint src/**/*.ts --fix","prepare":"npm run build","package:test":"npm pack --dry-run","package:local":"npm pack"},"dependencies":{"@modelcontextprotocol/sdk":"^1.13.0"},"devDependencies":{"@types/jest":"^29.5.14","@types/node":"^22.10.2","@typescript-eslint/eslint-plugin":"^8.18.2","@typescript-eslint/parser":"^8.18.2","eslint":"^9.17.0","jest":"^29.7.0","nock":"^13.5.6","shx":"^0.4.0","supertest":"^7.0.0","ts-jest":"^29.2.5","typescript":"^5.8.3"},"engines":{"node":">=18.0.0"},"keywords":["mcp","model-context-protocol","taiwan","holiday","calendar","claude","cursor"],"gitHead":"496a7610f82e17db7f601715606567239649c0dd","bugs":{"url":"https://github.com/BACH-AI-Tools/taiwan-holiday-mcp/issues"},"_id":"@bachstudio/taiwan-holiday-mcp@1.0.5","_nodeVersion":"18.17.1","_npmVersion":"9.6.7","dist":{"integrity":"sha512-HHQaWDVju6t3XcG+FO1wEj7leEmlj7nU/lLMmLVycXUwC8/5MDDacV/ENXiWNAVFVSsCuVbLWK9rlbYB6UVDkQ==","shasum":"820ff654fd9dd58bee2ca4573fd016386f6197c3","tarball":"https://registry.npmjs.org/@bachstudio/taiwan-holiday-mcp/-/taiwan-holiday-mcp-1.0.5.tgz","fileCount":47,"unpackedSize":231044,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDvL0jviWAyOod6I/lEXPq4VRLlVBT/6Du6PMrG4WmhMwIhAP2s4wGJ+zT+6fLsz8Fsb/yNL/bFewkJtjmozK6sA8Ca"}]},"_npmUser":{"name":"bachstudio","email":"bach_mcp_studio@bach.team"},"directories":{},"maintainers":[{"name":"bachstudio","email":"bach_mcp_studio@bach.team"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/taiwan-holiday-mcp_1.0.5_1763631042902_0.7711635262612442"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-20T09:30:42.700Z","1.0.5":"2025-11-20T09:30:43.102Z","modified":"2025-11-20T09:30:43.498Z"},"maintainers":[{"name":"bachstudio","email":"bach_mcp_studio@bach.team"}],"description":"MCP server for Taiwan holiday information","homepage":"https://github.com/BACH-AI-Tools/taiwan-holiday-mcp","keywords":["mcp","model-context-protocol","taiwan","holiday","calendar","claude","cursor"],"repository":{"type":"git","url":"git+https://github.com/BACH-AI-Tools/taiwan-holiday-mcp.git"},"author":{"name":"bachstudio"},"bugs":{"url":"https://github.com/BACH-AI-Tools/taiwan-holiday-mcp/issues"},"license":"MIT","readme":"# Taiwan Holiday MCP Server\n\n[![Node.js Version](https://img.shields.io/node/v/@bachstudio/taiwan-holiday-mcp.svg)](https://nodejs.org/)\n[![npm version](https://badge.fury.io/js/@bachstudio%2Ftaiwan-holiday-mcp.svg)](https://badge.fury.io/js/@bachstudio%2Ftaiwan-holiday-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=taiwan-holiday&config=eyJjb21tYW5kIjoibnB4IEBiYWNoc3R1ZGlvL3RhaXdhbi1ob2xpZGF5LW1jcCJ9)\n\n一個基於 Model Context Protocol (MCP) 的台灣假期查詢伺服器，提供準確的台灣國定假日和補班日資訊。\n\n## ✨ 特色功能\n\n- 🇹🇼 **準確的台灣假期資料**：基於 [TaiwanCalendar](https://github.com/ruyut/TaiwanCalendar) 提供的政府公告假期資訊\n- 🚀 **即時查詢**：支援單日查詢、範圍查詢和統計查詢\n- 📅 **多種日期格式**：支援 `YYYY-MM-DD` 和 `YYYYMMDD` 格式\n- 🔄 **智慧快取**：自動快取資料，提升查詢效能\n- 🛠️ **MCP 標準**：完全相容 Model Context Protocol 規範\n- 🎯 **AI 友善**：專為 Claude Desktop、Cursor 等 AI 工具設計\n- 📊 **豐富統計**：提供假期統計和分析功能\n- 🌐 **跨平台**：支援 Windows、macOS 和 Linux\n\n## 🚀 快速開始\n\n### NPX 直接使用（推薦）\n\n最簡單的使用方式，無需安裝：\n\n```bash\nnpx @bachstudio/taiwan-holiday-mcp\n```\n\n### 本地安裝\n\n```bash\nnpm install -g @bachstudio/taiwan-holiday-mcp\ntaiwan-holiday-mcp\n```\n\n### 開發環境安裝\n\n```bash\ngit clone https://github.com/BACH-AI-Tools/taiwan-holiday-mcp.git\ncd taiwan-holiday-mcp\nnpm install\nnpm run build\nnpm start\n```\n\n\n\n## 🔧 客戶端設定\n\n### Claude Desktop 設定\n\n在 Claude Desktop 的設定檔中新增：\n\n```json\n{\n  \"mcpServers\": {\n    \"taiwan-holiday\": {\n      \"command\": \"npx\",\n      \"args\": [\"@bachstudio/taiwan-holiday-mcp\"]\n    }\n  }\n}\n```\n\n**設定檔位置：**\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n### Cursor 設定\n\n點擊以下按鈕直接安裝。\n\n[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=taiwan-holiday&config=eyJjb21tYW5kIjoibnB4IEBiYWNoc3R1ZGlvL3RhaXdhbi1ob2xpZGF5LW1jcCJ9)\n\n### Windsurf 設定\n\n在專案的 `.cursorrules` 或設定檔中新增：\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"taiwan-holiday\": {\n        \"command\": \"npx\",\n        \"args\": [\"@bachstudio/taiwan-holiday-mcp\"]\n      }\n    }\n  }\n}\n```\n\n## 📖 使用範例\n\n安裝完成後，你可以直接在 Claude Desktop 中用自然語言與 AI 對話，詢問台灣假期相關問題：\n\n### 基本查詢\n\n**你可以這樣問：**\n> \"2025年10月10日是假期嗎？\"\n> \n> \"幫我查一下2025年1月有哪些假期\"\n> \n> \"2025年總共有多少個假期？\"\n\n**Claude 會自動呼叫相應的工具並回答：**\n- ✅ 2025年10月10日是國慶日，是假期\n- 📅 2025年1月共有14個假期，包含春節連假\n- 📊 2025年總共有115個假期\n\n### 實用對話範例\n\n#### 🏖️ 假期規劃\n\n**你：** \"我想規劃2025年第一季的旅遊，幫我找出有哪些連假可以安排？\"\n\n**Claude：** 會自動查詢1-3月的假期，分析連續假期，並告訴你：\n- 春節連假：1月27日-31日（5天）\n- 228連假：2月28日-3月2日（3天）\n- 其他週末假期安排建議\n\n#### 💼 工作安排\n\n**你：** \"下週一（2025年10月6日）需要上班嗎？\"\n\n**Claude：** 會檢查該日期並回答是否為工作日，如果是假期還會說明原因。\n\n#### 📈 假期統計\n\n**你：** \"2025年10月份有幾個假期？有什麼重要節日嗎？\"\n\n**Claude：** 會提供該月份的假期統計，包含國定假日和重要節慶資訊。\n\n### 進階應用\n\n#### 🎯 智慧假期分析\n\n**你：** \"幫我分析2025年哪個月份最適合請假旅遊？\"\n\n**Claude：** 會分析各月份的假期分布，考慮連假長度和頻率，給出最佳建議。\n\n#### 📅 年度假期規劃\n\n**你：** \"我想看2025年所有的長假期，幫我整理一個清單\"\n\n**Claude：** 會自動找出所有3天以上的連假，並按時間順序整理成清單。\n\n## 🛠️ API 文件\n\n### MCP 工具\n\n#### `check_holiday`\n\n檢查指定日期是否為台灣假期。\n\n**參數：**\n- `date` (string): 日期，格式為 `YYYY-MM-DD` 或 `YYYYMMDD`\n\n**回傳：**\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"date\": \"2025-10-10\",\n    \"isHoliday\": true,\n    \"description\": \"國慶日\",\n    \"week\": \"五\",\n    \"normalizedDate\": \"20251010\"\n  }\n}\n```\n\n#### `get_holidays_in_range`\n\n獲取指定日期範圍內的所有台灣假期。\n\n**參數：**\n- `start_date` (string): 開始日期\n- `end_date` (string): 結束日期\n\n**回傳：**\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"startDate\": \"2025-01-01\",\n    \"endDate\": \"2025-01-31\",\n    \"holidays\": [...],\n    \"totalCount\": 14,\n    \"summary\": \"在 2025-01-01 到 2025-01-31 期間共有 14 個假期\"\n  }\n}\n```\n\n#### `get_holiday_stats`\n\n獲取指定年份或年月的台灣假期統計資訊。\n\n**參數：**\n- `year` (number): 年份 (2017-2026)\n- `month` (number, 可選): 月份 (1-12)\n\n**回傳：**\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"year\": 2025,\n    \"statistics\": {\n      \"year\": 2025,\n      \"totalHolidays\": 115,\n      \"nationalHolidays\": 113,\n      \"compensatoryDays\": 2,\n      \"holidayTypes\": {...}\n    },\n    \"summary\": \"2025 年共有 115 個假期\"\n  }\n}\n```\n\n### MCP 資源\n\n伺服器提供以下資源：\n\n- `taiwan-holidays://years` - 支援的年份列表\n- `taiwan-holidays://holidays/{year}` - 指定年份的完整假期資料\n- `taiwan-holidays://stats/{year}` - 指定年份的統計資訊\n\n## 🔍 故障排除\n\n### 常見問題\n\n#### 1. 無法連接到伺服器\n\n**問題**：Claude Desktop 顯示 \"無法連接到 MCP 伺服器\"\n\n**解決方案**：\n```bash\n# 檢查 Node.js 版本（需要 18+）\nnode --version\n\n# 重新安裝套件\nnpm uninstall -g @bachstudio/taiwan-holiday-mcp\nnpm install -g @bachstudio/taiwan-holiday-mcp\n\n# 測試伺服器\ntaiwan-holiday-mcp --version\n```\n\n#### 2. 日期格式錯誤\n\n**問題**：收到 \"無效的日期格式\" 錯誤\n\n**解決方案**：\n- 確保使用正確格式：`YYYY-MM-DD` 或 `YYYYMMDD`\n- 檢查日期是否有效（例如：2025-02-30 是無效日期）\n\n#### 3. 網路連接問題\n\n**問題**：無法獲取假期資料\n\n**解決方案**：\n```bash\n# 檢查網路連接\ncurl -I https://cdn.jsdelivr.net/gh/ruyut/TaiwanCalendar/data/2025.json\n\n# 清除快取（如果有問題）\nrm -rf ~/.taiwan-holiday-mcp-cache\n```\n\n### 除錯模式\n\n啟用詳細日誌：\n\n```bash\ntaiwan-holiday-mcp --debug\n```\n\n### 效能調整\n\n如果查詢速度較慢：\n\n1. 檢查網路連接\n2. 確認快取機制正常運作\n3. 考慮使用本地資料來源\n\n## 🧪 開發與測試\n\n詳細的開發說明請參考 [DEVELOPMENT.md](DEVELOPMENT.md)。\n\n### 本地開發\n\n```bash\n# 複製專案\ngit clone https://github.com/BACH-AI-Tools/taiwan-holiday-mcp.git\ncd taiwan-holiday-mcp\n\n# 安裝依賴\nnpm install\n\n# 執行測試\nnpm test\n\n# 建置專案\nnpm run build\n\n# 啟動開發模式\nnpm run dev\n```\n\n### 測試覆蓋率\n\n```bash\nnpm run test:coverage\n```\n\n目前測試覆蓋率：**92.27%**（446 個測試案例，100% 通過）\n\n**核心模組覆蓋率**：\n- SmartCache: 98.97% ✅\n- HealthMonitor: 98.78% ✅\n- DateParser: 97.77% ✅\n- CircuitBreaker: 100% ✅\n- GracefulShutdown: 88.34% ✅\n\n## 📊 效能指標\n\n- **首次 API 呼叫**：< 2 秒\n- **快取 API 呼叫**：< 100ms\n- **併發處理**：支援 10+ 併發請求\n- **記憶體使用**：< 50MB\n- **測試穩定性**：100% 通過率，企業級品質標準\n- **程式碼覆蓋率**：92.34%（遠超業界 80% 標準）\n\n## 🤝 貢獻指南\n\n歡迎貢獻！請遵循以下步驟：\n\n1. Fork 專案\n2. 建立功能分支 (`git checkout -b feature/amazing-feature`)\n3. 提交變更 (`git commit -m 'Add amazing feature'`)\n4. 推送到分支 (`git push origin feature/amazing-feature`)\n5. 開啟 Pull Request\n\n## ⚠️ 免責聲明\n\n### 資料來源與準確性\n\n本專案的台灣假期資料來源於 [TaiwanCalendar](https://github.com/ruyut/TaiwanCalendar) 開源專案，該專案基於中華民國政府公告的官方假期資訊。\n\n**重要聲明：**\n\n1. **資料準確性**：雖然我們努力確保資料的準確性，但本專案不保證所提供的假期資訊完全正確或即時更新。\n2. **官方資料**：如需最準確的假期資訊，請以中華民國政府相關部門的官方公告為準。\n3. **資料更新**：假期資料可能因政府政策調整而變更，本專案會盡力跟進更新，但可能存在延遲。\n4. **使用責任**：使用者應自行驗證重要日期的假期狀態，特別是用於商業或法律用途時。\n\n### 服務可用性\n\n- 本服務依賴外部資料來源，可能因網路問題或資料來源異常而暫時無法使用\n- 我們不保證服務的 100% 可用性或回應時間\n- 建議在關鍵應用中實作適當的錯誤處理和備援機制\n\n### 責任限制\n\n在法律允許的最大範圍內，本專案的作者和貢獻者不對因使用本軟體而產生的任何直接、間接、偶然、特殊或後果性損害承擔責任。\n\n## 📄 授權條款\n\n本專案採用 MIT 授權條款。詳見 [LICENSE](LICENSE) 檔案。\n\n## 🙏 致謝\n\n- [TaiwanCalendar](https://github.com/ruyut/TaiwanCalendar) - 提供準確的台灣假期資料\n- [Model Context Protocol](https://modelcontextprotocol.io/) - 提供標準化的 AI 工具協議\n\n## 📞 支援\n\n- **GitHub Issues**: [回報問題](https://github.com/BACH-AI-Tools/taiwan-holiday-mcp/issues)\n- **文件**: [完整文件](https://github.com/BACH-AI-Tools/taiwan-holiday-mcp/docs)\n\n---\n\n**版本**: 1.0.4\n**最後更新**: 2025-10-10  \n**支援年份**: 2017-2026  \n**MCP SDK**: @modelcontextprotocol/sdk ^1.13.0  \n**Node.js 需求**: ≥ 18.0.0  \n**品質狀態**: 企業級生產就緒 ✅ ","readmeFilename":"README.md","_rev":"1-f65e92f5f3c19ce4b660cfa1cb3ea6ba"}