cfbd-mcp-server

Instructions

Implementation Reference

• src/cfbd_mcp_server/server.py:488-496 (registration)

  Registration of the get-advanced-box-score tool in the @server.list_tools() handler, specifying name, description, and inputSchema generated from getAdvancedBoxScore TypedDict.
  types.Tool( name="get-advanced-box-score", description=base_description + """Get advanced box score data for college football games. Required: gameId Example valid queries: - gameId=401403910 """, inputSchema=create_tool_schema(getAdvancedBoxScore) )
• src/cfbd_mcp_server/server.py:499-580 (handler)

  Generic tool handler decorated with @server.call_tool(). Maps 'get-advanced-box-score' to getAdvancedBoxScore schema (line 518) for validation and to '/game/box/advanced' endpoint (line 542). Makes authenticated API 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/cfbd_schema.py:202-208 (schema)

  TypedDict schemas for tool input parameters (getAdvancedBoxScore: requires gameId) and response (AdvancedBoxScoreResponse: contains teams and players stats). Supporting types like TeamStats, PlayerStats defined earlier in file.
  class getAdvancedBoxScore(TypedDict): # /game/box/advanced endpoint gameId: int class AdvancedBoxScoreResponse(TypedDict): # /game/box/advanced endpoint teams: TeamStats players: PlayerStats
• src/cfbd_mcp_server/server.py:197-249 (helper)

  validate_params helper function used by handler to validate tool arguments against the TypedDict schema (e.g., getAdvancedBoxScore). Handles optionals, required fields, type checks, and valid classifications.
  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)}")
• src/cfbd_mcp_server/schema_helpers.py:65-67 (helper)

  create_tool_schema helper converts TypedDict (e.g., getAdvancedBoxScore) to JSON Schema object used for tool's inputSchema in registration.
  def create_tool_schema(params_type: Type) -> dict: """Create a tool schema from a TypedDict.""" return typed_dict_to_json_schema(params_type)