MCP Time Workdays Node

🚀 MCP Time & Workdays (Node)

Model Context Protocol (MCP) をベースにした Node サーバーを提供します。

• 指定したタイムゾーンの現在時刻を取得します（フォーマットをカスタマイズ可能）。
• 特定の年と月の公式の平日、休日、振替出勤日を取得します（複数のデータソースから）。

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

✨ 主な機能

• オンラインデータソース（無料）：
  • Timor 年集約インターフェイス（デフォルト）
  • 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 が設定されています。

💻 使用例

基本的な使用法

サーバーが起動すると、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[]
• ロジック：
  • 平日 = 「当月のすべての月曜日から金曜日 - 公式休日 + 公式振替出勤日の土日」

高度な使用法

以下はコマンドラインからの模擬呼び出し方法を示しています（例のみ）。

# 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 に追加したり、より多くのデータソース（API Key 付きの商用 API など）を追加したい場合は、Issue/PR を投稿してください。