Formula One MCP Server

Instructions

Implementation Reference

• python/f1_data.py:29-45 (handler)

  The core handler function that executes the tool logic: fetches the F1 event schedule for the given year using fastf1.get_event_schedule(year), processes the pandas DataFrame into a JSON-serializable list of event dictionaries using json_serial helper, and returns success/error response.

  def get_event_schedule(year):
      """Get the event schedule for a specified season"""
      try:
          year = int(year)
          schedule = fastf1.get_event_schedule(year)
          
          # 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)
          
          return {"status": "success", "data": result}
      except Exception as e:
          return {"status": "error", "message": str(e), "traceback": traceback.format_exc()}

• src/index.ts:91-104 (schema)

  Defines the tool schema including name, description, and input schema requiring a 'year' number parameter for input validation.

  {
    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'],
    },
  },

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

  Registers the get_event_schedule function (along with others) in a dictionary used by main() to dynamically invoke the correct handler based on sys.argv[1].

  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
  }

• src/index.ts:292-295 (handler)

  MCP tool call handler case that proxies the request to the Python implementation by calling executePythonFunction with the tool name and year argument.

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

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

  Helper utility function used in get_event_schedule to serialize pandas/numpy/datetime objects into 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)