Pitstop

Instructions

Implementation Reference

• tools/live/pit_stops.py:9-95 (handler)

  The main tool handler function that fetches pit stop data using OpenF1Client, converts to Pydantic models, calculates statistics like fastest/slowest/average pit stop durations, and returns PitStopsResponse.

  def get_live_pit_stops(
      year: int,
      country: str,
      session_name: str = "Race",
      driver_number: Optional[int] = None
  ) -> PitStopsResponse:
      """
      Get pit stop analysis with crew timing 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:
          PitStopsResponse with pit stop durations and statistics
  
      Example:
          get_live_pit_stops(2024, "Monaco", "Race") → All pit stops with timing
          get_live_pit_stops(2024, "Monaco", "Race", 1) → Verstappen's pit stops
      """
      # Get meeting and session info
      meetings = openf1_client.get_meetings(year=year, country_name=country)
      if not meetings:
          return PitStopsResponse(
              session_name=session_name,
              year=year,
              country=country,
              pit_stops=[],
              total_pit_stops=0
          )
  
      # Get sessions for this meeting
      sessions = openf1_client.get_sessions(year=year, country_name=country, session_name=session_name)
      if not sessions:
          return PitStopsResponse(
              session_name=session_name,
              year=year,
              country=country,
              pit_stops=[],
              total_pit_stops=0
          )
  
      session = sessions[0]
      session_key = session['session_key']
  
      # Get pit stop data
      pit_data = openf1_client.get_pit_stops(
          session_key=session_key,
          driver_number=driver_number
      )
  
      # Convert to Pydantic models
      pit_stops = [
          PitStopData(
              date=stop['date'],
              driver_number=stop['driver_number'],
              lap_number=stop['lap_number'],
              pit_duration=stop['pit_duration'],
              session_key=stop['session_key'],
              meeting_key=stop['meeting_key']
          )
          for stop in pit_data
      ]
  
      # Calculate statistics
      fastest_stop = None
      slowest_stop = None
      average_duration = None
  
      if pit_stops:
          durations = [stop.pit_duration for stop in pit_stops]
          fastest_stop = min(durations)
          slowest_stop = max(durations)
          average_duration = sum(durations) / len(durations)
  
      return PitStopsResponse(
          session_name=session_name,
          year=year,
          country=country,
          pit_stops=pit_stops,
          total_pit_stops=len(pit_stops),
          fastest_stop=fastest_stop,
          slowest_stop=slowest_stop,
          average_duration=average_duration
      )

• models/live/openf1.py:25-44 (schema)

  Pydantic models PitStopData (individual pit stop details) and PitStopsResponse (aggregated response with list of pit stops and statistics) used for input/output validation in get_live_pit_stops.

  class PitStopData(BaseModel):
      """Pit stop data."""
      date: str = Field(..., description="Timestamp of pit stop")
      driver_number: int = Field(..., description="Driver number (1-99)")
      lap_number: int = Field(..., description="Lap number of pit stop")
      pit_duration: float = Field(..., description="Duration of pit stop in seconds")
      session_key: int = Field(..., description="Session identifier")
      meeting_key: int = Field(..., description="Meeting identifier")
  
  
  class PitStopsResponse(BaseModel):
      """Response for pit stop 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")
      pit_stops: list[PitStopData] = Field(..., description="List of pit stops")
      total_pit_stops: int = Field(..., description="Total number of pit stops")
      fastest_stop: Optional[float] = Field(None, description="Fastest pit stop duration")
      slowest_stop: Optional[float] = Field(None, description="Slowest pit stop duration")
      average_duration: Optional[float] = Field(None, description="Average pit stop duration")

• server.py:169-169 (registration)

  MCP server registration of the get_live_pit_stops tool using the mcp.tool() decorator.

  mcp.tool()(get_live_pit_stops)

• tools/live/__init__.py:3-10 (registration)

  Re-export of get_live_pit_stops from pit_stops.py module in tools/live package for easier imports.

  from .pit_stops import get_live_pit_stops
  from .intervals import get_live_intervals
  from .meetings import get_meeting_info
  from .stints import get_stints_live
  
  __all__ = [
      "get_driver_radio",
      "get_live_pit_stops",

• tools/__init__.py:43-75 (registration)

  Re-export of get_live_pit_stops from tools.live subpackage in main tools package.

  from .live import get_driver_radio, get_live_pit_stops, get_live_intervals, get_meeting_info, get_stints_live
  
  __all__ = [
      # Session
      "get_session_details",
      "get_session_results",
      "get_laps",
      "get_session_drivers",
      "get_tire_strategy",
      "get_qualifying_sessions",
      "get_track_evolution",
      # Telemetry
      "get_lap_telemetry",
      "compare_driver_telemetry",
      # Weather
      "get_session_weather",
      # Control
      "get_race_control_messages",
      # Standings
      "get_standings",
      # Media
      "get_f1_news",
      # Schedule
      "get_schedule",
      # Reference
      "get_reference_data",
      # Track
      "get_circuit",
      # Analysis
      "get_analysis",
      # Live (OpenF1)
      "get_driver_radio",
      "get_live_pit_stops",