@mrfentmen/timezone-mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# Time Zones
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+IANA time zone maths offline - the time right now in any zone, wall-clock conversion between zones, and the zone list, keyless.
+
+Keyless — no signup, no API key, no environment variables.
+
+## Install
+
+```bash
+npx -y @mrfentmen/timezone-mcp
+```
+
+Or add it to your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "timezone-mcp": { "command": "npx", "args": ["-y", "@mrfentmen/timezone-mcp"] }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `time_in_zone` | Current local time in one IANA zone, with weekday, abbreviation and UTC offset. |
+| `convert_time` | Show one moment in two zones; a bare wall-clock time is read in the from zone, handling daylight saving. |
+| `list_timezones` | Search the IANA zone list this runtime knows. |
+
+## Data source
+
+Runs fully offline — all work happens inside the server with no API calls and no keys.

package/dist/api.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Time Zones — keyless public API client.
+ */
+export declare class SourceError extends Error {
+}
+export declare function clean(s: unknown): string;
+export declare function timeInZone(a: {
+    zone: string;
+    at?: string;
+}): Promise<string>;
+export declare function convertTime(a: {
+    time: string;
+    from: string;
+    to: string;
+}): Promise<string>;
+export declare function listTimezones(a: {
+    search?: string;
+}): Promise<string>;

package/dist/api.js

@@ -0,0 +1,126 @@
+/**
+ * Time Zones — keyless public API client.
+ */
+export class SourceError extends Error {
+}
+export function clean(s) {
+    return String(s ?? "").replace(/\s+/g, " ").trim();
+}
+const WEEKDAY_OPTS = { hour12: false, weekday: "long", year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit", timeZoneName: "short" };
+function checkZone(value) {
+    const zone = clean(value);
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: zone });
+    }
+    catch {
+        throw new SourceError(`"${value}" is not a known IANA time zone (try list_timezones)`);
+    }
+    return zone;
+}
+function zoneOffsetMinutes(zone, date) {
+    const parts = new Intl.DateTimeFormat("en-GB", {
+        timeZone: zone,
+        hour12: false,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    }).formatToParts(date);
+    const get = (type) => Number(parts.find((p) => p.type === type)?.value ?? "0");
+    const asUtc = Date.UTC(get("year"), get("month") - 1, get("day"), get("hour") % 24, get("minute"), get("second"));
+    return Math.round((asUtc - date.getTime()) / 60000);
+}
+function offsetText(minutes) {
+    const sign = minutes < 0 ? "-" : "+";
+    const abs = Math.abs(minutes);
+    return `UTC${sign}${String(Math.floor(abs / 60)).padStart(2, "0")}:${String(abs % 60).padStart(2, "0")}`;
+}
+function describeIn(zone, date) {
+    const parts = new Intl.DateTimeFormat("en-GB", { timeZone: zone, ...WEEKDAY_OPTS }).formatToParts(date);
+    const get = (type) => parts.find((p) => p.type === type)?.value ?? "";
+    return {
+        wall: `${get("year")}-${get("month")}-${get("day")} ${String(Number(get("hour")) % 24).padStart(2, "0")}:${get("minute")}:${get("second")}`,
+        weekday: get("weekday"),
+        abbreviation: get("timeZoneName"),
+        offset: zoneOffsetMinutes(zone, date),
+    };
+}
+const NAIVE = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?$/;
+const HAS_OFFSET = /(Z|[+-]\d{2}:?\d{2})$/;
+function instantFromWall(zone, text) {
+    const m = NAIVE.exec(text.trim());
+    if (!m)
+        throw new SourceError(`time must be ISO 8601, e.g. 2026-01-01T09:00 or 2026-01-01T09:00Z (got "${text}")`);
+    const [, y, mo, d, h, mi, s] = m;
+    const wallUtc = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s ?? 0));
+    let instant = new Date(wallUtc);
+    for (let i = 0; i < 3; i++) {
+        const offset = zoneOffsetMinutes(zone, instant);
+        instant = new Date(wallUtc - offset * 60000);
+    }
+    const back = describeIn(zone, instant).wall;
+    const wanted = `${y}-${mo}-${d} ${h}:${mi}:${s ?? "00"}`;
+    return { instant, exact: back === wanted };
+}
+export async function timeInZone(a) {
+    const zone = checkZone(a.zone);
+    let when = new Date();
+    if (a.at) {
+        when = a.at.trim() && HAS_OFFSET.test(a.at.trim()) ? new Date(a.at) : instantFromWall(checkZone("UTC"), a.at).instant;
+        if (Number.isNaN(when.getTime()))
+            throw new SourceError(`at must be an ISO 8601 instant, got "${a.at}"`);
+    }
+    const info = describeIn(zone, when);
+    const utc = describeIn("UTC", when);
+    return [
+        `${info.wall} ${info.weekday} — ${zone}`,
+        "",
+        `local time:  ${info.wall} (${info.abbreviation}, ${offsetText(info.offset)})`,
+        `UTC:         ${utc.wall}`,
+        `unix:        ${Math.floor(when.getTime() / 1000)}`,
+    ].join("\n");
+}
+export async function convertTime(a) {
+    const from = checkZone(a.from);
+    const to = checkZone(a.to);
+    const text = clean(a.time);
+    let result;
+    if (HAS_OFFSET.test(text)) {
+        const instant = new Date(text);
+        if (Number.isNaN(instant.getTime()))
+            throw new SourceError(`time must be ISO 8601, got "${a.time}"`);
+        result = { instant, exact: true };
+    }
+    else {
+        result = instantFromWall(from, text);
+    }
+    const inFrom = describeIn(from, result.instant);
+    const inTo = describeIn(to, result.instant);
+    return [
+        `${result.instant.toISOString()} (UTC)`,
+        "",
+        `${from.padEnd(22)} ${inFrom.wall} ${inFrom.weekday} (${inFrom.abbreviation}, ${offsetText(inFrom.offset)})`,
+        `${to.padEnd(22)} ${inTo.wall} ${inTo.weekday} (${inTo.abbreviation}, ${offsetText(inTo.offset)})`,
+        !result.exact ? "\nNote: that wall-clock time does not exist in the source zone (a daylight-saving jump); the nearest valid instant is shown." : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+export async function listTimezones(a) {
+    const search = clean(a.search).toLowerCase();
+    const supported = Intl.supportedValuesOf;
+    if (typeof supported !== "function")
+        throw new SourceError("this Node build cannot list time zones; pass a zone your platform knows");
+    const zones = supported.call(Intl, "timeZone");
+    const hits = zones.filter((z) => !search || z.toLowerCase().includes(search));
+    if (!hits.length)
+        throw new SourceError(`no time zone matches "${clean(a.search)}"`);
+    const shown = hits.slice(0, 60);
+    return [
+        `${hits.length} zone(s)${search ? ` matching "${clean(a.search)}"` : ""}${hits.length > shown.length ? `, showing ${shown.length}` : ""}:`,
+        "",
+        ...shown,
+    ].join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("timezone-mcp running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,43 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { convertTime, listTimezones, timeInZone, SourceError } from "./api.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+function errorMessage(e) {
+    if (e instanceof SourceError || e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}
+export function createServer() {
+    const server = new McpServer({ name: "timezone-mcp", version: "1.0.0" });
+    server.tool("time_in_zone", "Current local time in one IANA zone, with weekday, abbreviation and UTC offset.", {
+        zone: z.string().describe('IANA zone, e.g. Asia/Tokyo'), at: z.string().optional().describe('Optional ISO 8601 instant to use instead of now')
+    }, async (a) => {
+        try {
+            return text(await timeInZone(a));
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: errorMessage(e) }], isError: true };
+        }
+    });
+    server.tool("convert_time", "Show one moment in two zones; a bare wall-clock time is read in the from zone, handling daylight saving.", {
+        time: z.string().describe('ISO 8601 instant (2026-01-01T09:00Z) or wall-clock time (2026-01-01 09:00)'), from: z.string().describe('Zone the time belongs to when no offset is given, e.g. Europe/Berlin'), to: z.string().describe('Zone to convert to, e.g. America/Los_Angeles')
+    }, async (a) => {
+        try {
+            return text(await convertTime(a));
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: errorMessage(e) }], isError: true };
+        }
+    });
+    server.tool("list_timezones", "Search the IANA zone list this runtime knows.", {
+        search: z.string().optional().describe('Substring filter, e.g. tokyo')
+    }, async (a) => {
+        try {
+            return text(await listTimezones(a));
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: errorMessage(e) }], isError: true };
+        }
+    });
+    return server;
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@mrfentmen/timezone-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "IANA time zone maths offline - the time right now in any zone, wall-clock conversion between zones, and the zone list, keyless.",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/timezone-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrfentmen/awesome-servers.git"
+  },
+  "bin": {
+    "timezone-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "timezone",
+    "time",
+    "utc",
+    "iana",
+    "offline",
+    "keyless"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}