jlumbroso/passage-of-time-mcp

current_datetime

Returns the current date and time as a string. If you are asked for the current date or time, call this function.

Args: timezone: Timezone name (e.g., 'UTC', 'US/Pacific', 'Europe/London'). Defaults to 'America/New_York'.

Returns: A formatted date and time string in format: YYYY-MM-DD HH:MM:SS TZ

time_difference

Calculate the time difference between two timestamps.

Timestamps must be in format: "YYYY-MM-DD HH:MM:SS" or "YYYY-MM-DD"

Args: timestamp1: First timestamp (earlier time expected) timestamp2: Second timestamp (later time expected) unit: Desired unit for the result. "auto" provides multiple formats timezone: Timezone for parsing ambiguous timestamps

Returns: Dictionary containing: - seconds: Total difference in seconds - formatted: Human-readable format (e.g., "3 hours, 10 minutes") - requested_unit: Difference in the requested unit (if not "auto") - is_negative: Boolean indicating if timestamp1 > timestamp2

time_since

Calculate time elapsed since a given timestamp until now.

Timestamp must be in format: "YYYY-MM-DD HH:MM:SS" or "YYYY-MM-DD"

Args: timestamp: Past timestamp to compare against current time timezone: Timezone for parsing and current time

Returns: Dictionary containing: - seconds: Seconds elapsed (negative if timestamp is in future) - formatted: Human-readable format (e.g., "2 days, 3 hours ago") - context: Contextual description (e.g., "earlier today", "yesterday")

parse_timestamp

Parse and convert a timestamp to multiple formats.

Timestamp must be in format: "YYYY-MM-DD HH:MM:SS" or "YYYY-MM-DD"

Args: timestamp: Timestamp string in standard format source_timezone: Timezone of the input (if None, uses target_timezone) target_timezone: Desired output timezone

Returns: Dictionary containing: - iso: ISO 8601 format - unix: Unix timestamp (seconds since epoch) - human: Human-friendly format - timezone: Timezone name - day_of_week: Full day name - date: Date only (YYYY-MM-DD) - time: Time only (HH:MM:SS)

add_time

Add a duration to a timestamp.

Timestamp must be in format: "YYYY-MM-DD HH:MM:SS" or "YYYY-MM-DD"

Args: timestamp: Starting timestamp in standard format duration: Amount to add (can be negative to subtract) unit: Unit of the duration timezone: Timezone for calculations

Returns: Dictionary containing: - result: Resulting timestamp in same format as input - iso: ISO 8601 format of result - description: Natural language description (e.g., "tomorrow at 3:00 PM")

timestamp_context

Provide contextual information about a timestamp.

Timestamp must be in format: "YYYY-MM-DD HH:MM:SS" or "YYYY-MM-DD"

Args: timestamp: Timestamp to analyze in standard format timezone: Timezone for context

Returns: Dictionary containing: - time_of_day: "early_morning", "morning", "afternoon", "evening", "late_night" - day_of_week: Full day name - is_weekend: Boolean - is_business_hours: Boolean (Mon-Fri 9-5) - hour_24: Hour in 24-hour format - typical_activity: Contextual description (e.g., "lunch_time", "commute_time") - relative_day: "today", "yesterday", "tomorrow", or None

format_duration

Format a duration in seconds into human-readable text.

Args: seconds: Duration in seconds (can be negative) style: Format style - "full": "2 hours, 30 minutes, 15 seconds" - "compact": "2h 30m 15s" - "minimal": "2:30:15"

Returns: Formatted duration string