Accessibility Agents

A11y Agent Team MCP Server

MCP（模型上下文协议）服务，通过 Streamable HTTP 或 stdio 提供 39 种无障碍扫描工具。可与 Claude Code、Claude Desktop、VS Code、Copilot CLI 及任何兼容 MCP 的客户端配合使用。它基于 @modelcontextprotocol/sdk 1.32.2 构建，并实现了该 SDK 提供的功能（协议修订版本最高至 2025-11-25）；关于其与 2026-07-28 标准的符合情况，请参阅 MCP 标准页面。

在此代码库中，MCP 服务位于顶层 mcp-server/ 目录。主要入口点为 server.js（HTTP）和 stdio.js（stdio）。

开箱即用的功能

MCP 服务是文档扫描的可执行部分。技能（PDF 相关的 skills/ 下的 pdf-accessibility 和 pdf-scan-config）会告知模型何时扫描；此服务则提供实际的 scan_pdf_document 工具。

安装内容	可获得的功能	PDF 扫描是否可用？
仅安装技能	聊天中的 PDF 扫描说明	否
技能 + MCP 服务	可用的 scan_pdf_document 工具	是
技能 + MCP 服务 + veraPDF	基础扫描 + 深度 PDF/UA 验证	是

安装插件时会启动 dist/stdio.mjs，这是 stdio 服务及其依赖项的单个 esbuild 捆绑包，因此无需执行 npm install 即可启动（mcp.json，以及 .claude-plugin/plugin.json 中的 mcpServers）。Playwright、@axe-core/playwright 和 pdf-lib 不会被纳入捆绑包，仍为可选依赖；需要它们的工具会说明安装方法。只有在使用 HTTP 服务（server.js）或处理源代码时，才需要在此文件夹中运行 npm install。

如果修改了服务源代码，请在此处运行 npm run build，并提交重新构建的 dist/stdio.mjs：当已提交的捆绑包与重新构建的结果不一致时，npm run verify 中的 bundle 检查会失败。

架构

服务支持两种传输模式：

模式	入口点	传输方式	使用场景
HTTP	server.js	Streamable HTTP（默认有状态，并使用 GET 事件流；设置 A11Y_MCP_STATELESS=1 时为无状态）。不提供旧版 HTTP+SSE 传输	远程客户端、共享服务、CI/CD
stdio	stdio.js（捆绑为 dist/stdio.mjs）	stdin/stdout	Claude Desktop、插件安装、本地使用

两种模式通过 server-core.js 共用相同的工具实现。

快速开始

开始前，请确保 node --version 显示受支持的 Node.js LTS 版本（26、24 或 22），且 npm 可用。代码库安装程序不会安装 Node.js；请从 https://nodejs.org/en/download 获取。

# stdio, from the bundle: no install needed
node mcp-server/dist/stdio.mjs

# HTTP mode needs the dependencies
cd mcp-server
npm install
npm start
# -> http://127.0.0.1:3100/mcp

通过 npm 安装，无需检出代码（从 7.1.0 起，待发布为 @community-access/accessibility-agents-mcp；也已列入 MCP Registry ，名称为 io.github.Community-Access/accessibility-agents）：

npx -y @community-access/accessibility-agents-mcp
claude mcp add accessibility-agents -- npx -y @community-access/accessibility-agents-mcp

npm 包仅包含 stdio 捆绑包。浏览器和 PDF 表单工具需要在同一个 node_modules 中安装可选依赖，因此如需使用这些工具，请将服务安装到含有这些依赖的文件夹中并从该处运行： npm install @community-access/accessibility-agents-mcp playwright @axe-core/playwright pdf-lib， npx playwright install chromium，然后运行 npx accessibility-agents-mcp。

仅针对 PDF 的操作指南，请参阅 PDF-QUICKSTART.md。

先决条件矩阵

各类别、对应要求、用途和是否必需。

类别	要求	用途	是否必需？
运行时	Node.js LTS（26、24 或 22）	运行 MCP 服务	是
运行时	stdio 打包文件不需要任何依赖	dist/stdio.mjs 内含 @modelcontextprotocol/sdk 和 zod	否
HTTP 或开发	npm，然后在此文件夹中运行 npm install（@modelcontextprotocol/sdk、zod、express）	HTTP 服务（server.js）、运行未打包的源代码和测试	仅这些场景需要
客户端	兼容 MCP 的客户端	调用服务工具	是
可选功能	Java 11+ 和 verapdf	使用 run_verapdf_scan 深度验证 PDF	否
可选功能	playwright、@axe-core/playwright、Chromium	基于浏览器的扫描工具	否
可选功能	pdf-lib	convert_pdf_form_to_html	否
仅安装程序	git	克隆仓库	否

运行 MCP 服务或安装软件包都不需要 Python。

本地服务与共享服务

你可以在自己的计算机上本地运行此 MCP 服务，也可以将其作为共享 HTTP 服务运行。

模式	运行位置	最适用于
本地 stdio	你的计算机，由客户端启动	Claude Desktop 和仅限本地的使用场景
本地 HTTP	你的计算机上的 127.0.0.1	VS Code Copilot、本地测试、调试
共享 HTTP	服务或容器	团队使用、CI/CD、远程客户端

对大多数用户而言，建议先在本地启动。默认 HTTP 绑定地址为 127.0.0.1，因此除非你主动更改主机地址，否则服务不会暴露到网络。

配置

各环境变量、默认值和说明。

环境变量	默认值	说明
PORT	3100	HTTP 服务端口
A11Y_MCP_HOST	127.0.0.1	绑定地址
A11Y_MCP_STATELESS	（未设置）	设置为 1 以启用无状态模式
GLOW_API_BASE_URL	https://letitglow.app/mcp	GLOW 桥接工具调用的端点

有状态与无状态

• 有状态（默认）：会话会在请求之间持久保留（Mcp-Session-Id），GET 请求会为该会话打开服务器发送事件流。最适合交互式使用。2026-07-28 的 MCP 修订版移除了会话和 GET 端点；此模式遵循 SDK。
• 无状态：每个请求都会创建一个全新的服务实例。不使用会话，仅支持 POST。最适合 CI/CD 和无服务器部署。

客户端配置

Claude Desktop（claude_desktop_config.json）

Claude Desktop 使用 stdio 从 claude_desktop_config.json 启动本地服务（Settings、Developer、Edit Config）：

{
  "mcpServers": {
    "a11y-agent-team": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/stdio.mjs"]
    }
  }
}

远程 HTTP 服务需在 Claude Desktop 中作为自定义连接器添加，而非写入此文件；请参阅 https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp。

Claude Code

插件会为你注册该服务。未使用插件时：

claude mcp add --transport stdio a11y-agent-team -- node /path/to/mcp-server/dist/stdio.mjs

VS Code（.vscode/mcp.json）

{
  "servers": {
    "a11y-agent-team": {
      "type": "http",
      "url": "http://127.0.0.1:3100/mcp"
    }
  }
}

使用 GLOW 桥接工具

GLOW 桥接工具是此 MCP 服务的一部分。你无需为 GLOW 单独注册第二个 MCP 服务。

默认行为

• 桥接默认指向 https://letitglow.app/mcp。
• 启动此服务后，你可以立即调用 glow_health_check。

使用不同的 GLOW 端点

选项 1：在启动前设置服务环境变量：

# Linux/macOS
export GLOW_API_BASE_URL="https://letitglow.app/mcp"
npm start

# Windows PowerShell
$env:GLOW_API_BASE_URL = "https://letitglow.app/mcp"
npm start

选项 2：在每次工具调用时传入 baseUrl（用于一次性测试）：

• 使用 baseUrl 调用 glow_health_check
• 使用 baseUrl 调用 glow_audit_document
• 使用 baseUrl 调用 glow_fix_document
• 使用 baseUrl 调用 glow_convert_document
• 使用 baseUrl 调用 glow_generate_report

连接后的提示词示例

• Run glow_health_check
• Audit ./docs/sample.md with glow_audit_document using format markdown
• Convert ./docs/sample.md from markdown to html with glow_convert_document
• Generate an html report for ./docs/sample.md with glow_generate_report

PDF 专用快速入门

如果你目前只想扫描 PDF 的无障碍性，以下是最精简的可用路径：

1. 安装 Node.js LTS 版本（26、24 或 22）。
2. 打开此文件夹：mcp-server/
3. 运行 npm install
4. 使用 npm start 启动服务
5. 将 MCP 客户端指向 http://127.0.0.1:3100/mcp
6. 如果你想在聊天中使用引导式 PDF 工作流，请安装技能（见开始使用）

MCP 端所需的最少文件：

• package.json
• server.js
• server-core.js
• stdio.js
• tools/

如果你还想使用聊天工作流层，请添加：

• pdf-accessibility 和 pdf-scan-config 技能（skills/pdf-accessibility/、skills/pdf-scan-config/），与软件包的其余部分一同安装
• 将 templates/pdf-config-moderate.json 复制到你的项目中，命名为 .a11y-pdf-config.json（可选）

可用工具

核心工具

每个工具及其描述。

工具	描述
check_contrast	计算两种颜色之间的 WCAG 对比度
get_accessibility_guidelines	获取适用于组件类型的 WCAG AA 指南
check_heading_structure	分析 HTML 标题层级
check_link_text	检测含糊或缺失的链接文本
check_form_labels	检查表单输入是否具有无障碍标签

文档工具

每个工具及其描述。

工具	描述
scan_office_document	扫描 .docx/.xlsx/.pptx 文件中的无障碍问题
scan_pdf_document	使用 PDF/UA 检查扫描 PDF
scan_epub_document	扫描 .epub 文件，检查其是否符合 EPUB Accessibility 1.1
extract_document_metadata	提取与无障碍相关的元数据
batch_scan_documents	一次调用扫描多个文档
fix_document_metadata	修正文档元数据（标题、语言、作者）
fix_document_headings	修正文档中的标题结构

GLOW 桥接工具

每个工具及其描述。

工具	描述
glow_health_check	检查 GLOW 端点的运行状况（默认：https://letitglow.app/mcp）
glow_audit_document	将 markdown/html/docx 文件上传至 GLOW 并运行 /audit
glow_fix_document	将 markdown/html/docx 文件上传至 GLOW 并运行 /fix
glow_convert_document	将 markdown/html/docx 文件上传至 GLOW 并运行 /convert
glow_generate_report	将 markdown/html/docx 文件上传至 GLOW 并运行 /report

高级工具（可选依赖项）

每个工具及其所需依赖项和描述。

工具	所需依赖项	描述
run_axe_scan	playwright, @axe-core/playwright	针对实时 URL 运行 axe-core
run_playwright_a11y_tree	playwright	捕获无障碍树
run_playwright_keyboard_scan	playwright	测试键盘导航
run_playwright_contrast_scan	playwright	进行视觉对比度分析
run_playwright_viewport_scan	playwright	测试不同宽度下的重排
run_verapdf_scan	veraPDF CLI	验证 PDF/UA-1（默认）、PDF/UA-2 或 PDF/A，使用 flavour 选择（SARIF 输出）
convert_pdf_form_to_html	pdf-lib	将 PDF 表单转换为无障碍 HTML

Markdown 工具

每个工具及其描述。

工具	描述
scan_markdown_document	扫描 markdown 文件中的无障碍问题（链接、替代文本、标题、表格、表情符号）

缓存工具

每个工具及其描述。

工具	描述
check_audit_cache	检查文件是否存在已缓存的审计结果
update_audit_cache	在缓存中存储或更新审计结果

安装可选依赖项

# Playwright + axe-core (for web scanning)
npm install playwright @axe-core/playwright
npx playwright install chromium

# pdf-lib (for PDF form conversion)
npm install pdf-lib

# veraPDF (external CLI)
# Download from https://verapdf.org/software/

可执行的 veraPDF 设置

veraPDF 为可选项。内置的 scan_pdf_document 工具无需安装即可使用。当你需要比内置启发式扫描更深入的 PDF/UA 验证时，请安装 veraPDF。

veraPDF 的用途

• 比内置扫描器更深入地验证 PDF/UA 符合性
• 使用专用 PDF 验证器确认结构和元数据问题
• 在基线扫描后进行第二轮检查

veraPDF 不适用于

• 基线 PDF 扫描不需要它
• 它不是此仓库中的主要修复工作流
• 不要假设 verapdf --fix 属于此处支持的工作流

安装 veraPDF

veraPDF 需要 Java 11 或更高版本。

Windows

如果尚未安装 Java，请先安装：

winget install --exact --id EclipseAdoptium.Temurin.21.JRE

然后在可用时使用 Chocolatey 安装 veraPDF：

choco install verapdf

如果你的环境中没有 Chocolatey，请使用 https://docs.verapdf.org/install/ 中的手动安装程序。

macOS

brew install verapdf

手动下载

从 https://docs.verapdf.org/install/ 下载，并确保 verapdf 可通过你的 PATH 使用。

验证 veraPDF

verapdf --version

在 Windows 上，安装 Java 或 veraPDF 后，请重启终端或编辑器，以便应用更新后的 PATH。

直接使用 veraPDF

verapdf --flavour ua1 --format text path/to/file.pdf

通过此 MCP 服务使用 veraPDF

服务运行且 veraPDF 安装在同一台机器上后，MCP 客户端即可调用 run_verapdf_scan。

自然语言请求示例：

• Run a deep PDF/UA scan on report.pdf using veraPDF
• Validate brochure.pdf with veraPDF and summarize the failures

如果未安装 verapdf，该工具会返回安装指南。

如需了解更多背景，请参阅 veraPDF 集成。

健康检查

curl http://127.0.0.1:3100/health
# {"status":"ok","name":"a11y-agent-team","version":"7.1.0","mode":"stateful"}

MCP 提示词

预构建的提示词模板，用于引导模型完成无障碍工作流。

提示词	参数	描述
audit-page	url（必填），level（可选：A/AA/AAA）	结构化的 WCAG 审计说明；逐步检查 axe-core、标题、链接、表单、键盘和对比度
check-component	component（必填）	使用内置指南对特定组件进行审查（modal、tabs、accordion、combobox、carousel、form、live-region、navigation、general）
explain-wcag	criterion（必填）	通过实用示例、常见违规情况和测试指南解释 WCAG 标准

MCP 资源

用于无障碍参考资料的只读数据端点。带有 {...} 参数的两个端点是资源模板：客户端会列出或补全它们，然后读取具体地址，例如 a11y://guidelines/modal。

资源 URI	描述
a11y://guidelines/{component}	Markdown 格式的组件无障碍指南（modal、tabs、accordion、combobox、carousel、form、live-region、navigation、general）
a11y://tools	自动生成的所有已注册工具及其描述的列表
a11y://config/{profile}	JSON 格式的扫描配置模板（strict、moderate、minimal）

安全性

• 路径遍历防护：文件操作会根据主目录和 CWD 边界验证路径（CWE-22）
• 符号链接解析：写入操作会解析符号链接以防止路径逃逸（CWE-59）
• SSRF 防护：基于 URL 的工具会验证协议（仅限 http/https）
• 命令注入防护：外部命令使用 execFile（而非 exec）和参数数组
• 文件大小限制：文档上限为 100 MB，批处理操作上限为 50 个文件
• 本地绑定：服务默认绑定到 127.0.0.1（不会暴露到网络）

部署

Docker

FROM node:24-slim
WORKDIR /app
COPY package.json .
RUN npm install
COPY . .
EXPOSE 3100
CMD ["node", "server.js"]

Systemd

[Unit]
Description=A11y Agent Team MCP Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/node /opt/a11y-mcp/server.js
Environment=PORT=3100
Restart=on-failure

[Install]
WantedBy=multi-user.target

许可证

MIT。请参阅仓库根目录中的 LICENSE。