# 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](https://github.com/riadh-mnasri/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

```bash
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 :

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

## Développement

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

## Licence

MIT, © 2026 Riadh MNASRI