Time Translator MCP Server

Convert structured date-time inputs into deterministic ISO-8601 results for AI agents.

Time Translator MCP Server is a Spring Boot MCP server for auditable date-time calculation. Agent runtimes handle natural-language understanding, context completion, current-time injection, and timezone selection; this server validates complete structured inputs and returns normalized target times using the Java Time API.

Core Features

• Deterministic normalization: Converts complete structured date-time inputs into ISO-8601 target times with timezone offsets.
• Three calculation modes: Supports absolute date-time construction, relative offsets, and week/day-of-week resolution.
• Strict validation: Rejects malformed ISO reference times, invalid IANA timezones, impossible dates, all-zero offsets, out-of-range week offsets, and DST gap or overlap local times.
• Consistent responses: Every successful tool call returns targetTime, timezone, referenceTime, tool, and explanation.
• Dual transport support: Runs as a Streamable HTTP MCP server for remote clients or as a STDIO MCP server for local clients.

Quick Start

Build the server:

mvn package

Run with Streamable HTTP:

mvn spring-boot:run "-Dspring-boot.run.profiles=streamable"

The MCP endpoint is available at:

http://127.0.0.1:8080/mcp

Run with STDIO:

java "-Dspring.profiles.active=stdio" -jar target/time-translator-mcp-server-0.0.1-SNAPSHOT.jar

Available Tools

1. resolve_absolute_datetime

Constructs a target time from complete year, month, day, hour, minute, and second fields in the supplied IANA timezone.

Input schema

Field	Type	Required	Description
referenceTime	string	yes	ISO-8601 date-time with offset, such as 2026-05-28T14:30:00+08:00.
timezone	string	yes	IANA timezone, such as Asia/Shanghai or America/New_York.
year	integer	yes	Target year. The resulting targetTime year must be between 1900 and 2100.
month	integer	yes	Target month, 1 to 12.
day	integer	yes	Target day of month, 1 to 31. The server validates the actual date.
hour	integer	yes	Target hour, 0 to 23.
minute	integer	yes	Target minute, 0 to 59.
second	integer	yes	Target second, 0 to 59.

{
  "referenceTime": "2026-05-28T14:30:00+08:00",
  "timezone": "Asia/Shanghai",
  "year": 2026,
  "month": 6,
  "day": 8,
  "hour": 9,
  "minute": 0,
  "second": 0
}

Expected targetTime:

2026-06-08T09:00:00+08:00

2. calculate_datetime_offset

Normalizes referenceTime into the supplied timezone, then applies year, month, day, hour, minute, and second offsets in order.

Input schema

Field	Type	Required	Description
referenceTime	string	yes	ISO-8601 date-time with offset, such as 2026-05-28T14:30:00+08:00.
timezone	string	yes	IANA timezone, such as Asia/Shanghai or America/New_York.
years	integer	yes	Year offset. Positive values mean future; negative values mean past.
months	integer	yes	Month offset. Positive values mean future; negative values mean past.
days	integer	yes	Day offset. Positive values mean future; negative values mean past.
hours	integer	yes	Hour offset. Positive values mean future; negative values mean past.
minutes	integer	yes	Minute offset. Positive values mean future; negative values mean past.
seconds	integer	yes	Second offset. At least one offset field must be non-zero.

{
  "referenceTime": "2026-05-28T14:30:00+08:00",
  "timezone": "Asia/Shanghai",
  "years": 0,
  "months": 0,
  "days": 1,
  "hours": 2,
  "minutes": 30,
  "seconds": 0
}

Expected targetTime:

2026-05-29T17:00:00+08:00

3. resolve_day_of_week_datetime

Uses the week containing referenceTime, treats Monday as the first day of week, applies weekOffset, selects the requested day, and sets the exact time.

Input schema

Field	Type	Required	Description
referenceTime	string	yes	ISO-8601 date-time with offset, such as 2026-05-28T14:30:00+08:00.
timezone	string	yes	IANA timezone, such as Asia/Shanghai or America/New_York.
day	string	yes	Target day of week: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, or SUNDAY.
weekOffset	integer	yes	Week offset relative to the week containing referenceTime, from -52 to 52.
hour	integer	yes	Target hour, 0 to 23.
minute	integer	yes	Target minute, 0 to 59.
second	integer	yes	Target second, 0 to 59.

{
  "referenceTime": "2026-05-28T14:30:00+08:00",
  "timezone": "Asia/Shanghai",
  "day": "MONDAY",
  "weekOffset": 1,
  "hour": 9,
  "minute": 0,
  "second": 0
}

Expected targetTime:

2026-06-01T09:00:00+08:00