@iflow-mcp/joshuaboys-datetime-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 joshuaboys
+
+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,125 @@
+# datetime-mcp
+
+A lightweight MCP (Model Context Protocol) server that provides date/time tools via stdio transport.
+
+## Installation
+
+```bash
+npm install -g datetime-mcp
+```
+
+Or use directly with npx:
+
+```bash
+npx datetime-mcp
+```
+
+## Tools
+
+### datetime.now
+
+Returns the current date/time from the host OS clock.
+
+**Parameters:**
+- `tz` (optional): IANA timezone string (e.g., `Australia/Perth`, `America/New_York`)
+
+**Returns:**
+```json
+{
+  "tz": "Australia/Perth",
+  "utcIso": "2026-01-22T03:30:00.000Z",
+  "epochMs": 1737516600000,
+  "human": "Thu, 22 Jan 2026, 11:30:00 AWST"
+}
+```
+
+### datetime.health
+
+Returns server health information including monotonic time (won't jump with NTP adjustments).
+
+**Returns:**
+```json
+{
+  "wallEpochMs": 1737516600000,
+  "monotonicMs": 12345678,
+  "processUptimeMs": 5000
+}
+```
+
+### datetime.parse
+
+Parses a date/time string and returns canonical forms.
+
+**Parameters:**
+- `value` (required): A date/time string parseable by JavaScript's `Date` constructor
+- `tz` (optional): IANA timezone for human-readable output
+
+**Returns:**
+```json
+{
+  "input": "2026-01-22",
+  "tz": "Australia/Perth",
+  "utcIso": "2026-01-22T00:00:00.000Z",
+  "epochMs": 1737504000000,
+  "human": "Thu, 22 Jan 2026, 08:00:00 AWST"
+}
+```
+
+## Configuration
+
+### Claude Code / Claude Desktop
+
+Add to your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "datetime": {
+      "command": "npx",
+      "args": ["-y", "datetime-mcp"],
+      "env": {
+        "MCP_TZ": "Australia/Perth"
+      }
+    }
+  }
+}
+```
+
+Or with global install:
+
+```json
+{
+  "mcpServers": {
+    "datetime": {
+      "command": "datetime-mcp",
+      "env": {
+        "MCP_TZ": "Australia/Perth"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+- `MCP_TZ`: Default IANA timezone (defaults to `Australia/Perth`)
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run in development mode
+pnpm dev
+
+# Build
+pnpm build
+
+# Start built server
+pnpm start
+```
+
+## License
+
+MIT

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const DEFAULT_TZ = process.env.MCP_TZ?.trim() || "Australia/Perth";
+function formatHuman(date, tz) {
+    // Uses the runtime's Intl/ICU timezone database to render in a specific IANA timezone.
+    try {
+        return new Intl.DateTimeFormat("en-GB", {
+            timeZone: tz,
+            weekday: "short",
+            year: "numeric",
+            month: "short",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            second: "2-digit",
+            hour12: false,
+            timeZoneName: "short",
+        }).format(date);
+    }
+    catch (err) {
+        if (err instanceof RangeError) {
+            throw new Error(`Invalid IANA timezone: ${tz}`);
+        }
+        throw err;
+    }
+}
+function nowPayload(tz) {
+    const d = new Date(); // <-- comes from the host OS clock
+    return {
+        tz,
+        utcIso: d.toISOString(),
+        epochMs: d.getTime(),
+        human: formatHuman(d, tz),
+    };
+}
+const MAX_INPUT_LENGTH_FOR_ERROR = 200;
+function formatInputForError(value) {
+    // Normalize whitespace to keep logs readable and bounded.
+    const normalized = value.replace(/\s+/g, " ").trim();
+    if (normalized.length <= MAX_INPUT_LENGTH_FOR_ERROR) {
+        return normalized;
+    }
+    return (normalized.slice(0, MAX_INPUT_LENGTH_FOR_ERROR) +
+        `… [truncated, original length=${normalized.length}]`);
+}
+function parsePayload(value, tz) {
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime())) {
+        throw new Error(`Unable to parse date value: ${formatInputForError(value)}`);
+    }
+    return {
+        input: value,
+        tz,
+        utcIso: d.toISOString(),
+        epochMs: d.getTime(),
+        human: formatHuman(d, tz),
+    };
+}
+function healthPayload() {
+    // Monotonic time (won't jump backwards/forwards with NTP clock changes)
+    const monotonicMs = Number(process.hrtime.bigint() / 1000000n);
+    const wallEpochMs = Date.now();
+    const processUptimeMs = Math.round(process.uptime() * 1000);
+    return { wallEpochMs, monotonicMs, processUptimeMs };
+}
+async function main() {
+    const server = new McpServer({
+        name: "datetime-mcp",
+        version: "0.1.0",
+    });
+    server.tool("datetime.now", {
+        tz: z.string().optional().describe("IANA timezone, e.g. Australia/Perth"),
+    }, async ({ tz }) => {
+        const zone = tz || DEFAULT_TZ;
+        const payload = nowPayload(zone);
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        };
+    });
+    server.tool("datetime.health", {}, async () => {
+        const payload = healthPayload();
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        };
+    });
+    server.tool("datetime.parse", {
+        value: z.string().describe("A date/time string parseable by JS Date"),
+        tz: z.string().optional().describe("IANA timezone, e.g. Australia/Perth"),
+    }, async ({ value, tz }) => {
+        const zone = tz || DEFAULT_TZ;
+        const payload = parsePayload(value, zone);
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr is safe for logs under stdio transport (clients may show/ignore it)
+    console.error(`datetime-mcp running (default TZ=${DEFAULT_TZ}) via stdio`);
+}
+main().catch((err) => {
+    console.error("datetime-mcp fatal error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1 @@
+{"name": "@iflow-mcp/joshuaboys-datetime-mcp", "version": "0.1.0", "description": "MCP server that returns current date/time information via stdio transport", "type": "module", "main": "dist/server.js", "types": "dist/server.d.ts", "license": "MIT", "author": "joshuaboys", "repository": {"type": "git", "url": "git+https://github.com/joshuaboys/datetime-mcp.git"}, "homepage": "https://github.com/joshuaboys/datetime-mcp#readme", "bugs": {"url": "https://github.com/joshuaboys/datetime-mcp/issues"}, "keywords": ["mcp", "model-context-protocol", "datetime", "time", "timezone", "claude", "anthropic"], "engines": {"node": ">=18.0.0"}, "files": ["dist", "src", "LICENSE"], "bin": {"iflow-mcp_joshuaboys-datetime-mcp": "dist/server.js"}, "scripts": {"build": "tsc -p tsconfig.json", "start": "node dist/server.js", "dev": "tsx src/server.ts", "prepublishOnly": "pnpm run build"}, "dependencies": {"@modelcontextprotocol/sdk": "^1.0.0", "zod": "^3.25.0"}, "devDependencies": {"@types/node": "^22.0.0", "tsx": "^4.0.0", "typescript": "^5.0.0"}}

package/src/server.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const DEFAULT_TZ = process.env.MCP_TZ?.trim() || "Australia/Perth";
+
+function formatHuman(date: Date, tz: string): string {
+  // Uses the runtime's Intl/ICU timezone database to render in a specific IANA timezone.
+  try {
+    return new Intl.DateTimeFormat("en-GB", {
+      timeZone: tz,
+      weekday: "short",
+      year: "numeric",
+      month: "short",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hour12: false,
+      timeZoneName: "short",
+    }).format(date);
+  } catch (err) {
+    if (err instanceof RangeError) {
+      throw new Error(`Invalid IANA timezone: ${tz}`);
+    }
+    throw err;
+  }
+}
+
+function nowPayload(tz: string) {
+  const d = new Date(); // <-- comes from the host OS clock
+  return {
+    tz,
+    utcIso: d.toISOString(),
+    epochMs: d.getTime(),
+    human: formatHuman(d, tz),
+  };
+}
+
+const MAX_INPUT_LENGTH_FOR_ERROR = 200;
+
+function formatInputForError(value: string): string {
+  // Normalize whitespace to keep logs readable and bounded.
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (normalized.length <= MAX_INPUT_LENGTH_FOR_ERROR) {
+    return normalized;
+  }
+  return (
+    normalized.slice(0, MAX_INPUT_LENGTH_FOR_ERROR) +
+    `… [truncated, original length=${normalized.length}]`
+  );
+}
+
+function parsePayload(value: string, tz: string) {
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) {
+    throw new Error(
+      `Unable to parse date value: ${formatInputForError(value)}`
+    );
+  }
+  return {
+    input: value,
+    tz,
+    utcIso: d.toISOString(),
+    epochMs: d.getTime(),
+    human: formatHuman(d, tz),
+  };
+}
+
+function healthPayload() {
+  // Monotonic time (won't jump backwards/forwards with NTP clock changes)
+  const monotonicMs = Number(process.hrtime.bigint() / 1_000_000n);
+  const wallEpochMs = Date.now();
+  const processUptimeMs = Math.round(process.uptime() * 1000);
+
+  return { wallEpochMs, monotonicMs, processUptimeMs };
+}
+
+async function main() {
+  const server = new McpServer({
+    name: "datetime-mcp",
+    version: "0.1.0",
+  });
+
+  server.tool(
+    "datetime.now",
+    {
+      tz: z.string().optional().describe("IANA timezone, e.g. Australia/Perth"),
+    },
+    async ({ tz }) => {
+      const zone = tz || DEFAULT_TZ;
+      const payload = nowPayload(zone);
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+      };
+    }
+  );
+
+  server.tool("datetime.health", {}, async () => {
+    const payload = healthPayload();
+    return {
+      content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    };
+  });
+
+  server.tool(
+    "datetime.parse",
+    {
+      value: z.string().describe("A date/time string parseable by JS Date"),
+      tz: z.string().optional().describe("IANA timezone, e.g. Australia/Perth"),
+    },
+    async ({ value, tz }) => {
+      const zone = tz || DEFAULT_TZ;
+      const payload = parsePayload(value, zone);
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+      };
+    }
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // stderr is safe for logs under stdio transport (clients may show/ignore it)
+  console.error(`datetime-mcp running (default TZ=${DEFAULT_TZ}) via stdio`);
+}
+
+main().catch((err) => {
+  console.error("datetime-mcp fatal error:", err);
+  process.exit(1);
+});