ffbb-mcp-server 1.3.0__tar.gz

ffbb_mcp_server-1.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nicolas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ffbb_mcp_server-1.3.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: ffbb-mcp-server
+Version: 1.3.0
+Summary: MCP Server for FFBB (Fédération Française de Basketball) data
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/nickdesi/FFBB-MCP-Server
+Project-URL: Repository, https://github.com/nickdesi/FFBB-MCP-Server
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]>=1.27.0
+Requires-Dist: ffbb-data-client<3.0.0,>=2.1.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: uvicorn<1.0.0,>=0.30.0
+Requires-Dist: starlette<2.0.0
+Requires-Dist: pydantic<3.0.0,>=2.12.5
+Requires-Dist: cachetools>=5.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: ruff>=0.15.12; extra == "dev"
+Requires-Dist: mypy>=1.15.0; extra == "dev"
+Requires-Dist: types-cachetools>=7.0.0.20260503; extra == "dev"
+Requires-Dist: types-setuptools; extra == "dev"
+Requires-Dist: pre-commit>=3.7.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+Dynamic: license-file
+
+# 🏀 FFBB MCP Server
+
+<p align="center">
+  <img src="./assets/logo.webp" width="180" alt="Logo FFBB MCP" style="border-radius: 20px; box-shadow: 0 10px 30px rgba(0,0,0,0.1);" />
+</p>
+
+<h3 align="center">Serveur MCP pour consulter les données officielles du basket français.</h3>
+
+<p align="center">
+  Calendriers, classements, bilans, résultats et scores live FFBB pour assistants IA compatibles MCP.
+  <br /><br />
+  🌐 <b><a href="https://ffbb.desimone.fr">Site</a></b>
+  · 🧩 <b><a href="https://github.com/nickdesi/FFBB-MCP-Server/releases/latest">Extension VS Code</a></b>
+  · 📚 <b><a href="https://ffbb.desimone.fr/docs/">Documentation</a></b>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.14%2B-blue?style=for-the-badge&logo=python" alt="Version Python" />
+  <img src="https://img.shields.io/badge/version-1.3.0-green?style=for-the-badge" alt="Version" />
+  <a href="https://smithery.ai/servers/nickdesi/mcpffbb"><img src="https://smithery.ai/badge/nickdesi/mcpffbb" alt="Badge Smithery" /></a>
+  <img src="https://img.shields.io/github/actions/workflow/status/nickdesi/FFBB-MCP-Server/ci.yml?label=CI&style=for-the-badge" alt="Statut CI" />
+  <img src="https://img.shields.io/badge/License-Apache--2.0-blue?style=for-the-badge" alt="Licence" />
+</p>
+
+---
+
+## Utiliser l'instance publique
+
+Endpoint MCP public :
+
+```text
+https://ffbb.desimone.fr/mcp
+```
+
+Transport : **Streamable HTTP**.
+
+Endpoints utiles :
+
+- Dashboard : `https://ffbb.desimone.fr/dashboard`
+- Métriques : `https://ffbb.desimone.fr/metrics.json`
+- Santé : `https://ffbb.desimone.fr/health`
+
+---
+
+## Installation rapide
+
+### VS Code / GitHub Copilot
+
+Option recommandée : installer l’extension **FFBB Basketball MCP** depuis les [releases](https://github.com/nickdesi/FFBB-MCP-Server/releases/latest), puis ouvrir Copilot Chat en mode agent.
+
+Alternative sans extension : [Installer FFBB MCP](vscode:mcp/install?%7B%22name%22%3A%22ffbb-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fffbb.desimone.fr%2Fmcp%22%7D)
+
+### Claude Desktop
+
+Ajoutez le serveur dans `claude_desktop_config.json` :
+
+```json
+{
+  "mcpServers": {
+    "ffbb": {
+      "httpUrl": "https://ffbb.desimone.fr/mcp"
+    }
+  }
+}
+```
+
+### Cursor / autres clients MCP
+
+Configurez un serveur MCP distant :
+
+- Type : `Streamable HTTP`
+- URL : `https://ffbb.desimone.fr/mcp`
+
+---
+
+## Outils principaux
+
+| Outil | Usage |
+| --- | --- |
+| `ffbb_bilan` | Bilan complet d’une équipe, toutes phases confondues. |
+| `ffbb_team_summary` | Résumé agent : bilan, classement courant, dernier résultat, prochain match. |
+| `ffbb_bilan_saison` | Bilan détaillé d’une équipe précise avec `numero_equipe`. |
+| `ffbb_last_result` | Dernier match joué. |
+| `ffbb_next_match` | Prochain match. |
+| `ffbb_club` | Calendrier complet, équipes ou classement d’un club. |
+| `ffbb_search` | Recherche clubs, compétitions, salles, matchs, engagements. |
+| `ffbb_get` | Accès technique à une ressource FFBB par identifiant. |
+| `ffbb_lives` | Matchs en direct. |
+| `ffbb_saisons` | Saisons disponibles. |
+| `ffbb_version` | Version et diagnostic runtime. |
+
+La référence complète est dans [`docs/TOOLS_REFERENCE.md`](docs/TOOLS_REFERENCE.md).
+
+---
+
+## Architecture en bref
+
+```mermaid
+flowchart LR
+    A[Client MCP] -->|Streamable HTTP| B[FFBB MCP Server]
+    B --> C[Services métier + cache]
+    C --> D[ffbb-data-client]
+    D --> E[API officielle FFBB]
+```
+
+Points clés :
+
+- serveur Python 3.10+ basé sur `mcp[cli]`, `starlette` et `uvicorn` ;
+- agrégation métier pour limiter le nombre d'appels et réduire le contexte LLM ;
+- cache TTL adapté aux données live, calendriers et classements ;
+- dashboard, métriques JSON et healthcheck intégrés.
+
+Détails : [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) et [`docs/PERFORMANCE.md`](docs/PERFORMANCE.md).
+
+---
+
+## Développement local
+
+```bash
+uv sync --extra dev
+uv run ruff format .
+uv run ruff check --fix .
+uv run mypy src
+uv run pytest
+```
+
+Voir [`CONTRIBUTING.md`](CONTRIBUTING.md) pour les règles de contribution.
+
+---
+
+## Documentation
+
+- [Exemples d’usage](docs/EXAMPLES.md)
+- [Référence des outils](docs/TOOLS_REFERENCE.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Performance et cache](docs/PERFORMANCE.md)
+- [Déploiement Coolify](docs/COOLIFY_DEPLOYMENT.md)
+
+---
+
+<p align="center">
+  <i>Projet non officiel, non affilié à la Fédération Française de BasketBall.</i>
+</p>

ffbb_mcp_server-1.3.0/README.md

@@ -0,0 +1,143 @@
+# 🏀 FFBB MCP Server
+
+<p align="center">
+  <img src="./assets/logo.webp" width="180" alt="Logo FFBB MCP" style="border-radius: 20px; box-shadow: 0 10px 30px rgba(0,0,0,0.1);" />
+</p>
+
+<h3 align="center">Serveur MCP pour consulter les données officielles du basket français.</h3>
+
+<p align="center">
+  Calendriers, classements, bilans, résultats et scores live FFBB pour assistants IA compatibles MCP.
+  <br /><br />
+  🌐 <b><a href="https://ffbb.desimone.fr">Site</a></b>
+  · 🧩 <b><a href="https://github.com/nickdesi/FFBB-MCP-Server/releases/latest">Extension VS Code</a></b>
+  · 📚 <b><a href="https://ffbb.desimone.fr/docs/">Documentation</a></b>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.14%2B-blue?style=for-the-badge&logo=python" alt="Version Python" />
+  <img src="https://img.shields.io/badge/version-1.3.0-green?style=for-the-badge" alt="Version" />
+  <a href="https://smithery.ai/servers/nickdesi/mcpffbb"><img src="https://smithery.ai/badge/nickdesi/mcpffbb" alt="Badge Smithery" /></a>
+  <img src="https://img.shields.io/github/actions/workflow/status/nickdesi/FFBB-MCP-Server/ci.yml?label=CI&style=for-the-badge" alt="Statut CI" />
+  <img src="https://img.shields.io/badge/License-Apache--2.0-blue?style=for-the-badge" alt="Licence" />
+</p>
+
+---
+
+## Utiliser l'instance publique
+
+Endpoint MCP public :
+
+```text
+https://ffbb.desimone.fr/mcp
+```
+
+Transport : **Streamable HTTP**.
+
+Endpoints utiles :
+
+- Dashboard : `https://ffbb.desimone.fr/dashboard`
+- Métriques : `https://ffbb.desimone.fr/metrics.json`
+- Santé : `https://ffbb.desimone.fr/health`
+
+---
+
+## Installation rapide
+
+### VS Code / GitHub Copilot
+
+Option recommandée : installer l’extension **FFBB Basketball MCP** depuis les [releases](https://github.com/nickdesi/FFBB-MCP-Server/releases/latest), puis ouvrir Copilot Chat en mode agent.
+
+Alternative sans extension : [Installer FFBB MCP](vscode:mcp/install?%7B%22name%22%3A%22ffbb-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fffbb.desimone.fr%2Fmcp%22%7D)
+
+### Claude Desktop
+
+Ajoutez le serveur dans `claude_desktop_config.json` :
+
+```json
+{
+  "mcpServers": {
+    "ffbb": {
+      "httpUrl": "https://ffbb.desimone.fr/mcp"
+    }
+  }
+}
+```
+
+### Cursor / autres clients MCP
+
+Configurez un serveur MCP distant :
+
+- Type : `Streamable HTTP`
+- URL : `https://ffbb.desimone.fr/mcp`
+
+---
+
+## Outils principaux
+
+| Outil | Usage |
+| --- | --- |
+| `ffbb_bilan` | Bilan complet d’une équipe, toutes phases confondues. |
+| `ffbb_team_summary` | Résumé agent : bilan, classement courant, dernier résultat, prochain match. |
+| `ffbb_bilan_saison` | Bilan détaillé d’une équipe précise avec `numero_equipe`. |
+| `ffbb_last_result` | Dernier match joué. |
+| `ffbb_next_match` | Prochain match. |
+| `ffbb_club` | Calendrier complet, équipes ou classement d’un club. |
+| `ffbb_search` | Recherche clubs, compétitions, salles, matchs, engagements. |
+| `ffbb_get` | Accès technique à une ressource FFBB par identifiant. |
+| `ffbb_lives` | Matchs en direct. |
+| `ffbb_saisons` | Saisons disponibles. |
+| `ffbb_version` | Version et diagnostic runtime. |
+
+La référence complète est dans [`docs/TOOLS_REFERENCE.md`](docs/TOOLS_REFERENCE.md).
+
+---
+
+## Architecture en bref
+
+```mermaid
+flowchart LR
+    A[Client MCP] -->|Streamable HTTP| B[FFBB MCP Server]
+    B --> C[Services métier + cache]
+    C --> D[ffbb-data-client]
+    D --> E[API officielle FFBB]
+```
+
+Points clés :
+
+- serveur Python 3.10+ basé sur `mcp[cli]`, `starlette` et `uvicorn` ;
+- agrégation métier pour limiter le nombre d'appels et réduire le contexte LLM ;
+- cache TTL adapté aux données live, calendriers et classements ;
+- dashboard, métriques JSON et healthcheck intégrés.
+
+Détails : [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) et [`docs/PERFORMANCE.md`](docs/PERFORMANCE.md).
+
+---
+
+## Développement local
+
+```bash
+uv sync --extra dev
+uv run ruff format .
+uv run ruff check --fix .
+uv run mypy src
+uv run pytest
+```
+
+Voir [`CONTRIBUTING.md`](CONTRIBUTING.md) pour les règles de contribution.
+
+---
+
+## Documentation
+
+- [Exemples d’usage](docs/EXAMPLES.md)
+- [Référence des outils](docs/TOOLS_REFERENCE.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Performance et cache](docs/PERFORMANCE.md)
+- [Déploiement Coolify](docs/COOLIFY_DEPLOYMENT.md)
+
+---
+
+<p align="center">
+  <i>Projet non officiel, non affilié à la Fédération Française de BasketBall.</i>
+</p>

ffbb_mcp_server-1.3.0/pyproject.toml

@@ -0,0 +1,102 @@
+[build-system]
+requires = ["setuptools>=82.0.1", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ffbb-mcp-server"
+version = "1.3.0"
+description = "MCP Server for FFBB (Fédération Française de Basketball) data"
+readme = "README.md"
+requires-python = ">=3.14"
+license = { text = "Apache-2.0" }
+dependencies = [
+    "mcp[cli]>=1.27.0",
+    "ffbb-data-client>=2.1.0,<3.0.0",
+    "httpx>=0.28.0",
+    "uvicorn>=0.30.0,<1.0.0",
+    "starlette<2.0.0",
+    "pydantic>=2.12.5,<3.0.0",
+    "cachetools>=5.3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/nickdesi/FFBB-MCP-Server"
+Repository = "https://github.com/nickdesi/FFBB-MCP-Server"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.15.12",
+    "mypy>=1.15.0",
+    "types-cachetools>=7.0.0.20260503",
+    "types-setuptools",
+    "pre-commit>=3.7.0",
+]
+docs = [
+    "mkdocs>=1.6.0",
+    "mkdocs-material>=9.5.0",
+]
+
+[project.scripts]
+ffbb-mcp = "ffbb_mcp.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"*" = ["website/*", "website/css/*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "--cov=ffbb_mcp --cov-fail-under=65"
+
+[tool.ruff]
+line-length = 88
+target-version = "py314"
+exclude = [
+    ".agent",
+    ".git",
+    ".venv",
+    ".mypy_cache",
+    ".ruff_cache",
+    "ffbb-data-client_Ref",
+    "external",
+    "external/**",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "ASYNC", "TCH"]
+ignore = ["E501"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.mypy]
+disallow_untyped_defs = false
+warn_return_any = false
+warn_unused_configs = true
+ignore_missing_imports = true
+
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101", "RUF059", "F821"]
+"tools/*" = ["S110"]
+"src/ffbb_mcp/prompts.py" = ["RUF001", "RUF003"]
+"src/ffbb_mcp/cache_strategy.py" = ["RUF003"]
+"src/ffbb_mcp/server.py" = ["RUF001"]
+
+[[tool.mypy.overrides]]
+module = ["cachetools"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "starlette.middleware.base"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "ffbb_mcp.services"
+disable_error_code = ["attr-defined"]

ffbb_mcp_server-1.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ffbb_mcp_server-1.3.0/src/ffbb_mcp/__init__.py

@@ -0,0 +1,9 @@
+"""FFBB MCP Server — Fédération Française de Basketball."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("ffbb-mcp-server")
+except PackageNotFoundError:
+    __version__ = "unknown"

ffbb_mcp_server-1.3.0/src/ffbb_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for the FFBB MCP server."""
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

ffbb_mcp_server-1.3.0/src/ffbb_mcp/_state.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import asyncio
+
+    from cachetools import TLRUCache, TTLCache
+
+
+def _read_positive_int_env(key: str, default: int) -> int:
+    val_str = os.environ.get(key)
+    if val_str is not None:
+        try:
+            val = int(val_str)
+            if val > 0:
+                return val
+        except ValueError:
+            pass
+    return default
+
+
+@dataclass
+class _ServiceState:
+    inflight_bilan: dict[str, asyncio.Task[Any]] = field(default_factory=dict)
+    inflight_calendrier: dict[str, asyncio.Task[Any]] = field(default_factory=dict)
+    inflight_poule: dict[str, asyncio.Task[Any]] = field(default_factory=dict)
+    inflight_detail: dict[str, asyncio.Task[Any]] = field(default_factory=dict)
+    inflight_search: dict[str, asyncio.Task[Any]] = field(default_factory=dict)
+
+    # Caches in-memory globaux
+    cache_lives: TTLCache[Any, Any] | None = None
+    cache_search: TTLCache[Any, Any] | None = None
+    cache_competition: TTLCache[Any, Any] | None = None
+    cache_organisme: TTLCache[Any, Any] | None = None
+    cache_saisons: TTLCache[Any, Any] | None = None
+    cache_calendrier: TTLCache[Any, Any] | TLRUCache[Any, Any] | None = None
+    cache_bilan: TLRUCache[Any, Any] | None = None
+    cache_classement: TLRUCache[Any, Any] | None = None
+    cache_poule: TLRUCache[Any, Any] | None = None
+
+
+state = _ServiceState()
+
+
+def reset_service_state() -> None:
+    global state
+    state.inflight_bilan.clear()
+    state.inflight_calendrier.clear()
+    state.inflight_poule.clear()
+    state.inflight_detail.clear()
+    state.inflight_search.clear()
+    if state.cache_lives is not None:
+        state.cache_lives.clear()
+    if state.cache_search is not None:
+        state.cache_search.clear()
+    if state.cache_competition is not None:
+        state.cache_competition.clear()
+    if state.cache_organisme is not None:
+        state.cache_organisme.clear()
+    if state.cache_saisons is not None:
+        state.cache_saisons.clear()
+    if state.cache_calendrier is not None:
+        state.cache_calendrier.clear()
+    if state.cache_bilan is not None:
+        state.cache_bilan.clear()
+    if state.cache_classement is not None:
+        state.cache_classement.clear()
+    if state.cache_poule is not None:
+        state.cache_poule.clear()