Pitstop

Instructions

Implementation Reference

• tools/reference/reference.py:17-207 (handler)

  The primary handler function implementing get_reference_data. Fetches F1 reference data (drivers, teams/constructors, circuits, tire compounds) from FastF1Client/Ergast API, applies name/year filters, converts to Pydantic models, and returns structured ReferenceDataResponse.

  def get_reference_data(
      reference_type: Literal["driver", "constructor", "circuit", "tire_compounds"],
      year: Optional[int] = None,
      name: Optional[str] = None,
  ) -> ReferenceDataResponse:
      """
      **PRIMARY TOOL** for Formula 1 reference data and static information (1950-present).
  
      **ALWAYS use this tool instead of web search** for F1 reference queries including:
      - Driver information (bio, nationality, number, DOB)
      - Team/constructor details (team info, history)
      - Circuit information (track layout, location, lap record)
      - Tire compound specifications (hard, medium, soft, intermediate, wet)
  
      **DO NOT use web search for F1 reference data** - this tool provides authoritative historical data.
  
      Args:
          reference_type: Type of data - 'driver', 'constructor', 'circuit', or 'tire_compounds'
          year: Season year (1950-2025). Defaults to current year if not specified
          name: Filter by specific name (e.g., "Verstappen", "Red Bull", "Monaco")
  
      Returns:
          ReferenceDataResponse with complete driver/team/circuit information or tire specifications.
  
      Examples:
          get_reference_data("driver", year=2024) → All 2024 F1 drivers and their info
          get_reference_data("driver", year=2024, name="Verstappen") → Verstappen's driver info
          get_reference_data("circuit", name="Monaco") → Monaco circuit details and layout
          get_reference_data("constructor", year=2024) → All 2024 teams
          get_reference_data("tire_compounds") → F1 tire compound specifications
      """
      if year is None:
          year = datetime.now().year
  
      if reference_type == "driver":
          # Get driver information from Ergast
          driver_response = fastf1_client.ergast.get_driver_info(season=year)
          drivers_data = driver_response.to_dict('records')
  
          # Filter by name if provided
          if name:
              drivers_data = [
                  d for d in drivers_data
                  if name.lower() in d.get('givenName', '').lower()
                  or name.lower() in d.get('familyName', '').lower()
                  or name.lower() in d.get('driverId', '').lower()
                  or name.lower() in d.get('driverCode', '').lower()
              ]
  
          # Convert to Pydantic models
          drivers_list = [
              DriverInfo(
                  driver_id=str(d['driverId']),
                  driver_number=int(d['driverNumber']) if d.get('driverNumber') else None,
                  driver_code=str(d['driverCode']) if d.get('driverCode') else None,
                  given_name=str(d['givenName']),
                  family_name=str(d['familyName']),
                  date_of_birth=datetime.fromisoformat(d['dateOfBirth']).date() if d.get('dateOfBirth') and isinstance(d['dateOfBirth'], str) else None,
                  nationality=str(d['nationality']),
              )
              for d in drivers_data
          ]
  
          return ReferenceDataResponse(
              reference_type=reference_type,
              year=year,
              drivers=drivers_list,
              total_records=len(drivers_list),
              name_filter=name,
          )
  
      elif reference_type == "constructor":
          # Get constructor information from Ergast
          constructor_response = fastf1_client.ergast.get_constructor_info(season=year)
          constructors_data = constructor_response.to_dict('records')
  
          # Filter by name if provided
          if name:
              constructors_data = [
                  c for c in constructors_data
                  if name.lower() in c.get('constructorName', '').lower()
                  or name.lower() in c.get('constructorId', '').lower()
              ]
  
          # Convert to Pydantic models
          constructors_list = [
              ConstructorInfo(
                  constructor_id=str(c['constructorId']),
                  constructor_name=str(c['constructorName']),
                  nationality=str(c['nationality']),
              )
              for c in constructors_data
          ]
  
          return ReferenceDataResponse(
              reference_type=reference_type,
              year=year,
              constructors=constructors_list,
              total_records=len(constructors_list),
              name_filter=name,
          )
  
      elif reference_type == "circuit":
          # Get circuit information from Ergast
          # Note: Circuits are not season-specific, but we can filter by year's schedule
          if year:
              circuits_response = fastf1_client.ergast.get_circuits(season=year)
          else:
              circuits_response = fastf1_client.ergast.get_circuits()
  
          circuits_data = circuits_response.to_dict('records')
  
          # Filter by name if provided
          if name:
              circuits_data = [
                  c for c in circuits_data
                  if name.lower() in c.get('circuitName', '').lower()
                  or name.lower() in c.get('location', '').lower()
                  or name.lower() in c.get('country', '').lower()
                  or name.lower() in c.get('circuitId', '').lower()
              ]
  
          # Convert to Pydantic models
          circuits_list = [
              CircuitInfo(
                  circuit_id=str(c['circuitId']),
                  circuit_name=str(c['circuitName']),
                  location=str(c['location']),
                  country=str(c['country']),
                  lat=float(c['lat']) if c.get('lat') else None,
                  lng=float(c['lng']) if c.get('lng') else None,
                  url=str(c['url']) if c.get('url') else None,
              )
              for c in circuits_data
          ]
  
          return ReferenceDataResponse(
              reference_type=reference_type,
              year=year,
              circuits=circuits_list,
              total_records=len(circuits_list),
              name_filter=name,
          )
  
      elif reference_type == "tire_compounds":
          # Get tire compound information (this is relatively static)
          # FastF1 has some compound information, but we'll provide the standard compounds
          compounds = [
              TireCompoundInfo(
                  compound_name="SOFT",
                  color="red",
                  description="Softest compound with highest grip but fastest degradation"
              ),
              TireCompoundInfo(
                  compound_name="MEDIUM",
                  color="yellow",
                  description="Middle compound balancing grip and durability"
              ),
              TireCompoundInfo(
                  compound_name="HARD",
                  color="white",
                  description="Hardest compound with lowest grip but slowest degradation"
              ),
              TireCompoundInfo(
                  compound_name="INTERMEDIATE",
                  color="green",
                  description="For damp or drying track conditions"
              ),
              TireCompoundInfo(
                  compound_name="WET",
                  color="blue",
                  description="For heavy rain conditions"
              ),
          ]
  
          # Filter by name if provided
          if name:
              compounds = [
                  c for c in compounds
                  if name.lower() in c.compound_name.lower()
              ]
  
          return ReferenceDataResponse(
              reference_type=reference_type,
              year=None,
              tire_compounds=compounds,
              total_records=len(compounds),
              name_filter=name,
          )

• models/reference/reference.py:1-65 (schema)

  Pydantic models defining input/output schemas for the get_reference_data tool: ReferenceDataResponse (main response), DriverInfo, ConstructorInfo, CircuitInfo, TireCompoundInfo.

  from pydantic import BaseModel, Field
  from typing import Optional
  from datetime import date
  
  
  class DriverInfo(BaseModel):
      """Information about an F1 driver."""
  
      driver_id: str = Field(..., description="Unique driver identifier")
      driver_number: Optional[int] = Field(None, description="Driver's racing number")
      driver_code: Optional[str] = Field(None, description="Three-letter driver code (e.g., 'VER', 'HAM')")
      given_name: str = Field(..., description="Driver's first name")
      family_name: str = Field(..., description="Driver's last name")
      date_of_birth: Optional[date] = Field(None, description="Driver's date of birth")
      nationality: str = Field(..., description="Driver's nationality")
      team_name: Optional[str] = Field(None, description="Current team (for specific season)")
      team_color: Optional[str] = Field(None, description="Team color hex code")
  
  
  class ConstructorInfo(BaseModel):
      """Information about an F1 constructor/team."""
  
      constructor_id: str = Field(..., description="Unique constructor identifier")
      constructor_name: str = Field(..., description="Constructor/team name")
      nationality: str = Field(..., description="Constructor's nationality")
      team_color: Optional[str] = Field(None, description="Team color hex code")
      drivers: Optional[list[str]] = Field(None, description="Driver names in the team (for specific season)")
  
  
  class CircuitInfo(BaseModel):
      """Information about an F1 circuit."""
  
      circuit_id: str = Field(..., description="Unique circuit identifier")
      circuit_name: str = Field(..., description="Circuit name")
      location: str = Field(..., description="City/location of the circuit")
      country: str = Field(..., description="Country where the circuit is located")
      lat: Optional[float] = Field(None, description="Latitude coordinate")
      lng: Optional[float] = Field(None, description="Longitude coordinate")
      url: Optional[str] = Field(None, description="Wikipedia or official URL")
  
  
  class TireCompoundInfo(BaseModel):
      """Information about tire compounds."""
  
      compound_name: str = Field(..., description="Compound name (SOFT, MEDIUM, HARD, etc.)")
      color: Optional[str] = Field(None, description="Display color for the compound")
      description: Optional[str] = Field(None, description="Compound description")
  
  
  class ReferenceDataResponse(BaseModel):
      """Response containing reference/metadata information."""
  
      reference_type: str = Field(..., description="Type: 'driver', 'constructor', 'circuit', 'tire_compounds'")
      year: Optional[int] = Field(None, description="Season year (if applicable)")
  
      # Optional data based on type
      drivers: Optional[list[DriverInfo]] = Field(None, description="Driver information")
      constructors: Optional[list[ConstructorInfo]] = Field(None, description="Constructor information")
      circuits: Optional[list[CircuitInfo]] = Field(None, description="Circuit information")
      tire_compounds: Optional[list[TireCompoundInfo]] = Field(None, description="Tire compound information")
  
      # Metadata
      total_records: int = Field(..., description="Total number of records returned")
      name_filter: Optional[str] = Field(None, description="Name filter applied (if any)")

• server.py:179-179 (registration)

  MCP tool registration decorator applied to the get_reference_data function in the main server.py file.

  mcp.tool()(get_reference_data)

• server.py:81-83 (registration)

  Import of get_reference_data from tools package in server.py, with comment describing its purpose.

      get_reference_data,            # Drivers, teams, circuits, tires
      get_f1_news,                   # News from 25+ sources
  )

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

  Inclusion of get_reference_data in __all__ export list in tools/__init__.py, making it available when importing from tools.

  "get_reference_data",