Pitstop

Instructions

Implementation Reference

• tools/live/stints.py:29-105 (handler)

  Main handler function for get_stints_live tool. Fetches live tire stint data from OpenF1 API using meeting/session keys, applies optional filters for driver and compound, converts raw data to Pydantic models (StintData), and returns structured StintsResponse.

  def get_stints_live(
      year: int,
      country: str,
      session_name: str = "Race",
      driver_number: Optional[int] = None,
      compound: Optional[str] = None
  ) -> StintsResponse:
      """
      Get real-time tire stint tracking 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)
          compound: Optional filter by compound ('SOFT', 'MEDIUM', 'HARD', 'INTERMEDIATE', 'WET')
  
      Returns:
          StintsResponse with tire stint data
  
      Example:
          get_stints_live(2024, "Monaco", "Race") → All stints in race
          get_stints_live(2024, "Monaco", "Race", 1) → Verstappen's stints
          get_stints_live(2024, "Monaco", "Race", compound="SOFT") → All soft tire stints
      """
      # Get meeting and session info
      meetings = openf1_client.get_meetings(year=year, country_name=country)
      if not meetings:
          return StintsResponse(
              session_name=session_name,
              year=year,
              country=country,
              stints=[],
              total_stints=0
          )
  
      # Get sessions for this meeting
      sessions = openf1_client.get_sessions(year=year, country_name=country, session_name=session_name)
      if not sessions:
          return StintsResponse(
              session_name=session_name,
              year=year,
              country=country,
              stints=[],
              total_stints=0
          )
  
      session = sessions[0]
      session_key = session['session_key']
  
      # Get stint data
      stint_data = openf1_client.get_stints(
          session_key=session_key,
          driver_number=driver_number,
          compound=compound
      )
  
      # Convert to Pydantic models
      stints = [
          StintData(
              stint_number=stint['stint_number'],
              driver_number=stint['driver_number'],
              compound=stint['compound'],
              lap_start=stint['lap_start'],
              lap_end=stint['lap_end'],
              tyre_age_at_start=stint['tyre_age_at_start']
          )
          for stint in stint_data
      ]
  
      return StintsResponse(
          session_name=session_name,
          year=year,
          country=country,
          stints=stints,
          total_stints=len(stints)
      )

• tools/live/stints.py:10-27 (schema)

  Pydantic models for input validation and structured output: StintData for individual stints and StintsResponse for the tool's return type.

  class StintData(BaseModel):
      """Tire stint data."""
      stint_number: int = Field(..., description="Stint number")
      driver_number: int = Field(..., description="Driver number (1-99)")
      compound: str = Field(..., description="Tire compound (SOFT, MEDIUM, HARD, etc.)")
      lap_start: Optional[int] = Field(None, description="Starting lap number")
      lap_end: Optional[int] = Field(None, description="Ending lap number")
      tyre_age_at_start: int = Field(..., description="Tyre age at start of stint")
  
  
  class StintsResponse(BaseModel):
      """Response for tire stint 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")
      stints: list[StintData] = Field(..., description="List of tire stints")
      total_stints: int = Field(..., description="Total number of stints")

• server.py:172-172 (registration)

  MCP tool registration decorator applied to the get_stints_live handler function.

  mcp.tool()(get_stints_live)

• tools/__init__.py:78-78 (registration)

  Exported in tools __all__ for import in server.py.

  "get_stints_live",

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

  Listed in tools/live __all__ and imported from stints.py.

  "get_stints_live",