get-games-teams
Retrieve college football team game data from the College Football Data API by specifying parameters like year, week, team, or conference.
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 team game data.
Required: year plus at least one of: week, team or conference.
Example valid queries:
- year=2023, team="Alabama"
- year=2023, week=1
- year=2023, conference="SEC
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | ||
| week | No | ||
| season_type | No | ||
| team | No | ||
| conference | No | ||
| game_id | No | ||
| classification | No |
Implementation Reference
- src/cfbd_mcp_server/server.py:499-580 (handler)The MCP tool handler function that dispatches 'get-games-teams' to the CFBD API /games/teams endpoint after schema validation. This is the core execution logic for all tools including get-games-teams.
@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)}" )] - TypedDict schemas defining input parameters and response structure for the get-games-teams tool, used for validation and type hints.
class getGamesTeams(TypedDict): # /games/teams endpoint year: int week: Optional[int] season_type: Optional[str] team: Optional[str] conference: Optional[str] game_id: Optional[int] classification: Optional[str] class GamesTeamsResponse(TypedDict): # /games/teams response id: int teams: List[Team] - src/cfbd_mcp_server/server.py:417-427 (registration)MCP tool registration in list_tools(): defines the tool name, description, and input schema for server advertisement.
types.Tool( name="get-games-teams", description=base_description + """Get college football team game data. Required: year plus at least one of: week, team or conference. Example valid queries: - year=2023, team="Alabama" - year=2023, week=1 - year=2023, conference="SEC """, inputSchema=create_tool_schema(getGamesTeams) ), - src/cfbd_mcp_server/server.py:509-519 (registration)Maps the tool name to its input schema class for parameter validation during tool calls.
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 } - src/cfbd_mcp_server/server.py:533-543 (registration)Maps the tool name to the CFBD API endpoint path (/games/teams) used in the HTTP request.
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" }