ffbb-mcp-server 1.3.0__py3-none-any.whl

ffbb_mcp/__init__.py

@@ -0,0 +1,9 @@
+"""FFBB MCP Server — Fédération Française de Basketball."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("ffbb-mcp-server")
+except PackageNotFoundError:
+    __version__ = "unknown"

ffbb_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for the FFBB MCP server."""
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

ffbb_mcp/_state.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import asyncio
+
+    from cachetools import TLRUCache, TTLCache
+
+
+def _read_positive_int_env(key: str, default: int) -> int:
+    val_str = os.environ.get(key)
+    if val_str is not None:
+        try:
+            val = int(val_str)
+            if val > 0:
+                return val
+        except ValueError:
+            pass
+    return default
+
+
+@dataclass
+class _ServiceState:
+    inflight_bilan: dict[str, asyncio.Task[Any]] = field(default_factory=dict)
+    inflight_calendrier: dict[str, asyncio.Task[Any]] = field(default_factory=dict)
+    inflight_poule: dict[str, asyncio.Task[Any]] = field(default_factory=dict)
+    inflight_detail: dict[str, asyncio.Task[Any]] = field(default_factory=dict)
+    inflight_search: dict[str, asyncio.Task[Any]] = field(default_factory=dict)
+
+    # Caches in-memory globaux
+    cache_lives: TTLCache[Any, Any] | None = None
+    cache_search: TTLCache[Any, Any] | None = None
+    cache_competition: TTLCache[Any, Any] | None = None
+    cache_organisme: TTLCache[Any, Any] | None = None
+    cache_saisons: TTLCache[Any, Any] | None = None
+    cache_calendrier: TTLCache[Any, Any] | TLRUCache[Any, Any] | None = None
+    cache_bilan: TLRUCache[Any, Any] | None = None
+    cache_classement: TLRUCache[Any, Any] | None = None
+    cache_poule: TLRUCache[Any, Any] | None = None
+
+
+state = _ServiceState()
+
+
+def reset_service_state() -> None:
+    global state
+    state.inflight_bilan.clear()
+    state.inflight_calendrier.clear()
+    state.inflight_poule.clear()
+    state.inflight_detail.clear()
+    state.inflight_search.clear()
+    if state.cache_lives is not None:
+        state.cache_lives.clear()
+    if state.cache_search is not None:
+        state.cache_search.clear()
+    if state.cache_competition is not None:
+        state.cache_competition.clear()
+    if state.cache_organisme is not None:
+        state.cache_organisme.clear()
+    if state.cache_saisons is not None:
+        state.cache_saisons.clear()
+    if state.cache_calendrier is not None:
+        state.cache_calendrier.clear()
+    if state.cache_bilan is not None:
+        state.cache_bilan.clear()
+    if state.cache_classement is not None:
+        state.cache_classement.clear()
+    if state.cache_poule is not None:
+        state.cache_poule.clear()

ffbb_mcp/aliases.py

@@ -0,0 +1,374 @@
+"""Gestion des alias et acronymes de clubs FFBB.
+
+Ce module fournit :
+- Un dictionnaire statique d'alias bien connus (CLUB_ALIASES)
+- Un cache persistant d'acronymes auto-enrichi (acronyms_cache.json)
+- normalize_query() : résolution d'alias dans les recherches
+- resolve_acronym() : résolution spécifique d'acronymes (< 7 chars, tout en majuscules)
+- enrich_acronym_cache() : enrichissement automatique après chaque recherche réussie
+"""
+
+import json
+import logging
+import os
+import re
+from pathlib import Path
+from threading import Lock
+
+logger = logging.getLogger("ffbb-mcp")
+
+# ---------------------------------------------------------------------------
+# Dictionnaire statique d'alias (toujours en lowercase)
+# ---------------------------------------------------------------------------
+
+CLUB_ALIASES = {
+    "jav": "jeanne d'arc de vichy",
+    "ja vichy": "jeanne d'arc de vichy",
+    "scba": "stade clermontois basket auvergne",
+    "scbf": "stade clermontois basket feminin",
+    "asvel": "lyon villeurbanne",
+    "ldlc asvel": "lyon villeurbanne",
+    "chorale": "roanne",
+    "cb": "cholet basket",
+    "jlb": "jl bourg",
+    "bourg": "jl bourg",
+    "bcm": "gravelines dunkerque",
+    "gravelines": "bcm gravelines dunkerque",
+    "pau": "elan bearnais",
+    "msb": "le mans sarthe basket",
+    "le mans": "le mans sarthe basket",
+    "sluc": "nancy",
+    "nancy": "sluc nancy",
+    "sig": "strasbourg",
+    "csp": "limoges csp",
+    "essm": "essm le portel",
+    "sqbb": "saint quentin basket ball",
+    "ada": "ada blois basket 41",
+    "alm": "alm evreux basket",
+    "stb": "saint thomas basket le havre",
+    "rmb": "rouen metropole basket",
+    "amsb": "aix maurienne savoie basket",
+    "ujap": "ujap quimper",
+    "urb": "union rennes basket 35",
+    "cep": "cep lorient basket",
+    "olb": "orleans loiret basket",
+    "esbva": "esb villeneuve d'ascq lille metropole",
+    "blma": "basket lattes montpellier",
+    "bbd": "boulazac basket dordogne",
+    "htv": "hyeres toulon var basket",
+    "tgb": "tarbes gespe bigorre",
+    "asa": "alliance sport alsace",
+    "asm": "as monaco basket",
+    "jsf": "jsf nanterre",
+    "lmb": "lille metropole basket",
+    "lyonso": "lyonso basket",
+    "avbb": "aurore vitre basket bretagne",
+    "rac": "rac basket premiere",
+    "svbd": "saint-vallier basket drôme",
+    "mba": "mulhouse basket agglomeration",
+    "besac": "besancon avenir comtois",
+    "cbc": "caen basket calvados",
+    "utlpb": "union tarbes lourdes pyrenees basket",
+    "eab": "etoile angers basket",
+    "bco": "sasp bc orchies",
+    "fpb": "sas fos provence basket",
+    "usom": "uso mondeville basket",
+    "cnb": "cavigal nice basket 06",
+    "lbb": "landerneau bretagne basket",
+    "cbbs": "charnay basket bourgogne sud",
+    "fcba": "flammes carolo basket ardennes",
+    "sahb": "saint-amand hainaut basket",
+}
+
+# ---------------------------------------------------------------------------
+# Expressions régulières pré-compilées (Optimisation des performances)
+# ---------------------------------------------------------------------------
+# Le pré-calcul d'une regex globale combinée et d'un dictionnaire de lookup
+# permet d'effectuer tous les remplacements en une seule passe C.
+# Cela offre un gain de performance notable (~x2 par rapport à une boucle).
+
+_VALID_ALIASES_DICT = {
+    alias: official
+    for alias, official in CLUB_ALIASES.items()
+    if not re.search(r"\b" + re.escape(alias) + r"\b", official)
+}
+
+# Trie par longueur décroissante pour que les alias les plus longs matchent en priorité
+_ALIASES_SORTED = sorted(_VALID_ALIASES_DICT.keys(), key=len, reverse=True)
+_ALIAS_PATTERN_ALL = re.compile(
+    r"\b(" + "|".join(re.escape(k) for k in _ALIASES_SORTED) + r")\b"
+)
+
+# ---------------------------------------------------------------------------
+# Cache persistant d'acronymes (acronyms_cache.json)
+# ---------------------------------------------------------------------------
+
+_DEFAULT_ACRONYMS = {
+    "ASVEL": "Villeurbanne",
+    "JAV": "Jeanne d'Arc de Vichy",
+    "SLUC": "Nancy",
+    "SCBA": "Stade Clermontois",
+    "JDA": "Dijon",
+    "BCM": "Gravelines",
+    "SIG": "Strasbourg",
+    "MSB": "Le Mans",
+    "GB": "GERZAT BASKET",
+    "SCBF": "STADE CLERMONTOIS BASKET FEMININ",
+    "CSP": "LIMOGES CSP",
+    "ESSM": "ESSM LE PORTEL",
+    "SQBB": "SAINT QUENTIN BASKET BALL",
+    "ADA": "ADA BLOIS BASKET 41",
+    "ALM": "ALM EVREUX BASKET",
+    "STB": "SAINT THOMAS BASKET LE HAVRE",
+    "RMB": "ROUEN METROPOLE BASKET",
+    "AMSB": "AIX MAURIENNE SAVOIE BASKET",
+    "UJAP": "UJAP QUIMPER",
+    "URB": "UNION RENNES BASKET 35",
+    "CEP": "CEP LORIENT BASKET",
+    "OLB": "ORLEANS LOIRET BASKET",
+    "ESBVA": "ESB VILLENEUVE D'ASCQ LILLE METROPOLE",
+    "BLMA": "BASKET LATTES MONTPELLIER",
+    "BBD": "BOULAZAC BASKET DORDOGNE",
+    "HTV": "HYERES TOULON VAR BASKET",
+    "TGB": "TARBES GESPE BIGORRE",
+    "ASA": "ALLIANCE SPORT ALSACE",
+    "ASM": "AS MONACO BASKET",
+    "JSF": "JSF NANTERRE",
+    "LMB": "LILLE METROPOLE BASKET",
+    "LYONSO": "LYONSO BASKET",
+    "AVBB": "AURORE VITRE BASKET BRETAGNE",
+    "RAC": "RAC BASKET PREMIERE",
+    "SVBD": "SAINT-VALLIER BASKET DRÔME",
+    "MBA": "MULHOUSE BASKET AGGLOMERATION",
+    "BESAC": "BESANCON AVENIR COMTOIS",
+    "CBC": "CAEN BASKET CALVADOS",
+    "UTLPB": "UNION TARBES LOURDES PYRENEES BASKET",
+    "EAB": "ETOILE ANGERS BASKET",
+    "BCO": "SASP BC ORCHIES",
+    "FPB": "SAS FOS PROVENCE BASKET",
+    "USOM": "USO MONDEVILLE BASKET",
+    "CNB": "CAVIGAL NICE BASKET 06",
+    "LBB": "LANDERNEAU BRETAGNE BASKET",
+    "CBBS": "CHARNAY BASKET BOURGOGNE SUD",
+    "FCBA": "FLAMMES CAROLO BASKET ARDENNES",
+    "SAHB": "SAINT-AMAND HAINAUT BASKET",
+}
+
+
+def _resolve_cache_dir() -> Path:
+    """Retourne un dossier cache utilisateur robuste et écrivable."""
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    if xdg:
+        return Path(xdg).expanduser() / "ffbb-mcp"
+    return Path.home() / ".cache" / "ffbb-mcp"
+
+
+_CACHE_DIR = _resolve_cache_dir()
+_CACHE_FILE = _CACHE_DIR / "acronyms_cache.json"
+_cache_lock = Lock()
+_acronyms_cache: dict[str, str] | None = None
+_acronyms_cache_upper: dict[str, str] | None = None
+
+
+def _load_acronyms_cache() -> dict[str, str]:
+    """Charge le cache d'acronymes depuis le fichier JSON.
+
+    Si le fichier n'existe pas, l'initialise avec les valeurs par défaut.
+    """
+    global _acronyms_cache
+    global _acronyms_cache_upper
+    if _acronyms_cache is not None:
+        return _acronyms_cache
+
+    with _cache_lock:
+        # Double-check après acquisition du lock
+        if _acronyms_cache is not None:
+            return _acronyms_cache
+
+        if _CACHE_FILE.exists():
+            try:
+                data = json.loads(_CACHE_FILE.read_text(encoding="utf-8"))
+                if isinstance(data, dict):
+                    _acronyms_cache_upper = {k.upper(): v for k, v in data.items()}
+                    _acronyms_cache = data
+                    logger.info(
+                        "Cache d'acronymes chargé: %d entrées depuis %s",
+                        len(data),
+                        _CACHE_FILE,
+                    )
+                    return _acronyms_cache
+            except (json.JSONDecodeError, OSError) as e:
+                logger.warning(
+                    "Erreur lecture %s: %s — réinitialisation", _CACHE_FILE, e
+                )
+
+        # Initialisation avec les valeurs par défaut
+        _acronyms_cache_upper = {k.upper(): v for k, v in _DEFAULT_ACRONYMS.items()}
+        _acronyms_cache = dict(_DEFAULT_ACRONYMS)
+        _save_acronyms_cache()
+        logger.info(
+            "Cache d'acronymes initialisé avec %d entrées par défaut",
+            len(_acronyms_cache),
+        )
+        return _acronyms_cache
+
+
+def _save_acronyms_cache() -> None:
+    """Sauvegarde le cache d'acronymes dans le fichier JSON."""
+    if _acronyms_cache is None:
+        return
+    try:
+        _CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        _CACHE_FILE.write_text(
+            json.dumps(_acronyms_cache, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+    except OSError as e:
+        logger.warning("Erreur sauvegarde %s: %s", _CACHE_FILE, e)
+
+
+_SKIP_WORDS: frozenset[str] = frozenset(
+    {"de", "du", "le", "la", "les", "et", "en", "des", "aux"}
+)
+
+
+def _extract_initials(name: str) -> str:
+    """Extrait les initiales d'un nom officiel FFBB.
+
+    Prend la première lettre de chaque mot commençant par une majuscule.
+    Ignore les mots courants courts (de, du, le, la, les, d', l', et).
+    """
+    words = name.split()
+    initials = []
+    for w in words:
+        # ⚡ Bolt: Accès direct par index plutôt que de créer un tuple et
+        # d'appeler startswith, évitant des allocations inutiles.
+        # Supprimer les articles collés (d', l', D', L')
+        if len(w) >= 2 and w[1] == "'" and w[0] in ("d", "l", "D", "L"):
+            clean = w[2:]
+        else:
+            clean = w
+
+        if not clean:
+            continue
+        if clean.lower() in _SKIP_WORDS:
+            continue
+        if clean[0].isupper():
+            initials.append(clean[0])
+    return "".join(initials)
+
+
+# ---------------------------------------------------------------------------
+# API publique
+# ---------------------------------------------------------------------------
+
+
+def resolve_acronym(query: str) -> str:
+    """Résout un acronyme de club vers son nom complet.
+
+    Règle de détection : si le terme est entièrement en majuscules
+    et fait moins de 7 caractères, tenter une résolution via le cache.
+
+    Retourne le nom résolu si trouvé, sinon retourne `query` tel quel.
+    """
+    if not query or len(query) >= 7:
+        return query
+
+    stripped = query.strip()
+    if not stripped:
+        return query
+
+    # Vérifier que c'est bien un acronyme (tout en majuscules, lettres uniquement)
+    if not stripped.isalpha() or not stripped.isupper():
+        return query
+
+    _load_acronyms_cache()
+
+    # Recherche case-insensitive dans le cache
+    assert _acronyms_cache_upper is not None
+    if value := _acronyms_cache_upper.get(stripped.upper()):
+        logger.info("Acronyme résolu: %s → %s", stripped, value)
+        return value
+
+    return query
+
+
+def enrich_acronym_cache(official_name: str) -> None:
+    """Enrichit automatiquement le cache d'acronymes après une recherche réussie.
+
+    Extrait les initiales du nom officiel retourné par la FFBB.
+    Si ces initiales ne sont pas déjà dans le cache, les ajoute
+    avec le nom complet comme valeur et sauvegarde immédiatement.
+    """
+    if not official_name or len(official_name) < 3:
+        return
+
+    initials = _extract_initials(official_name)
+    if not initials or len(initials) < 2 or len(initials) >= 7:
+        return
+
+    cache = _load_acronyms_cache()
+
+    # Vérifier si l'acronyme existe déjà (case-insensitive)
+    # _load_acronyms_cache guarantees _acronyms_cache_upper is initialized
+    initials_upper = initials.upper()
+    assert _acronyms_cache_upper is not None
+    if initials_upper in _acronyms_cache_upper:
+        return
+
+    with _cache_lock:
+        cache[initials] = official_name
+        _acronyms_cache_upper[initials_upper] = official_name
+        _save_acronyms_cache()
+        logger.info("Acronyme auto-enrichi: %s → %s", initials, official_name)
+
+
+_APOSTROPHES_MAP = str.maketrans("\u2019\u2018\u201b\u0060", "''''")
+
+
+def _normalize_apostrophes(text: str) -> str:
+    """Normalise toutes les variantes typographiques d'apostrophe en apostrophe ASCII.
+
+    Variantes couvertes : \u2019 (U+2019), \u2018 (U+2018), \u201b (U+201B), \u0060 (backtick).
+    """
+    # Fast-path : la plupart des textes sont déjà ASCII et ne contiennent pas de backtick.
+    if text.isascii() and "`" not in text:
+        return text
+
+    return text.translate(_APOSTROPHES_MAP)
+
+
+def normalize_query(query: str) -> str:
+    """Normalize a search query to replace common club abbreviations
+    or alternative names with their official FFBB names.
+    This helps the FFBB API find the correct results.
+
+    Applique aussi la résolution d'acronymes en premier.
+    """
+    if not query:
+        return query
+
+    # 0. Normalisation des apostrophes typographiques → apostrophe ASCII
+    query = _normalize_apostrophes(query)
+
+    # 1. Résolution d'acronyme en priorité
+    resolved = resolve_acronym(query)
+    if resolved != query:
+        return resolved
+
+    # 2. Normalisation via le dictionnaire statique
+    normalized = query.lower().strip()
+
+    # Try exact match first
+    if normalized in CLUB_ALIASES:
+        return CLUB_ALIASES[normalized]
+
+    # Replace whole words in a single pass using the combined regex
+    if _ALIAS_PATTERN_ALL.search(normalized):
+        normalized = _ALIAS_PATTERN_ALL.sub(
+            lambda m: _VALID_ALIASES_DICT[m.group(1)], normalized
+        )
+
+    # Remove excessive spaces
+    normalized = " ".join(normalized.split())
+    return normalized

ffbb_mcp/app_factory.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+import re
+import uuid
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator
+
+    from mcp.server.fastmcp import FastMCP
+
+from starlette.applications import Starlette
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.middleware.cors import CORSMiddleware
+from starlette.middleware.gzip import GZipMiddleware
+from starlette.responses import JSONResponse
+from starlette.routing import Mount
+from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware
+
+logger = logging.getLogger("ffbb-mcp")
+
+_REQUEST_ID_RE = re.compile(r"^[a-zA-Z0-9\-]{1,64}$")
+
+
+def create_app(mcp: FastMCP, allowed_origins: list[str]) -> Starlette:
+    @contextlib.asynccontextmanager
+    async def lifespan(app: Starlette) -> AsyncGenerator[None]:
+        async with mcp.session_manager.run():
+            yield
+
+    mcp_app = mcp.streamable_http_app()
+
+    app = Starlette(
+        debug=False,
+        routes=[Mount("/", app=mcp_app)],
+        lifespan=lifespan,
+    )
+    app.router.redirect_slashes = False
+
+    # Default to trusting only localhost; set TRUSTED_PROXY_HOSTS for production
+    # reverse-proxy scenarios (e.g. "10.0.0.1,10.0.0.2").
+    _proxy_hosts_raw = os.environ.get("TRUSTED_PROXY_HOSTS", "127.0.0.1")
+    _trusted_hosts = [h.strip() for h in _proxy_hosts_raw.split(",") if h.strip()]
+    app.add_middleware(
+        ProxyHeadersMiddleware, trusted_hosts=_trusted_hosts or ["127.0.0.1"]
+    )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=allowed_origins,
+        allow_methods=["GET", "POST", "OPTIONS", "DELETE"],
+        allow_headers=[
+            "Content-Type",
+            "Accept",
+            "Authorization",
+            "Mcp-Session-Id",
+            "MCP-Protocol-Version",
+            "X-Forwarded-For",
+            "X-Forwarded-Proto",
+            "X-Real-IP",
+        ],
+        expose_headers=["Content-Type", "Mcp-Session-Id"],
+    )
+
+    app.add_middleware(GZipMiddleware, minimum_size=1000)
+
+    class RequestIdMiddleware(BaseHTTPMiddleware):
+        async def dispatch(self, request: Any, call_next: Any) -> Any:
+            raw_id = request.headers.get("X-Request-ID", "")
+            request_id = raw_id if _REQUEST_ID_RE.match(raw_id) else str(uuid.uuid4())
+            try:
+                response = await call_next(request)
+            except Exception as e:
+                # Don't log broken pipes or client disconnects as errors
+                err_str = str(e).lower()
+                if any(
+                    x in err_str
+                    for x in ["broken pipe", "connection closed", "client disconnected"]
+                ):
+                    logger.debug("Client disconnected: %s", e)
+                else:
+                    logger.error(
+                        "Middleware error on %s: %s", request.url.path, e, exc_info=True
+                    )
+
+                response = JSONResponse(
+                    {"error": "Internal Server Error", "request_id": request_id},
+                    status_code=500,
+                )
+
+            response.headers["X-Request-ID"] = request_id
+            return response
+
+    app.add_middleware(RequestIdMiddleware)
+
+    return app