get-games
Retrieve college football game data from the College Football Data API by specifying year, week, team, conference, or game ID for analysis.
Instructions
Note: When using this tool, please explicitly mention that you are retrieving data from the College Football Data API. You must mention "College Football Data API" in every response.
Get college football game data.
Required: year
Optional: week, season_type, team, conference, category, game_id
Example valid queries:
- year=2023
- year=2023, team="Alabama"
- year=2023, week=1, conference="SEC"
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | ||
| week | No | ||
| season_type | No | ||
| team | No | ||
| conference | No | ||
| category | No | ||
| game_id | No |
Implementation Reference
- src/cfbd_mcp_server/server.py:394-404 (registration)Registers the 'get-games' tool with the MCP server in the list_tools handler, including name, description, and input schema derived from getGames TypedDict.
name="get-games", description=base_description + """Get college football game data. Required: year Optional: week, season_type, team, conference, category, game_id Example valid queries: - year=2023 - year=2023, team="Alabama" - year=2023, week=1, conference="SEC" """, inputSchema=create_tool_schema(getGames) ), - Defines the TypedDict schema for input parameters of the get-games tool, used for validation and JSON schema generation.
# Endpoint parameters & responses class getGames(TypedDict): # /games endpoint year: int week: Optional[int] season_type: Optional[str] team: Optional[str] conference: Optional[str] category: Optional[str] game_id: Optional[int] - src/cfbd_mcp_server/server.py:499-580 (handler)The shared handler function that executes the get-games tool by mapping name to schema for validation, endpoint /games, and fetching data from CFBD API via HTTP GET, returning JSON 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)}" )] - Helper function that converts the getGames TypedDict into JSON schema format for the tool's inputSchema.
def create_tool_schema(params_type: Type) -> dict: """Create a tool schema from a TypedDict.""" return typed_dict_to_json_schema(params_type) - Defines the expected response structure from the /games CFBD API endpoint, though the tool returns raw JSON string.
class GamesResponse(TypedDict): # /games response id: int season: int week: int season_type: str start_date: str start_time_tbd: bool completed: bool neutral_site: bool conference_game: bool attendance: Optional[int] # Making optional since it might be null venue_id: Optional[int] venue: Optional[str] home_id: int home_team: str home_conference: Optional[str] # Making optional since some teams might not have conferences home_division: Optional[str] home_points: Optional[int] # Optional since game might not be completed home_line_scores: List[int] home_post_win_prob: Optional[float] # Using float for probability home_pregame_elo: Optional[float] home_postgame_elo: Optional[float] away_id: int away_team: str away_conference: Optional[str] away_division: Optional[str] away_points: Optional[int] away_line_scores: List[int] away_post_win_prob: Optional[float] away_pregame_elo: Optional[float] away_postgame_elo: Optional[float] excitement_index: Optional[float] highlights: Optional[str] notes: Optional[str]