MCP Time Workdays Node

🚀 MCP Time & Workdays (Node)

This project provides a Node server based on the Model Context Protocol (MCP), offering the following capabilities:

• Retrieve the current time in a specified time zone with customizable formatting.
• Obtain official workdays, holidays, and makeup workdays for a given year and month from multiple data sources.

The default online data source is the Timor annual aggregation API. Additionally, NateScarlet holiday-cn (GitHub Raw) is supported as a free alternative, requiring no API Key.

🚀 Quick Start

This Node server offers convenient ways to get started, whether you prefer a quick setup or local development.

✨ Features

• Online Data Sources (Free):
  • Timor annual aggregation API (default).
  • NateScarlet holiday-cn (GitHub Raw, with built-in CDN fallback).
• Unified Output: Clearly distinguish workdays (workdays), holidays (holidays), and makeup workdays (makeup_workdays).
• MCP Compatibility: All tool outputs are encapsulated as MCP text content, ensuring compatibility with strict clients.
• Native Execution: Runs natively on Node 18+ without additional dependencies (except the MCP SDK).

📦 Installation

Method 1: NPX (Recommended)

# Global installation
npm install -g mcp-time-workdays-node

# Or use npx directly
npx mcp-time-workdays-node

Method 2: Local Development

# Clone the project
git clone https://github.com/tanranv5/mcp_time_workdays_node.git
cd mcp-time-workdays-node

# Install dependencies
npm install

# Run the server
node mcp_time_workdays_node.mjs
# Or
npm start

Tip: The package.json of this project is configured with type: module and has a minimal dependency on @modelcontextprotocol/sdk.

💻 Usage Examples

MCP Tools

After the server starts, the following tools are exposed via stdio:

1. get_current_time

• Input:
  • tz: IANA time zone name or local (default: local).
  • fmt: Time format, default is %Y-%m-%d %H:%M:%S%z.
• Output: text (string).
• Example Output: 2025-09-10 10:30:45+08:00

2. get_workdays_from_api

• Input:
  • year: Integer (default: current year).
  • month: 1 - 12 (default: current month).
  • tz: local or IANA time zone name (default: local, only used to get the "current year and month").
  • provider: timor (default) or nate.
  • timeout: Timeout in seconds (default: 8.0).
• Output: text (JSON string):
  • provider, year, month, workdays[], holidays[], makeup_workdays[]
• Logic:
  • Workdays = "All Mondays to Fridays in the month - Official holidays + Official makeup workdays on weekends"

Example: Manual Invocation (Simulating MCP Client Logic)

The following shows how to simulate an invocation from the command line (example only):

# Get October 2025 (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"}}}'

In actual use, let an MCP-compatible client (e.g., Claude Desktop) connect via stdio.

Client Configuration Example (Claude Desktop)

NPX Method (Recommended)

Add the following to claude_desktop_config.json (or equivalent):

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

Local Development Method

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

📚 Documentation

Data Source Explanation

• timor (Default):

  • Annual aggregation API: https://timor.tech/api/holiday/year/{year}
  • The response fields include a holiday mapping: { 'MM-DD': { date, holiday, name, ... } }
  • Usage: Filter items for the current month from the mapping; holiday=true indicates a holiday; holiday=false and name containing "makeup workday" indicates a makeup workday.

• nate:

  • Annual file (GitHub Raw): https://raw.githubusercontent.com/NateScarlet/holiday-cn/master/{year}.json
  • Built-in CDN fallback: https://cdn.jsdelivr.net/gh/NateScarlet/holiday-cn@master/{year}.json
  • In days[], isOffDay=true means a holiday; isOffDay=false for weekends indicates a makeup workday.

Note: Data sources not recommended for "makeup workday" determination (e.g., Nager.Date) are not built-in.

🔧 Technical Details

Frequently Asked Questions

• Output as text: To enhance compatibility with MCP clients, this service uniformly returns text-type content (JSON strings or plain text).
• Time Zone Parameter tz: Only affects the determination of the "default year and month" and does not impact workday calculations (workdays are calculated according to local/official rules).
• Timeout timeout: Measured in seconds. Increase it appropriately during network fluctuations.

📄 License

Acknowledgments

• Timor annual aggregation API: https://timor.tech/
• NateScarlet holiday-cn: https://github.com/NateScarlet/holiday-cn
• Model Context Protocol: https://github.com/modelcontextprotocol

If you want to add the CLI to npm bin or include more data sources (e.g., commercial APIs with keys), feel free to submit an Issue/PR.