FFE MCP

Serveur MCP qui permet à Claude d'interroger les données publiques de la Fédération Française des Échecs (echecs.asso.fr) directement en conversation : rechercher un joueur, lister les tournois d'un département, consulter la cadence et le classement d'un tournoi, suivre les résultats d'un joueur ronde par ronde.

Un modèle à copier, pas un service

Comme ecoledirecte-mcp, ce projet n'est pas un service auquel tu te connectes : c'est un programme que tu installes et fais tourner chez toi. Ici, c'est même plus simple : les données FFE sont publiques, donc aucun identifiant à fournir, aucun fichier .env à sécuriser.

Important : API non officielle

La FFE n'expose aucune API publique documentée. Ce serveur scrape les pages HTML publiques d'echecs.asso.fr. Conséquences concrètes :

Le format des pages peut changer sans préavis. Si un outil commence à renvoyer une erreur "le site a probablement changé sa mise en page", le parseur (src/domain/ffe-parsers.ts) doit être mis à jour.
En cas d'échec du live (site indisponible), chaque outil retombe automatiquement sur le dernier résultat mis en cache (dossier ~/.ffe-mcp/cache/) en signalant qu'il s'agit de données potentiellement périmées.
Merci de ne pas appeler les outils en boucle rapprochée : c'est un site public partagé par toute la communauté échiquéenne, pas une API taillée pour l'usage intensif.

Ce qui a été vérifié par capture réelle (2026-09-10)

ListeJoueurs.aspx?Action=FFE (POST JoueurNom=<recherche>) : recherche de licencié, colonnes NrFFE / nom / Elo standard + lettre d'origine (F=FIDE, N=national, E=estimé). Testé en direct sur le fichier des licenciés.
ListeTournois.aspx?Action=TOURNOICOMITE&ComiteRef=<departement> : liste des tournois d'un département (le ComiteRef FFE correspond au code département pour la France métropolitaine). Testé en direct sur le 92.
FicheTournoi.aspx?Ref=<ref> : cadence, nombre de rondes, annonce. Le nom et la ville du tournoi n'y sont volontairement pas extraits (sélecteurs non vérifiés), utiliser lister_tournois pour ces champs.
Resultats.aspx?URL=Tournois/Id/<ref>/<ref>&Action=Cl : classement général après la dernière ronde publiée par l'organisateur (pas systématique, dépend du logiciel utilisé côté club).
Resultats.aspx?URL=Tournois/Id/<ref>/<ref>&Action=Ga : grille américaine, résultats ronde par ronde d'un joueur précis (recherche par nom exact tel qu'affiché par la FFE).

Ce qui reste à vérifier

Les colonnes Elo rapide et blitz de la recherche de joueur (présentes sur la page mais pas encore parsées).
Une éventuelle fiche joueur individuelle par NrFFE (historique complet, progression Elo), pas encore identifiée avec certitude.

Outils exposés

Outil	Description
`rechercher_joueur`	Recherche un joueur par nom, retourne NrFFE + Elo standard
`lister_tournois`	Liste les tournois homologués d'un département
`details_tournoi`	Cadence, nombre de rondes, annonce d'un tournoi
`classement_tournoi`	Classement général après la dernière ronde publiée
`resultats_joueur_tournoi`	Résultats ronde par ronde d'un joueur dans un tournoi

Stack

Node.js + TypeScript, exécuté en local uniquement (pas de serveur HTTP, pas de déploiement)
@modelcontextprotocol/sdk, transport stdio
zod pour la validation des schémas de sortie
vitest pour les tests (fixtures HTML réelles capturées sur echecs.asso.fr)

Installation

git clone https://github.com/riadh-mnasri/ffe-mcp.git
cd ffe-mcp
npm install
npm run build

Connexion à Claude Desktop / Claude Code

Ajouter dans la configuration MCP :

{
  "mcpServers": {
    "ffe": {
      "command": "node",
      "args": ["/chemin/vers/ffe-mcp/dist/index.js"]
    }
  }
}

Développement

npm run dev    # lance le serveur en TypeScript direct (tsx)
npm test       # tests unitaires (parseurs HTML)
npm run build  # compilation TypeScript