🏀 FFBB MCP Server

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

Serveur MCP pour consulter calendriers, classements, bilans, résultats et scores live de la FFBB.

🌐 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 ? » « Donne-moi le classement de la poule 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, cache 30s). Retourne [] si aucun match.
ffbb_saisons	Liste des saisons FFBB. active_only=True pour la saison en cours uniquement.
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).

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 Directus &<br/>Meilisearch FFBB)]

Loading

Points clés :

• Double transport : Streamable HTTP distant (spec 2025-11-25) ou Stdio local (uvx) ;
• SDK Python découplé : Requêtes réseau et parsing Pydantic v2 délégués à ffbb-data-client ;
• 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.