Time MCP Server

Instructions

Implementation Reference

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

  Core implementation of the convert_time tool: parses HH:MM time string, constructs full datetime in source timezone for today, converts to target timezone, computes offset difference, and returns structured TimeConversionResult.

  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)

  Registration of the 'convert_time' tool via @server.list_tools(), specifying name, description, and JSON schema for inputs: source_timezone, time (HH:MM), target_timezone.

  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:22-32 (schema)

  Pydantic schemas for output structures: TimeResult (per-timezone info) and TimeConversionResult (source/target times and difference). Used by the handler to validate/structure response.

  class TimeResult(BaseModel):
      timezone: str
      datetime: str
      is_dst: bool
  
  
  class TimeConversionResult(BaseModel):
      source: TimeResult
      target: TimeResult
      time_difference: str

• src/mcp_server_time/server.py:17-20 (helper)

  Enum defining tool names, including CONVERT_TIME used in registration and dispatch.

  class TimeTools(str, Enum):
      GET_CURRENT_TIME = "get_current_time"
      CONVERT_TIME = "convert_time"

• src/mcp_server_time/server.py:179-190 (handler)

  Dispatch logic in @server.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"],
      )