DateTime MCP Server

Instructions

Implementation Reference

• server.py:98-124 (handler)

  The handler function for the 'get_current_time' tool. It is registered via the @mcp.tool decorator. Loads timezone and format from configuration, computes current time, formats it (12h or 24h), and returns as ToolResult.

  @mcp.tool
  def get_current_time(ctx: Context = None) -> ToolResult:
      """
      Get the current time in the configured format.
      
      Returns:
          Time string in 12-hour or 24-hour format based on TIMEFMT setting
          
      Examples:
          With TIMEFMT="12": "2:30 PM"
          With TIMEFMT="24": "14:30"
      """
      tz_string, time_format = load_config(ctx)
      timezone = get_timezone(tz_string)
      
      # Get current time in the specified timezone
      now = datetime.now(timezone)
      
      if time_format == "12":
          # 12-hour format with AM/PM
          result_text = now.strftime("%I:%M %p").lstrip('0')
      else:
          # 24-hour format (default)
          result_text = now.strftime("%H:%M")
      
      # Return raw text without JSON wrapping - more efficient per policy
      return ToolResult(content=[TextContent(type="text", text=result_text)])

• server.py:19-46 (helper)

  Helper function to load timezone string and time format from context headers or environment variables, with defaults.

  def load_config(context: Optional[Context] = None) -> tuple[str, str]:
      """
      Load timezone and time format configuration.
      
      For HTTP transport, configuration comes from headers.
      For stdio transport, configuration comes from environment variables.
      
      Returns:
          tuple: (timezone_string, time_format)
      """
      # Default values
      default_tz = "UTC"
      default_timefmt = "24"
      
      # Try to get from context headers first (HTTP transport)
      if context and hasattr(context, 'meta') and context.meta:
          headers = context.meta.get('headers', {})
          tz_string = headers.get('DEFAULT_TZ', headers.get('default_tz'))
          time_format = headers.get('TIMEFMT', headers.get('timefmt'))
          
          if tz_string and time_format:
              return tz_string, time_format
      
      # Fall back to environment variables (stdio transport)
      tz_string = os.getenv('DEFAULT_TZ', default_tz)
      time_format = os.getenv('TIMEFMT', default_timefmt)
      
      return tz_string, time_format

• server.py:49-64 (helper)

  Helper function to resolve timezone string to ZoneInfo object, falling back to UTC on error.

  def get_timezone(tz_string: str) -> ZoneInfo:
      """
      Convert timezone string to ZoneInfo object.
      
      Args:
          tz_string: Timezone identifier (e.g., "America/New_York", "UTC")
          
      Returns:
          ZoneInfo object, defaults to UTC if invalid timezone
      """
      try:
          return ZoneInfo(tz_string)
      except Exception:
          # Graceful fallback to UTC for invalid timezones
          return ZoneInfo("UTC")

• server.py:98-98 (registration)

  The @mcp.tool decorator registers the get_current_time function as an MCP tool.

  @mcp.tool