cfbd-mcp-server

Instructions

Implementation Reference

• src/cfbd_mcp_server/server.py:405-416 (registration)

  Registration of the 'get-records' tool in handle_list_tools(), including name, description, and inputSchema generated from getTeamRecords TypedDict
  types.Tool( name="get-records", description=base_description + """Get college football team record data. Optional: year, team, conference Example valid queries: - year=2023 - team="Alabama" - conference="SEC" - year=2023, team="Alabama" """, inputSchema=create_tool_schema(getTeamRecords) ),
• src/cfbd_mcp_server/cfbd_schema.py:209-212 (schema)

  TypedDict defining the input parameters for the get-records tool: optional year (int), team (str), conference (str)
  class getTeamRecords(TypedDict): # /records endpoint year: Optional[int] team: Optional[str] conference: Optional[str]
• src/cfbd_mcp_server/server.py:499-580 (handler)

  The @server.call_tool() handler function that executes get-records by validating parameters with getTeamRecords schema, mapping to /records endpoint, and fetching data from CFBD API
  @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:197-249 (helper)

  validate_params helper function used in tool handler to validate input arguments against the getTeamRecords TypedDict schema
  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 that converts getTeamRecords TypedDict to JSON schema for the tool inputSchema
  def create_tool_schema(params_type: Type) -> dict: """Create a tool schema from a TypedDict.""" return typed_dict_to_json_schema(params_type)