get_championship_standings

Instructions

Implementation Reference

• src/f1_mcp_server/f1_data.py:522-580 (handler)

  Handler function that fetches F1 championship standings (drivers and constructors) using the FastF1 Ergast API. Accepts a year (required) and optional round_num. Returns JSON-serializable driver and constructor standings data.

  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 analyzing driver performance: {str(e)}", exc_info=True)
          return {
              "status": "error",
              "message": f"Failed to analyze driver performance: {str(e)}",
          }

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

  Schema definition for get_championship_standings tool registration. Defines input parameters: year (required, number) and round_num (optional, number).

  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:512-532 (registration)

  Tool registration via list_tools() function returning a types.Tool object with name 'get_championship_standings'.

  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-251 (handler)

  Call handler routing in f1_tool() - validates round_num argument then dispatches to get_championship_standings handler 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)

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

  Import of get_championship_standings from f1_data module into server.py.

  from .f1_data import (
      analyze_driver_performance,
      compare_drivers,
      get_championship_standings,