Mcp_time_workdays_node

MCP Time & Workdays (Node)

Model Context Protocol（MCP）に基づく Node サーバーを提供します：

• 指定したタイムゾーンの現在時刻を取得します（書式はカスタマイズ可能）
• 指定した年月の公式営業日、祝日、振替出勤日を取得します（複数のデータソース）

デフォルトのオンラインデータソースは Timor 年別集約 API です。無料の代替手段として NateScarlet holiday-cn（GitHub Raw）もサポートしており、API Key は不要です。

---

特長

• オンラインデータソース（無料）：
  • Timor 年別集約 API（デフォルト）
  • NateScarlet holiday-cn（GitHub Raw、CDN フォールバック内蔵）
• 出力を統一：営業日(workdays)、祝日(holidays)、振替出勤日(makeup_workdays)
• ツールの出力はすべて MCP text コンテンツでラップされ、厳格なクライアントと互換性があります
• Node 18+ でネイティブ実行可能。追加の依存関係は不要です（MCP SDK を除く）

環境とインストール

• 要件：Node.js >= 18.17

方法 1：NPX（推奨）

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

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

方法 2：ローカル開発

# 克隆项目
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 が設定されています。

MCP ツール

サーバーの起動後、stdio 経由で以下のツールを公開します：

1. get_current_time

• 入力：
  • tz：IANA タイムゾーン名または local（デフォルトは local）
  • fmt：時刻の書式。デフォルトは%Y-%m-%d %H:%M:%S%z
• 出力：text（文字列）
• 出力例：2025-09-10 10:30:45+08:00

2. 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"}}}'

実際に使用する際は、Claude Desktop などの MCP 互換クライアントから 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（デフォルト）：

  • 年別集約 API：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 年別集約 API：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 をお寄せください。