Convert datetimes across IANA timezones and rewrite ICS timestamps

mumuzhang — Tue, 27 Oct 2026 03:27:27 +0000

The problem

I kept hitting the same friction: wiring one tool into every client by hand, then rewriting the same glue code each time a new client showed up. Copying a previous project helped for about an hour, and then the small differences took over: different payload shapes, different failure modes, different places to look when nothing arrived. So I built timezone-convert-mcp to make the whole thing repeatable instead of memorable.

How it works

Ingest — accept the inbound request and normalize it into one shape.
Verify — check the signature before trusting anything in the body.
Guard — drop events that were already processed.
Deliver — forward the normalized record and route failures somewhere visible.

The order matters more than the individual pieces. Verifying before parsing means a malformed or hostile body never reaches the part of the system that would act on it. The idempotency guard is the piece I used to skip, and it is the piece that actually saves time: once duplicates are dropped at the door, every downstream failure is a real failure instead of noise.

The code

The structure below is taken directly from the generated artifact, not rewritten for the post:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.your-scope/timezone-convert-mcp",
  "description": "Convert datetimes across IANA timezones and rewrite ICS timestamps",
  "version": "1.0.0",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "timezone-convert-mcp",
      "version": "1.0.0",
      "transport": {
        "type": "stdio"
      }
    }
  ],
  "repository": {
    "url": "https://github.com/your-scope/REPLACE_ME",
    "source": "github"
  }
}

Nothing here is clever on purpose. Each node does one thing, and the thing it does is readable from its name.

What broke

The first version passed every happy-path test and then lost events in production for two reasons that only show up under load. The first was treating a signature check as optional on internal traffic — it is not optional, because "internal" stops being true the moment someone copies the webhook URL into a second service. The second was writing failures to a log nobody read. An error branch that only appends to a file is not an error branch; it has to end somewhere a human looks.

What I'd do differently

Start smaller. The first version had features I could not explain to myself a week later, and every one of them became a place for a silent failure to hide. Cutting it down to trigger, verify, guard, deliver made the whole thing easier to trust, and trust is the actual feature — the automation is only useful if you stop checking it. I would also write the idempotency key format down before writing code, because retrofitting a key scheme onto events already in flight is the least fun kind of migration.

Full workflow and setup live in the GitHub repo.

What the project actually does

Convert datetimes across IANA timezones and rewrite ICS timestamps

A Model Context Protocol server. It exposes 3 tools over stdio and has no hosted component — everything runs on your machine.

Most MCP servers wrap a SaaS API, which means an OAuth dance before you get anything useful. This one does not. Convert datetimes across IANA timezones and rewrite ICS timestamps is a small, bounded problem, so the server implements it directly with Node's standard library and returns plain JSON you can inspect. There is no account, no API key, and no data leaving your process.

That trade-off has a cost, and it is stated plainly in the limitations section below. If your use case needs more than this server does, the source is short enough to read in one sitting and extend.

Run it directly with npx:

Or install it globally:

Requires Node 18 or newer.

Add the server to your client configuration (Claude Desktop, Cursor, or any MCP-compatible host):

Restart the client after editing the configuration. The 3 tools below should appear in the tool list.

Convert a datetime from one IANA timezone to another

Parameter	Type
`datetime`	`string`	required
`from`	`string`	required
`to`	`string`	required

Search IANA timezone names

Parameter	Type
`query`	`string`	optional

Rewrite every DTSTART/DTEND in an ICS payload to another timezone

Parameter	Type
`ics`	`string`	required
`to`	`string`	required

Every tool takes plain strings or numbers and returns a JSON string in a text content block. Errors come back as isError: true with a readable message rather than a stack trace, so an agent can recover instead of crashing.

The general pattern is: call the read tool first to see what the payload actually looks like, then call the transform tool with explicit parameters. Tools never mutate their input and never write to disk — running the same call twice gives the same result.

Optional dependencies are loaded lazily. If a tool needs pdf-parse or qrcode and the package is missing, the call fails with a message telling you exactly what to install, while the rest of the server keeps working.

Uses the ICU timezone database bundled with Node — keep Node updated for recent rule changes.
convert_ics only rewrites UTC timestamps (ending in Z); already-local times are left alone.
Ambiguous times during a DST fall-back resolve to the first occurrence.
No duration formatting: callers convert both endpoints themselves.

These are deliberate scope limits, not bugs. Each one exists because doing it properly needs a dependency, a network service, or an amount of code that no longer belongs in a single-file server.

To test a tool by hand, pipe a JSON-RPC request into stdin:

Because the transport is stdio, all diagnostics go to stderr. If you add a console.log anywhere in a handler, you will corrupt the protocol stream — use console.error.

MIT.

Production version with documentation and support: https://your-checkout.example.com

DEV Community: mumuzhang

Convert datetimes across IANA timezones and rewrite ICS timestamps

The problem

How it works

The code

What broke

What I'd do differently

What the project actually does