get_event_schedule

Instructions

Implementation Reference

• src/f1_mcp_server/f1_data.py:90-122 (handler)

  The core handler function for 'get_event_schedule'. It validates the year using validate_year(), calls fastf1.get_event_schedule(year_int), converts the resulting DataFrame to a JSON-serializable list of dicts, and returns {'status': 'success', 'data': result} or {'status': 'error', 'message': ...} on failure.

  def get_event_schedule(year: Any) -> dict[str, Any]:
      """
      Get the event schedule for a specified Formula One season.
  
      Args:
          year (int or str): The year of the F1 season
  
      Returns:
          dict: Status and schedule data or error information
      """
      try:
          # Validate year
          year_int = validate_year(year)
  
          logger.debug(f"Fetching event schedule for {year_int}")
          schedule = fastf1.get_event_schedule(year_int)
  
          # Convert DataFrame to JSON serializable format
          result = []
          for _, row in schedule.iterrows():
              event_dict = row.to_dict()
              # Clean and convert non-serializable values
              clean_dict = {k: json_serial(v) for k, v in event_dict.items()}
              result.append(clean_dict)
  
          logger.info(f"Successfully retrieved {len(result)} events for {year_int}")
          return {"status": "success", "data": result}
      except Exception as e:
          logger.error(f"Error retrieving event schedule: {str(e)}", exc_info=True)
          return {
              "status": "error",
              "message": f"Failed to retrieve event schedule: {str(e)}",
          }

• src/f1_mcp_server/server.py:284-297 (schema)

  Tool registration with input schema for 'get_event_schedule'. Defines the tool name, description, and inputSchema requiring a 'year' property of type 'number'.

  types.Tool(
      name="get_event_schedule",
      description=("Get Formula One race calendar for a specific season"),
      inputSchema={
          "type": "object",
          "properties": {
              "year": {
                  "type": "number",
                  "description": "Season year (e.g., 2023)",
              },
          },
          "required": ["year"],
      },
  ),

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

  Registration of 'get_event_schedule' in the list_tools() function returning the Tool object with name, description, and inputSchema.

  types.Tool(
      name="get_event_schedule",
      description=("Get Formula One race calendar for a specific season"),
      inputSchema={
          "type": "object",
          "properties": {
              "year": {
                  "type": "number",
                  "description": "Season year (e.g., 2023)",
              },
          },
          "required": ["year"],
      },
  ),

• src/f1_mcp_server/f1_data.py:66-88 (helper)

  The validate_year() helper function used by get_event_schedule to ensure the year is a valid integer between 1950 and current_year+1.

  def validate_year(year: Any) -> int:
      """
      Validate that the provided year is valid for F1 data.
  
      Args:
          year: Year value to validate
  
      Returns:
          Valid year as integer
  
      Raises:
          ValueError: If year is invalid
      """
      try:
          year_int = int(year)
          # F1 started in 1950 and we don't want future years far ahead
          current_year = datetime.now().year
          if year_int < 1950 or year_int > current_year + 1:
              raise ValueError(f"Year must be between 1950 and {current_year + 1}")
          return year_int
      except (ValueError, TypeError) as e:
          raise ValueError(f"Invalid year format: {year}") from e

• src/f1_mcp_server/f1_data.py:45-63 (helper)

  The json_serial() helper used by get_event_schedule to convert non-JSON-serializable objects (datetime, Timestamp, numpy types, NaN) to serializable values.

  def json_serial(obj: Any) -> str | int | float | None:
      """
      Convert non-JSON serializable objects to strings.
  
      Args:
          obj: Object to be serialized to JSON
  
      Returns:
          JSON serializable representation of the object
      """
      if isinstance(obj, datetime | pd.Timestamp):
          return obj.isoformat()
      if isinstance(obj, np.integer):
          return int(obj)
      if isinstance(obj, np.floating):
          return float(obj)
      if pd.isna(obj) or obj is None:
          return None
      return str(obj)