ecoledirecte-mcp

Serveur MCP personnel pour École Directe : notes, devoirs, emploi du temps, vie scolaire, vie de classe, fil d'actualité, téléchargement de documents.

Installation locale (stdio)

npm install
npm run build
node dist/cli/index.js login

login demande l'identifiant et le mot de passe École Directe, puis, à la première connexion depuis cette machine, une question de sécurité (QCM) — c'est obligatoire côté École Directe, il n'y a pas de contournement.

La session est enregistrée dans ~/.config/ecoledirecte-mcp/session.json (permissions 600) et rafraîchie automatiquement ensuite.

Related MCP server: EduPage MCP Server

Utilisation avec Claude Code

claude mcp add ecoledirecte -- node /chemin/absolu/vers/dist/cli/index.js serve

Le serveur démarre même sans session valide : get_auth_status sert justement à diagnostiquer ce cas, et les autres outils renvoient une erreur explicite au lieu de faire tomber le serveur.

Outils exposés

La messagerie est en deux outils parce que l'API l'impose : la liste renvoie content: "" pour chaque message, les corps n'existent que sur l'endpoint par message. Les pièces jointes se récupèrent avec download_document en passant fileType = PIECE_JOINTE.

En HTTP, le fichier atterrit sur le serveur, hors de portée du client : le chemin ne lui servirait à rien. download_document renvoie donc le texte du document, ce dont le modèle a besoin (tronqué à 100 000 caractères), et un lien temporaire …/downloads/<jeton> valable une heure pour que tu récupères le fichier toi-même. Un navigateur ne sait pas envoyer le jeton MCP : c'est le jeton aléatoire de 256 bits dans l'URL qui fait office d'accès, et il ne désigne qu'un fichier que le serveur a lui-même écrit. Les liens vivent en mémoire et disparaissent au redémarrage. L'URL de base est l'origine de MCP_PUBLIC_URL si elle est définie, sinon la première entrée de MCP_ALLOWED_HOSTS.

Les moyennes sont calculées et non lues : un établissement peut ne les publier qu'une fois la période close (moyenneUniquementPeriodeCloture), et École Directe renvoie alors des champs vides. Chaque note compte pour note/barème × 20 × coefficient, la moyenne générale pondère les matières par leur coefficient, et les notes non chiffrées ou non significatives sont exclues. Vérifié sur une année archivée : le calcul retombe exactement sur les moyennes officielles publiées. Celles-ci sont renvoyées à côté une fois la période close.

Variables d'environnement

• SESSION_PATH — chemin du fichier de session (défaut ~/.config/ecoledirecte-mcp/session.json)

• DEVICE_ID_PATH — chemin de l'identifiant d'appareil (défaut ~/.config/ecoledirecte-mcp/device-id)

• DOWNLOAD_DIR — dossier de téléchargement (défaut ~/.local/share/ecoledirecte-mcp/downloads)

• READ_ONLY — true pour désactiver mark_homework_done (défaut false en local)

• SESSION_MAX_AGE_MS — âge au-delà duquel la session est rafraîchie préventivement (défaut 15 min)

Transport HTTP uniquement :

• MCP_AUTH_TOKEN — obligatoire, le serveur refuse de démarrer sans (openssl rand -hex 32)

• MCP_HTTP_HOST — adresse d'écoute (défaut 127.0.0.1, jamais 0.0.0.0)

• MCP_HTTP_PORT — port (défaut 8787)

• MCP_ALLOWED_HOSTS — en-têtes Host acceptés, séparés par des virgules (défaut : l'adresse d'écoute)

Le deviceUUID généré au premier login est stocké séparément dans ~/.config/ecoledirecte-mcp/device-id. Ne pas le supprimer entre deux logins, sous peine de redéclencher le QCM à chaque fois.

Authentification : ce qu'il faut savoir

École Directe délivre deux secrets distincts, tous deux dans session.json :

• token — jeton de session court, envoyé en header X-Token à chaque appel de données ; il tourne à chaque login ou re-login ;

• accessToken — credential long, lié à l'appareil, seule chose capable de régénérer un token sans le mot de passe.

Les confondre fait échouer tous les appels avec 520 "Token invalide !". C'est pour cette raison que l'authentification (login, QCM, re-login) est implémentée directement dans src/client/edAuth.ts plutôt que déléguée à @blockshub/blocksdirecte, dont le module d'auth :

1. ne lit le jeton que dans le corps de la réponse, alors qu'École Directe le renvoie aussi (parfois uniquement) dans le header X-Token ;

2. ne reconnaît que les codes 250 et 505 au re-login — le 526 « Votre session est invalide ou expirée » tombe dans son chemin de succès et produit une session vide qui ressemble à une réussite ;

3. écrit sur stdout, ce qui corrompt le flux JSON-RPC du transport stdio.

Le reste a suivi : tous les appels passent désormais en HTTP direct (src/client/edData.ts pour les notes, devoirs, EDT, vie scolaire, vie de classe et fil d'actualité ; messaging.ts, documents.ts, download.ts), et la librairie n'est plus une dépendance. Elle posait trois problèmes :

1. elle jetait le code numérique d'École Directe sur les appels de données, si bien qu'un jeton expiré ne se devinait qu'à une réponse vide ; désormais 520/525 deviennent une vraie TokenExpiredError, et le rafraîchissement automatique s'applique aussi aux écritures ;

2. elle décodait en base64 toute chaîne qui en avait l'air, ce qui transforme un code de 4 lettres comme ESP2 en charabia ; seuls les champs réellement encodés (contenus des devoirs, des séances, de la vie de classe, des messages) sont décodés ;

3. elle démarrait un setInterval impossible à arrêter, qu'il fallait neutraliser pour qu'un script ponctuel se termine.

downloader.getStream(), lui, jetait les en-têtes de réponse : le vrai nom de fichier — porté par Content-Disposition — était perdu et chaque document atterrissait sur le disque nommé d'après son identifiant numérique.

Le User-Agent BlocksDirecte/1.0 … est conservé tel quel : École Directe lie le jeton au User-Agent qui l'a obtenu, en changer invaliderait les sessions existantes.

À noter : un téléchargement en échec répond quand même HTTP 200. École Directe met son propre code dans l'en-tête X-Code (403 pour un identifiant inconnu, avec une page d'erreur HTML en guise de contenu), ce que le code vérifie avant d'écrire quoi que ce soit sur le disque.

Limitations connues (V1)

Expiration de session en cours d'utilisation. La session est rafraîchie préventivement au-delà de SESSION_MAX_AGE_MS, et un appel de données qui échoue de façon récupérable déclenche un rafraîchissement puis une seule nouvelle tentative — jamais de boucle. Si le re-login lui-même est refusé (identifiant d'appareil révoqué, QCM redemandé), il faut relancer login ; le health check le signale (voir plus bas).

Durée de vie réelle du jeton inconnue. Les 15 minutes par défaut de SESSION_MAX_AGE_MS sont une valeur prudente, pas une valeur observée. À calibrer à l'usage (voir « Développement » ci-dessous).

Hébergement sur le VPS, via Tailscale (V2)

Le transport HTTP est fait pour être joignable depuis le tailnet et nulle part ailleurs. Trois protections se cumulent :

1. Le port n'est publié que sur une adresse explicite. docker-compose.yml exige PUBLISH_ADDRESS et refuse de démarrer sans — écrire 8787:8787 aurait lié 0.0.0.0 sur l'hôte et exposé le serveur à l'internet ouvert. Pour un déploiement tailnet, mets-y l'IP Tailscale du VPS.

2. Chaque requête /mcp doit porter Authorization: Bearer $MCP_AUTH_TOKEN. La comparaison passe par timingSafeEqual sur des empreintes SHA-256 : à temps constant, et sans fuir la longueur du jeton attendu.

3. Protection anti DNS rebinding : le Host de la requête doit figurer dans MCP_ALLOWED_HOSTS, sinon 403. Sans elle, une page ouverte dans ton navigateur pourrait faire pointer son propre domaine vers l'adresse tailnet et parler au serveur à ta place.

READ_ONLY vaut true par défaut sur ce transport (contre false en stdio) : il est joignable depuis d'autres machines, pas seulement par toi à ton clavier. mark_homework_done disparaît alors de la liste des outils.

Mise en route

cp .env.example .env      # renseigner MCP_AUTH_TOKEN et PUBLISH_ADDRESS
docker compose build      # build natif arm64 sur le VPS Ampere
docker compose run --rm -it ecoledirecte-mcp login
docker compose up -d

Le login se fait bien avant le up, et via run --rm -it pour avoir un terminal : il faut répondre au QCM. Session et identifiant d'appareil sont écrits sur le volume session, donc conservés entre deux recréations du conteneur — c'est pourquoi DEVICE_ID_PATH existe : sans lui l'identifiant serait recréé à chaque fois et École Directe redemanderait le QCM.

Le conteneur écoute sur 0.0.0.0 à l'intérieur de son espace réseau, ce qui est correct : l'isolation vient de la publication du port sur la seule IP Tailscale.

/health répond sans jeton, et volontairement sans rien dire du compte. Il ne se contente pas de dire que le processus tourne : toutes les 15 minutes (HEALTH_CHECK_INTERVAL_MS), le serveur fait un vrai appel léger, avec rafraîchissement du jeton comme pour un outil. Après deux échecs d'affilée — un seul serait peut-être un incident réseau —, /health répond 503 avec un motif sommaire :

{"status":"failing","sessionExists":true,
 "session":{"status":"failing","reason":"auth_required",
            "since":"…","checkedAt":"…"}}

reason vaut auth_required (QCM redemandé, appareil révoqué : relancer login), school_unavailable (maintenance École Directe), no_session ou error. Le HEALTHCHECK Docker passe alors le conteneur en unhealthy, et la supervision (Uptime Kuma, Gatus) alerte sur le 503 via le tailnet — http://<ip-tailscale>:8789/health, en n'acceptant que 2xx. Le serveur n'envoie lui-même aucune notification.

Connecter un client

claude mcp add --transport http ecoledirecte http://<ip-tailscale>:8787/mcp \
  --header "Authorization: Bearer $MCP_AUTH_TOKEN"

Le transport est sans état (pas de mcp-session-id) : le serveur est mono-utilisateur et ne pousse rien vers le client, donc il n'y a aucun cycle de vie de session à gérer côté serveur.

Exposition publique, pour un connecteur Claude.ai

Un connecteur personnalisé Claude.ai est appelé par les serveurs d'Anthropic, pas par ton appareil : la doc exige un serveur « reachable over the public internet from Anthropic's IP ranges ». Tailscale ne peut donc pas servir ce cas — même installé sur tous tes appareils, l'endpoint resterait injoignable pour Anthropic. Une exposition publique est la seule voie.

Ce qui limite les dégâts

Anthropic publie sa plage de sortie, 160.79.104.0/21. En l'allowlistant dans Nginx Proxy Manager, le domaine est public dans le DNS mais seule l'infrastructure d'Anthropic peut parler à /mcp, /token, /register et aux métadonnées : un scanner se fait refouler avant même d'atteindre l'authentification.

Trois chemins font exception : /authorize et /oauth/consent, ainsi que les liens de téléchargement /downloads/<jeton>, sont ouverts par ton navigateur, pas par Anthropic. Un deny all global les bloquerait : l'autorisation échouerait sur un 403, et aucun lien ne s'ouvrirait. Ils restent donc ouverts, protégés par la phrase secrète (cinq essais par demande) et la limitation de débit du routeur OAuth pour les premiers, par un jeton aléatoire qui expire au bout d'une heure pour les liens. Onglet Advanced du Proxy Host :

# Streamable HTTP peut ouvrir un flux SSE sur GET /mcp :
proxy_buffering off;
proxy_read_timeout 3600s;

# Ouverts par ton navigateur : autorisation OAuth et liens de téléchargement.
location ~ ^/(authorize|oauth/consent|downloads/[A-Za-z0-9_-]+)$ {
  include conf.d/include/proxy.conf;
}

# Tout le reste : Anthropic uniquement. Définir `location /` ici fait que
# NPM n'émet pas le sien.
location / {
  allow 160.79.104.0/21;
  deny all;
  include conf.d/include/proxy.conf;
}

Plus un certificat Let's Encrypt avec Force SSL. Garde READ_ONLY=true.

Authentification : OAuth

Claude ne sait pas envoyer un en-tête fixe sur un connecteur personnalisé, sauf via static_headers, en beta et réservé à un administrateur d'organisation. Le serveur implémente donc un serveur d'autorisation OAuth 2.0 complet : métadonnées RFC 8414 et RFC 9728, enregistrement dynamique de client (RFC 7591), PKCE S256, rotation des refresh tokens, 401 avec WWW-Authenticate pointant vers les métadonnées de ressource.

Comme le serveur ne dessert qu'un seul compte, l'« utilisateur » OAuth est toujours toi : le consentement est un écran qui demande MCP_OAUTH_PASSPHRASE. Anthropic impose un humain dans la boucle — un flux purement machine-à-machine n'est pas accepté. Cinq mauvaises réponses brûlent la demande en cours.

Clients enregistrés et jetons sont persistés sur le volume, en empreintes SHA-256 : le serveur n'a jamais besoin de relire un jeton, seulement de vérifier une correspondance, donc une fuite du fichier ne donne aucun identifiant utilisable. La persistance évite aussi que le connecteur casse à chaque docker compose up.

Mise en route

Dans .env :

MCP_PUBLIC_URL=https://ed.ton-domaine.fr/mcp
MCP_OAUTH_PASSPHRASE=<une phrase longue>
MCP_ALLOWED_HOSTS=ed.ton-domaine.fr
READ_ONLY=true

Si NPM tourne en conteneur, aucun port n'est publié sur l'hôte : le proxy joint le service par son nom sur un réseau Docker partagé.

docker compose -f docker-compose.yml -f docker-compose.npm.yml up -d

avec NPM_NETWORK réglé sur le réseau de NPM (docker network ls), et dans NPM : Scheme http, Forward Hostname ecoledirecte-mcp, Forward Port 8787. Si NPM tourne sur l'hôte, garde docker-compose.yml seul avec PUBLISH_ADDRESS=127.0.0.1.

Pour servir les deux à la fois — tailnet avec le jeton fixe pour tes machines, et connecteur Claude.ai public via NPM en conteneur — docker-compose.npm-and-tailnet.yml garde le port publié sur PUBLISH_ADDRESS (l'IP Tailscale) et rejoint en plus le réseau de NPM. Mettre dans .env :

COMPOSE_FILE=docker-compose.yml:docker-compose.npm-and-tailnet.yml
MCP_ALLOWED_HOSTS=<ip-tailscale>:<port>,ed.ton-domaine.fr

MCP_HTTP_PORT ne règle que le port côté hôte ; dans le conteneur, le serveur écoute toujours sur 8787, qui est donc le Forward Port à donner à NPM.

Ensuite, dans Claude.ai : Paramètres → Connecteurs → connecteur personnalisé, URL https://ed.ton-domaine.fr/mcp. Claude découvre le serveur d'autorisation, s'enregistre, et t'affiche l'écran de consentement où tu saisis la phrase secrète.

Statut

stdio (local), HTTP sur tailnet, et HTTP public avec OAuth pour un connecteur Claude.ai sont faits. Un outil d'envoi de messages reste volontairement non implémenté.

La messagerie est en lecture seule : lister et lire. Envoyer, répondre et transférer ne sont pas implémentés — ce sont des écritures visibles par des tiers (professeurs, administration), à n'ajouter que délibérément.

Développement

npm test           # tests unitaires — aucun appel réseau réel
npm run typecheck  # vérifie aussi test/ et scripts/
npm run build
npm run smoke-test # vérification manuelle contre le vrai compte

smoke-test utilise la session déjà enregistrée par login, n'a besoin d'aucun identifiant, et n'est jamais lancé en CI. Il appelle chaque outil de lecture à la suite et continue même si l'un échoue, pour montrer d'un coup l'état réel de tous les endpoints.