Utility MCP Server

Instructions

Calculate the time difference between two datetimes or from a start time to now.

Args:
    start_datetime: Start datetime in ISO format (YYYY-MM-DD HH:MM:SS or YYYY-MM-DDTHH:MM:SS)
    end_datetime: End datetime in ISO format (optional - defaults to current time)
    timezone_name: Timezone for interpretation (default: UTC)

Returns:
    Time difference with detailed breakdown

Implementation Reference

• util_server.py:169-259 (handler)

  The handler function for the 'calculate_time_difference' tool, automatically registered via @mcp.tool() decorator. It calculates the time difference between two datetimes (or start to now), handles various ISO formats, timezones via pytz, and returns a detailed formatted breakdown including total seconds, days/hours/mins/secs, and human-readable summary.

  @mcp.tool()
  async def calculate_time_difference(start_datetime: str, end_datetime: str = "", timezone_name: str = "UTC") -> str:
      """
      Calculate the time difference between two datetimes or from a start time to now.
  
      Args:
          start_datetime: Start datetime in ISO format (YYYY-MM-DD HH:MM:SS or YYYY-MM-DDTHH:MM:SS)
          end_datetime: End datetime in ISO format (optional - defaults to current time)
          timezone_name: Timezone for interpretation (default: UTC)
  
      Returns:
          Time difference with detailed breakdown
      """
      try:
          # Parse timezone
          if timezone_name.upper() == "UTC":
              tz = timezone.utc
          else:
              try:
                  tz = pytz.timezone(timezone_name)
              except pytz.UnknownTimeZoneError:
                  return f"❌ Unknown timezone: {timezone_name}\n💡 Try: UTC, US/Eastern, Europe/London, America/Sao_Paulo, etc."
  
          # Parse start datetime
          try:
              # Handle different datetime formats
              if 'T' in start_datetime:
                  start_dt = datetime.fromisoformat(
                      start_datetime.replace('Z', '+00:00'))
              else:
                  start_dt = datetime.strptime(
                      start_datetime, "%Y-%m-%d %H:%M:%S")
                  start_dt = start_dt.replace(tzinfo=tz)
          except ValueError:
              return f"❌ Invalid start datetime format: {start_datetime}\n💡 Use: YYYY-MM-DD HH:MM:SS or YYYY-MM-DDTHH:MM:SS"
  
          # Parse end datetime or use current time
          if end_datetime:
              try:
                  if 'T' in end_datetime:
                      end_dt = datetime.fromisoformat(
                          end_datetime.replace('Z', '+00:00'))
                  else:
                      end_dt = datetime.strptime(
                          end_datetime, "%Y-%m-%d %H:%M:%S")
                      end_dt = end_dt.replace(tzinfo=tz)
              except ValueError:
                  return f"❌ Invalid end datetime format: {end_datetime}\n💡 Use: YYYY-MM-DD HH:MM:SS or YYYY-MM-DDTHH:MM:SS"
          else:
              end_dt = datetime.now(tz)
  
          # Calculate difference
          time_diff = end_dt - start_dt
  
          # Extract components
          total_seconds = abs(time_diff.total_seconds())
          days = int(total_seconds // 86400)
          hours = int((total_seconds % 86400) // 3600)
          minutes = int((total_seconds % 3600) // 60)
          seconds = int(total_seconds % 60)
  
          # Determine direction
          direction = "later" if time_diff.total_seconds() >= 0 else "earlier"
  
          # Format result
          result = f"⏱️ **Time Difference Calculation**\n"
          result += f"**From:** {start_dt.strftime('%Y-%m-%d %H:%M:%S %Z')}\n"
          result += f"**To:** {end_dt.strftime('%Y-%m-%d %H:%M:%S %Z')}\n"
          result += f"**Timezone:** {timezone_name}\n\n"
  
          result += f"**Total Duration:** {total_seconds:,.0f} seconds\n"
          result += f"**Breakdown:**\n"
          result += f"- Days: {days}\n"
          result += f"- Hours: {hours}\n"
          result += f"- Minutes: {minutes}\n"
          result += f"- Seconds: {seconds}\n\n"
  
          # Human-readable summary
          if days > 0:
              result += f"**Summary:** {days} days, {hours} hours, {minutes} minutes ({direction})\n"
          elif hours > 0:
              result += f"**Summary:** {hours} hours, {minutes} minutes ({direction})\n"
          elif minutes > 0:
              result += f"**Summary:** {minutes} minutes, {seconds} seconds ({direction})\n"
          else:
              result += f"**Summary:** {seconds} seconds ({direction})\n"
  
          return result
  
      except Exception as e:
          return f"❌ Error calculating time difference: {str(e)}"

• util_server.py:169-169 (registration)

  The @mcp.tool() decorator registers the calculate_time_difference function as an MCP tool with the name matching the function name.

  @mcp.tool()

• util_server.py:170-180 (schema)

  Input schema defined by function parameters and docstring: start_datetime (str, required), end_datetime (str, optional default empty), timezone_name (str, default UTC). Output: formatted string with time difference details.

  async def calculate_time_difference(start_datetime: str, end_datetime: str = "", timezone_name: str = "UTC") -> str:
      """
      Calculate the time difference between two datetimes or from a start time to now.
  
      Args:
          start_datetime: Start datetime in ISO format (YYYY-MM-DD HH:MM:SS or YYYY-MM-DDTHH:MM:SS)
          end_datetime: End datetime in ISO format (optional - defaults to current time)
          timezone_name: Timezone for interpretation (default: UTC)
  
      Returns:
          Time difference with detailed breakdown

• util_server.py:381-383 (helper)

  Documentation of the tool in the util_server_status tool's output listing available tools.

  status += "2. `calculate_time_difference` - Calculate time differences with detailed breakdown\n"
  status += "3. `download_meeting_data` - Download Read.AI meeting transcripts and summaries\n"
  status += "4. `util_server_status` - Check utility server status and configuration\n"