Chronos Protocol

Instructions

Implementation Reference

• src/chronos_protocol/server.py:498-528 (handler)

  Main handler function in TimeServer that retrieves activity log from database and calculates elapsed time, returning formatted duration for both ongoing and completed activities.

  def get_elapsed_time(self, activity_id: str) -> Dict[str, Any]:
      """Get elapsed time for an activity"""
      log_data = self.db.get_activity_log(activity_id)
      if not log_data:
          raise ValueError(f"Activity log with ID {activity_id} not found")
  
      start_time = datetime.fromisoformat(log_data['startTime'].replace('Z', '+00:00'))
  
      if log_data['status'] == 'completed':
          end_time = datetime.fromisoformat(log_data['endTime'].replace('Z', '+00:00'))
          elapsed_seconds = int((end_time - start_time).total_seconds())
          return {
              'activityId': activity_id,
              'startTime': log_data['startTime'],
              'endTime': log_data['endTime'],
              'elapsedTime': format_duration(elapsed_seconds),
              'elapsedSeconds': elapsed_seconds,
              'status': 'completed'
          }
      else:
          current_time = datetime.now(ZoneInfo('UTC'))
          elapsed_seconds = int((current_time - start_time).total_seconds())
          return {
              'activityId': activity_id,
              'startTime': log_data['startTime'],
              'currentTime': current_time.isoformat(timespec="seconds"),
              'elapsedTime': format_duration(elapsed_seconds),
              'elapsedSeconds': elapsed_seconds,
              'status': 'ongoing'
          }

• src/chronos_protocol/server.py:727-740 (registration)

  Registers the get_elapsed_time tool with the MCP server in list_tools(), defining name, description, and input schema requiring activityId.

  Tool(
      name=TimeTools.GET_ELAPSED_TIME.value,
      description="Get the elapsed time for an ongoing or completed activity",
      inputSchema={
          "type": "object",
          "properties": {
              "activityId": {
                  "type": "string",
                  "description": "Unique identifier of the activity log",
              },
          },
          "required": ["activityId"],
      },
  ),

• src/chronos_protocol/server.py:900-906 (registration)

  In _execute_tool match statement, handles tool calls for get_elapsed_time by extracting activityId and invoking the TimeServer.get_elapsed_time handler.

  case TimeTools.GET_ELAPSED_TIME.value:
      activity_id = arguments.get("activityId")
      if not activity_id:
          raise ValueError("Missing required argument: activityId")
  
      result = time_server.get_elapsed_time(activity_id)

• src/chronos_protocol/server.py:113-126 (schema)

  Pydantic model defining the structure of activity logs used by get_elapsed_time, including activityId, startTime, endTime, status essential for elapsed time calculation.

  class ActivityLog(BaseModel):
      activityId: str  # Changed from timeId for better naming
      activityType: str
      task_scope: TaskScope
      description: Optional[str] = None
      tags: Optional[List[str]] = None
      startTime: str
      endTime: Optional[str] = None
      duration: Optional[str] = None
      durationSeconds: Optional[int] = None
      result: Optional[str] = None
      notes: Optional[str] = None
      status: str  # "started", "completed"

• src/chronos_protocol/server.py:301-314 (helper)

  Utility function used by the handler to format elapsed seconds into human-readable string (e.g., '2h 30m 45s').

  def format_duration(seconds: int) -> str:
      """Format duration in seconds to human-readable format"""
      if seconds < 60:
          return f"{seconds}s"
      elif seconds < 3600:
          minutes = seconds // 60
          remaining_seconds = seconds % 60
          return f"{minutes}m {remaining_seconds}s"
      else:
          hours = seconds // 3600
          remaining_minutes = (seconds % 3600) // 60
          remaining_seconds = seconds % 60
          return f"{hours}h {remaining_minutes}m {remaining_seconds}s"