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 ! â
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.
- đïž 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.
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
Option A â Via l'interface de Claude (recommandĂ©, sans prĂ©requis)
- Ouvrez les ParamĂštres de Claude, puis Connecteurs (ou Plugins).
- Cliquez sur Ajouter un connecteur personnalisé.
- Renseignez l'URL publique
https://ffbb.desimone.fr/mcpet 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
npmetnpx). Sans Node.js, privilégiez l'Option A.
{
"mcpServers": {
"ffbb": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/client-sse", "https://ffbb.desimone.fr/mcp"]
}
}
}Configurez un serveur MCP distant :
| Champ | Valeur |
|---|---|
| Type | Streamable HTTP |
| URL | https://ffbb.desimone.fr/mcp |
Configurez directement l'URL distante dans mcp_config.json via la directive native serverUrl :
{
"mcpServers": {
"ffbb_mcp": {
"serverUrl": "https://ffbb.desimone.fr/mcp"
}
}
}Le serveur expose 19 outils MCP optimisés pour les LLMs (réponses compactes, cache SWR, déduplication automatique) :
| Outil | Usage |
|---|---|
ffbb_last_result |
Dernier résultat connu d'une équipe avec score précis et détails du match. |
ffbb_next_match |
Prochaine rencontre programmée (date, heure, gymnase et adversaire). |
ffbb_team_summary |
SynthÚse complÚte d'une équipe (matchs passés, à venir, classement et dynamique). |
ffbb_bilan |
Bilan synthétique victoires / défaites, points marqués / encaissés et différentiel. |
ffbb_bilan_saison |
SynthĂšse exhaustive d'un club sur toute la saison toutes phases confondues. |
ffbb_head_to_head |
Confrontation directe et historique récent entre deux clubs ou équipes. |
ffbb_match_lookup |
Recherche ciblée d'une rencontre par identifiant ou critÚres. |
ffbb_lives |
Scores en direct des rencontres en cours (rafraĂźchi toutes les 30s). |
| Outil | Usage |
|---|---|
ffbb_search |
Recherche universelle plein texte (clubs, compétitions, salles, tournois). |
ffbb_club |
Fiche complÚte d'un club, coordonnées et calendrier de toutes ses équipes. |
ffbb_resolve_team |
Résolution canonique d'un libellé d'équipe (catégorie, genre, numéro d'équipe). |
ffbb_find_team_candidates |
Liste des équipes candidates pour un nom de club ou d'organisme. |
ffbb_get |
Extraction brute d'un objet Directus / Meilisearch par identifiant. |
ffbb_saisons |
Liste des saisons sportives fédérales disponibles. |
| Outil | Usage |
|---|---|
ffbb_search_regulations |
Recherche sémantique dans les RÚglements Sportifs Généraux (RSG 2026-2027) et comités. |
ffbb_get_regulation_article |
Consultation intégrale et inaltérée d'un article réglementaire officiel (ex: Art. 28). |
ffbb_explain_tiebreak_rules |
Explication certifiée des rÚgles de départage d'égalité (point-average, quotient). |
ffbb_list_regulations |
Catalogue hiérarchique des rÚglements fédéraux et départementaux indexés. |
ffbb_version |
Diagnostic, transport actif, version FastMCP et SDK. |
Note
Référence complÚte des schémas et paramÚtres : docs/TOOLS_REFERENCE.md.
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 |
flowchart LR
A[Client MCP<br/>Claude · Cursor · Antigravity] -->|Streamable HTTP / Stdio| B[FFBB MCP Server<br/>FastMCP Streamable]
B --> C[Services métier<br/>Cache SWR & Agrégation]
C --> D[ffbb-data-client<br/>SDK Python v2.4.37]
D --> E[(Directus api.ffbb.com<br/>Origine officielle mobile pullzone 5204911)]
D --> F[(Meilisearch Nginx<br/>meilisearch-prod.ffbb.app)]
Points clés :
- RĂ©silience WAF & Directus : Les requĂȘtes Directus sont routĂ©es nativement vers
https://api.ffbb.com/(pullzone mobile officielle 5204911, amorcée via/items/configuration), éliminant définitivement les erreurs 403 HTML des anciens domaines bloqués ; - Auto-résolution des tokens : Découverte dynamique et transparente des jetons de session sans clé API requise ;
- Double transport : Streamable HTTP distant (spec
2026-07-28, Stateless Core) 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; - 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.
| Variable | Description | Valeur par défaut |
|---|---|---|
API_FFBB_BASE_URL |
Base URL du backend Directus FFBB | https://api.ffbb.com/ |
FFBB_USER_AGENT |
User-Agent authentique transmis Ă Directus | FFBB Android Mobile (1.6.7.42) |
API_FFBB_APP_BEARER_TOKEN |
Jeton Directus explicite (override l'auto-résolution) | Auto-résolu dynamiquement |
MEILISEARCH_BEARER_TOKEN |
Jeton Meilisearch explicite (override l'auto-résolution) | Auto-résolu dynamiquement |
MCP_MODE |
Mode de transport du serveur | streamable-http (ou stdio) |
PORT |
Port d'écoute HTTP | 9123 |
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 testsVoir CONTRIBUTING.md pour les rĂšgles de contribution.
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.
- Exemples dâusage
- Référence des outils
- Architecture
- Performance et cache
- Déploiement Dokploy & Zoraxy
| SymptĂŽme | Cause probable | Solution |
|---|---|---|
FFBB access blocked by CDN (403 BunnyCDN) |
IP bloquée par le WAF ou User-Agent non officiel | Utiliser ffbb-data-client ℠v2.4.42 (pullzone mobile api.ffbb.com + UA Dalvik) ou un proxy sortant VPN (Gluetun) |
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 |
Projet non officiel, non affilié à la Fédération Française de BasketBall.