get_championship_standings

Instructions

Implementation Reference

• src/f1_mcp_server/f1_data.py:540-598 (handler)

  Core handler function that retrieves driver and constructor championship standings using FastF1's Ergast API, processes the data into JSON-serializable format, and handles errors.

  def get_championship_standings(year, round_num=None):
      """
      Get championship standings for drivers and constructors.
  
      Args:
          year (int or str): The year of the F1 season
          round_num (int, optional): Specific round number or None for latest
  
      Returns:
          dict: Status and championship standings or error information
      """
      try:
          year = int(year)
  
          # Create Ergast API client
          ergast = fastf1.ergast.Ergast()
  
          # Get Ergast API data
          if round_num:
              round_num = int(round_num)  # Ensure proper type conversion
              drivers_standings = ergast.get_driver_standings(
                  season=year, round=round_num
              ).content[0]
              constructor_standings = ergast.get_constructor_standings(
                  season=year, round=round_num
              ).content[0]
          else:
              drivers_standings = ergast.get_driver_standings(season=year).content[0]
              constructor_standings = ergast.get_constructor_standings(
                  season=year
              ).content[0]
  
          # Convert driver standings to JSON serializable format
          drivers_list = []
          for _, row in drivers_standings.iterrows():
              driver_dict = row.to_dict()
              clean_dict = {k: json_serial(v) for k, v in driver_dict.items()}
              drivers_list.append(clean_dict)
  
          # Convert constructor standings to JSON serializable format
          constructors_list = []
          for _, row in constructor_standings.iterrows():
              constructor_dict = row.to_dict()
              clean_dict = {k: json_serial(v) for k, v in constructor_dict.items()}
              constructors_list.append(clean_dict)
  
          return {
              "status": "success",
              "data": {
                  "drivers": drivers_list,
                  "constructors": constructors_list,
              },
          }
      except Exception as e:
          logger.error(f"Error getting championship standings: {str(e)}", exc_info=True)
          return {
              "status": "error",
              "message": f"Failed to get championship standings: {str(e)}",
          }

• src/f1_mcp_server/server.py:512-532 (schema)

  MCP tool schema definition including input parameters (year required, round_num optional) and description.

  types.Tool(
      name="get_championship_standings",
      description="Get Formula One championship standings",
      inputSchema={
          "type": "object",
          "properties": {
              "year": {
                  "type": "number",
                  "description": "Season year (e.g., 2023)",
              },
              "round_num": {
                  "type": "number",
                  "description": (
                      "Round number (optional, gets latest "
                      "standings if not provided)"
                  ),
              },
          },
          "required": ["year"],
      },
  ),

• src/f1_mcp_server/server.py:241-252 (registration)

  Dispatch logic in the MCP call_tool handler that validates arguments and calls the get_championship_standings function.

  elif name == "get_championship_standings":
      round_num = arguments.get("round_num")
      if round_num is not None:
          try:
              round_num = int(round_num)
              if round_num <= 0:
                  raise ValueError("Round number must be positive")
          except (ValueError, TypeError) as e:
              raise ValueError(f"Invalid round number: {round_num}") from e
  
      result = get_championship_standings(sanitized_args["year"], round_num)
  else:

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

  Import of the get_championship_standings handler function into the MCP server module.

  get_championship_standings,