get_event_schedule
Retrieve the Formula One race calendar for a specific season by inputting the year. Access event schedules directly using Python-based FastF1 library integration.
Instructions
Get Formula One race calendar for a specific season
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | Season year (e.g., 2023) |
Implementation Reference
- src/f1_mcp_server/f1_data.py:90-122 (handler)Core handler function that validates the year, fetches the F1 event schedule using fastf1.get_event_schedule, converts the DataFrame to JSON-serializable format, and returns structured success/error response.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)MCP Tool schema definition including input schema requiring 'year' as 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:161-164 (registration)Dispatch logic in the main tool handler that calls the get_event_schedule function with sanitized year argument.if name == "get_event_schedule": if "year" not in sanitized_args: sanitized_args["year"] = int(arguments["year"]) result = get_event_schedule(sanitized_args["year"])
- src/f1_mcp_server/f1_data.py:66-88 (helper)Helper function to validate the input year is an 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)Helper function to serialize non-JSON objects (datetimes, numpy types, NaN) for the response.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)