Utility MCP Server

Instructions

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"