Formula One MCP Server

Instructions

Implementation Reference

• src/f1_mcp_server/f1_data.py:186-249 (handler)

  Core handler function that implements the get_session_results tool logic using FastF1 API to load session data, extract results, serialize to JSON-compatible format, and handle validation/errors.

  def get_session_results(
      year: Any, event_identifier: str, session_name: str
  ) -> dict[str, Any]:
      """
      Get results for a specific Formula One session.
  
      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.)
  
      Returns:
          dict: Status and session results data or error information
      """
      try:
          # Validate year
          year_int = validate_year(year)
  
          # Validate session name
          valid_sessions = [
              "Race",
              "Qualifying",
              "Sprint",
              "FP1",
              "FP2",
              "FP3",
              "SprintQualifying",
          ]
          if session_name not in valid_sessions:
              raise ValueError(
                  f"Invalid session name. Must be one of: {', '.join(valid_sessions)}"
              )
  
          logger.debug(
              f"Fetching session results for {year_int}, "
              f"event: {event_identifier}, session: {session_name}"
          )
  
          session = fastf1.get_session(year_int, event_identifier, session_name)
          # Load session without telemetry for faster results
          session.load(telemetry=False)
  
          # Get results as a DataFrame
          results = session.results
  
          # Convert results to JSON serializable format
          result_list = []
          for _, result in results.items():
              driver_result = result.to_dict()
              # Clean and convert non-serializable values
              clean_dict = {k: json_serial(v) for k, v in driver_result.items()}
              result_list.append(clean_dict)
  
          logger.info(
              f"Successfully retrieved results for {year_int}, "
              f"event: {event_identifier}, session: {session_name}"
          )
          return {"status": "success", "data": result_list}
      except Exception as e:
          logger.error(f"Error retrieving session results: {str(e)}", exc_info=True)
          return {
              "status": "error",
              "message": f"Failed to retrieve session results: {str(e)}",
          }

• src/f1_mcp_server/server.py:320-346 (schema)

  MCP tool schema definition including input validation schema for get_session_results parameters (year, event_identifier, session_name).

  types.Tool(
      name="get_session_results",
      description="Get results for a specific Formula One session",
      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')"
                  ),
              },
          },
          "required": ["year", "event_identifier", "session_name"],
      },
  ),

• src/f1_mcp_server/server.py:24-33 (registration)

  Import of the get_session_results handler function into the MCP server module for registration and use in tool dispatching.

  from .f1_data import (
      analyze_driver_performance,
      compare_drivers,
      get_championship_standings,
      get_driver_info,
      get_event_info,
      get_event_schedule,
      get_session_results,
      get_telemetry,
  )

• src/f1_mcp_server/server.py:170-200 (registration)

  Tool dispatching logic in the MCP call_tool handler that validates inputs and invokes the get_session_results function.

  elif name == "get_session_results":
      # Additional validations for session-related tools
      if "event_identifier" not in arguments:
          raise ValueError("Missing required argument: event_identifier")
      if "session_name" not in arguments:
          raise ValueError("Missing required argument: session_name")
  
      event_identifier = str(arguments["event_identifier"])
      session_name = str(arguments["session_name"])
  
      # Validate session_name format
      valid_sessions = [
          "Race",
          "Qualifying",
          "Sprint",
          "FP1",
          "FP2",
          "FP3",
          "SprintQualifying",
      ]
      if session_name not in valid_sessions:
          raise ValueError(
              "Invalid session_name: must be one of "
              f"{', '.join(valid_sessions)}"
          )
  
      result = get_session_results(
          sanitized_args["year"],
          event_identifier,
          session_name,
      )