cfbd-mcp-server

Instructions

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"
        

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)