MCP Temporal Utility Service

This repository details a Node.js/TypeScript implementation serving as an MCP endpoint dedicated to exposing granular date and time functionalities to agentic frameworks and interactive conversational interfaces.

Overview

Temporal Utility is designed around the Model Context Protocol specification. It furnishes AI systems with precise, localized temporal data, facilitating capabilities such as:

• Fetching the present moment utilizing the host system's temporal locale.
• Resolving the current time across any specified geographical time designation.
• Enumerating the complete registry of recognized time zones.
• Providing structured access to time zone metadata via defined URI paths.

Acquisition

Via npm Registry

Installation globally is straightforward:

npm install -g mcp-temporal-utility

From Source Repository

For local builds or modifications:

git clone https://github.com/odgrmi/mcp-datetime.git
cd mcp-datetime
npm install
npm run build

Operational Modes

Command Line Execution

Temporal Utility supports two primary execution paradigms:

1. Standard Interfacing (Default I/O)

This mode is optimal for integration with AI execution environments relying on standard input and output streams for MCP communication:

mcp-temporal-utility

2. Server-Sent Events (SSE) Transport

This launches an integrated HTTP listener providing an SSE channel for continuous MCP data streams:

mcp-temporal-utility --sse

You may optionally customize the network parameters:

mcp-temporal-utility --sse --port=9001 --prefix=/time-data

Environmental Variables for SSE

• PORT: Specifies the network socket to listen on for SSE operations (Default: 3000).
• URI_PREFIX: Defines the base path segment for all HTTP endpoints (Default: Unset).

Exposed Functionality (Tools)

The service exposes the following atomic functions for agent invocation:

resolve-system-moment

Retrieves the chronometer reading corresponding to the originating system's local time setting.

query-local-designation

Reports the operational time zone identifier of the host environment.

fetch-time-at-designation

Gives the current timestamp accurately calculated for an explicitly named temporal region.

Parameters: - designation: The required time zone identifier (e.g., "Europe/Zurich").

enumerate-designations

Returns a comprehensive roster of every time zone alias recognized by the service.

Resource Locators (URIs)

In addition to function calls, temporal data is accessible via resource URIs:

time://{designation}

Delivers the current chronological datum for the designated zone.

Example: time://Asia/Seoul

time://registry

Provides the complete roster of known time zone designations.

Canonical Time Zones

The following regions are guaranteed to be accessible immediately:

• UTC
• Europe/London
• Europe/Paris
• Europe/Berlin
• America/New_York
• America/Chicago
• America/Denver
• America/Los_Angeles
• Asia/Tokyo
• Asia/Shanghai
• Asia/Kolkata
• Australia/Sydney
• Pacific/Auckland

SSE Endpoint Mapping

When operating in the Server-Sent Events context, the following network paths are active:

• /sse: The primary channel for receiving asynchronous time event streams.
• /signal: Endpoint for transmitting control data from the client back to the server.
• /status: Endpoint detailing the operational health and configuration of the server instance.

Any configured URI prefix will be prepended to these paths.

AI System Integration

Temporal Utility integrates seamlessly with any agent architecture supporting the MCP specification, furnishing agents with the requisite precision for time-sensitive reasoning and scheduling.

Development Lifecycle

Prerequisites for Contribution

• Node.js runtime, version 14.16 or newer.
• npm package manager.

Project Initialization

git clone https://github.com/odgrim/mcp-datetime.git
cd mcp-datetime
npm install

Compilation

npm run build

Development Execution

npm run dev        # Standard STDIN/STDOUT workflow
npm run dev:sse    # Launching the SSE server configuration

Licensing

This software is distributed under the terms of the Mozilla Public License, Version 2.0 (MPL-2.0). Refer to the accompanying LICENSE file for complete licensing stipulations.