Formula One MCP Server

Instructions

Implementation Reference

• src/f1_mcp_server/f1_data.py:143-183 (handler)

  The core handler function implementing the get_event_info tool logic. It validates inputs, fetches event data using fastf1.get_event(), serializes to JSON-compatible format using json_serial helper, and returns structured success/error response.

  def get_event_info(year: Any, identifier: str) -> dict[str, Any]:
      """
      Get information about a specific Formula One event.
  
      Args:
          year (int or str): The year of the F1 season
          identifier (str): Event name or round number
  
      Returns:
          dict: Status and event data or error information
      """
      try:
          # Validate year
          year_int = validate_year(year)
  
          # Validate identifier
          if not identifier or not isinstance(identifier, str | int):
              raise ValueError("Invalid event identifier")
  
          logger.debug(f"Fetching event info for {year_int}, event: {identifier}")
  
          # Identifier can be event name or round number
          if str(identifier).isdigit():
              event = fastf1.get_event(year_int, int(identifier))
          else:
              event = fastf1.get_event(year_int, str(identifier))
  
          # Convert Series to dict and clean non-serializable values
          event_dict = event.to_dict()
          clean_dict = {k: json_serial(v) for k, v in event_dict.items()}
  
          logger.info(
              f"Successfully retrieved event info for {year_int}, event: {identifier}"
          )
          return {"status": "success", "data": clean_dict}
      except Exception as e:
          logger.error(f"Error retrieving event info: {str(e)}", exc_info=True)
          return {
              "status": "error",
              "message": f"Failed to retrieve event information: {str(e)}",
          }

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

  MCP tool registration in list_tools(). Defines the tool name, description, and input schema for get_event_info.

  types.Tool(
      name="get_event_info",
      description=(
          "Get detailed information about a specific Formula One Grand Prix"
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "year": {
                  "type": "number",
                  "description": "Season year (e.g., 2023)",
              },
              "identifier": {
                  "type": "string",
                  "description": (
                      "Event name or round number (e.g., 'Monaco' or '7')"
                  ),
              },
          },
          "required": ["year", "identifier"],
      },
  ),

• src/f1_mcp_server/server.py:165-169 (handler)

  Dispatch logic in the MCP call_tool handler that invokes the get_event_info function with sanitized arguments.

  elif name == "get_event_info":
      if "identifier" not in arguments:
          raise ValueError("Missing required argument: identifier")
      identifier = str(arguments["identifier"])
      result = get_event_info(sanitized_args["year"], identifier)

• f1-messenger-app/src/services/f1ToolSchemas.ts:43-58 (schema)

  Client-side TypeScript schema definition for get_event_info tool used in Gemini function calling.

  name: 'get_event_info',
  description: 'Get detailed information about a specific Formula One Grand Prix including dates, location, and track details',
  parameters: {
    type: SchemaType.OBJECT,
    properties: {
      year: {
        type: SchemaType.NUMBER,
        description: 'Season year (e.g., 2024, 2023, 2022)',
      },
      identifier: {
        type: SchemaType.STRING,
        description: 'Event name or round number (e.g., "Monaco", "British", "7", "15")',
      }
    },
    required: ['year', 'identifier']
  }

• f1-messenger-app/mcp-bridge.py:105-105 (registration)

  Tool mapping registration in the HTTP bridge that directly imports and calls the get_event_info handler from f1_mcp_server.f1_data.

  'get_event_info': get_event_info,