Time MCP Server

Instructions

Implementation Reference

• src/mcp_server_time/server.py:70-116 (handler)

  The main handler function in TimeServer class that performs timezone conversion from source_tz time_str to target_tz, outputs TimeConversionResult with source/target times and difference.

  def convert_time(
      self, source_tz: str, time_str: str, target_tz: str
  ) -> TimeConversionResult:
      """Convert time between timezones"""
      source_timezone = get_zoneinfo(source_tz)
      target_timezone = get_zoneinfo(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"
  
      return TimeConversionResult(
          source=TimeResult(
              timezone=source_tz,
              datetime=source_time.isoformat(timespec="seconds"),
              is_dst=bool(source_time.dst()),
          ),
          target=TimeResult(
              timezone=target_tz,
              datetime=target_time.isoformat(timespec="seconds"),
              is_dst=bool(target_time.dst()),
          ),
          time_difference=time_diff_str,
      )

• src/mcp_server_time/server.py:141-162 (registration)

  Tool registration in list_tools(), defining name, description, and inputSchema for 'convert_time' tool.

  Tool(
      name=TimeTools.CONVERT_TIME.value,
      description="Convert time between timezones",
      inputSchema={
          "type": "object",
          "properties": {
              "source_timezone": {
                  "type": "string",
                  "description": f"Source IANA timezone name (e.g., 'America/New_York', 'Europe/London'). Use '{local_tz}' as local timezone if no source timezone provided by the user.",
              },
              "time": {
                  "type": "string",
                  "description": "Time to convert in 24-hour format (HH:MM)",
              },
              "target_timezone": {
                  "type": "string",
                  "description": f"Target IANA timezone name (e.g., 'Asia/Tokyo', 'America/San_Francisco'). Use '{local_tz}' as local timezone if no target timezone provided by the user.",
              },
          },
          "required": ["source_timezone", "time", "target_timezone"],
      },
  ),

• src/mcp_server_time/server.py:179-191 (registration)

  Dispatch logic in call_tool() that validates arguments and invokes the 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")
  
      result = time_server.convert_time(
          arguments["source_timezone"],
          arguments["time"],
          arguments["target_timezone"],
      )
  case _:

• src/mcp_server_time/server.py:28-32 (schema)

  Pydantic model for the output structure of convert_time tool.

  class TimeConversionResult(BaseModel):
      source: TimeResult
      target: TimeResult
      time_difference: str

• src/mcp_server_time/server.py:22-26 (schema)

  Pydantic model used in TimeConversionResult for source and target time details.

  class TimeResult(BaseModel):
      timezone: str
      datetime: str
      is_dst: bool