Time MCP Server

Instructions

Implementation Reference

• src/mcp_server_time/server.py:73-120 (handler)

  The primary handler method for the 'convert_time' tool in the TimeServer class. It validates the input time format, converts the time from the source timezone to the target timezone using datetime operations, calculates the time difference, and constructs a TimeConversionResult object.

  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"),
              day_of_week=source_time.strftime("%A"),
              is_dst=bool(source_time.dst()),
          ),
          target=TimeResult(
              timezone=target_tz,
              datetime=target_time.isoformat(timespec="seconds"),
              day_of_week=target_time.strftime("%A"),
              is_dst=bool(target_time.dst()),
          ),
          time_difference=time_diff_str,
      )

• src/mcp_server_time/server.py:29-33 (schema)

  Pydantic model defining the output structure for the 'convert_time' tool response, including source and target time details and the time difference.

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

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

  Pydantic model used within TimeConversionResult for representing time information in a specific timezone.

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

• src/mcp_server_time/server.py:146-167 (registration)

  Registration of the 'convert_time' tool in the MCP server's list_tools() method, defining the tool name, description, and input schema.

  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:184-195 (registration)

  Dispatch logic in the MCP server's call_tool() method 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"],
      )