Skip to content

About

🏀 Serveur MCP FFBB — AccĂ©dez aux donnĂ©es officielles de l'API FFBB (clubs, classements, calendriers, scores live) depuis Claude, Cursor, Copilot et ChatGPT.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

 

History

1,089 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

🏀 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


Version Python CI MCP Glama License: Apache 2.0 GitHub stars


⭐ 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 (19 outils exposĂ©s)

Le serveur expose 19 outils MCP optimisés pour les LLMs (réponses compactes, cache SWR, déduplication automatique) :

🏀 Matchs, RĂ©sultats & Calendriers

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).

🏱 Clubs, Équipes & DĂ©couverte

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.

📜 Rùglements Officiels FFBB (Index FTS5)

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.


🌐 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 & RĂ©silience RĂ©seau

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)]
Loading

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.


⚙ Variables d'Environnement

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

đŸ’» 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


đŸ€ CommunautĂ©


❓ DĂ©pannage

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

🌟 Stargazers & CommunautĂ©

Star History Chart


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

About

🏀 Serveur MCP FFBB — AccĂ©dez aux donnĂ©es officielles de l'API FFBB (clubs, classements, calendriers, scores live) depuis Claude, Cursor, Copilot et ChatGPT.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages