Formula One MCP Server

Instructions

Implementation Reference

• python/f1_data.py:47-63 (handler)

  The core handler function that executes the tool logic: fetches F1 event data using fastf1.get_event based on year and identifier (name or round number), serializes it to JSON-compatible dict using json_serial helper.

  def get_event_info(year, identifier):
      """Get information about a specific event"""
      try:
          year = int(year)
          # Identifier can be event name or round number
          if identifier.isdigit():
              event = fastf1.get_event(year, int(identifier))
          else:
              event = fastf1.get_event(year, 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()}
          
          return {"status": "success", "data": clean_dict}
      except Exception as e:
          return {"status": "error", "message": str(e), "traceback": traceback.format_exc()}

• src/index.ts:105-122 (schema)

  MCP tool schema definition: input validation schema specifying 'year' (number) and 'identifier' (string) parameters.

  {
    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/index.ts:298-304 (registration)

  Tool handler registration in the MCP CallToolRequestSchema switch: casts arguments and calls the Python bridge function executePythonFunction.

  case 'get_event_info': {
    const typedArgs = args as EventInfoArgs;
    result = await executePythonFunction('get_event_info', [
      typedArgs.year.toString(),
      typedArgs.identifier.toString(),
    ]);
    break;

• python/f1_data.py:290-299 (registration)

  Registers get_event_info in the Python script's function dispatcher dictionary for invocation via command-line arguments in main().

  functions = {
      "get_event_schedule": get_event_schedule,
      "get_event_info": get_event_info,
      "get_session_results": get_session_results,
      "get_driver_info": get_driver_info,
      "analyze_driver_performance": analyze_driver_performance,
      "compare_drivers": compare_drivers,
      "get_telemetry": get_telemetry,
      "get_championship_standings": get_championship_standings
  }

• python/f1_data.py:19-27 (helper)

  Supporting utility function used by get_event_info to serialize pandas/fastf1 objects to JSON-compatible formats.

  def json_serial(obj):
      """Helper function to convert non-JSON serializable objects to strings"""
      if isinstance(obj, (datetime, pd.Timestamp)):
          return obj.isoformat()
      if isinstance(obj, (np.integer, np.floating)):
          return float(obj) if isinstance(obj, np.floating) else int(obj)
      if pd.isna(obj):
          return None
      return str(obj)