cfbd-mcp-server

Instructions

Implementation Reference

• src/cfbd_mcp_server/server.py:499-580 (handler)

  Main handler for all MCP tools including 'get-drives'. Validates arguments using the getDrives schema, maps to CFBD API endpoint '/drives', performs HTTP GET request, and returns JSON response as text.
  @server.call_tool() async def handle_call_tool( name: str, arguments: dict[str, Any] | None ) -> list[types.TextContent]: """Handle tool execution requests.""" if not arguments: raise ValueError("Arguments are required") # Map tool names to their parameter schemas schema_map = { "get-games": getGames, "get-records": getTeamRecords, "get-games-teams": getGamesTeams, "get-plays": getPlays, "get-drives": getDrives, "get-play-stats": getPlayStats, "get-rankings": getRankings, "get-pregame-win-probability": getMetricsPregameWp, "get-advanced-box-score": getAdvancedBoxScore } if name not in schema_map: raise ValueError(f"Unknown tool: {name}") # Validate parameters against schema try: validated_params = validate_params(arguments, schema_map[name]) except ValueError as e: return [types.TextContent( type="text", text=f"Validation error: {str(e)}" )] endpoint_map = { "get-games": "/games", "get-records": "/records", "get-games-teams": "/games/teams", "get-plays": "/plays", "get-drives": "/drives", "get-play-stats": "/play/stats", "get-rankings": "/rankings", "get-pregame-win-probability": "/metrics/wp/pregame", "get-advanced-box-score": "/game/box/advanced" } async with await get_api_client() as client: try: response = await client.get(endpoint_map[name], params=arguments) response.raise_for_status() data = response.json() return [types.TextContent( type="text", text=str(data) )] except httpx.HTTPStatusError as e: if e.response.status_code == 401: return [types.TextContent( type="text", text="401: API authentication failed. Please check your API key." )] elif e.response.status_code == 403: return [types.TextContent( type="text", text="403: API access forbidden. Please check your permission." )] elif e.response.status_code == 429: return [types.TextContent( type="text", text="429: Rate limit exceeded. Please try again later." )] else: return [types.TextContent( type="text", text=f"API Error: {e}" )] except httpx.RequestError as e: return [types.TextContent( type="text", text=f"Network error: {str(e)}" )]
• src/cfbd_mcp_server/server.py:440-451 (registration)

  Registers the 'get-drives' tool with the MCP server in list_tools(), defining its name, description, and input schema from getDrives TypedDict.
  types.Tool( name="get-drives", description=base_description + """Get college football drive data. Required: year Optional: season_type, week, team, offense, defense, conference, offense_conference, defense_conference, classification Example valid queries: - year=2023 - year=2023, team="Alabama" - year=2023, offense="Alabama", defense="Auburn" """, inputSchema=create_tool_schema(getDrives) ),
• src/cfbd_mcp_server/cfbd_schema.py:281-292 (schema)

  TypedDict defining the input parameters for the 'get-drives' tool corresponding to CFBD /drives endpoint.
  class getDrives(TypedDict): # /drives endpoint year: int season_type: Optional[str] week: Optional[int] team: Optional[str] offense: Optional[str] defense: Optional[str] conference: Optional[str] offense_conference: Optional[str] defense_conference: Optional[str] classification: Optional[str]
• src/cfbd_mcp_server/cfbd_schema.py:293-318 (schema)

  TypedDict defining the expected response structure from CFBD /drives endpoint used by 'get-drives' tool.
  class DrivesResponse(TypedDict): # /drives response offense: str offense_conference: Optional[str] # Optional since team might not have conference defense: str defense_conference: Optional[str] game_id: int id: int drive_number: int scoring: bool start_period: int start_yardline: int start_yards_to_goal: int start_time: GameClock end_period: int end_yardline: int end_yards_to_goal: int end_time: GameClock plays: int yards: int drive_result: str is_home_offense: bool start_offense_score: int start_defense_score: int end_offense_score: int end_defense_score: int
• src/cfbd_mcp_server/server.py:197-249 (helper)

  Helper function to validate tool input parameters against TypedDict schema (e.g., getDrives), enforces types, optionality, and valid values for classification.
  def validate_params(params: dict, schema_class: Type[TypedDict]) -> dict: """Validate parameters against a TypedDict schema.""" try: # Get the annotations from the schema class expected_types = schema_class.__annotations__ validated_params = {} # Validate each parameter for key, value in params.items(): if key not in expected_types: raise ValueError(f"Unexpected parameter: {key}") expected_type = expected_types[key] # Special handling for classification parameter if key == "classification" and value is not None: value = value.lower() if value not in VALID_DIVISIONS: raise ValueError(f"Invalid Classification: Must be one of: {', '.join(VALID_DIVISIONS)}") # Handle Optional types if hasattr(expected_type, "__origin__") and expected_type.__origin__ is Union: if type(None) in expected_type.__args__: # Parameter is optional if value is not None: # Validate against the non-None type non_none_type = next(t for t in expected_type.__args__ if t != type(None)) # Handle primitive types if non_none_type in (str, int, float, bool): if not isinstance(value, non_none_type): raise ValueError(f"Parameter {key} must be of type {non_none_type.__name__}") validated_params[key] = value else: validated_params[key] = None else: # Parameter is required if not isinstance(value, expected_type): raise ValueError(f"Parameter {key} must be of type {expected_type.__name__}") validated_params[key] = value # Check for required parameters for param, param_type in expected_types.items(): is_optional = (hasattr(param_type, "__origin__") and param_type.__origin__ is Union and type(None) in param_type.__args__) if not is_optional and param not in params: raise ValueError(f"Missing required parameter: {param}") return validated_params except Exception as e: raise ValueError(f"Parameter validation failed: {str(e)}")