Skip to main content
Glama
ghis94

agoraplus-saintmaur-mcp

by ghis94
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Agora Plus Saint-Maur MCP

Serveur MCP local et non officiel pour consulter le portail familial Agora Plus de Saint-Maur-des-Fossés et encadrer les réservations ou annulations par une confirmation explicite.

Python 3.11+ MCP Licence MIT

Projet expérimental. Il dépend d'endpoints internes d'Agora Plus, susceptibles de changer sans préavis. Ce dépôt n'est affilié ni à Agora Plus ni à la ville de Saint-Maur-des-Fossés.

À quoi sert ce projet ?

Une fois connecté à un client MCP compatible, vous pouvez demander à votre assistant de :

  • ouvrir une session Agora Plus et vérifier son état ;

  • consulter les inscriptions périscolaires ;

  • lire les réservations et les créneaux disponibles sur une période ;

  • produire une vue calendrier ou un résumé hebdomadaire ;

  • préparer puis, après confirmation, exécuter une réservation ou une annulation.

Le projet ne gère ni paiement, ni compte utilisateur, ni synchronisation Google Calendar.

Related MCP server: mcp-data-issy

Principes de sécurité

Les consultations n'écrivent rien sur le portail. Une réservation ou une annulation suit obligatoirement ce parcours :

  1. lecture d'un créneau réellement observé dans Agora Plus ;

  2. génération d'un aperçu exact, sans écriture ;

  3. émission d'une empreinte et d'un jeton valable cinq minutes, à usage unique ;

  4. confirmation explicite transmise par le client MCP ;

  5. nouvelle lecture du créneau, revalidation de son identité et de son tarif, puis écriture.

Une action peut être facturée ou soumise à pénalité. Vérifiez toujours l'enfant, la date, l'activité, le créneau et le tarif avant de confirmer.

Les identifiants et cookies restent locaux. Aucun outil MCP n'accepte de mot de passe en argument et le fichier .env ne doit jamais être versionné.

Voir la documentation de sécurité pour les garanties et les limites résiduelles.

Prérequis

Pour la méthode Docker recommandée :

  • Docker avec le plugin Compose ;

  • un compte valide sur le portail Agora Plus de Saint-Maur-des-Fossés ;

  • un client compatible MCP en transport stdio, par exemple Hermes Agent.

Pour une installation sans Docker : Python 3.11 ou plus récent est requis.

Démarrage rapide avec Docker

1. Récupérer le projet

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

2. Configurer la connexion

cp .env.example .env
chmod 600 .env

Renseignez ensuite ces variables dans .env :

AGORAPLUS_USERNAME=votre-identifiant
AGORAPLUS_PASSWORD=votre-mot-de-passe

3. Construire l'image

docker compose build

Le service MCP se lance avec :

docker compose run --rm -T mcp

Cette commande attend normalement qu'un client MCP communique avec elle sur stdin/stdout ; l'absence d'interface interactive dans le terminal est donc normale.

4. Connecter Hermes Agent

Le script scripts/run-agora-docker.sh fournit une commande stdio silencieuse adaptée à Hermes. Il retrouve automatiquement le fichier Compose à partir de son propre emplacement ; le dépôt peut donc être installé où vous le souhaitez.

hermes mcp add agora \
  --command /chemin/absolu/agoraplus-saintmaur-mcp/scripts/run-agora-docker.sh
hermes mcp test agora

Une nouvelle session Hermes peut être nécessaire après l'ajout ou la modification d'un serveur MCP.

5. Vérifier la première connexion

Demandez d'abord au client d'appeler :

  1. start_login ;

  2. connection_status ;

  3. calendar_slots sur une courte période.

Une découverte réussie des outils ne prouve pas que l'authentification fonctionne. L'état attendu après connexion contient authenticated: true et browser_running: true.

Exemples d'utilisation

  • « Montre-moi les créneaux Agora Plus du 14 au 18 septembre. »

  • « Résume les réservations de la semaine prochaine. »

  • « Prépare la réservation de ce créneau, sans l'exécuter. »

Pour une action d'écriture, le client doit afficher l'aperçu puis demander une confirmation séparée. N'appelez pas directement l'outil d'exécution avec confirmed=true sans validation humaine.

Outils MCP disponibles

Session et informations

  • portal_info — décrit le portail, le mode de sécurité et la surface d'outils ;

  • initial_config — lit la configuration publique du portail ;

  • start_login — ouvre Chromium et tente la connexion automatique ;

  • connection_status — indique si le navigateur et la session sont utilisables ;

  • session_status — alias de compatibilité de connection_status.

Consultations

  • inscriptions — lit les inscriptions périscolaires observées ;

  • peri_inscriptions — alias de compatibilité de inscriptions ;

  • calendar_slots — lit les créneaux disponibles et sélectionnés sur une période ;

  • reservations_calendar — construit une vue datée à partir des inscriptions ;

  • weekly_summary — résume une semaine à partir des inscriptions.

Actions protégées

  • agora_reservation_preview — prépare une réservation et retourne son aperçu ;

  • agora_cancellation_preview — prépare une annulation et retourne son aperçu ;

  • agora_actions_available — indique si les routes d'écriture sont disponibles ;

  • agora_action_execute — exécute uniquement l'action correspondant au jeton confirmé.

Le serveur expose actuellement 14 outils.

Configuration

Variables nécessaires à la connexion automatique :

  • AGORAPLUS_USERNAME ;

  • AGORAPLUS_PASSWORD.

Variables optionnelles :

  • AGORAPLUS_HEADLESS — lance Chromium sans interface visible ; Compose force true par défaut ;

  • AGORAPLUS_BROWSER_PROFILE — chemin du profil Chromium ;

  • AGORAPLUS_TIMEOUT — délai d'attente du navigateur en secondes, 20 par défaut ;

  • AGORAPLUS_PORTAL_URL — URL du portail, à modifier uniquement pour une instance compatible vérifiée ;

  • VNC_PASSWORD — active le serveur noVNC du conteneur lorsqu'elle est définie.

Dans le service Compose, le profil Chromium se trouve dans le /tmp privé du conteneur et n'est pas conservé après son arrêt. La connexion automatique est donc recréée à chaque nouveau processus MCP.

MFA, CAPTCHA et noVNC

Le mode headless suffit tant que la connexion automatique aboutit. Pour une intervention manuelle, définissez VNC_PASSWORD dans .env, puis remplacez explicitement la valeur Compose de AGORAPLUS_HEADLESS et publiez noVNC uniquement sur la boucle locale :

docker compose run --rm -T \
  -e AGORAPLUS_HEADLESS=false \
  -p 127.0.0.1:6080:6080 \
  mcp

Ouvrez ensuite http://127.0.0.1:6080/vnc.html. N'exposez jamais ce port directement sur Internet.

La procédure détaillée figure dans docs/DEPLOYMENT.md.

Installation locale sans Docker

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

En installation locale, AGORAPLUS_HEADLESS vaut false par défaut si la variable est absente.

Développement et vérification

Après avoir installé les dépendances de test :

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

Le dépôt contient aussi un lanceur d'audit hors ligne qui bloque le réseau, les sous-processus et les suppressions pendant les tests. Depuis l'environnement virtuel du projet :

env -i PATH=/usr/bin:/bin HOME="$PWD/temp" PYTHONDONTWRITEBYTECODE=1 \
  "$VIRTUAL_ENV/bin/python" tests/run_offline.py

Ce garde-fou n'est pas une sandbox système. Il ignore volontairement un test qui supprime de vrais verrous Chromium obsolètes.

Pour vérifier uniquement la structure Compose sans lire .env :

env -i PATH=/usr/bin:/bin HOME="$PWD/temp" COMPOSE_DISABLE_ENV_FILE=1 \
  docker compose --env-file /dev/null -f docker-compose.yml \
  config --no-env-resolution --services

La sortie attendue est mcp.

Limites connues

  • Les endpoints utilisés sont internes et peuvent évoluer avec le portail.

  • Le code cible l'instance Saint-Maur-des-Fossés ; les autres collectivités ne sont pas garanties compatibles.

  • Les tests automatisés utilisent des données fictives et ne valident pas le compte d'un nouvel utilisateur.

  • Un résultat d'écriture peut devenir indéterminé si la connexion coupe après l'envoi. Dans ce cas, relisez l'état avant toute nouvelle tentative.

  • Certaines erreurs techniques peuvent contenir une URL interne ; ne les publiez pas sans vérification.

  • Une réponse d'inscriptions peut rester en mémoire pendant la session pour le payload observé ; relancez la session pour forcer une nouvelle capture.

  • Le serveur ne peut pas prouver qu'un humain est à l'origine de confirmed=true : cette garantie dépend aussi du client MCP.

Structure du dépôt

src/agoraplus_saintmaur_mcp/  serveur MCP, navigateur et workflows protégés
tests/                        tests unitaires et contrats publics
docker/                       point d'entrée du conteneur
docs/                         déploiement, sécurité et feuille de route
scripts/                      lanceur Docker stdio pour Hermes

Licence

Distribué sous licence MIT.

Available Tools

5 tools
initial_configB

Read the public/portal configuration without exposing credentials.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full transparency burden. It does disclose that the operation is a read and that credentials are not exposed, which is a useful safety trait. However, it omits details such as return format, error behavior, or whether any session/context is required, leaving some ambiguity about side effects and limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that directly states the tool's function and a key safety property. Every word earns its place, with no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no params, no output schema), the description covers the core function but not the broader context. It lacks usage guidance, differentiation from 'portal_info', and any indication of what the configuration contains or how it might be used. This is sufficient for a trivial read but leaves room for improvement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema is trivially complete. The description does not need to add parameter details. The baseline for zero-parameter tools is 4, and the description provides no conflicting information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Read the public/portal configuration', which identifies a specific verb and resource. The addition of 'without exposing credentials' adds a safety constraint. However, it does not explicitly differentiate from the sibling tool 'portal_info', which may perform a similar read operation, so it lacks sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description does not mention any prerequisites, exclusions, or alternative tools. An agent is left to guess when this tool is appropriate, especially given the overlapping 'portal_info' sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

peri_inscriptionsA

Read current peri-school inscriptions through the authenticated browser session.

No reservation or cancellation is made. The payload format is portal-version dependent and must be captured from an authenticated session.

ParametersJSON Schema
NameRequiredDescriptionDefault
payloadYes

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses that no reservation or cancellation is made, confirming read-only behavior. It also warns that the payload format is portal-version dependent and must be captured from an authenticated session, adding important behavioral context beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the purpose, each sentence adds distinct information: purpose, non-mutation, payload dependency. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and annotations, the description covers the read-only nature and payload requirement but omits details about response format or potential error conditions. It is adequate for a simple read tool but not fully comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single 'payload' parameter has no schema descriptions (0% coverage). The description adds that the payload format is portal-version dependent and must be captured from an authenticated session, providing some origin and dependency context, but it does not specify internal structure or required fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'Read current peri-school inscriptions through the authenticated browser session,' using a specific verb (Read) and resource (peri-school inscriptions). It distinguishes from siblings by emphasizing read-only and the authenticated session context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage requires an authenticated session ('through the authenticated browser session') but does not explicitly compare to alternatives or state when not to use. No exclusions are mentioned, so guidance is only implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

portal_infoA

Return non-sensitive portal metadata and the supported read-only scope.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden for behavioral disclosure. It states that the tool returns 'non-sensitive' data and is 'read-only,' which conveys safety and side-effect-free behavior. However, it does not disclose authentication requirements, error behavior, or what happens on failure. For a simple tool, this is adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that directly states the action and scope. Every word earns its place, with no unnecessary filler. It is appropriately sized for a zero-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters, an output schema is present, and the description states the purpose and the read-only nature, the description is largely complete. It could mention more about the 'supported read-only scope' or when to use it relative to siblings, but for a simple metadata tool, it is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is trivially 100%. The rubric assigns a baseline of 4 for zero parameters. The description adds no parameter information, but none is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'Return non-sensitive portal metadata and the supported read-only scope.' This identifies a specific verb (Return), resource (portal metadata), and scope (read-only), which distinguishes it from sibling tools like initial_config, start_login, and session_status. The qualifier 'non-sensitive' adds precision.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: when you need portal metadata and supported read-only scope, this is the tool. However, it does not explicitly state when to use it over alternatives or mention any exclusions. Sibling tools exist, but no differentiation guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_statusA

Report whether the persistent browser session appears authenticated.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only says 'appears authenticated' without clarifying whether the tool makes a network request, has side effects, or what actions it takes if the session is not authenticated. This is insufficient for a tool that may interact with a live browser session.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is entirely on topic. It is concise, front-loaded, and contains no verbose or redundant phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters) and the presence of an output schema, the description covers the essential purpose. However, it does not provide usage context (e.g., preconditions or relationship to start_login), which is a minor gap for a session-status check.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the input schema is empty. With no parameters to explain, the baseline score is 4, and the description does not need to add parameter-level detail. No gap exists here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to report whether the persistent browser session appears authenticated. The verb 'Report' and specific outcome 'appears authenticated' distinguish it from siblings like start_login or portal_info, making its role unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage in scenarios where checking authentication status is needed (e.g., before deciding to log in), but it does not explicitly state when to use this tool versus alternatives like start_login or portal_info. No 'when not to use' guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_loginA

Open a persistent Chromium profile for a manual Agora Plus login.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the full burden of behavioral disclosure. It mentions the profile is 'persistent,' implying statefulness, but does not explain critical behaviors: whether it blocks on user interaction, what side effects occur (e.g., creating a profile, storing cookies), or what the call returns. This leaves significant behavioral uncertainty.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the verb and purpose. It contains no redundant or filler words, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the description clearly states the action, it omits crucial context such as the return value (despite an output schema existing), whether the call requires user interaction or waits, and how it fits into the broader login workflow with sibling tools. For a stateful, manual login process, this leaves too much unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is trivially 100%. The description does not need to explain parameters, and the baseline for 0 params is 4. It adds no param-specific detail, but none is necessary.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description is specific and action-oriented: 'Open a persistent Chromium profile' clearly states the action, and 'for a manual Agora Plus login' specifies the purpose. This differentiates it from sibling tools like portal_info or session_status, which likely inspect or query rather than initiate a login.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear context for use: it is for performing a manual Agora Plus login. However, it does not explicitly state when to use this tool versus alternatives (e.g., checking session_status first) or mention any prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.1.0
    • First observedinitial_config
    • First observedperi_inscriptions
    • First observedportal_info
    • First observedsession_status
    • First observedstart_login
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a distinct purpose: portal_info and initial_config expose metadata/config, start_login and session_status handle authentication, and peri_inscriptions reads data. There is no overlap or ambiguity between them.

Naming Consistency3/5

Names are readable and snake_case, but they mix noun phrases (portal_info, initial_config) with verb-led commands (start_login) and state descriptors (session_status). This is a mild inconsistency, though still predictable due to the small set.

Tool Count5/5

With 5 tools, the server is well-scoped around portal metadata, configuration, authentication, and data reading. This is an appropriate size for a focused MCP server.

Completeness4/5

The surface covers the full read-only workflow: config, login, session check, and data retrieval. Minor gaps exist, such as a logout tool or explicit session refresh, but these are not blocking for the stated read-only scope.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-data-issy

    pipeworx-io
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for querying and exploring Issy-les-Moulineaux open data datasets (city services, mobility, environment) via OpenDataSoft API.
    3 npm
    MIT

  • bluemind-mcp

    AlexMili
    A
    license
    A
    quality
    C
    maintenance
    Read-only MCP server to search and read emails and calendar events from a BlueMind account via the BlueMind REST API.
    7
    MIT

  • kanpla-mcp

    diarmind
    A
    license
    B
    quality
    C
    maintenance
    Unofficial read-only MCP server to log into Kanpla and read canteen menus using your account credentials.
    3
    2 npm
    MIT