compare_drivers

Instructions

Implementation Reference

• src/f1_mcp_server/f1_data.py:393-458 (handler)

  Core handler function that implements the compare_drivers tool logic using FastF1 to load session data, extract laps for multiple drivers, compute performance metrics like fastest lap, average lap time, and total laps, and return structured comparison data.

  def compare_drivers(year, event_identifier, session_name, drivers):
      """
      Compare performance between multiple Formula One drivers.
  
      Args:
          year (int or str): The year of the F1 season
          event_identifier (str): Event name or round number
          session_name (str): Session type (Race, Qualifying, Sprint, etc.)
          drivers (str): Comma-separated list of driver codes
  
      Returns:
          dict: Status and driver comparison data or error information
      """
      try:
          year = int(year)
          drivers_list = drivers.split(",")
  
          session = fastf1.get_session(year, event_identifier, session_name)
          session.load()
  
          driver_comparisons = []
  
          for driver in drivers_list:
              # Get laps and fastest lap for each driver
              driver_laps = session.laps.pick_driver(driver)
              fastest_lap = driver_laps.pick_fastest()
  
              # Calculate average lap time
              valid_lap_times = []
              for _, lap in driver_laps.iterrows():
                  if lap["LapTime"] is not None and not pd.isna(lap["LapTime"]):
                      valid_lap_times.append(lap["LapTime"].total_seconds())
  
              avg_lap_time = (
                  sum(valid_lap_times) / len(valid_lap_times) if valid_lap_times else None
              )
  
              # Format lap time as string
              formatted_fastest = None
              fastest_lap_number = None
              if fastest_lap is not None:
                  formatted_fastest = (
                      str(fastest_lap["LapTime"])
                      if not pd.isna(fastest_lap["LapTime"])
                      else None
                  )
                  fastest_lap_number = (
                      int(fastest_lap["LapNumber"])
                      if not pd.isna(fastest_lap["LapNumber"])
                      else None
                  )
  
              # Compile driver data
              driver_data = {
                  "DriverCode": driver,
                  "FastestLap": formatted_fastest,
                  "FastestLapNumber": fastest_lap_number,
                  "TotalLaps": len(driver_laps),
                  "AverageLapTime": avg_lap_time,
              }
  
              driver_comparisons.append(driver_data)
  
          return {"status": "success", "data": driver_comparisons}
      except Exception as e:
          return {"status": "error", "message": str(e)}

• src/f1_mcp_server/server.py:217-223 (registration)

  Dispatch logic in the MCP server's call_tool handler that routes requests for 'compare_drivers' to the actual implementation function.

  elif name == "compare_drivers":
      result = compare_drivers(
          sanitized_args["year"],
          str(arguments["event_identifier"]),
          str(arguments["session_name"]),
          str(arguments["drivers"]),
      )

• src/f1_mcp_server/server.py:425-465 (schema)

  MCP tool registration in list_tools() that defines the compare_drivers tool name, description, and input schema for validation.

  types.Tool(
      name="compare_drivers",
      description=(
          "Compare performance between multiple Formula One drivers"
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "year": {
                  "type": "number",
                  "description": "Season year (e.g., 2023)",
              },
              "event_identifier": {
                  "type": "string",
                  "description": (
                      "Event name or round number (e.g., 'Monaco' or '7')"
                  ),
              },
              "session_name": {
                  "type": "string",
                  "description": (
                      "Session name (e.g., 'Race', 'Qualifying', "
                      "'Sprint', 'FP1', 'FP2', 'FP3')"
                  ),
              },
              "drivers": {
                  "type": "string",
                  "description": (
                      "Comma-separated list of driver codes "
                      "(e.g., 'HAM,VER,LEC')"
                  ),
              },
          },
          "required": [
              "year",
              "event_identifier",
              "session_name",
              "drivers",
          ],
      },
  ),

• f1-messenger-app/mcp-bridge.py:102-111 (registration)

  Secondary registration of compare_drivers in the FastAPI bridge's tool_functions mapping for direct HTTP tool calls.

  tool_functions = {
      'get_championship_standings': get_championship_standings,
      'get_event_schedule': get_event_schedule,
      'get_event_info': get_event_info,
      'get_session_results': get_session_results,
      'get_driver_info': get_driver_info,
      'analyze_driver_performance': analyze_driver_performance,
      'compare_drivers': compare_drivers,
      'get_telemetry': get_telemetry
  }

• f1-messenger-app/src/services/f1ToolSchemas.ts:139-139 (schema)

  Client-side TypeScript schema reference for the compare_drivers tool.

  name: 'compare_drivers',