mcp-datetime 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hong Teoh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# mcp-datetime
+
+MCP server with **10 date & time tools** for LLMs. Timezone conversion, date math, cron explanation, business days, Unix timestamps, and more. Zero dependencies beyond the MCP SDK.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `now` | Current time in multiple timezones |
+| `convert_timezone` | Convert between 60+ timezones (IANA, abbreviations, UTC offsets) |
+| `date_math` | Add/subtract years, months, days, hours, minutes, seconds |
+| `date_diff` | Difference between dates in days, hours, weeks, business days |
+| `format_date` | Format dates with custom tokens (YYYY-MM-DD HH:mm:ss) |
+| `unix_timestamp` | Convert between Unix timestamps and ISO 8601 |
+| `business_days` | Count or add business days (excludes weekends) |
+| `explain_cron` | Explain cron expressions in plain English |
+| `countdown` | Time remaining/elapsed to a target date |
+| `date_info` | Day of week, ISO week, quarter, leap year, day of year |
+
+## Quick Start
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "datetime": {
+      "command": "npx",
+      "args": ["-y", "mcp-datetime"]
+    }
+  }
+}
+```
+
+### Cursor / VS Code
+
+Add to MCP settings:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "datetime": {
+        "command": "npx",
+        "args": ["-y", "mcp-datetime"]
+      }
+    }
+  }
+}
+```
+
+## Supported Timezones
+
+60+ timezones including:
+- **Abbreviations**: UTC, GMT, EST, EDT, CST, CDT, MST, MDT, PST, PDT, CET, CEST, IST, JST, KST, SGT, MYT, AEST, NZST, and more
+- **IANA names**: Asia/Tokyo, America/New_York, Europe/London, Australia/Sydney, etc.
+- **UTC offsets**: +05:30, -08:00, +09, etc.
+
+## Examples
+
+**"What time is it in Tokyo and New York?"**
+→ Uses `now` with `["JST", "EST"]`
+
+**"Add 90 business days to March 1, 2026"**
+→ Uses `business_days` with `operation: "add"`
+
+**"What does `0 */6 * * *` mean?"**
+→ Uses `explain_cron` → "Runs at minute 0 of every 6 hours"
+
+**"How many days until December 25?"**
+→ Uses `countdown` with target date
+
+## Part of the MCP Tools Suite
+
+- [mcp-devutils](https://www.npmjs.com/package/mcp-devutils) — 8 developer utility tools
+- [mcp-apitools](https://www.npmjs.com/package/mcp-apitools) — 7 API & HTTP tools
+- [mcp-texttools](https://www.npmjs.com/package/mcp-texttools) — 8 text processing tools
+- [mcp-mathtools](https://www.npmjs.com/package/mcp-mathtools) — 12 math & statistics tools
+- **mcp-datetime** — 10 date & time tools ← you are here
+- [readmecraft](https://www.npmjs.com/package/readmecraft) — README generator
+
+**55+ MCP tools** across 6 packages. Install any combination you need.
+
+## License
+
+MIT
+
+---
+
+[☕ Buy me a coffee](https://buymeacoffee.com/gl89tu25lp)

package/index.js

@@ -0,0 +1,535 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+const server = new Server(
+  { name: "mcp-datetime", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+// ── Timezone offset database (minutes from UTC) ──
+const TZ_OFFSETS = {
+  UTC: 0, GMT: 0,
+  EST: -300, EDT: -240, CST: -360, CDT: -300, MST: -420, MDT: -360, PST: -480, PDT: -420,
+  "US/Eastern": -300, "US/Central": -360, "US/Mountain": -420, "US/Pacific": -480,
+  CET: 60, CEST: 120, EET: 120, EEST: 180, WET: 0, WEST: 60,
+  IST: 330, JST: 540, KST: 540, CST_ASIA: 480, HKT: 480, SGT: 480, MYT: 480,
+  AEST: 600, AEDT: 660, ACST: 570, ACDT: 630, AWST: 480, NZST: 720, NZDT: 780,
+  BRT: -180, ART: -180, CLT: -240, COT: -300, PET: -300,
+  WAT: 60, CAT: 120, EAT: 180, SAST: 120,
+  GST: 240, PKT: 300, ICT: 420, WIB: 420,
+  "Asia/Tokyo": 540, "Asia/Seoul": 540, "Asia/Shanghai": 480, "Asia/Singapore": 480,
+  "Asia/Kuala_Lumpur": 480, "Asia/Kolkata": 330, "Asia/Dubai": 240, "Asia/Bangkok": 420,
+  "Europe/London": 0, "Europe/Paris": 60, "Europe/Berlin": 60, "Europe/Moscow": 180,
+  "America/New_York": -300, "America/Chicago": -360, "America/Denver": -420,
+  "America/Los_Angeles": -480, "America/Sao_Paulo": -180, "America/Toronto": -300,
+  "Australia/Sydney": 600, "Australia/Melbourne": 600, "Australia/Perth": 480,
+  "Pacific/Auckland": 720, "Pacific/Honolulu": -600,
+};
+
+function getTzOffset(tz) {
+  const key = tz.replace(/\s+/g, "_");
+  if (key in TZ_OFFSETS) return TZ_OFFSETS[key];
+  // Try case-insensitive
+  const upper = key.toUpperCase();
+  for (const [k, v] of Object.entries(TZ_OFFSETS)) {
+    if (k.toUpperCase() === upper) return v;
+  }
+  // Try parsing ±HH:MM or ±HHMM
+  const m = key.match(/^([+-])(\d{1,2}):?(\d{2})?$/);
+  if (m) return (m[1] === "-" ? -1 : 1) * (parseInt(m[2]) * 60 + parseInt(m[3] || "0"));
+  return null;
+}
+
+function formatDate(d, fmt) {
+  const pad = (n, w = 2) => String(n).padStart(w, "0");
+  const tokens = {
+    YYYY: d.getUTCFullYear(),
+    MM: pad(d.getUTCMonth() + 1),
+    DD: pad(d.getUTCDate()),
+    HH: pad(d.getUTCHours()),
+    mm: pad(d.getUTCMinutes()),
+    ss: pad(d.getUTCSeconds()),
+    SSS: pad(d.getUTCMilliseconds(), 3),
+  };
+  let result = fmt;
+  for (const [tok, val] of Object.entries(tokens)) {
+    result = result.replace(new RegExp(tok, "g"), String(val));
+  }
+  return result;
+}
+
+function parseFlexibleDate(input) {
+  if (!input || input.toLowerCase() === "now") return new Date();
+  const d = new Date(input);
+  if (!isNaN(d.getTime())) return d;
+  // Try Unix timestamp (seconds)
+  const num = Number(input);
+  if (!isNaN(num)) {
+    return num > 1e12 ? new Date(num) : new Date(num * 1000);
+  }
+  return null;
+}
+
+function getISOWeek(d) {
+  const date = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+  date.setUTCDate(date.getUTCDate() + 4 - (date.getUTCDay() || 7));
+  const yearStart = new Date(Date.UTC(date.getUTCFullYear(), 0, 1));
+  const weekNo = Math.ceil(((date - yearStart) / 86400000 + 1) / 7);
+  return { year: date.getUTCFullYear(), week: weekNo };
+}
+
+function isWeekend(d) {
+  const day = d.getUTCDay();
+  return day === 0 || day === 6;
+}
+
+const DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+const MONTH_NAMES = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+
+// ── Cron field parser ──
+function describeCronField(field, names) {
+  if (field === "*") return "every";
+  if (field.includes("/")) {
+    const [base, step] = field.split("/");
+    return `every ${step}${base !== "*" ? ` starting at ${names ? names[+base] || base : base}` : ""}`;
+  }
+  if (field.includes(",")) {
+    return field.split(",").map(v => names ? names[+v] || v : v).join(", ");
+  }
+  if (field.includes("-")) {
+    const [a, b] = field.split("-");
+    return `${names ? names[+a] || a : a} through ${names ? names[+b] || b : b}`;
+  }
+  return names ? names[+field] || field : field;
+}
+
+function explainCron(expr) {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length < 5 || parts.length > 6) return "Invalid cron expression (expected 5 or 6 fields)";
+  const [minute, hour, dom, month, dow] = parts;
+  const monthNames = { 1: "Jan", 2: "Feb", 3: "Mar", 4: "Apr", 5: "May", 6: "Jun", 7: "Jul", 8: "Aug", 9: "Sep", 10: "Oct", 11: "Nov", 12: "Dec" };
+  const dayNames = { 0: "Sun", 1: "Mon", 2: "Tue", 3: "Wed", 4: "Thu", 5: "Fri", 6: "Sat", 7: "Sun" };
+
+  const lines = [];
+  lines.push(`Minute: ${describeCronField(minute)}`);
+  lines.push(`Hour: ${describeCronField(hour)}`);
+  lines.push(`Day of month: ${describeCronField(dom)}`);
+  lines.push(`Month: ${describeCronField(month, monthNames)}`);
+  lines.push(`Day of week: ${describeCronField(dow, dayNames)}`);
+
+  // Human summary
+  let summary = "Runs ";
+  if (minute === "*" && hour === "*") summary += "every minute";
+  else if (minute === "0" && hour === "*") summary += "every hour";
+  else if (minute !== "*" && hour !== "*" && !hour.includes("/") && !hour.includes(",")) {
+    summary += `at ${hour.padStart(2, "0")}:${minute.padStart(2, "0")}`;
+  } else {
+    summary += `at minute ${describeCronField(minute)} of hour ${describeCronField(hour)}`;
+  }
+  if (dom !== "*") summary += `, on day ${describeCronField(dom)} of the month`;
+  if (month !== "*") summary += `, in ${describeCronField(month, monthNames)}`;
+  if (dow !== "*") summary += `, on ${describeCronField(dow, dayNames)}`;
+  lines.push(`\nSummary: ${summary}`);
+  return lines.join("\n");
+}
+
+// ── Tool definitions ──
+const tools = [
+  {
+    name: "now",
+    description: "Get the current date and time in one or more timezones. Returns ISO 8601, Unix timestamp, and human-readable format.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        timezones: {
+          type: "array", items: { type: "string" },
+          description: "Timezones to show (e.g. ['UTC', 'PST', 'Asia/Tokyo']). Default: ['UTC']"
+        }
+      }
+    }
+  },
+  {
+    name: "convert_timezone",
+    description: "Convert a date/time from one timezone to another.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        datetime: { type: "string", description: "Date/time string (ISO 8601 or flexible). Use 'now' for current time." },
+        from_tz: { type: "string", description: "Source timezone (e.g. 'PST', 'Asia/Tokyo', '+05:30')" },
+        to_tz: { type: "string", description: "Target timezone" }
+      },
+      required: ["datetime", "from_tz", "to_tz"]
+    }
+  },
+  {
+    name: "date_math",
+    description: "Add or subtract time from a date. Supports years, months, days, hours, minutes, seconds.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        date: { type: "string", description: "Starting date (ISO 8601 or 'now')" },
+        add: {
+          type: "object",
+          description: "Time to add (use negative values to subtract)",
+          properties: {
+            years: { type: "number" }, months: { type: "number" }, days: { type: "number" },
+            hours: { type: "number" }, minutes: { type: "number" }, seconds: { type: "number" }
+          }
+        }
+      },
+      required: ["date", "add"]
+    }
+  },
+  {
+    name: "date_diff",
+    description: "Calculate the difference between two dates in multiple units (days, hours, minutes, seconds, weeks, business days).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "Start date (ISO 8601 or 'now')" },
+        to: { type: "string", description: "End date (ISO 8601 or 'now')" }
+      },
+      required: ["from", "to"]
+    }
+  },
+  {
+    name: "format_date",
+    description: "Format a date/time using a format string. Tokens: YYYY, MM, DD, HH, mm, ss, SSS.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        date: { type: "string", description: "Date to format (ISO 8601, unix timestamp, or 'now')" },
+        format: { type: "string", description: "Format string, e.g. 'YYYY-MM-DD HH:mm:ss'" }
+      },
+      required: ["date", "format"]
+    }
+  },
+  {
+    name: "unix_timestamp",
+    description: "Convert between Unix timestamps and ISO 8601 dates. Pass a timestamp to get ISO, or a date to get timestamp.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        value: { type: "string", description: "Unix timestamp (seconds or ms) OR ISO date string OR 'now'" }
+      },
+      required: ["value"]
+    }
+  },
+  {
+    name: "business_days",
+    description: "Calculate business days between two dates, or add N business days to a date. Excludes weekends (Sat/Sun).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        operation: { type: "string", enum: ["between", "add"], description: "'between': count business days. 'add': add N business days to start." },
+        start: { type: "string", description: "Start date" },
+        end: { type: "string", description: "End date (for 'between' operation)" },
+        days: { type: "number", description: "Number of business days to add (for 'add' operation)" }
+      },
+      required: ["operation", "start"]
+    }
+  },
+  {
+    name: "explain_cron",
+    description: "Explain a cron expression in plain English. Supports standard 5-field cron format (minute hour dom month dow).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        expression: { type: "string", description: "Cron expression, e.g. '0 9 * * 1-5' or '*/15 * * * *'" }
+      },
+      required: ["expression"]
+    }
+  },
+  {
+    name: "countdown",
+    description: "Calculate time remaining until a target date, or time elapsed since a past date.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: { type: "string", description: "Target date (ISO 8601)" },
+        from: { type: "string", description: "Reference date (default: now)" }
+      },
+      required: ["target"]
+    }
+  },
+  {
+    name: "date_info",
+    description: "Get detailed information about a date: day of week, ISO week number, day of year, leap year, quarter, and more.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        date: { type: "string", description: "Date to analyze (ISO 8601 or 'now')" }
+      },
+      required: ["date"]
+    }
+  }
+];
+
+// ── Tool handlers ──
+function handleNow(args) {
+  const now = new Date();
+  const zones = args.timezones || ["UTC"];
+  const results = {};
+  for (const tz of zones) {
+    const offset = getTzOffset(tz);
+    if (offset === null) { results[tz] = "Unknown timezone"; continue; }
+    const local = new Date(now.getTime() + offset * 60000);
+    results[tz] = {
+      iso: local.toISOString().replace("Z", offset === 0 ? "Z" : `${offset >= 0 ? "+" : "-"}${String(Math.floor(Math.abs(offset) / 60)).padStart(2, "0")}:${String(Math.abs(offset) % 60).padStart(2, "0")}`),
+      human: `${DAY_NAMES[local.getUTCDay()]}, ${MONTH_NAMES[local.getUTCMonth()]} ${local.getUTCDate()}, ${local.getUTCFullYear()} ${String(local.getUTCHours()).padStart(2, "0")}:${String(local.getUTCMinutes()).padStart(2, "0")}:${String(local.getUTCSeconds()).padStart(2, "0")}`,
+      unix: Math.floor(now.getTime() / 1000),
+      offset_hours: offset / 60
+    };
+  }
+  return results;
+}
+
+function handleConvertTimezone(args) {
+  const fromOff = getTzOffset(args.from_tz);
+  const toOff = getTzOffset(args.to_tz);
+  if (fromOff === null) return { error: `Unknown source timezone: ${args.from_tz}` };
+  if (toOff === null) return { error: `Unknown target timezone: ${args.to_tz}` };
+
+  const d = parseFlexibleDate(args.datetime);
+  if (!d) return { error: `Cannot parse date: ${args.datetime}` };
+
+  // Convert: input is in from_tz, so UTC = input - fromOff, then target = UTC + toOff
+  const utcMs = d.getTime() - fromOff * 60000;
+  const targetMs = utcMs + toOff * 60000;
+  const target = new Date(targetMs);
+
+  return {
+    original: { datetime: d.toISOString(), timezone: args.from_tz },
+    converted: {
+      datetime: formatDate(target, "YYYY-MM-DDTHH:mm:ss"),
+      timezone: args.to_tz,
+      day: DAY_NAMES[target.getUTCDay()]
+    },
+    offset_difference_hours: (toOff - fromOff) / 60
+  };
+}
+
+function handleDateMath(args) {
+  const d = parseFlexibleDate(args.date);
+  if (!d) return { error: `Cannot parse date: ${args.date}` };
+  const a = args.add || {};
+
+  const result = new Date(d);
+  if (a.years) result.setUTCFullYear(result.getUTCFullYear() + a.years);
+  if (a.months) result.setUTCMonth(result.getUTCMonth() + a.months);
+  if (a.days) result.setUTCDate(result.getUTCDate() + a.days);
+  if (a.hours) result.setUTCHours(result.getUTCHours() + a.hours);
+  if (a.minutes) result.setUTCMinutes(result.getUTCMinutes() + a.minutes);
+  if (a.seconds) result.setUTCSeconds(result.getUTCSeconds() + a.seconds);
+
+  return {
+    original: d.toISOString(),
+    added: a,
+    result: result.toISOString(),
+    day: DAY_NAMES[result.getUTCDay()]
+  };
+}
+
+function handleDateDiff(args) {
+  const from = parseFlexibleDate(args.from);
+  const to = parseFlexibleDate(args.to);
+  if (!from) return { error: `Cannot parse 'from' date: ${args.from}` };
+  if (!to) return { error: `Cannot parse 'to' date: ${args.to}` };
+
+  const diffMs = to.getTime() - from.getTime();
+  const diffSec = diffMs / 1000;
+  const diffMin = diffSec / 60;
+  const diffHr = diffMin / 60;
+  const diffDays = diffHr / 24;
+
+  // Count business days
+  let bizDays = 0;
+  const step = diffMs >= 0 ? 1 : -1;
+  const start = new Date(Math.min(from.getTime(), to.getTime()));
+  const end = new Date(Math.max(from.getTime(), to.getTime()));
+  const cursor = new Date(start);
+  while (cursor < end) {
+    if (!isWeekend(cursor)) bizDays++;
+    cursor.setUTCDate(cursor.getUTCDate() + 1);
+  }
+  if (diffMs < 0) bizDays = -bizDays;
+
+  return {
+    from: from.toISOString(),
+    to: to.toISOString(),
+    difference: {
+      days: Math.round(diffDays * 100) / 100,
+      hours: Math.round(diffHr * 100) / 100,
+      minutes: Math.round(diffMin),
+      seconds: Math.round(diffSec),
+      weeks: Math.round(diffDays / 7 * 100) / 100,
+      business_days: bizDays
+    }
+  };
+}
+
+function handleFormatDate(args) {
+  const d = parseFlexibleDate(args.date);
+  if (!d) return { error: `Cannot parse date: ${args.date}` };
+  return { original: d.toISOString(), formatted: formatDate(d, args.format), format: args.format };
+}
+
+function handleUnixTimestamp(args) {
+  const val = args.value;
+  // Try as number (unix timestamp)
+  const num = Number(val);
+  if (!isNaN(num) && val !== "" && val.toLowerCase() !== "now") {
+    const isMs = num > 1e12;
+    const ms = isMs ? num : num * 1000;
+    const d = new Date(ms);
+    return {
+      input: val,
+      interpreted_as: isMs ? "milliseconds" : "seconds",
+      unix_seconds: Math.floor(ms / 1000),
+      unix_milliseconds: ms,
+      iso: d.toISOString(),
+      human: `${DAY_NAMES[d.getUTCDay()]}, ${MONTH_NAMES[d.getUTCMonth()]} ${d.getUTCDate()}, ${d.getUTCFullYear()} ${String(d.getUTCHours()).padStart(2, "0")}:${String(d.getUTCMinutes()).padStart(2, "0")}:${String(d.getUTCSeconds()).padStart(2, "0")} UTC`
+    };
+  }
+  // Try as date string
+  const d = parseFlexibleDate(val);
+  if (!d) return { error: `Cannot parse: ${val}` };
+  return {
+    input: val,
+    unix_seconds: Math.floor(d.getTime() / 1000),
+    unix_milliseconds: d.getTime(),
+    iso: d.toISOString(),
+    human: `${DAY_NAMES[d.getUTCDay()]}, ${MONTH_NAMES[d.getUTCMonth()]} ${d.getUTCDate()}, ${d.getUTCFullYear()} ${String(d.getUTCHours()).padStart(2, "0")}:${String(d.getUTCMinutes()).padStart(2, "0")}:${String(d.getUTCSeconds()).padStart(2, "0")} UTC`
+  };
+}
+
+function handleBusinessDays(args) {
+  const start = parseFlexibleDate(args.start);
+  if (!start) return { error: `Cannot parse start date: ${args.start}` };
+
+  if (args.operation === "between") {
+    if (!args.end) return { error: "End date required for 'between' operation" };
+    const end = parseFlexibleDate(args.end);
+    if (!end) return { error: `Cannot parse end date: ${args.end}` };
+    let count = 0;
+    const cursor = new Date(start);
+    while (cursor < end) {
+      if (!isWeekend(cursor)) count++;
+      cursor.setUTCDate(cursor.getUTCDate() + 1);
+    }
+    return { start: start.toISOString(), end: end.toISOString(), business_days: count };
+  }
+
+  if (args.operation === "add") {
+    let remaining = args.days || 0;
+    const cursor = new Date(start);
+    const step = remaining >= 0 ? 1 : -1;
+    remaining = Math.abs(remaining);
+    while (remaining > 0) {
+      cursor.setUTCDate(cursor.getUTCDate() + step);
+      if (!isWeekend(cursor)) remaining--;
+    }
+    return {
+      start: start.toISOString(),
+      days_added: args.days,
+      result: cursor.toISOString(),
+      day: DAY_NAMES[cursor.getUTCDay()]
+    };
+  }
+
+  return { error: `Unknown operation: ${args.operation}` };
+}
+
+function handleExplainCron(args) {
+  return { expression: args.expression, explanation: explainCron(args.expression) };
+}
+
+function handleCountdown(args) {
+  const target = parseFlexibleDate(args.target);
+  if (!target) return { error: `Cannot parse target date: ${args.target}` };
+  const from = args.from ? parseFlexibleDate(args.from) : new Date();
+  if (!from) return { error: `Cannot parse from date: ${args.from}` };
+
+  const diffMs = target.getTime() - from.getTime();
+  const isPast = diffMs < 0;
+  const abs = Math.abs(diffMs);
+
+  const days = Math.floor(abs / 86400000);
+  const hours = Math.floor((abs % 86400000) / 3600000);
+  const minutes = Math.floor((abs % 3600000) / 60000);
+  const seconds = Math.floor((abs % 60000) / 1000);
+
+  return {
+    target: target.toISOString(),
+    from: from.toISOString(),
+    direction: isPast ? "elapsed" : "remaining",
+    breakdown: { days, hours, minutes, seconds },
+    human: `${days}d ${hours}h ${minutes}m ${seconds}s ${isPast ? "ago" : "remaining"}`,
+    total_days: Math.round(abs / 86400000 * 100) / 100
+  };
+}
+
+function handleDateInfo(args) {
+  const d = parseFlexibleDate(args.date);
+  if (!d) return { error: `Cannot parse date: ${args.date}` };
+
+  const year = d.getUTCFullYear();
+  const isLeap = (year % 4 === 0 && year % 100 !== 0) || (year % 400 === 0);
+  const startOfYear = new Date(Date.UTC(year, 0, 1));
+  const dayOfYear = Math.floor((d.getTime() - startOfYear.getTime()) / 86400000) + 1;
+  const daysInYear = isLeap ? 366 : 365;
+  const isoWeek = getISOWeek(d);
+  const quarter = Math.ceil((d.getUTCMonth() + 1) / 3);
+
+  return {
+    date: d.toISOString(),
+    day_of_week: DAY_NAMES[d.getUTCDay()],
+    day_of_year: dayOfYear,
+    days_remaining_in_year: daysInYear - dayOfYear,
+    iso_week: `${isoWeek.year}-W${String(isoWeek.week).padStart(2, "0")}`,
+    quarter: `Q${quarter}`,
+    is_leap_year: isLeap,
+    is_weekend: isWeekend(d),
+    month_name: MONTH_NAMES[d.getUTCMonth()],
+    days_in_month: new Date(Date.UTC(year, d.getUTCMonth() + 1, 0)).getUTCDate(),
+    unix_timestamp: Math.floor(d.getTime() / 1000)
+  };
+}
+
+const handlers = {
+  now: handleNow,
+  convert_timezone: handleConvertTimezone,
+  date_math: handleDateMath,
+  date_diff: handleDateDiff,
+  format_date: handleFormatDate,
+  unix_timestamp: handleUnixTimestamp,
+  business_days: handleBusinessDays,
+  explain_cron: handleExplainCron,
+  countdown: handleCountdown,
+  date_info: handleDateInfo,
+};
+
+// ── MCP handlers ──
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const handler = handlers[name];
+  if (!handler) {
+    return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+  }
+  try {
+    const result = handler(args || {});
+    if (result.error) {
+      return { content: [{ type: "text", text: `Error: ${result.error}` }], isError: true };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  } catch (err) {
+    return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "mcp-datetime",
+  "version": "1.0.0",
+  "description": "MCP server with 10 date & time tools — timezone conversion, date math, formatting, parsing, cron explanation, countdown, unix timestamps, business days, ISO weeks, and relative time. Zero dependencies beyond MCP SDK.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "mcp-datetime": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "datetime",
+    "timezone",
+    "date",
+    "time",
+    "cron",
+    "timestamp",
+    "unix-time",
+    "business-days",
+    "date-math",
+    "claude",
+    "cursor",
+    "ai-tools",
+    "llm-tools",
+    "date-formatting"
+  ],
+  "author": "Hong Teoh",
+  "license": "MIT",
+  "funding": {
+    "type": "buymeacoffee",
+    "url": "https://buymeacoffee.com/gl89tu25lp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}