Your MCP Server Is Only as Good as Its Docstrings

cfb-mcp-server/
├── server.py        # MCP server — tool definitions
├── cfbd_client.py   # CFBD REST API wrapper
├── cache.py         # In-memory TTL cache
├── .env             # CFBD_API_KEY
└── pyproject.toml

# cfbd_client.py
import httpx
import os
from dotenv import load_dotenv
from cache import get as cache_get, set as cache_set

load_dotenv()

BASE_URL = "https://api.collegefootballdata.com"

def _headers() -> dict:
    return {"Authorization": f"Bearer {os.environ['CFBD_API_KEY']}"}

def get_game_results(team: str, year: int) -> list[dict]:
    key = f"games:{team}:{year}"
    if cached := cache_get(key):
        return cached
    r = httpx.get(
        f"{BASE_URL}/games",
        headers=_headers(),
        params={"year": year, "team": team, "classification": "fbs"}
    )
    r.raise_for_status()
    result = r.json()
    cache_set(key, result)
    return result

def get_advanced_team_stats(team: str, year: int) -> list[dict]:
    key = f"advanced:{team}:{year}"
    if cached := cache_get(key):
        return cached
    r = httpx.get(
        f"{BASE_URL}/stats/season/advanced",
        headers=_headers(),
        params={"year": year, "team": team}
    )
    r.raise_for_status()
    result = r.json()
    cache_set(key, result)
    return result

def get_conference_stats(conference: str, year: int) -> list[dict]:
    key = f"conference:{conference}:{year}"
    if cached := cache_get(key):
        return cached
    r = httpx.get(
        f"{BASE_URL}/stats/season/advanced",
        headers=_headers(),
        params={"year": year, "conference": conference}
    )
    r.raise_for_status()
    result = r.json()
    cache_set(key, result)
    return result

# cache.py
import time

_cache: dict = {}
TTL = 3600

def get(key: str):
    entry = _cache.get(key)
    if entry and time.time() - entry["ts"] < TTL:
        return entry["value"]
    return None

def set(key: str, value):
    _cache[key] = {"value": value, "ts": time.time()}

@mcp.tool()
def advanced_team_stats(team: str, year: int) -> list[dict]:
    return get_advanced_team_stats(team, year)

@mcp.tool()
def advanced_team_stats(team: str, year: int) -> list[dict]:
    """Get advanced stats for a team."""
    return get_advanced_team_stats(team, year)

@mcp.tool()
def advanced_team_stats(team: str, year: int) -> list[dict]:
    """
    Get advanced efficiency stats for a team: EPA (Expected Points Added) per
    play, success rate, and explosiveness for both offense and defense.

    EPA is the best single metric for team quality — positive offensive EPA
    and negative defensive EPA indicate an efficient team. Use this when the
    user asks about team quality, efficiency, or wants to compare teams beyond
    win-loss record.

    Pair with team_game_results to give context for why a team won or lost
    specific games. A team can have strong EPA and still lose games — context
    matters.
    """
    return get_advanced_team_stats(team, year)

@mcp.tool()
def conference_advanced_stats(conference: str, year: int) -> list[dict]:
    """
    Get advanced efficiency stats for all teams in a conference in a given
    year. Returns EPA, success rate, and explosiveness for every team.

    Use this when the user asks which team in a conference led a particular
    stat — avoids calling advanced_team_stats once per team. Valid conference
    abbreviations: SEC, ACC, B1G, B12, PAC, AAC.
    """
    return get_conference_stats(conference, year)

# server.py
from mcp.server.fastmcp import FastMCP
from cfbd_client import (
    get_game_results,
    get_advanced_team_stats,
    get_team_season_stats,
    get_player_season_stats,
    get_rankings,
    get_conference_stats,
)

mcp = FastMCP("CFB Stats")


@mcp.tool()
def team_game_results(team: str, year: int) -> list[dict]:
    """
    Get the full schedule and results for a college football team in a given
    year. Returns each game with date, opponent, score, and home/away status.
    Use when the user asks about a team's record, schedule, or specific game
    outcomes. Pair with advanced_team_stats to explain performance beyond the
    score.
    """
    return get_game_results(team, year)


@mcp.tool()
def team_season_stats(team: str, year: int) -> list[dict]:
    """
    Get aggregated season statistics for a college football team. Includes
    standard box score stats: total yards, points, turnovers, third down
    conversions. Use for general volume stats. For efficiency and quality
    metrics, prefer advanced_team_stats.
    """
    return get_team_season_stats(team, year)


@mcp.tool()
def player_stats(team: str, year: int, category: str) -> list[dict]:
    """
    Get player season stats for a team by category.
    Valid categories: passing, rushing, receiving, defensive, kicking, punting.
    Use when the user asks about individual players or who led a team in a
    specific stat.
    """
    return get_player_season_stats(team, year, category)


@mcp.tool()
def ap_rankings(year: int, week: int, season_type: str = "regular") -> list[dict]:
    """
    Get AP Top 25 college football rankings for a specific week and year.
    Season type is 'regular' or 'postseason'. Use when the user asks about
    rankings, polls, or whether a team was ranked at a specific point in
    the season.
    """
    return get_rankings(year, week, season_type)


@mcp.tool()
def advanced_team_stats(team: str, year: int) -> list[dict]:
    """
    Get advanced efficiency stats for a team: EPA (Expected Points Added) per
    play, success rate, and explosiveness for both offense and defense.

    EPA is the best single metric for team quality — positive offensive EPA
    and negative defensive EPA indicate an efficient team. Use when the user
    asks about team quality, efficiency, or wants to compare teams beyond
    win-loss record.

    Pair with team_game_results to explain why a team won or lost specific
    games. A team can have strong EPA and still lose — context matters.
    """
    return get_advanced_team_stats(team, year)


@mcp.tool()
def conference_advanced_stats(conference: str, year: int) -> list[dict]:
    """
    Get advanced efficiency stats for all teams in a conference in a given
    year. Returns EPA, success rate, and explosiveness for every team.

    Use when the user asks which team in a conference led a stat category —
    avoids calling advanced_team_stats once per team. Valid conference
    abbreviations: SEC, ACC, B1G, B12, PAC, AAC.
    """
    return get_conference_stats(conference, year)


if __name__ == "__main__":
    mcp.run()