Ara — audits d'accessibilité RGAA

Ara MCP 服务 — 使用 AI 审核 RGAA

MCP（Model Context Protocol）服务，提供对 Ara 平台无障碍审核的增删改查操作。可通过 Claude Code、Codex 或任何兼容的 MCP 客户端，完全操控 Ara 审核，无需在浏览器中手动登录。

社区项目，非官方。 本服务是 Ara API 的第三方客户端。Ara 是 DINUM 的无障碍审核服务。本项目并非由 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.

安装

1. 登录一次：

npx ara-rgaa-mcp login

浏览器会在您自己的电脑上打开一个页面。请在页面中输入您的 Ara 登录凭据；令牌会以 600 权限保存至 ~/.config/ara-rgaa-mcp/credentials.json。您的密码绝不会被保存。

2. 声明服务——配置中无需包含任何机密信息：

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

前置条件：Node.js ≥ 18，且拥有 ara.numerique.gouv.fr 账户。

对于 Claude Code，配置文件为 ~/.claude/claude_desktop_config.json。对于 Codex 或 Cursor，请在各自的 MCP 设置中使用相同格式。

令牌会自动续期。 Ara 令牌有效期为 24 小时，但服务每次启动时都会申请新令牌：经常使用时，无需再次登录。超过 24 小时未使用后，服务会提示您重新运行 login。

命令
npx ara-rgaa-mcp login	登录并保存令牌
npx ara-rgaa-mcp status	账户、实例、令牌时长
npx ara-rgaa-mcp logout	删除已保存的令牌

登录页面的安全性

要求输入登录凭据的本地页面看起来像钓鱼页面，因此本服务采取了四项预防措施。

• 仅监听 127.0.0.1，绝不监听网络接口。
• URL 中包含随机令牌，其他本地页面无法猜到；访问任何其他地址都会返回 404。
• 页面仅供使用一次：登录成功后，服务会立即停止。
• 终端会显示确切的 URL——输入任何信息前，请先确认它与浏览器中的 URL 一致。

您的密码只会从浏览器传输到本地进程，然后传输到 ara.numerique.gouv.fr，不会写入任何地方。

如果您没有亲自运行该命令，请关闭页面。

## 通过环境变量进行身份验证

login 的替代方式，适用于自动化或没有浏览器的环境。

变量	默认值	说明
ARA_AUTH_TOKEN	—	JWT 令牌。⚠️ 仅有效 24 h
ARA_USERNAME	—	电子邮件，用于启动时进行身份验证
ARA_PASSWORD	—	密码，用于启动时进行身份验证
ARA_BASE_URL	https://ara.numerique.gouv.fr/api	Ara API 的基础 URL

工具参数中绝不接受凭据。 工具参数会经过模型上下文，并保存在对话记录中。因此，凭据仅从进程环境或 login 写入的文件中读取。

⚠️ ARA_AUTH_TOKEN 会在 24 小时后过期。 Ara 令牌使用 expiresIn: "24h" 签名：手动粘贴的令牌隔天就会失效。仅在能够自动续期的自动化集成中使用。日常使用时，请优先选择上文的 login，或使用 ARA_USERNAME / ARA_PASSWORD——但这需要将明文密码写入配置文件。

如果令牌已过期，工具 auth_refresh 会在当前会话中重新进行身份验证。

工具

每个工具都带有注解（readOnlyHint、destructiveHint、idempotentHint），以便 MCP 客户端在执行敏感操作前请求确认。

工具	类型	说明
get_audit_method	📖 参考资料	工作计划：各项标准要求做什么
list_rgaa_criteria	📖 参考资料	RGAA 标准索引（编号 + 标题），可筛选
get_rgaa_criterion	📖 参考资料	一项标准、其测试以及验证所需内容
auth_refresh	↻	从环境中重新进行身份验证
create_audit	✚ 新增	创建新审计
duplicate_audit	✚ 新增	复制审计以进行复测，包括审计记录（不会修改源审计）
get_audit	🔒 只读	获取完整审计
get_audit_progress	🔒 只读	进度：按页面列出仍待评估的内容
compare_audits	🔒 只读	复测：前后比率，以及发生变化的标准和结果
get_audit_results	🔒 只读	标准结果，可按页面和状态筛选
get_report	🔒 只读	包含符合率的完整报告
export_csv	🔒 只读	导出结果为 CSV
update_audit	⚠️ 有破坏性	完整更新——替换元数据
patch_audit_notes	⚠️ 有破坏性	替换审计备注
update_audit_results	⚠️ 有破坏性	替换目标标准的评估结果
update_statement	⚠️ 有破坏性	替换并发布无障碍声明
publish_audit	⚠️ 有破坏性	公开审计——不可撤销（见下文）
delete_audit	⚠️ 有破坏性	删除（之后返回 410）——不会取消发布

修复后重新测试

建议的周期：初始审计、修复、复制审计、重新测试受影响的标准、从副本提交。

• duplicate_audit 会复制审计记录。 Ara 的副本不会包含申请人、审计员所属组织、URL、联系人、技术和工具（已通过 API 验证）。服务会从源记录中补齐这些信息，同时保留源记录中的页面顺序。若只需复制 Ara 中的内容，请传入 copyMetadata: false。如果这第二步失败，副本仍然存在：其标识符会随警告一并返回。
• update_audit 会按照所发送数组中的顺序重新编号页面。 请按 order（get_audit 返回的值）对页面排序后再发送，否则报告中的抽样顺序会被打乱。
• compare_audits 会比较初始审计及其副本。页面按名称和 URL 配对。它会返回按 Ara 规则计算的每次审计通过率（某个页面上不符合 = 不符合；至少一个页面上符合且没有任何页面不符合 = 符合；通过率 = 符合数 / 适用数）、状态发生变化的标准，以及逐页状态转换（NC→C、C→NC……）。

分批发送结果

update_audit_results 会将结果分批发送给 Ara，每批 20 条（batchSize，范围为 1 到 100）。有时，即使每条结果单独发送都能通过，Ara 仍会对整个批次返回 500 错误（曾在主题 10 和 12 的 23 至 36 条结果批次中观察到）。此时，服务会将批次一分为二，直到拆分为单条结果：

• Ara 接受的结果会被记录；
• 即使单独发送也被 Ara 拒绝的结果会列在 echecs 中；
• 发生 4xx 错误时会停止发送，并指出此前已记录的结果数量。

每次发送都会替换目标评估：重新发送一个批次不会产生副作用。

内置 RGAA 参考标准

服务内置了完整的 RGAA 4.1 参考标准——13 个主题、106 条标准，以及每条标准的测试。没有这些内容，Agent 只能操作编号（topic: 6, criterium: 1），却不知道要评估什么。

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)

审计期间的预期操作：使用 get_rgaa_criterion 阅读标准及其测试，然后使用 update_audit_results 给出判定。依据测试进行判断，而不是猜测。

数据来自 Ara 项目的 rgaa.json，由 DINUM 根据 Licence Ouverte 2.0 发布。数据已内置于软件包中，因此服务可离线运行，参考标准部分无需网络请求。重新生成：node scripts/build-rgaa-data.mjs。

请注意：FAST 和 COMPLEMENTARY 审计类型各涵盖 25 条标准，且互不重叠；完整方法论（快速 + 补充）涵盖 50 条标准。

源代码还不够

RGAA 的 106 项标准中，只有 40 项可以通过阅读 HTML 作出判断——快速审计的 25 项中也只有 6 项。其他项目需要查看渲染后的页面、实际进行键盘导航、检查无障碍树，或作出编辑判断。

这是 AI 辅助审计的陷阱：Agent 读取标记，找到看似合理的答案，然后完成一份毫无依据的审计。三种机制可以避免这种情况。

get_audit_method(auditType) — 开始前的工作计划：哪些标准需要检查源代码、渲染结果、键盘操作、呈现方式或作出判断。

get_rgaa_criterion 会为每项标准附上一个 verification 区块：sourceSuffit、所需条件，以及如何进行检查。

update_audit_results 会拒绝无依据的判定。 对需要更多信息的标准，如果未填写对应的 evidence 字段就判定为 CONFORME 或 NON CONFORME，会返回明确的错误：

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 和 NOT_APPLICABLE 不受此限制：它们不代表任何结论。而且 evidence 仍由调用方自行声明——Agent 仍可能撒谎，但不能再通过省略信息来做到。

此分类是本服务提供的指导建议，根据测试词汇推导而来，并经过人工修订。RGAA 说明要检查什么，但没有说明使用什么工具。

⚠️ 发布不可撤销

Ara 不提供取消发布的功能，而且删除审计不会移除已发布的报告：

执行 publish_audit 后再执行 delete_audit
GET /audits/:editUniqueId	410 Gone — 审计从您的列表中消失
GET /reports/:consultUniqueId	200 — 报告仍可公开查看

此时，您将无法再通过 Ara 界面访问报告：既无法查看或更正，也无法将其移除。公开报告中只会删除您的审计员姓名；审计内容仍会保留。

两点实际建议：

• 切勿将删除视为撤销发布的方式；
• 发布针对第三方网站的审计，意味着在线发布一份由您签署的、关于该网站的无障碍声明——请确认您已获得授权。

在评论中引用 HTML

Ara 会以富文本形式显示标准评论：直接写入的 <th> 会被解析为标签，并从渲染后的评论中消失——API 返回 200，检查结果却失去了实质内容，而且不会有任何提示。

从 2.2.1 版起，update_audit_results 会对 compliantComment、notApplicableComment 以及每个 notCompliantItems 中的 title/comment 里的 < 和 > 进行转义。因此可以放心引用标记：

"comment": "Le champ n'a ni <label for>, ni aria-label."
      ↳ affiché dans Ara :  Le champ n'a ni <label for>, ni aria-label.

请勿自行转义：& 会保持原样，因此已经转义的 <th> 仍然有效。

例外：notes 字段（patch_audit_notes）仍为未转义的富文本——该字段专用于格式化。要在其中引用标记，请写作 <th>。

MCP 协议修订版本

从 2.1.0 版起，服务端可通过同一份代码支持该规范的两个修订版本，并在连接建立时进行协商：

• 2025-11-25 — 与以往相同，使用 initialize 握手。
• 2026-07-28 — 无状态：不再需要 initialize，新增 server/discover、resultType，并在工具目录中提供缓存提示（ttlMs / cacheScope）。

无需进行任何配置：客户端会获得其能够使用的修订版本。

从 1.x 迁移

2.0 移除了 auth_signin 工具，该工具会将电子邮箱和密码作为参数接收——也就是说，这些信息会经过模型上下文。

• 从脚本或提示词中移除对 auth_signin 的所有调用。
• 将凭据放入 MCP 配置的 env 块中（参见身份验证）：服务器会在启动时自动完成身份验证。
• 不带参数的 auth_refresh 可替代会话期间手动重新登录。

顺便修复了一处问题：signin 会在请求中携带当前令牌的 Authorization 标头。令牌过期时，API 就会返回 404 Cannot POST /api/auth/signin——而这恰恰是用户尝试重新登录的情况。

典型工作流

1. get_audit_method("FULL")                  # De quoi aurai-je besoin ?
2. create_audit(FULL, "MonSite", pages...)   # Créer l'audit (106 critères)
3. get_audit(editUniqueId)                   # Récupérer les IDs de page
4. get_rgaa_criterion(topic, criterium)      # Lire le critère et ses tests
5. update_audit_results(...)                 # Poser le verdict (envoi par paquets)
6. get_audit_progress(editUniqueId)          # Que reste-t-il ?
   ↳ revenir en 4 tant qu'il reste des critères
7. update_statement(editUniqueId, ...)       # Remplir la déclaration
8. publish_audit(editUniqueId)               # Publier l'audit terminé
9. get_report(consultUniqueId)               # Consulter le rapport final

Retest : duplicate_audit (fiche comprise) → update_audit_results sur la copie
         → compare_audits(initial, copie) → update_statement sur la copie

完整审计才是常规做法：只有基于 106 项标准的审计，才能作为无障碍声明的依据。FAST（25 项标准）和 COMPLEMENTARY（另外 25 项）用于发现问题，而非用于声明。

一次完整审计包含每个页面的 106 项标准，包括跨页面元素——两个页面会产生 318 条结果，八个页面的抽样则接近一千条。因此需要采用 4→6 循环：分批评估，然后通过 get_audit_progress 查询剩余内容，而不是一次性取回所有结果。

身份验证在服务器启动时通过环境变量完成：工作流中无需登录步骤。

RGAA 枚举值

审计类型

• FULL — 106 项标准（完整审计）
• FAST — 25 项标准（快速审计）
• COMPLEMENTARY — 50 项标准（补充审计）

标准状态

• COMPLIANT — 符合
• NOT_COMPLIANT — 不符合
• NOT_APPLICABLE — 不适用
• NOT_TESTED — 未测试

对用户的影响

• MINOR — 轻微
• MAJOR — 严重
• BLOCKING — 阻断

RGAA 主题（topic 1-13）

1. 图像
2. 框架
3. 颜色
4. 多媒体
5. 表格
6. 链接
7. 脚本
8. 必要元素
9. 信息结构
10. 信息呈现
11. 表单
12. 导航
13. 内容查阅

Ara 路由映射

审计（/audits）

方法	路由	MCP 工具
POST	/audits	create_audit
GET	/audits/:uniqueId	get_audit
PUT	/audits/:uniqueId	update_audit
PATCH	/audits/:uniqueId	patch_audit_notes
DELETE	/audits/:uniqueId	delete_audit
POST	/audits/:uniqueId/duplicate	duplicate_audit
PUT	/audits/:uniqueId/publish	publish_audit
GET	/audits/:uniqueId/results	get_audit_results
PATCH	/audits/:uniqueId/results	update_audit_results
GET	/audits/:uniqueId/exports/csv	export_csv
PUT	/audits/:editUniqueId/statement	update_statement

报告（/reports）— 只读

方法	路由	MCP 工具
GET	/reports/:consultUniqueId	get_report

身份验证（/auth）

方法	路由	MCP 工具
POST	/auth/signin	auth_refresh（仅通过环境变量）

未公开的路由（不属于 MCP 范围）

路由	原因
GET /audits/:id/pages/:slug	slug 是每个审计中唯一的一列，任何 API 响应都不会返回它——既无法通过顺序也无法通过页面标识符解析。请使用 get_audit_results 并按 pageId 筛选
POST /audits/:id/results/examples	上传图像（已弃用）
POST /audits/:id/notes/files	上传文件
POST /audits/editor/images	上传编辑器图像
DELETE /audits/:id/results/examples/:id	删除图像
DELETE /audits/:id/notes/files/:id	删除文件
GET /audits	审计列表（需要 account 身份验证）
POST /auth/signup	创建账户
POST /auth/verify	验证账户
PATCH /profile	用户个人资料
POST /feedback	用户反馈

开发

git clone https://github.com/DavidPivert/ara-rgaa-mcp.git
cd ara-rgaa-mcp
npm install
npm run build      # compile vers build/
npm run typecheck  # tsc --noEmit
npm test           # tests hors ligne (envoi par paquets, fiche, comparaison), après le build

发布。 此软件包通过 GitHub Actions（.github/workflows/publier.yml）以“可信发布”（OIDC）方式发布到 npm，无需令牌或密钥，并附带来源证明。发布新版本：更新 package.json 和 server.json 中的版本号，合并到 main，然后推送标签 vX.Y.Z。工作流会拒绝与 package.json 不匹配的标签，也不会重新发布已上线的版本。点击“Run workflow”按钮会在 package.json 中的版本尚未发布时发布该版本。

要将本地副本连接到 MCP 客户端，请将 command 指向 node，并将 args 设为 build/index.js 的绝对路径；或者使用 run.sh，它会执行必要的 cd，以便解析 node_modules。

许可证

EUPL-1.2——本仓库代码适用的《欧盟公共许可证》。

内嵌的 RGAA 规范库（src/rgaa-data.ts）摘自 Ara 项目，仍适用开放许可证 2.0——法国数字事务部际委员会（DINUM）。

此服务是一个独立项目：它调用 Ara 的 API，但不复用其代码。Ara 由 DINUM 按照 MIT 许可证发布，该许可证不会对本仓库的许可证施加任何限制。