get-pregame-win-probability

Retrieve pregame win probability data for college football games using parameters like year, week, or team to analyze matchups before kickoff.

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 pregame win probability data.
        Optional: year, week, team, season_type
        At least one parameter is required
        Example valid queries:
        - year=2023
        - team="Alabama"
        - year=2023, week=1

Input Schema

TableJSON Schema

Name	Required	Description	Default
`year`	No
`week`	No
`team`	No
`season_type`	No

Implementation Reference

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

The MCP call_tool handler function that executes the tool: maps name to schema for validation, maps to API endpoint /metrics/wp/pregame, calls CFBD API with params, returns JSON data or error

@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:361-365 (schema)

TypedDict schema defining optional input parameters: year, week, team, season_type

class getMetricsPregameWp(TypedDict): # /metrics/wp/pregame endpoint
    year: Optional[int]
    week: Optional[int]
    team: Optional[str]
    season_type: Optional[str]

src/cfbd_mcp_server/server.py:476-487 (registration)

Registration of the tool in handle_list_tools(): defines name, description, and links to input schema

types.Tool(
    name="get-pregame-win-probability",
    description=base_description + """Get college football pregame win probability data.
    Optional: year, week, team, season_type
    At least one parameter is required
    Example valid queries:
    - year=2023
    - team="Alabama"
    - year=2023, week=1
    """,
    inputSchema=create_tool_schema(getMetricsPregameWp)
),

src/cfbd_mcp_server/cfbd_schema.py:367-376 (schema)

TypedDict schema for the expected response from the API endpoint

class MetricsPregameWpResponse(TypedDict): # /metrics/wp/pregame response
    season: int
    seasonType: str
    week: int
    gameId: int
    homeTeam: str
    awayTeam: str
    spread: float  # Using float since spread can be decimal
    homeWinProb: float  # Using float for probability (0-1)

src/cfbd_mcp_server/server.py:148-152 (registration)

Schema registration in handle_read_resource() for exposing parameter and response schemas via MCP resources

"schema://metrics/wp/pregame": {
    "endpoint": "/metrics/wp/pregame",
    "parameters": getMetricsPregameWp.__annotations__,
    "response": MetricsPregameWpResponse.__annotations__,
    "description": "Get pregame win probability records for specified parameters"

cfbd-mcp-server