cfbd-mcp-server

Instructions

Get college football game data.
        Required: year
        Optional: week, season_type, team, conference, category, game_id
        Example valid queries:
        - year=2023
        - year=2023, team="Alabama"
        - year=2023, week=1, conference="SEC"
        

Implementation Reference

• src/cfbd_mcp_server/server.py:394-404 (registration)

  Registers the 'get-games' tool with the MCP server in the list_tools handler, including name, description, and input schema derived from getGames TypedDict.

      name="get-games",
      description=base_description + """Get college football game data.
      Required: year
      Optional: week, season_type, team, conference, category, game_id
      Example valid queries:
      - year=2023
      - year=2023, team="Alabama"
      - year=2023, week=1, conference="SEC"
      """,
      inputSchema=create_tool_schema(getGames)
  ),

• src/cfbd_mcp_server/cfbd_schema.py:157-165 (schema)

  Defines the TypedDict schema for input parameters of the get-games tool, used for validation and JSON schema generation.

  # Endpoint parameters & responses
  class getGames(TypedDict): # /games endpoint
      year: int
      week: Optional[int]
      season_type: Optional[str]
      team: Optional[str]
      conference: Optional[str]
      category: Optional[str]
      game_id: Optional[int]

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

  The shared handler function that executes the get-games tool by mapping name to schema for validation, endpoint /games, and fetching data from CFBD API via HTTP GET, returning JSON 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/schema_helpers.py:65-67 (helper)

  Helper function that converts the getGames TypedDict into JSON schema format for the tool's inputSchema.

  def create_tool_schema(params_type: Type) -> dict:
      """Create a tool schema from a TypedDict."""
      return typed_dict_to_json_schema(params_type)

• src/cfbd_mcp_server/cfbd_schema.py:167-201 (schema)

  Defines the expected response structure from the /games CFBD API endpoint, though the tool returns raw JSON string.

  class GamesResponse(TypedDict): # /games response
      id: int
      season: int
      week: int
      season_type: str
      start_date: str
      start_time_tbd: bool
      completed: bool
      neutral_site: bool
      conference_game: bool
      attendance: Optional[int]  # Making optional since it might be null
      venue_id: Optional[int]
      venue: Optional[str]
      home_id: int
      home_team: str
      home_conference: Optional[str]  # Making optional since some teams might not have conferences
      home_division: Optional[str]
      home_points: Optional[int]  # Optional since game might not be completed
      home_line_scores: List[int]
      home_post_win_prob: Optional[float]  # Using float for probability
      home_pregame_elo: Optional[float]
      home_postgame_elo: Optional[float]
      away_id: int
      away_team: str
      away_conference: Optional[str]
      away_division: Optional[str]
      away_points: Optional[int]
      away_line_scores: List[int]
      away_post_win_prob: Optional[float]
      away_pregame_elo: Optional[float]
      away_postgame_elo: Optional[float]
      excitement_index: Optional[float]
      highlights: Optional[str]
      notes: Optional[str]