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。