Ara — audits d'accessibilité RGAA

Ara MCP Server — Audits RGAA via IA

Serveur MCP (Model Context Protocol) qui expose les opérations CRUD sur les audits d'accessibilité RGAA de la plateforme Ara. Permet de piloter un audit Ara entièrement depuis Claude Code, Codex ou tout client MCP compatible — sans login manuel dans le navigateur.

Projet communautaire, non officiel. Ce serveur est un client tiers de l'API d'Ara, le service d'audit d'accessibilité de la DINUM. Il n'est ni édité ni maintenu par la DINUM.

English — An MCP server for Ara, the French government platform for RGAA 4.1 accessibility audits. It exposes 17 tools to create, fill in, publish and export accessibility audits from any MCP client. Requires an account on ara.numerique.gouv.fr. Documentation is in French, matching the audience of the RGAA. Unofficial community project.

Installation

1. Se connecter, une fois :

npx ara-rgaa-mcp login

Une page s'ouvre dans votre navigateur, sur votre propre ordinateur. Vous y saisissez vos identifiants Ara ; le jeton est enregistré dans ~/.config/ara-rgaa-mcp/credentials.json, en permissions 600. Votre mot de passe n'est jamais enregistré.

2. Déclarer le serveur — sans aucun secret dans la configuration :

{

"mcpServers": { "ara-rgaa": { "command": "npx", "args": ["-y", "ara-rgaa-mcp"] } } }

Prérequis : Node.js ≥ 18 et un compte sur ara.numerique.gouv.fr.

Pour Claude Code, le fichier est ~/.claude/claude_desktop_config.json. Pour Codex ou Cursor, même format dans leurs réglages MCP respectifs.

Le renouvellement est automatique. Les jetons d'Ara durent 24 h, mais le serveur en demande un neuf à chaque démarrage : un usage régulier ne redemande jamais de se connecter. Après plus de 24 h sans usage, le serveur vous dit de relancer login.

Sécurité de la page de connexion

Une page locale qui réclame des identifiants ressemble à du hameçonnage : le serveur prend donc quatre précautions.

• Il écoute uniquement sur `127.0.0.1`, jamais sur une interface réseau.
• L'URL comporte un jeton aléatoire qu'une autre page locale ne peut pas deviner ; toute autre adresse renvoie 404.
• Elle est à usage unique : le serveur s'arrête dès la connexion réussie.
• L'URL exacte est affichée dans le terminal — comparez-la à celle du navigateur avant de saisir quoi que ce soit.

Votre mot de passe ne transite que du navigateur vers ce processus local, puis vers ara.numerique.gouv.fr. Il n'est écrit nulle part.

Si vous n'avez pas lancé la commande vous-même, fermez la page.

Authentification par variables d'environnement

Alternative à login, pour l'automatisation ou les environnements sans navigateur.

Les identifiants ne sont jamais acceptés en paramètres d'outil. Un paramètre d'outil transite par le contexte du modèle et se retrouve conservé dans les transcripts de conversation. Ils sont donc lus uniquement depuis l'environnement du processus ou depuis le fichier écrit par login.

⚠️ `ARA_AUTH_TOKEN` expire au bout de 24 heures. Les jetons d'Ara sont signés avec expiresIn: "24h" : un jeton collé à la main cesse de fonctionner le lendemain. Ne l'utilisez que pour une intégration automatisée qui sait le renouveler. Pour un usage quotidien, préférez login ci-dessus, ou à défaut ARA_USERNAME / ARA_PASSWORD — qui suppose en revanche d'écrire un mot de passe en clair dans un fichier de configuration.

L'outil auth_refresh rejoue l'authentification en cours de session, si un jeton a expiré.

Outils

Chaque outil porte des annotations (readOnlyHint, destructiveHint, idempotentHint) qui permettent à votre client MCP de demander confirmation avant les opérations sensibles.

Retest après correctifs

Le cycle conseillé : audit initial, correctifs, copie de l'audit, retest des critères touchés, déclaration depuis la copie.

• `duplicate_audit` recopie la fiche. La duplication d'Ara laisse vides le demandeur, l'organisation de l'auditeur, l'URL, le contact, les technologies et les outils (vérifié sur l'API). Le serveur les reprend de la source, en gardant les pages dans l'ordre de la source. Passer copyMetadata: false pour s'en tenir à la copie d'Ara. Si cette seconde étape échoue, la copie existe quand même : ses identifiants sont renvoyés avec un avertissement.
• `update_audit` renumérote les pages dans l'ordre du tableau envoyé. Renvoyer les pages triées par order (celui de get_audit), sinon l'échantillon est réordonné dans le rapport.
• `compare_audits` confronte l'audit initial et sa copie. Les pages sont appariées par nom et URL. Il renvoie le taux de chaque audit calculé selon la règle d'Ara (non conforme sur une page = non conforme ; conforme sur au moins une page et non conforme nulle part = conforme ; taux = conformes / applicables), les critères dont le statut a changé et les transitions page par page (NC→C, C→NC…).

Envoi des résultats par paquets

update_audit_results envoie les résultats à Ara par paquets de 20 (batchSize, de 1 à 100). Ara répond parfois 500 à un paquet dont chaque résultat passe seul (constaté sur des paquets de 23 à 36 résultats des thématiques 10 et 12). Le serveur coupe alors le paquet en deux, jusqu'au résultat isolé :

• les résultats acceptés sont enregistrés ;
• ceux qu'Ara refuse même seuls sont listés dans echecs ;
• une erreur 4xx arrête l'envoi et indique combien de résultats étaient déjà enregistrés.

Chaque envoi remplace l'évaluation visée : renvoyer un paquet est sans effet de bord.

Le référentiel RGAA embarqué

Le serveur embarque le référentiel RGAA 4.1 complet — 13 thématiques, 106 critères, et les tests de chacun. Sans lui, un agent ne manipule que des numéros (topic: 6, criterium: 1) sans savoir ce qu'il évalue.

list_rgaa_criteria(auditType: "FAST")   → les 25 critères de l'audit rapide (~5 Ko)

get_rgaa_criterion(topic: 6, criterium: 1) → « Chaque lien est-il explicite (hors cas particuliers) ? » + ses 5 tests (~2 Ko)

Le geste attendu pendant un audit : get_rgaa_criterion pour lire le critère et ses tests, puis update_audit_results pour poser le verdict. Juger plutôt que deviner.

Les données proviennent de rgaa.json du projet Ara, publié par la DINUM sous [Licence Ouverte 2.0](https://github.com/DISIC/Ara/blob/main/LICENCES.md). Elles sont embarquées dans le paquet — le serveur fonctionne donc hors ligne, sans appel réseau pour la partie référentiel. Régénération : node scripts/build-rgaa-data.mjs.

À noter : les types d'audit FAST et COMPLEMENTARY couvrent 25 critères chacun et sont disjoints ; c'est la méthodologie complète (rapide + complémentaire) qui en couvre 50.

Le code source ne suffit pas

Sur les 106 critères du RGAA, 40 seulement se tranchent en lisant le HTML — et 6 sur les 25 d'un audit rapide. Les autres exigent la page rendue, une navigation clavier réelle, l'arbre d'accessibilité, ou un jugement éditorial.

C'est le piège de l'audit assisté par IA : un agent lit du balisage, y trouve des réponses plausibles, et remplit un audit qui ne repose sur rien. Trois mécanismes s'y opposent.

`get_audit_method(auditType)` — le plan de travail avant de commencer : quels critères relèvent du source, du rendu, du clavier, de la restitution, du jugement.

`get_rgaa_criterion` joint à chaque critère un bloc verification : sourceSuffit, les besoins, et comment s'y prendre.

`update_audit_results` refuse un verdict non fondé. Déclarer CONFORME ou NON CONFORME sur un critère qui exige davantage, sans renseigner le champ evidence correspondant, produit une erreur explicite :

Verdict refusé sur 1 critère(s) : le code source ne suffit pas à les trancher,

et la vérification correspondante n'a pas été déclarée.

10.7 — exige : clavier (…) ; rendu (…)

Effectuez réellement ces vérifications, puis renseignez le champ "evidence". Si vous ne pouvez pas les faire, utilisez le statut NOT_TESTED plutôt qu'un verdict non fondé.

NOT_TESTED et NOT_APPLICABLE en sont dispensés : ils n'affirment rien. Et evidence reste déclaratif — un agent peut mentir, mais plus par omission.

Cette classification est une guidance de ce serveur, déduite du vocabulaire des tests puis corrigée à la main. Le RGAA dit quoi vérifier, pas avec quel outil.

⚠️ Publier est irréversible

Ara n'offre aucune dépublication, et supprimer un audit ne retire pas son rapport publié :

Le rapport devient alors inaccessible depuis l'interface d'Ara : vous ne pouvez plus ni le consulter, ni le corriger, ni le retirer. Seul votre nom d'auditeur disparaît du rapport public ; le contenu de l'audit demeure.

Deux conséquences pratiques :

• ne traitez jamais la suppression comme un moyen d'annuler une publication ;
• publier un audit portant sur un site tiers met en ligne une déclaration d'accessibilité le concernant, signée de vous — assurez-vous d'en avoir le mandat.

Citer du HTML dans un commentaire

Ara affiche les commentaires de critère en texte riche : un écrit tel quel est interprété comme une balise et disparaît du commentaire rendu — l'API répond 200, le constat perd sa substance, et rien ne le signale.

Depuis la 2.2.1, update_audit_results **éc