get_live_intervals

Instructions

Implementation Reference

• tools/live/intervals.py:9-81 (handler)

  The core handler function implementing the get_live_intervals tool logic, fetching live driver gaps and intervals from OpenF1 API using session keys.

  def get_live_intervals(
      year: int,
      country: str,
      session_name: str = "Race",
      driver_number: Optional[int] = None
  ) -> IntervalsResponse:
      """
      Get real-time gaps and intervals between drivers from OpenF1.
  
      Args:
          year: Season year (2023+, OpenF1 data availability)
          country: Country name (e.g., "Monaco", "Italy", "United States")
          session_name: Session name - 'Race', 'Qualifying', 'Sprint', 'Practice 1/2/3' (default: 'Race')
          driver_number: Optional filter by driver number (1-99)
  
      Returns:
          IntervalsResponse with gap to leader and interval to car ahead
  
      Example:
          get_live_intervals(2024, "Monaco", "Race") → All intervals during race
          get_live_intervals(2024, "Monaco", "Race", 1) → Verstappen's gaps
      """
      # Get meeting and session info
      meetings = openf1_client.get_meetings(year=year, country_name=country)
      if not meetings:
          return IntervalsResponse(
              session_name=session_name,
              year=year,
              country=country,
              intervals=[],
              total_data_points=0
          )
  
      # Get sessions for this meeting
      sessions = openf1_client.get_sessions(year=year, country_name=country, session_name=session_name)
      if not sessions:
          return IntervalsResponse(
              session_name=session_name,
              year=year,
              country=country,
              intervals=[],
              total_data_points=0
          )
  
      session = sessions[0]
      session_key = session['session_key']
  
      # Get intervals data
      interval_data = openf1_client.get_intervals(
          session_key=session_key,
          driver_number=driver_number
      )
  
      # Convert to Pydantic models
      intervals = [
          IntervalData(
              date=data['date'],
              driver_number=data['driver_number'],
              gap_to_leader=data.get('gap_to_leader'),
              interval=data.get('interval'),
              session_key=data['session_key'],
              meeting_key=data['meeting_key']
          )
          for data in interval_data
      ]
  
      return IntervalsResponse(
          session_name=session_name,
          year=year,
          country=country,
          intervals=intervals,
          total_data_points=len(intervals)
      )

• models/live/openf1.py:47-64 (schema)

  Pydantic models (IntervalData and IntervalsResponse) defining the input parameters and output schema for the get_live_intervals tool.

  class IntervalData(BaseModel):
      """Interval and gap data."""
      date: str = Field(..., description="Timestamp")
      driver_number: int = Field(..., description="Driver number (1-99)")
      gap_to_leader: Optional[Union[str, float]] = Field(None, description="Gap to race leader")
      interval: Optional[Union[str, float]] = Field(None, description="Interval to car ahead")
      session_key: int = Field(..., description="Session identifier")
      meeting_key: int = Field(..., description="Meeting identifier")
  
  
  class IntervalsResponse(BaseModel):
      """Response for intervals data."""
      session_name: Optional[str] = Field(None, description="Session name")
      year: Optional[int] = Field(None, description="Year")
      country: Optional[str] = Field(None, description="Country name")
      intervals: list[IntervalData] = Field(..., description="List of interval data points")
      total_data_points: int = Field(..., description="Total number of data points")

• server.py:170-170 (registration)

  Registration of the get_live_intervals tool with the MCP server using the mcp.tool() decorator.

  mcp.tool()(get_live_intervals)

• tools/live/intervals.py:6-6 (helper)

  Initialization of the shared OpenF1Client instance used by the get_live_intervals handler.

  openf1_client = OpenF1Client()