MCP Time Workdays Node

🚀 MCP 時間與工作日（Node 版）

本項目提供一個基於 Model Context Protocol (MCP) 的 Node 服務器，具備以下功能：

• 可獲取指定時區的當前時間，且支持自定義時間格式。
• 能獲取某年某月的官方工作日、假期與補班信息，支持多數據源。

默認在線數據源為 Timor 年聚合接口，同時額外支持 NateScarlet holiday-cn（GitHub Raw）作為免費備選，無需 API Key。

🚀 快速開始

本項目要求 Node.js 版本 >= 18.17。以下為你提供兩種安裝和使用方式：

📦 安裝指南

方式一：NPX（推薦）

# 全局安裝
npm install -g mcp-time-workdays-node

# 或直接使用 npx
npx mcp-time-workdays-node

方式二：本地開發

# 克隆項目
git clone https://github.com/tanranv5/mcp_time_workdays_node.git
cd mcp-time-workdays-node

# 安裝依賴
npm install

# 運行服務器
node mcp_time_workdays_node.mjs
# 或
npm start

提示：本項目 package.json 已設定 type: module 與最小依賴 @modelcontextprotocol/sdk。

✨ 主要特性

• 在線數據源（免費）：
  • Timor 年聚合接口（默認）
  • NateScarlet holiday-cn（GitHub Raw，內置 CDN 兜底）
• 統一輸出：工作日(workdays)、假期(holidays)、補班(makeup_workdays)
• 工具輸出統一封裝：為 MCP text 內容，兼容嚴格客戶端
• 原生運行：Node 18+ 原生運行，無需額外依賴（除 MCP SDK）

💻 使用示例

服務器啟動後會通過 stdio 暴露以下工具：

基礎用法

get_current_time

• 輸入：
  • tz：IANA 時區名或 local（默認 local）
  • fmt：時間格式，默認%Y-%m-%d %H:%M:%S%z
• 輸出：text（字符串）
• 示例輸出：2025-09-10 10:30:45+08:00

get_workdays_from_api

• 輸入：
  • year：整數（默認當前年）
  • month：1 - 12（默認當前月）
  • tz：local 或 IANA 時區名（默認 local，僅用於獲取“當前年月”）
  • provider：timor（默認）或 nate
  • timeout：超時秒數（默認 8.0）
• 輸出：text（JSON 字符串）：
  • provider, year, month, workdays[], holidays[], makeup_workdays[]
• 邏輯：
  • 工作日 = “當月所有周一至週五 - 官方假期 + 官方補班週末”

高級用法

例：手動調用（模擬 MCP 客戶端邏輯）

以下展示從命令行模擬調用的方式（僅示例）：

# 獲取 2025 - 10 月（Timor）
node -e "(async()=>{const s=await import('./mcp_time_workdays_node.mjs');})();" \
| echo '{"method":"tools/call","params":{"name":"get_workdays_from_api","arguments":{"year":2025,"month":10,"provider":"timor"}}}'

實際使用中，請讓 MCP 兼容的客戶端（如 Claude Desktop）通過 stdio 連接。

📚 詳細文檔

客戶端配置示例（Claude Desktop）

NPX 方式（推薦）

在 claude_desktop_config.json（或等效位置）中添加：

{
  "mcpServers": {
    "time-and-workdays-node": {
      "command": "npx",
      "args": ["mcp-time-workdays-node"],
      "env": {}
    }
  }
}

本地開發方式

{
  "mcpServers": {
    "time-and-workdays-node": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_time_workdays_node.mjs"],
      "env": {}
    }
  }
}

數據源說明

• timor（默認）：

  • 年聚合接口：https://timor.tech/api/holiday/year/{year}
  • 響應字段包含 holiday 映射：{ 'MM-DD': { date, holiday, name, ... } }
  • 使用方式：從映射中過濾當月項；holiday=true 視為放假；holiday=false 且 name 包含“補班”視為補班

• nate：

  • 年文件（GitHub Raw）：https://raw.githubusercontent.com/NateScarlet/holiday-cn/master/{year}.json
  • 內置 CDN 兜底：https://cdn.jsdelivr.net/gh/NateScarlet/holiday-cn@master/{year}.json
  • days[] 內 isOffDay=true 為放假；isOffDay=false 若對應週末則視為補班

備註：不推薦用於“補班”判斷的數據源（例如 Nager.Date）未內置。

🔧 技術細節

常見問題

• 輸出是 text：為提升 MCP 客戶端兼容性，本服務統一返回 text 類型內容（JSON 字符串或純文本）。
• 時區參數 tz：僅影響“默認年月”的判定，不影響工作日計算（工作日按本地/官方規則計算）。
• 超時 timeout：單位秒。網絡波動時可適當增大。

📄 許可證

本項目未提及許可證相關信息。

致謝

• Timor 年聚合接口：https://timor.tech/
• NateScarlet holiday-cn：https://github.com/NateScarlet/holiday-cn
• Model Context Protocol：https://github.com/modelcontextprotocol

如需把 CLI 也加入 npm bin 或增加更多數據源（例如帶 Key 的商業 API），歡迎提 Issue/PR。