cfbd-mcp-server

Instructions

Implementation Reference

• src/cfbd_mcp_server/server.py:499-580 (handler)

  The main handler function for all tools including get-plays. It validates input using the getPlays schema, maps 'get-plays' to the '/plays' endpoint, makes an authenticated HTTP GET request to the College Football Data API, and returns the JSON response as text content.
  @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:239-251 (schema)

  TypedDict defining the input parameters for the get-plays tool, used for validation and JSON schema generation.
  class getPlays(TypedDict): # /plays endpoint year: int week: int season_type: Optional[str] team: Optional[str] offense: Optional[str] defense: Optional[str] conference: Optional[str] offense_conference: Optional[str] defense_conference: Optional[str] play_type: Optional[int] classification: Optional[str]
• src/cfbd_mcp_server/server.py:428-439 (registration)

  Registration of the get-plays tool in the MCP server list_tools handler, including name, description, and input schema from getPlays TypedDict.
  types.Tool( name="get-plays", description=base_description + """Get college football play-by-play data. Required: year AND week Optional: season_type, team, offense, defense, conference, offense_conference, defense_conference, play_type, classification Example valid queries: - year=2023, week=1 - year=2023, week=1, team="Alabama" - year=2023, week=1, offense="Alabama", defense="Auburn" """, inputSchema=create_tool_schema(getPlays) ),
• src/cfbd_mcp_server/cfbd_schema.py:252-280 (schema)

  TypedDict defining the expected response structure from the /plays API endpoint.
  class PlaysResponse(TypedDict): # /plays response id: int drive_id: int game_id: int drive_number: int play_number: int offense: str offense_conference: Optional[str] # Optional since team might not have conference offense_score: int defense: str home: str away: str defense_conference: Optional[str] defense_score: int period: int clock: GameClock offense_timeouts: int defense_timeouts: int yard_line: int yards_to_goal: int down: Optional[int] # Optional since some plays might not have downs (kickoffs, etc) distance: Optional[int] yards_gained: int scoring: bool play_type: str play_text: str ppa: Optional[float] # Using float for predicted points added wallclock: Optional[str] # Timestamp of the play
• src/cfbd_mcp_server/schema_helpers.py:65-67 (helper)

  Helper function used to generate the JSON schema for the tool inputSchema from the getPlays TypedDict.
  def create_tool_schema(params_type: Type) -> dict: """Create a tool schema from a TypedDict.""" return typed_dict_to_json_schema(params_type)