🏀 FFBB MCP Server

Le basket français officiel, directement dans vos assistants IA.

Serveur MCP pour consulter calendriers, classements, bilans, résultats, scores live et règlements officiels de la FFBB (Fédération Française de Basketball).

🇺🇸 English Summary: Official Model Context Protocol (MCP) server for French Basketball (FFBB). Connect your AI assistants (Claude, Cursor, Copilot, ChatGPT, Antigravity) to live French basketball schedules, standings, scores, team records, club directories, and official federal regulations via Streamable HTTP or Stdio.

🌐 Site · 🧩 Extension VS Code · 📚 Documentation · 💬 Support

---

⭐ Si ce serveur MCP FFBB vous est utile pour vos assistants IA, n'hésitez pas à laisser une étoile sur GitHub ! ⭐

---

⚡ Démarrage express (< 2 min)

Tip

Aucune installation requise : le serveur est hébergé publiquement. Ajoutez simplement l'endpoint MCP à votre client :

https://ffbb.desimone.fr/mcp

Puis posez vos questions en langage naturel :

« Quel est le prochain match des U15 de mon club (nommer le club) ? » « Donne-moi le classement de la poule des U15M2 du Stade Clermontois et le dernier résultat. » « Y a-t-il des matchs en direct ce soir ? »

👉 Voir la section Installation pour brancher l'endpoint sur VS Code, Claude, Cursor, etc.

---

✨ Fonctionnalités

• 🗓️ Calendriers & résultats — matchs passés et à venir, par club ou par équipe.
• 🏆 Classements — poules complètes avec points, différentiel et forme.
• 📊 Bilans agrégés — toutes phases confondues en un seul appel.
• 🔴 Scores live — matchs en cours, mis à jour toutes les 30 s.
• 🔎 Recherche universelle — clubs, compétitions, salles, engagements.
• 🚀 Optimisé pour les LLM — réponses agrégées et cache TTL pour réduire le contexte et le nombre d'appels.

---

🚀 Installation

VS Code / GitHub Copilot

Option recommandée — installer l'extension FFBB Basketball MCP depuis les releases, puis ouvrir Copilot Chat en mode agent.

Alternative sans extension — ➕ Installer FFBB MCP en un clic

Claude Desktop

Option A — Via l'interface de Claude (recommandé, sans prérequis)

1. Ouvrez les Paramètres de Claude, puis Connecteurs (ou Plugins).
2. Cliquez sur Ajouter un connecteur personnalisé.
3. Renseignez l'URL publique https://ffbb.desimone.fr/mcp et validez.

Option B — Via claude_desktop_config.json (nécessite Node.js)

Claude Desktop n'accepte que le transport stdio local : on utilise donc le bridge SSE officiel via npx.

[!WARNING] Prérequis : Node.js (inclut npm et npx). Sans Node.js, privilégiez l'Option A.

{
  "mcpServers": {
    "ffbb": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/client-sse", "https://ffbb.desimone.fr/mcp"]
    }
  }
}

Cursor / autres clients MCP

Configurez un serveur MCP distant :

Champ	Valeur
Type	Streamable HTTP
URL	https://ffbb.desimone.fr/mcp

Google Antigravity

Configurez directement l'URL distante dans mcp_config.json via la directive native serverUrl :

{
  "mcpServers": {
    "ffbb_mcp": {
      "serverUrl": "https://ffbb.desimone.fr/mcp"
    }
  }
}

---

🧰 Outils principaux

Outil	Usage
ffbb_version	Informations de version et configuration runtime du serveur FFBB MCP.
ffbb_search	Recherche FFBB — clubs, compétitions, matchs, salles, tournois, etc.
ffbb_bilan	Bilan complet d'une équipe toutes phases confondues en UN seul appel (V/D/N, paniers, phases).
ffbb_get	Recupere une ressource FFBB par identifiant.
ffbb_club	Outils agrégés club : calendrier (matchs pluriels), équipes engagées ou classement.
ffbb_lives	Matchs en cours (scores live, rafraîchissement toutes les 15s). Retourne [] si aucun match.
ffbb_saisons	Liste des saisons FFBB (référentiel temporel).
ffbb_resolve_team	Identifie une equipe unique (Pivot central).
ffbb_team_summary	Résumé complet et agent-friendly pour une équipe.
ffbb_last_result	Dernier résultat d'une équipe précise.
ffbb_next_match	Prochain match à jouer pour une équipe précise.
ffbb_bilan_saison	Bilan détaillé de la saison pour une équipe précise (toutes phases).
ffbb_head_to_head	Compare deux équipes et analyse leurs confrontations directes (H2H).
ffbb_search_regulations	Recherche plein texte déterministe dans les règlements officiels FFBB, régionaux et départementaux.
ffbb_get_regulation_article	Récupère le texte intégral et exact d'un article spécifique de règlement sans troncature.
ffbb_explain_tiebreak_rules	Fournit les règles officielles de départage en cas d'égalité (Article 28 du RSG FFBB).
ffbb_list_regulations	Liste l'ensemble des textes réglementaires fédéraux (RSG, RSP Élite, NM1-NM3, LF2-NF3),.

Note

Référence complète des paramètres : docs/TOOLS_REFERENCE.md.

---

🌐 Instance publique

Endpoint MCP (transport Streamable HTTP) :

https://ffbb.desimone.fr/mcp

Endpoint	URL
📊 Dashboard	https://ffbb.desimone.fr/dashboard
📈 Métriques	https://ffbb.desimone.fr/metrics.json
❤️ Santé	https://ffbb.desimone.fr/health

---

🏗️ Architecture

flowchart LR
    A[Client MCP<br/>Claude · Cursor · Antigravity] -->|Streamable HTTP / Stdio| B[FFBB MCP Server<br/>FastMCP]
    B --> C[Services métier<br/>Cache SWR & Agrégation]
    C --> D[ffbb-data-client<br/>SDK Python]
    D --> E[(API FFBB · Meilisearch · Directus)]

Loading

Points clés :

• Double transport : Streamable HTTP distant (spec 2025-11-25) ou Stdio local (uvx) ;
• SDK Python découplé : Requêtes vers les sources fédérales et parsing Pydantic v2 délégués à ffbb-data-client ; le serveur MCP ne les interroge pas directement ;
• Agrégation composite : 12 outils optimisés pour réduire les allers-retours et le contexte LLM ;
• Cache intelligent & SWR : Stale-While-Revalidate avec TTL par type de donnée (30 s lives, 1 h bilans, 24 h clubs) ;
• Observabilité complète : Dashboard HTML, métriques Prometheus, snapshot JSON et healthcheck intégrés.

Détails : docs/ARCHITECTURE.md et docs/PERFORMANCE.md.

---

💻 Développement local

uv sync --extra dev       # installer les dépendances
uv run ruff format .      # formater
uv run ruff check --fix . # linter
uv run mypy src           # vérifier les types
uv run pytest             # lancer les tests

Voir CONTRIBUTING.md pour les règles de contribution.

---

🧪 Tests

uv run pytest             # tests unitaires + couverture
uv run pytest tests/      # ciblé

Le pipeline CI (.github/workflows/ci.yml) exécute ruff, mypy, pytest et le contrôle de couverture à chaque push/PR.

---

📚 Documentation

• Exemples d’usage
• Référence des outils
• Architecture
• Performance et cache
• Déploiement Coolify

---

🤝 Communauté

• Contribuer
• Code de conduite
• Support
• Sécurité

---

❓ Dépannage

Symptôme	Cause probable	Solution
Missing session ID / deadline exceeded	Wrapper mcp-remote ou mauvais transport	Utiliser serverUrl natif dans mcp_config.json (voir Google Antigravity)
Claude Desktop refuse l'URL http	Claude Desktop impose stdio	Utiliser le bridge @modelcontextprotocol/client-sse via npx (voir Claude Desktop)
Données live obsolètes	Cache TTL	Attendre le rafraîchissement (≤ 30 s) ou interroger l'endpoint /health

---

🌟 Stargazers & Communauté

---

Projet non officiel, non affilié à la Fédération Française de BasketBall.