agoraplus-saintmaur-mcp

Serveur MCP stdio en lecture seule pour le portail famille Agora Plus de Saint-Maur-des-Fossés.

Le serveur lance un navigateur Chromium Playwright avec un profil persistant, se connecte automatiquement avec les identifiants présents dans .env, puis expose les lectures observées du portail via des outils MCP. Il n'implémente aucune réservation, annulation, paiement, suppression ou modification dans Agora Plus.

État du projet : prototype fonctionnel pour l'authentification automatique et la lecture des inscriptions. Les routes internes d'Agora Plus ne sont pas une API publique et peuvent changer sans préavis.

Fonctionnalités

• authentification automatique depuis AGORAPLUS_USERNAME et AGORAPLUS_PASSWORD ;

• attente et détection robustes du formulaire de connexion ;

• profil Chromium persistant et privé ;

• repli manuel noVNC si le portail demande une étape interactive, un CAPTCHA ou un MFA ;

• vérification de session sans retourner de cookies ni de secrets ;

• capture limitée à l'endpoint de lecture des inscriptions périscolaires ;

• lecture de la réponse obtenue par le navigateur, avec ses en-têtes et sa session authentifiée ;

• calendrier local et synthèse hebdomadaire calculés à partir des données lues ;

• transport MCP stdio, utilisable localement ou dans Docker ;

• conteneur Docker non privilégié, avec Xvfb et noVNC intégrés.

Related MCP server: mcp-datagouv

Prérequis

Installation Docker — recommandée

• Docker Engine et Docker Compose v2 ;

• accès de l'utilisateur au daemon Docker, ou utilisation d'un mécanisme équivalent autorisé par l'administrateur ;

• un compte Agora Plus actif ;

• un mot de passe VNC distinct si noVNC est publié.

Installation locale

• Python 3.11 ou plus récent ;

• dépendances Python du projet ;

• Chromium Playwright ;

• un affichage X si AGORAPLUS_HEADLESS=false.

Docker est recommandé car il fournit automatiquement Xvfb, x11vnc, websockify, Chromium et noVNC.

Installation Docker

Clonez le dépôt puis entrez dans son répertoire :

git clone https://github.com/ghis94/agoraplus-saintmaur-mcp.git
cd agoraplus-saintmaur-mcp

Copiez le modèle de configuration :

cp .env.example .env
chmod 600 .env

Éditez ensuite .env et renseignez au minimum :

AGORAPLUS_USERNAME=votre-adresse-email
AGORAPLUS_PASSWORD=votre-mot-de-passe
VNC_PASSWORD=un-secret-vnc-long-et-different

Construisez l'image :

docker compose build

Lancez le serveur MCP :

docker compose run --rm --service-ports mcp

Le processus reste attaché à stdin/stdout pour le protocole MCP. Il ne faut pas écrire de messages de diagnostic sur stdout, car cela corromprait le transport MCP.

Configuration des credentials

Les credentials sont lus uniquement depuis le fichier local .env.

Variables disponibles :

Règles de sécurité

• ne commitez jamais .env ;

• ne transmettez jamais .env à un client MCP ; Docker l'injecte localement ;

• ne mettez jamais les credentials dans les arguments d'un outil MCP ;

• ne publiez pas noVNC sur Internet ;

• utilisez NOVNC_BIND=127.0.0.1 par défaut ;

• si un accès LAN temporaire est nécessaire, utilisez uniquement une adresse IP privée et un mot de passe VNC distinct ;

• traitez le volume du profil Chromium comme un secret : il contient les cookies et la session persistante.

Utilisation avec Hermes Agent

Le dépôt fournit un lanceur adapté à Hermes :

scripts/run-agora-docker.sh

Sur l'hôte prévu, ce lanceur publie noVNC sur 192.168.1.182:6081 afin de ne pas entrer en conflit avec le navigateur Camofox qui utilise déjà le port 6080. Adaptez l'adresse dans le script si vous déployez le projet ailleurs.

Exemple de serveur MCP stdio :

mcp_servers:
  agora:
    command: /chemin/absolu/agoraplus-saintmaur-mcp/scripts/run-agora-docker.sh

Après toute modification de la configuration MCP ou de l'image Docker, ouvrez une nouvelle session Hermes : une session existante peut conserver l'ancien processus MCP.

Vérification de la configuration Hermes :

hermes mcp list
hermes mcp test agora

hermes mcp test vérifie le lancement et la découverte MCP. Il ne suffit pas à prouver que le navigateur est authentifié : il faut appeler start_login, puis connection_status et un outil de lecture réel.

Utilisation avec un autre client MCP

Exemple générique :

{
  "command": "docker",
  "args": [
    "compose",
    "-f",
    "/chemin/absolu/agoraplus-saintmaur-mcp/docker-compose.yml",
    "run",
    "--rm",
    "--service-ports",
    "mcp"
  ]
}

Pour une installation locale, le point d'entrée Python est :

agoraplus-saintmaur-mcp

Première connexion automatique

Avec les credentials correctement renseignés :

1. le client MCP appelle start_login ;

2. Chromium ouvre l'URL applicative ;

3. le serveur détecte les champs e-mail et mot de passe ;

4. les credentials sont remplis localement ;

5. le formulaire est soumis ;

6. le serveur attend une preuve de session authentifiée ;

7. le portail charge ses données de lecture ;

8. le serveur capture uniquement la requête et la réponse de l'endpoint d'inscriptions autorisé.

Le retour de start_login ne contient pas le mot de passe, les cookies ou les headers de session. Les indicateurs utiles sont notamment :

• automatic_login ;

• authenticated ;

• browser_running ;

• inscriptions_payload_observed ;

• url.

Repli manuel avec noVNC

Le repli manuel reste disponible si le formulaire change ou si le portail exige une action interactive.

1. démarrez le serveur MCP ;

2. appelez start_login ;

3. ouvrez noVNC : http://127.0.0.1:6080/vnc.html ;

4. utilisez le mot de passe VNC_PASSWORD ;

5. terminez vous-même le MFA, CAPTCHA ou formulaire ;

6. appelez connection_status ;

7. ouvrez la page des inscriptions dans Chromium.

Le mot de passe VNC n'est pas le mot de passe Agora Plus et ne doit jamais être envoyé dans une conversation.

Outils MCP exposés

Tous les outils sont en lecture seule :

• portal_info : métadonnées et portée du serveur ;

• initial_config : configuration publique du portail ;

• start_login : lance Chromium et tente la connexion automatique ;

• connection_status : état navigateur/session sans secrets ;

• session_status : alias de compatibilité ;

• inscriptions : lecture de la réponse des inscriptions ;

• peri_inscriptions : alias de compatibilité ;

• reservations_calendar : vue locale filtrée par dates ;

• weekly_summary : synthèse locale du lundi au dimanche.

Les outils ne réalisent aucune réservation, annulation, paiement ou écriture.

Installation locale sans Docker

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[test]'
python -m playwright install chromium
cp .env.example .env
chmod 600 .env
agoraplus-saintmaur-mcp

Avec AGORAPLUS_HEADLESS=false, un serveur X est nécessaire. Pour un serveur sans interface, utilisez AGORAPLUS_HEADLESS=true et un profil de navigateur accessible par l'utilisateur courant.

Validation et tests

Depuis le dépôt :

python -m pytest
python -m compileall -q src tests
bash -n scripts/run-agora-docker.sh
docker compose config
docker compose build

La validation runtime doit également vérifier le chemin complet :

.env → Docker Compose → MCP stdio → Playwright → Chromium → Agora Plus

Une simple réussite de tools/list ne prouve pas que le login ou la lecture métier fonctionnent.

Dépannage

automatic_login=not_configured

Une des deux variables suivantes est absente ou vide :

• AGORAPLUS_USERNAME

• AGORAPLUS_PASSWORD

Vérifiez uniquement leur présence, sans afficher leur valeur.

automatic_login=manual_required

Le formulaire Agora Plus a probablement changé ou demande une étape interactive. Utilisez noVNC et ne modifiez pas les sélecteurs à l'aveugle.

Session authentifiée mais aucune inscription

Ouvrez la rubrique des inscriptions dans le navigateur. L'API interne est chargée par le portail et son payload dépend de la version du site.

AuthenticationFailedException: No headers provided

Ne rejouez pas l'endpoint avec une requête HTTP indépendante. La session Agora dépend des headers et cookies du navigateur. Le serveur doit lire la réponse observée par Playwright, ce que fait l'implémentation actuelle.

Profil Chromium verrouillé

Une seule instance doit utiliser un profil donné. Ne lancez pas simultanément hermes mcp test, un serveur MCP persistant et une session manuelle avec le même profil. Utilisez un autre profil temporaire pour un probe isolé.

Conflit de port noVNC

Vérifiez le propriétaire du port avant de modifier quoi que ce soit :

docker ps --format '{{.Names}}\t{{.Ports}}' | grep -E '6080|6081'

Utilisez un autre NOVNC_PORT plutôt que d'arrêter un navigateur existant.

Limites et périmètre

• l'API Agora Plus est interne et non documentée publiquement ;

• la structure de ses réponses et ses sélecteurs peuvent changer ;

• les données familiales restent locales et ne doivent pas être publiées ;

• le projet reste strictement en lecture seule ;

• aucune synchronisation Google Calendar n'est implémentée dans ce dépôt ;

• aucune écriture Agora Plus ne doit être ajoutée sans analyse séparée et confirmation explicite.

Licence et confidentialité

Ce projet manipule une session authentifiée d'un portail familial. Conservez le fichier .env, le volume Chromium, les logs et les captures dans un emplacement privé. Ne publiez pas de données d'enfants, d'horaires familiaux, de cookies ou de réponses brutes Agora Plus.