🏀 FFBB MCP Server

Un pont intelligent entre les données de la Fédération Française de Basketball et les assistants IA du futur.

Le serveur FFBB MCP permet à votre IA (Claude Desktop, Google Antigravity, Cursor, etc.) d'accéder nativement et en temps réel aux calendriers, classements et résultats du basketball français.

---

🏗️ Architecture

Le serveur agit comme une interface normalisée entre les agents IA et l'API FFBB, gérant l'authentification et offrant un filtrage sémantique intelligent.

graph TD
    User([Utilisateur]) --> Agent[Assistant IA / Agent]
    Agent -->|Requête MCP| Server[FFBB MCP Server]
    Server -->|Token Auto| Auth[Token Manager]
    Server -->|Fetch| API[FFBB Public API]
    API -.->|Data JSON| Server
    Server -->|Réponse Structurée| Agent
    Agent -->|Réponse Naturelle| User

---

✨ Fonctionnalités Clés

• ⚡ Temps Réel : Accès aux scores live via ffbb_get_lives.
• 🔍 Recherche Puissante : Recherche globale via ffbb_multi_search (Clubs, Salles, Compétitions).
• 📋 Calendriers & Résultats : Historique et matchs à venir pour n'importe quelle équipe.
• 🏆 Classements : Positions actualisées dans toutes les poules (Nationale, Régionale, Départementale).
• 🛠️ Zero Config Auth : Les jetons d'accès sont récupérés automatiquement, aucune clé API manuelle n'est nécessaire.

---

🚀 Installation & Lancement

# 1. Cloner le repo
git clone https://github.com/nickdesi/FFBB-MCP-Server.git
cd FFBB-MCP-Server

# 2. Setup de l'environnement
python -m venv .venv
source .venv/bin/activate
pip install -e "."

# 3. Tester en local (MCP Inspector)
npx @modelcontextprotocol/inspector python -m ffbb_mcp

---

⚙️ Intégration IDE & Desktop

🪐 Google Antigravity (Gemini Code Assist / CLI)

Éditez votre fichier ~/.gemini/settings.json :

{
  "mcpServers": {
    "ffbb": {
      "command": "python",
      "args": ["-m", "ffbb_mcp"],
      "cwd": "/votre/chemin/FFBB-MCP-Server"
    }
  }
}

💻 VS Code (Roo Code / Cline)

Installez l'extension et configurez la source :

{
  "mcpServers": {
    "ffbb": {
      "command": "/votre/chemin/.venv/bin/python",
      "args": ["-m", "ffbb_mcp"],
      "cwd": "/votre/chemin/FFBB-MCP-Server"
    }
  }
}

🧠 Claude Desktop

Éditez ~/Library/Application Support/Claude/claude_desktop_config.json :

{
  "mcpServers": {
    "ffbb": {
      "command": "/votre/chemin/.venv/bin/python",
      "args": ["-m", "ffbb_mcp"],
      "cwd": "/votre/chemin/FFBB-MCP-Server"
    }
  }
}

---

🤖 Guide de Survie pour Agents IA (Best Practices)

Pour les développeurs d'agents, ce serveur a été optimisé pour une utilisation sémantique :

1. Fiabilité Max : Ne tentez pas de deviner les IDs. Utilisez ffbb_search_organismes pour trouver le club, puis listez les équipes via ffbb_get_organisme.
2. Filtrage Intelligent : Les agents doivent utiliser les indices de texte (ex: "Equipe 2", "U11M") pour filtrer les résultats d'engagement avant d'appeler ffbb_get_poule.
3. Gestion des Alias : Le serveur supporte les recherches par acronymes si l'agent est capable de faire le lien (ex: SCBA -> Stade Clermontois).

---

📚 Source & Crédits

• Données : Fédération Française de Basketball.
• Core Library : ffbb-api-client-v2.
• Maintenance : Nicolas De Simone.

---

Fait avec ❤️ par et pour les passionnés de basket.