cfbd-mcp-server

Instructions

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
        

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)

• src/cfbd_mcp_server/cfbd_schema.py:319-328 (schema)

  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]

• src/cfbd_mcp_server/cfbd_schema.py:329-349 (schema)

  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

• src/cfbd_mcp_server/schema_helpers.py:65-66 (helper)

  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."""