Chronos Protocol

Instructions

Implementation Reference

• src/chronos_protocol/server.py:358-437 (handler)

  Core implementation of the convert_time tool in TimeServer class. Parses input time, handles timezone resolution including 'system'/'local', converts using pytz, computes time difference, and returns structured TimeConversionResult.
  def convert_time( self, source_tz: str, time_str: str, target_tz: str ) -> TimeConversionResult: """Convert time between timezones (defaults to system time)""" local_tz_name = str(get_local_tz()) # Handle system/local timezone references actual_source_tz = source_tz if source_tz.lower() in ["system", "local"]: actual_source_tz = local_tz_name actual_target_tz = target_tz if target_tz.lower() in ["system", "local"]: actual_target_tz = local_tz_name source_timezone = get_zoneinfo(actual_source_tz) target_timezone = get_zoneinfo(actual_target_tz) try: parsed_time = datetime.strptime(time_str, "%H:%M").time() except ValueError: raise ValueError("Invalid time format. Expected HH:MM [24-hour format]") now = datetime.now(source_timezone) source_time = datetime( now.year, now.month, now.day, parsed_time.hour, parsed_time.minute, tzinfo=source_timezone, ) target_time = source_time.astimezone(target_timezone) source_offset = source_time.utcoffset() or timedelta() target_offset = target_time.utcoffset() or timedelta() hours_difference = (target_offset - source_offset).total_seconds() / 3600 if hours_difference.is_integer(): time_diff_str = f"{hours_difference:+.1f}h" else: # For fractional hours like Nepal's UTC+5:45 time_diff_str = f"{hours_difference:+.2f}".rstrip("0").rstrip(".") + "h" # Create formatted timezone displays source_formatted = source_time.strftime("%B %d, %Y at %I:%M:%S %p") target_formatted = target_time.strftime("%B %d, %Y at %I:%M:%S %p") if source_tz.lower() in ["system", "local"]: source_formatted += f" (System Time - {local_tz_name})" display_source_tz = f"System ({local_tz_name})" else: source_formatted += f" ({source_tz})" display_source_tz = source_tz if target_tz.lower() in ["system", "local"]: target_formatted += f" (System Time - {local_tz_name})" display_target_tz = f"System ({local_tz_name})" else: target_formatted += f" ({target_tz})" display_target_tz = target_tz return TimeConversionResult( source=TimeResult( timezone=display_source_tz, datetime=source_time.isoformat(timespec="seconds"), formatted_timezone=source_formatted, day_of_week=source_time.strftime("%A"), is_dst=bool(source_time.dst()), ), target=TimeResult( timezone=display_target_tz, datetime=target_time.isoformat(timespec="seconds"), formatted_timezone=target_formatted, day_of_week=target_time.strftime("%A"), is_dst=bool(target_time.dst()), ), time_difference=time_diff_str, )
• src/chronos_protocol/server.py:655-677 (registration)

  MCP tool registration in list_tools(). Defines name, description, and input schema (source_timezone, time HH:MM, target_timezone).
  Tool( name=TimeTools.CONVERT_TIME.value, description="Convert time between timezones (defaults to system time for source/target)", inputSchema={ "type": "object", "properties": { "source_timezone": { "type": "string", "description": f"Source timezone. Use 'system' or 'local' for user's local time ({local_tz}), or IANA names like 'America/New_York', 'UTC'. System time is the most practical default.", }, "time": { "type": "string", "description": "Time to convert in 24-hour format (HH:MM)", }, "target_timezone": { "type": "string", "description": f"Target timezone. Use 'system' or 'local' for user's local time ({local_tz}), or IANA names like 'Asia/Tokyo', 'UTC'. System time is the most practical default.", }, }, "required": ["source_timezone", "time", "target_timezone"], }, ), Tool(
• src/chronos_protocol/server.py:864-877 (handler)

  Tool dispatch logic in _execute_tool(). Validates inputs using helper functions and calls the TimeServer.convert_time handler.
  case TimeTools.CONVERT_TIME.value: if not all( k in arguments for k in ["source_timezone", "time", "target_timezone"] ): raise ValueError("Missing required arguments") # Validate inputs with helpful error messages source_tz = validate_timezone(arguments["source_timezone"]) target_tz = validate_timezone(arguments["target_timezone"]) validated_time = validate_time_format(arguments["time"]) result = time_server.convert_time(source_tz, validated_time, target_tz)
• src/chronos_protocol/server.py:107-111 (schema)

  Pydantic model defining the output structure for convert_time: source/target TimeResult and time_difference.
  class TimeConversionResult(BaseModel): source: TimeResult target: TimeResult time_difference: str
• src/chronos_protocol/server.py:45-74 (helper)

  Helper function to validate input time string format (HH:MM, 00:00-23:59), used in convert_time execution.
  def validate_time_format(time_str: str) -> str: """Validate time format and provide helpful error messages.""" if not isinstance(time_str, str): raise ValueError("Time must be a string") # Check HH:MM format if not time_str or len(time_str) != 5 or time_str[2] != ':': raise ValueError( f"Invalid time format '{time_str}'. Expected 24-hour format HH:MM (00:00-23:59)" ) try: hours, minutes = time_str.split(':') hours = int(hours) minutes = int(minutes) if not (0 <= hours <= 23): raise ValueError(f"Hours must be between 00-23, got {hours:02d}") if not (0 <= minutes <= 59): raise ValueError(f"Minutes must be between 00-59, got {minutes:02d}") return time_str except ValueError as e: if "too many values" in str(e) or "not enough values" in str(e): raise ValueError( f"Invalid time format '{time_str}'. Expected HH:MM format (e.g., 14:30)" ) raise