atag-mcp

ATAG MCP

一个 MCP（Model Context Protocol）服务，提供 ATAG 2.0——W3C 作者工具无障碍指南——相关指导，帮助作者工具开发者构建更易于访问的软件。

什么是 ATAG？

ATAG 2.0 规定了作者工具（富文本编辑器、CMS、IDE、网站构建器等）应如何：

• Part A — 让残障作者也能使用（工具自身的 UI）
• Part B — 帮助作者创作无障碍 Web 内容（替代文本提示、无障碍检查器、无障碍模板等）

为何创建此项目

ATAG 2.0 自 2015 年起便成为 W3C 推荐标准，但作者工具对其采用仍然有限——部分原因是，在实际做出设计和实现决策时，这些指导很容易被忽视。如今，越来越多的作者工具功能在 AI 编码助手的帮助下开发，这个服务将完整规范提供给助手：描述你正在开发的功能（图片上传对话框、富文本工具栏、模板选择器），即可获取适用的实际成功标准，而不是凭模糊记忆整理出的摘要。我们的目标是降低考虑采用 ATAG 的成本——这是打造支持 ATAG 的工具的第一步。

数据是 ATAG 2.0 规范的静态、人工核查副本，不会在运行时获取或生成，因此回答始终忠实于 W3C 原文。每周工作流都会检查上游规范是否有变更。

工具

工具	说明
get-server-info	数据集统计信息和来源说明
explain-atag	ATAG 概览、与 WCAG 的区别及其两部分结构
list-parts	Part A 和 Part B 的摘要
list-principles	全部 8 项原则，可按部分筛选
list-guidelines	全部 24 项指南，可按部分或原则筛选
list-success-criteria	全部 63 项成功标准，可按部分、原则、指南或级别筛选
get-criterion	特定 SC 的完整详情（例如 B.2.3.1）
get-guideline	指南完整详情及其所有子级成功标准
get-criteria-by-level	所有 A、AA 或 AAA 级别的标准
search-atag	在所有 ATAG 内容中按关键词搜索
list-glossary-terms	所有 ATAG 术语表词条
get-glossary-term	特定 ATAG 术语的定义
get-guidance	核心工具 — 描述你正在开发的功能，并获取最相关的 ATAG 标准

设置

无需本地安装——添加以下配置后，MCP 客户端会通过 npx 自动获取软件包。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

VS Code（Claude 扩展）

{
  "mcp": {
    "servers": {
      "atag-mcp": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "atag-mcp"]
      }
    }
  }
}

本地开发安装

npm install
npm run build
# then point your config to dist/index.js directly

使用示例

向 Claude 提问：

• “图片插入对话框适用哪些 ATAG 标准？” → 使用 get-guidance
• “显示 Part B 中所有 A 级标准” → 使用 get-criteria-by-level
• “解释指南 B.3.1” → 使用 get-guideline
• “ATAG 中的 ‘editing-view’ 是什么意思？” → 使用 get-glossary-term
• “在 ATAG 中搜索键盘访问” → 使用 search-atag

开发

npm run dev          # Run server directly with tsx (no compile step)
npm test             # Run all tests
npm run test:watch   # Watch mode
npm run validate-data  # Validate data/atag.json structure
npm run check-updates  # Check if W3C spec has changed

分支和提交

本项目遵循 git flow 和 Conventional Commits：

• main — 仅包含已发布代码；每次合并到 main 都会打标签并发布
• develop — 集成分支；日常工作会合并到此分支
• feature/<name> — 从 develop 分出并合并回 develop
• release/<version> — 从 develop 分出，合并到 main（并打标签）后再合并回 develop
• hotfix/<name> — 从 main 分出以处理紧急修复，合并到 main 和 develop

提交消息使用 Conventional Commits 前缀：feat:、fix:、docs:、test:、ci:、chore:、refactor:（对于破坏性变更，使用 ! 或添加 BREAKING CHANGE: 页脚）。

发布

版本管理采用标准的 npm 版本升级方式。推送 v* 标签会触发 GitHub Actions 发布工作流，该工作流会运行测试并自动发布到 npm。

npm version patch   # bug fixes:    1.0.0 → 1.0.1
npm version minor   # new features: 1.0.0 → 1.1.0
npm version major   # breaking:     1.0.0 → 2.0.0

git push && git push --tags

升级版本时，也要更新 server.json 中的 version 字段，使其保持一致——MCP Registry 会验证这些字段是否与已发布的 npm 包匹配。npm 发布成功后，使用以下命令刷新注册表条目：

mcp-publisher login github
mcp-publisher publish

发布需要 NPM_TOKEN 仓库密钥（具有 atag-mcp 写入权限的细粒度 npm 访问令牌）。如果令牌过期或已轮换，请使用相同的密钥名称添加新令牌，然后运行手动 检查 npm 令牌工作流（Actions 选项卡），在打标签发布前验证其是否通过身份验证。

保持数据最新

ATAG 2.0 规范记录在 data/atag.json 中。GitHub Actions 工作流（.github/workflows/update-atag.yml）每周运行一次，并在 W3C 规范内容发生变化时创建问题。

手动更新：

1. 查看 https://www.w3.org/TR/ATAG20/ 中的变更
2. 编辑 data/atag.json，加入变更
3. 运行 npm run validate-data 检查结构
4. 运行 npm run check-updates -- --save 更新存储的哈希值

数据

• 版本： ATAG 2.0
• 规范： https://www.w3.org/TR/ATAG20/
• 部分： 2（A 部分 + B 部分）
• 原则： 8
• 指南： 24
• 成功标准： 63
• 术语表词条： 18

许可证

MIT