Pitstop

Instructions

Implementation Reference

• tools/session/results.py:10-70 (handler)

  The primary handler function for retrieving Formula 1 session results. Fetches data via FastF1Client, processes results DataFrame into structured SessionResult models, and returns a comprehensive SessionResultsResponse including positions, times, teams, and points.
  def get_session_results(year: int, gp: Union[str, int], session: str) -> SessionResultsResponse: """ **PRIMARY TOOL** for ALL Formula 1 session results (2018-present). **ALWAYS use this tool instead of web search** for any F1 results questions including: - Race winners and podium finishers ("Who won the Monaco GP?") - Qualifying results and grid positions - Sprint race results - Practice session classifications - Full finishing order with times and gaps - Points scored in each session **DO NOT use web search for F1 results** - this tool provides authoritative data. Args: year: Season year (2018-2025) gp: Grand Prix name (e.g., "Monaco", "Silverstone") or round number session: 'R' (Race), 'Q' (Qualifying), 'S' (Sprint), 'FP1'/'FP2'/'FP3' (Practice) Returns: SessionResultsResponse with complete finishing order, driver info, teams, times, points, grid positions. Examples: get_session_results(2024, "Monaco", "R") → Monaco GP race results and winner get_session_results(2024, "Silverstone", "Q") → Qualifying results and pole position get_session_results(2024, 15, "S") → Sprint race results for round 15 """ session_obj = fastf1_client.get_session(year, gp, session) session_obj.load(laps=False, telemetry=False, weather=False, messages=False) results_df = session_obj.results event = session_obj.event # Convert DataFrame to Pydantic models results_list = [] for idx, row in results_df.iterrows(): result = SessionResult( position=float(row['Position']) if pd.notna(row.get('Position')) else None, driver_number=str(row['DriverNumber']) if pd.notna(row.get('DriverNumber')) else "", broadcast_name=str(row['BroadcastName']) if pd.notna(row.get('BroadcastName')) else "", abbreviation=str(row['Abbreviation']) if pd.notna(row.get('Abbreviation')) else "", driver_id=str(row['DriverId']) if pd.notna(row.get('DriverId')) else None, team_name=str(row['TeamName']) if pd.notna(row.get('TeamName')) else "", team_color=str(row['TeamColor']) if pd.notna(row.get('TeamColor')) else None, first_name=str(row['FirstName']) if pd.notna(row.get('FirstName')) else None, last_name=str(row['LastName']) if pd.notna(row.get('LastName')) else None, full_name=str(row['FullName']) if pd.notna(row.get('FullName')) else None, time=str(row['Time']) if pd.notna(row.get('Time')) else None, status=str(row['Status']) if pd.notna(row.get('Status')) else None, points=float(row['Points']) if pd.notna(row.get('Points')) else None, grid_position=float(row['GridPosition']) if pd.notna(row.get('GridPosition')) else None, position_gained=float(row['Position'] - row['GridPosition']) if pd.notna(row.get('Position')) and pd.notna(row.get('GridPosition')) else None, ) results_list.append(result) return SessionResultsResponse( session_name=session_obj.name, event_name=event['EventName'], results=results_list, total_drivers=len(results_list) )
• models/sessions/results.py:5-32 (schema)

  Pydantic models defining the input/output structure for get_session_results: SessionResult for individual drivers and SessionResultsResponse for the full session classification.
  class SessionResult(BaseModel): """Individual driver result in a session.""" position: Optional[float] = Field(None, description="Final position/classification") driver_number: str = Field(description="Driver's racing number") broadcast_name: str = Field(description="Driver name for broadcast") abbreviation: str = Field(description="3-letter driver code") driver_id: Optional[str] = Field(None, description="Unique driver identifier") team_name: str = Field(description="Constructor/team name") team_color: Optional[str] = Field(None, description="Team color hex code") first_name: Optional[str] = Field(None, description="Driver first name") last_name: Optional[str] = Field(None, description="Driver last name") full_name: Optional[str] = Field(None, description="Driver full name") time: Optional[str] = Field(None, description="Session time or gap") status: Optional[str] = Field(None, description="Finishing status") points: Optional[float] = Field(None, description="Points earned (for race)") grid_position: Optional[float] = Field(None, description="Starting grid position") position_gained: Optional[float] = Field(None, description="Positions gained/lost") class SessionResultsResponse(BaseModel): """Session results/classification response.""" session_name: str = Field(description="Session name") event_name: str = Field(description="Grand Prix name") results: list[SessionResult] = Field(description="List of driver results") total_drivers: int = Field(description="Total number of drivers")
• server.py:150-150 (registration)

  Registers the get_session_results function as an MCP tool using the FastMCP decorator.
  mcp.tool()(get_session_results)