This MCP server lets AI clients query Taiwan holiday, workday, and related calendar information through standardized tools.
Check whether a specific date is a Taiwan holiday using YYYY-MM-DD or YYYYMMDD.
List all holidays within a start/end date range.
Get holiday statistics for a year or a specific year-month.
Get the next N holidays after a date, with optional weekend skipping and data-truncation metadata.
Calculate workdays for a full month or date range, excluding weekends/holidays and separately reporting makeup workdays.
The README also describes typhoon-closure lookup, but the provided server schema does not include that tool.
Utilizes GitHub as a data source for Taiwan holiday information through the TaiwanCalendar repository.
Uses jsDelivr's CDN to fetch Taiwan holiday data from the TaiwanCalendar GitHub repository.
Provides cross-platform support including Linux systems.
Supports macOS with specific configuration file paths for Claude Desktop integration.
Built on Node.js runtime, requiring version 18+ for proper functionality.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Taiwan Holiday MCP Server what holidays are there in October 2025?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
一個基於 Model Context Protocol (MCP) 的台灣假期查詢伺服器，提供準確的台灣國定假日和補班日資訊，以及颱風假（天然災害停止上班上課）查詢。
🇹🇼 準確的台灣假期資料：基於 TaiwanCalendar 提供的政府公告假期資訊
🚀 即時查詢：支援單日查詢、範圍查詢、接下來的假期、工作天（含補班日）與統計查詢
🌀 颱風假查詢：今天、明天讀人事行政總處即時頁，其他日期讀 2001-07-30 起的歸檔
📅 多種日期格式：支援 YYYY-MM-DD 和 YYYYMMDD 格式
🔄 智慧快取：自動快取資料，提升查詢效能
🛠️ MCP 標準：完全相容 Model Context Protocol 規範
🎯 AI 友善：專為 Claude Desktop、Cursor 等 AI 工具設計
📊 豐富統計：提供假期統計和分析功能
🌐 跨平台：支援 Windows、macOS 和 Linux
Related MCP server: 12306-MCP
最簡單的使用方式，無需安裝：
npx taiwan-holiday-mcpnpm install -g taiwan-holiday-mcp
taiwan-holiday-mcpgit clone https://github.com/lis186/taiwan-holiday-mcp.git
cd taiwan-holiday-mcp
npm install
npm run build
npm start在 Claude Desktop 的設定檔中新增：
{
"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
點擊以下按鈕直接安裝。
在專案的 .cursorrules 或設定檔中新增：
{
"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天以上的連假，並按時間順序整理成清單。
check_holiday檢查指定日期是否為台灣假期。
參數：
date (string): 日期，格式為 YYYY-MM-DD 或 YYYYMMDD
回傳：
{
"success": true,
"data": {
"date": "2025-10-10",
"isHoliday": true,
"description": "國慶日",
"week": "五",
"normalizedDate": "20251010"
}
}get_holidays_in_range獲取指定日期範圍內的所有台灣假期。
參數：
start_date (string): 開始日期
end_date (string): 結束日期
回傳：
{
"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)
回傳：
{
"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 的 holiday next：起算日當天即使放假也不算，搜尋範圍是起算日後 365 天（且不超過上游已發布的最後一年）。
參數：
date (string, 可選): 起算日，YYYY-MM-DD 或 YYYYMMDD。省略時為台北時區的今天
count (integer, 可選): 要取得的數量，預設 1，最大 366
skip_weekends (boolean, 可選): 略過一般週末（週六日且說明為空或「週末」），仍保留落在週末的具名假日。預設 false
回傳：
{
"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): 迄日，同一格式
整月回傳：
{
"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"
}區間回傳：
{
"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 提供，
欄位語意見該專案 README 的「颱風假查詢」一節。
資料來源： 今天、明天讀 DGPA 天然災害停止上班及上課情形 即時頁； 其他日期讀 TaiwanTyphoonDays 歸檔（2001-07-30 起）。
參數：
date (string, 可選): today、tomorrow、YYYY-MM-DD 或 YYYYMMDD，省略為今天（臺灣時間）
city (string, 可選): 縣市名稱，台／臺視為相同；省略為全國
回傳： summary 為一行結論，data 為完整的 TyphoonQueryResult。
{
"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：即時頁只有今天與明天，歸檔通常延遲數天才收錄。
請以各縣市政府公告為準。
伺服器提供以下資源：
taiwan-holidays://years - 支援的年份列表
taiwan-holidays://holidays/{year} - 指定年份的完整假期資料
taiwan-holidays://stats/{year} - 指定年份的統計資訊
問題：Claude Desktop 顯示 "無法連接到 MCP 伺服器"
解決方案：
# 檢查 Node.js 版本（需要 22+）
node --version
# 重新安裝套件
npm uninstall -g taiwan-holiday-mcp
npm install -g taiwan-holiday-mcp
# 測試伺服器
taiwan-holiday-mcp --version問題：收到 "無效的日期格式" 錯誤
解決方案：
確保使用正確格式：YYYY-MM-DD 或 YYYYMMDD
檢查日期是否有效（例如：2025-02-30 是無效日期）
問題：無法獲取假期資料
解決方案：
# 檢查網路連接
curl -I https://cdn.jsdelivr.net/gh/ruyut/TaiwanCalendar/data/2025.json
# 清除快取（如果有問題）
rm -rf ~/.taiwan-holiday-mcp-cache啟用詳細日誌：
taiwan-holiday-mcp --debug如果查詢速度較慢：
檢查網路連接
確認快取機制正常運作
考慮使用本地資料來源
詳細的開發說明請參考 DEVELOPMENT.md。
# 複製專案
git clone https://github.com/lis186/taiwan-holiday-mcp.git
cd taiwan-holiday-mcp
# 安裝依賴
npm install
# 執行測試
npm test
# 建置專案
npm run build
# 啟動開發模式
npm run devnpm 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% 標準）
歡迎貢獻！請遵循以下步驟：
Fork 專案
建立功能分支 (git checkout -b feature/amazing-feature)
提交變更 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
開啟 Pull Request
本專案的台灣假期資料來源於 TaiwanCalendar 開源專案，該專案基於中華民國政府公告的官方假期資訊。
颱風假（天然災害停止上班上課）資料來源：今天、明天讀行政院人事行政總處的 天然災害停止上班及上課情形 即時頁，其他日期讀 TaiwanTyphoonDays 歸檔。即時頁格式並非官方承諾， 可能隨時改變而導致無法解析；歸檔通常在事件後數天才收錄。停班停課請以各縣市政府的正式公告為準， 本專案回報「無法判斷」時，不代表照常上班上課。
重要聲明：
資料準確性：雖然我們努力確保資料的準確性，但本專案不保證所提供的假期資訊完全正確或即時更新。
官方資料：如需最準確的假期資訊，請以中華民國政府相關部門的官方公告為準。
資料更新：假期資料可能因政府政策調整而變更，本專案會盡力跟進更新，但可能存在延遲。
使用責任：使用者應自行驗證重要日期的假期狀態，特別是用於商業或法律用途時。
本服務依賴外部資料來源，可能因網路問題或資料來源異常而暫時無法使用
我們不保證服務的 100% 可用性或回應時間
建議在關鍵應用中實作適當的錯誤處理和備援機制
在法律允許的最大範圍內，本專案的作者和貢獻者不對因使用本軟體而產生的任何直接、間接、偶然、特殊或後果性損害承擔責任。
taiwan-holiday-cli —— 同一資料來源的命令列工具，適合終端機與腳本使用
taiwan-holiday-skills —— 打包好的 Claude Agent Skill（底層透過 CLI 呼叫）
三個專案共享 MAJOR 版號，目前為 3.x 世代。
本專案採用 MIT 授權條款。詳見 LICENSE 檔案。
TaiwanCalendar - 提供準確的台灣假期資料
Model Context Protocol - 提供標準化的 AI 工具協議
支援年份: 2017 年起，上限跟隨上游資料（新年度發布即自動支援）
MCP SDK: @modelcontextprotocol/sdk ^1.13.0
Node.js 需求: ≥ 22.0.0
品質狀態: 企業級生產就緒 ✅
檢查指定日期是否為台灣假期
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | 要查詢的日期，支援格式：YYYY-MM-DD 或 YYYYMMDD |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral details such as return format, handling of invalid dates, or what constitutes a 'holiday' (e.g., official calendar). The description carries the full burden and is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence in Chinese that is front-loaded and free of fluff. Every word contributes to the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema or annotations, the description should explain what the tool returns (e.g., true/false) and any relevant context about holiday definitions. It does neither, making it incomplete for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the single parameter (date) with format constraints and description. The tool description adds no additional parameter semantics beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks if a specified date is a Taiwan holiday. It uses a specific verb ('check') and resource ('date is Taiwan holiday'), distinguishing it from sibling tools that handle ranges or statistics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the alternatives (get_holidays_in_range, get_holiday_stats). The intended use case (single-date checking) is implied by the name and description but not explicitly contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查詢台灣颱風假（天然災害停止上班上課）。今天、明天讀行政院人事行政總處（DGPA）即時頁，其他日期讀 2001-07-30 起的歸檔。 頂層 work／school 的 status 判讀規則：
stopped：全縣市停止，時段見 period／from。
conditional：只有部分地區、學制或時段停止，必須逐一讀 cities[].rows 判斷是否適用使用者所在地；未指定縣市時只要有任何停止就是 conditional。
normal：有公告且照常，或確定當日無公告。
unknown：無法判斷。絕對不可當成「照常上班上課」回答，應告知無法確認並請使用者查看縣市政府或 DGPA 公告。 reason 非 null 代表結果仍可能改變：live 為即時頁、當天仍可能更新；pending 為歸檔可能尚未收錄（昨天到 21 天前常見）；source_not_ready 為當年度資料尚未產生。 回答時請轉述 summary 與 notes，並以各縣市政府公告為準。
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | 縣市名稱（可選），例如「臺北市」；台／臺視為相同。縣市名保留當時名稱，不對應改制前後的行政區。省略則回傳全國 | |
| date | No | 要查詢的日期（臺灣時間），支援 today、tomorrow、YYYY-MM-DD 或 YYYYMMDD；省略為今天。最早 2001-07-30 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses live vs archive behavior, status semantics including conditional and unknown edge cases, reason field meanings (live/pending/source_not_ready), and the critical rule that unknown must not be treated as normal. This is rich behavioral context beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and a front-loaded purpose statement. It is moderately long but the complexity justifies most of it; some output guidance (e.g., relaying summary and notes) could be trimmed slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers data sources, status interpretation, reason meanings, and answer guidance. It could describe the return structure more fully (e.g., what fields exist beyond work/school status), but it is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. The description adds semantic meaning: date controls whether live or archive data is read, and city omission triggers 'any stop = conditional' interpretation. These rules go beyond the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (query Taiwan typhoon days off / natural disaster work-school suspension). It does not name sibling tools, but the domain is clearly distinct from general holiday tools like check_holiday, so an agent can tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains data sources by date (live page for today/tomorrow, archive for other dates) and gives interpretation rules (e.g., when no city specified, any stop is conditional). It also instructs on handling unknown results. No explicit exclusions or alternatives vs sibling holiday tools, but usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
獲取指定日期範圍內的所有台灣假期
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | 結束日期，支援格式：YYYY-MM-DD 或 YYYYMMDD | |
| start_date | Yes | 開始日期，支援格式：YYYY-MM-DD 或 YYYYMMDD |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. However, it only states the purpose (retrieving holidays in a range) and does not mention return format, error handling, rate limits, or whether it is a read-only operation. This leaves significant behavioral context unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core action and resource. It contains no wasted words and is appropriately minimal for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only two parameters, and the schema adequately documents those. However, there is no output schema, and the description does not clarify the return structure or format (e.g., a list of holiday objects). The description implies the result is all holidays in the range, but a bit more detail would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions of date formats (YYYY-MM-DD or YYYYMMDD). The description adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb '獲取' (get) with a clear resource '所有台灣假期' (all Taiwan holidays) and scope '指定日期範圍內' (within specified date range). This clearly differentiates it from sibling tools like check_holiday (which checks a single date) and get_holiday_stats (which provides statistics).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used for retrieving holidays within a date range, but it does not explicitly state when to use this tool versus alternatives like check_holiday or get_holiday_stats. No exclusions or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
獲取指定年份或年月的台灣假期統計資訊
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | 要查詢的年份 | |
| month | No | 要查詢的月份（可選），1-12 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It only says it returns '統計資訊' (statistics) without describing what those statistics contain, whether the call is read-only, what happens when month is omitted, or any cost/rate considerations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single efficient sentence with the scoping qualifier front-loaded and no filler. It is economical, though the brevity leaves room that could have been spent on disambiguation without becoming bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description must explain the return values, but '統計資訊' is left undefined — an agent cannot tell whether it gets holiday counts, names, total days off, or workday ratios. It also gives no guidance on how the optional month changes the result shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'year' and the optional 'month' fully documented in the schema (including 1-12 bounds). The description's 'year or year-month' phrasing mirrors the schema's optional month without adding format or semantics beyond it, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (獲取/get) and a specific resource (台灣假期統計資訊/Taiwan holiday statistics), and scopes it to a year or year-month. It is clearly a statistics/aggregate tool rather than a lister, but it never explicitly distinguishes itself from siblings like get_holidays_in_range or get_workdays.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus get_holidays_in_range, get_workdays, check_holiday, or get_next_holidays. The only hint is the mention of year-or-year-month granularity, which is a scoping detail rather than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
取得指定日期之後的接下來 N 個台灣假期。未指定日期時以台北時區的今天為起算日（不含當天）。可略過一般週末，只保留具名假日。補班日不是假期，不會出現在結果裡。結果含 searchedThrough 與 truncatedByData；搜尋被上游最後一個已發布年度截斷時 truncatedByData 為 true。起算日晚於已發布資料時不會回「查無假期」。
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | 起算日（不含當天）。支援 YYYY-MM-DD 或 YYYYMMDD。省略時為台北時區的今天 | |
| count | No | 要取得的假期數量，預設 1，最大 366 | |
| skip_weekends | No | 略過一般週末（週六日且沒有具名假日），只回傳國定假日、補假等特殊假期。預設 false |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does well: it discloses that make-up workdays are excluded, that results carry searchedThrough and truncatedByData, that truncation occurs at the last published year, and that a start date beyond published data does not yield a 'no holidays' answer. Missing auth/rate-limit context, but edge-case disclosure is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded and each subsequent sentence adds distinct information (default date, weekend skipping, workday exclusion, output fields, edge case). It is dense but not padded, though it reads as one long block rather than cleanly separated concerns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description compensates by naming the returned fields (searchedThrough, truncatedByData) and their truncation semantics, plus the boundary behavior for late start dates. For a 3-param read tool this is nearly complete, lacking only error/permission context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents date format, count bounds, and skip_weekends semantics. The description largely restates these (Taipei today default, named-holiday-only weekends), adding no format or syntax detail beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: fetching the next N Taiwan holidays after a given date. The 'next N' framing implicitly separates it from get_holidays_in_range and check_holiday, but no sibling is named explicitly, so an agent must infer the routing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied through the default-date behavior and the skip_weekends option, but the description never states when to prefer this tool over get_holidays_in_range, check_holiday, or get_workdays. No explicit exclusions or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
計算工作天數。指定 year 與 month 可查整月；指定 start_date 與 end_date 可查區間（含起迄日）。週末與假期不計入工作天，補班日（補行上班）計入工作天並另外列出。上游筆數與日曆天數不符時回報錯誤，不會把缺日當成工作天。兩種查法請擇一，不要同時指定。
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | 月份查詢的年份。須與 month 一起使用 | |
| month | No | 月份查詢的月份 (1-12)。須與 year 一起使用 | |
| end_date | No | 區間迄日（含當天）。支援 YYYY-MM-DD 或 YYYYMMDD。須與 start_date 一起使用 | |
| start_date | No | 區間起日（含當天）。支援 YYYY-MM-DD 或 YYYYMMDD。須與 end_date 一起使用 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so well: weekends and holidays are excluded, makeup workdays (補班日) are counted and listed separately, and a mismatch between upstream records and calendar days raises an error rather than silently treating missing days as workdays. It stops short of describing the exact return shape or data-source coverage/limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first clause, followed by mode rules and edge-case semantics; every sentence carries information with no filler. Density is high but the structure remains scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no annotations and no output schema, the description covers mode selection, counting semantics, error behavior, and even notes that makeup workdays are returned separately. What is missing is a fuller picture of the output/return structure, though that is a minor gap given the task's clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the pairing constraints for each parameter; baseline is 3. The description adds the cross-parameter rule that the two modes are mutually exclusive ('不要同時指定'), which the schema does not state, pushing it above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('計算工作天數') and immediately defines the two supported query modes (whole month via year+month, range via start_date+end_date). It is clearly distinguishable from the holiday-oriented siblings (check_holiday, get_next_holidays, etc.) because it describes a counting/aggregation operation rather than a lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use each mode (year+month for a full month, start_date+end_date for a range) and explicitly forbids combining them ('兩種查法請擇一，不要同時指定'). It does not name or compare against alternative tools, so it gives clear context but no exclusions relative to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v3.0.0check_typhoon_closurev2.1.0get_holiday_stats1 field changedInput schema / properties / year / maximumPrevious value: -2026New value: +2031get_next_holidaysget_workdaysv1.0.0get_holiday_stats1 field changedInput schema / properties / year / maximumPrevious value: -2025New value: +2026check_holidayget_holiday_statsget_holidays_in_rangeScored across 6 tools
The tools are mostly distinct: single-date holiday checking, range listing, next-holiday lookup, statistics, workday calculation, and typhoon closures each serve a clear purpose. There is minor overlap between check_holiday and using get_holidays_in_range or get_workdays for a single date, but the descriptions make the intended boundaries reasonably clear.
All tool names use consistent snake_case with a verb_noun structure. The check_ prefix is used for boolean/status-style checks and get_ for retrieval or calculation, which is predictable and readable.
Six tools is well-scoped for a Taiwan holiday server. Each tool covers a distinct common query type, and there is no obvious bloat or missing essential operation at the count level.
The surface covers the main holiday workflows: single-date checks, range queries, statistics, upcoming holidays, workday calculations, and typhoon closures. Minor gaps remain, such as workday calculations not explicitly accounting for typhoon closures and no standalone holiday-by-name lookup, but agents can mostly work around these.
Public holiday data for 30+ countries. Check holidays, working days and calendars via AI assistants.
A Model Context Protocol server for Wix AI tools
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Japanese business days, holiday checks and invoice due dates for your AI agent.
