get-play-stats
Retrieve college football play statistics from the College Football Data API. Filter data by year, week, team, game, athlete, or conference to analyze performance metrics.
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 play statistic data.
Optional: year, week, team, game_id, athlete_id, stat_type_id, season_type, conference
At least one parameter is required
Example valid queries:
- year=2023
- game_id=401403910
- team="Alabama", year=2023
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | ||
| week | No | ||
| team | No | ||
| game_id | No | ||
| athlete_id | No | ||
| stat_type_id | No | ||
| season_type | No | ||
| conference | No |
Implementation Reference
- src/cfbd_mcp_server/server.py:499-580 (handler)Generic handler for all MCP tools. For 'get-play-stats', uses getPlayStats schema for validation (line 515), maps to '/play/stats' endpoint (line 539), calls CFBD API, 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:452-462 (registration)MCP tool registration in list_tools(). Defines name, description, and inputSchema generated from getPlayStats TypedDict.types.Tool( name="get-play-stats", description=base_description + """Get college football play statistic data. Optional: year, week, team, game_id, athlete_id, stat_type_id, season_type, conference At least one parameter is required Example valid queries: - year=2023 - game_id=401403910 - team="Alabama", year=2023 """, inputSchema=create_tool_schema(getPlayStats)
- Input schema (TypedDict) defining optional parameters for the get-play-stats tool, corresponding to CFBD API /play/stats endpoint.class getPlayStats(TypedDict): # /play/stats endpoint year: Optional[int] week: Optional[int] team: Optional[str] game_id: Optional[int] athlete_id: Optional[int] stat_type_id: Optional[int] season_type: Optional[str] conference: Optional[str]
- Output/response schema (TypedDict) defining the structure of play stats data returned by the /play/stats endpoint.class PlayStatsResponse(TypedDict): # /play/stats response gameId: int season: int week: int team: str conference: Optional[str] # Optional since team might not have conference opponent: str teamScore: Optional[int] # Optional since game might not be completed opponentScore: Optional[int] driveId: int playId: int period: int clock: GameClock yardsToGoal: int down: Optional[int] # Optional since some plays don't have downs (kickoffs, etc) distance: Optional[int] athleteId: int athleteName: str statType: str stat: int # The numerical value of the statistic
- Helper function used to generate JSON Schema for MCP tool inputSchema from TypedDict like getPlayStats.def create_tool_schema(params_type: Type) -> dict: """Create a tool schema from a TypedDict."""