内容
# axe-devtools-mcp
一个运行 [axe-core](https://www.npmjs.com/package/axe-core) 无障碍审计的 [MCP](https://modelcontextprotocol.io) 服务器，并将结果返回给任何MCP客户端——包括 **Claude Code**、Claude Desktop 和 Cursor。
它在无头 Chromium（通过 Playwright）中渲染页面，注入 axe-core，并报告 WCAG 违规情况，包括影响级别、受影响的元素和修复指南。
## 工具列表
| 工具 | 描述 |
| --- | --- |
| `scan_url` | 在无头 Chromium 中加载 URL（实时网站或本地开发服务器）并运行 axe-core 审计。 |
| `scan_html` | 对原始 HTML 字符串运行 axe-core 审计。 |
| `scan_file` | 扫描本地磁盘上的 `.html` 文件（通过 `file://` 加载，以便链接的 CSS/资产解析）。适用于静态网站构建输出。 |
| `scan_site` | 从起始 URL 广度优先爬取正在运行的网站，遵循同源链接，并审计每个页面（最多 `maxPages`）。返回聚合报告和每页详细信息。 |
两种工具都接受：
- `tags` — WCAG / 规则标签来运行，例如 `["wcag2a", "wcag2aa", "wcag21aa", "best-practice"]`
- `rules` — 只运行这些 axe 规则 ID，例如 `["color-contrast", "image-alt"]`
- `excludeRules` — 要跳过的 axe 规则 ID
- `detail` — `"full"`（默认；列出违规元素 + 修复）或 `"summary"`（仅规则 + 计数）
- `maxNodes` — 当 `detail="full"` 时，每个规则要列出的最大违规元素（默认 `5`）
- `includeIncomplete` — 还要报告 axe **"incomplete"** 项：需要手动审查的检查（例如，背景图像上的 color-contrast，`aria-hidden` 焦点）。默认关闭；设置为 `true` 以显示可能的问题，而自动化规则无法确认。
`scan_url` 和 `scan_file` 还接受 `include`（用于限定扫描的 CSS 选择器）和 `timeoutMs`。`scan_file` 接受 `path`（绝对路径，或相对于服务器工作目录的路径）。`scan_site` 还接受 `maxPages`（默认 `5`，最大 `50`）和 `sameOriginOnly`（默认 `true`）。
### 扫描您自己的网站/代码库
axe-core 是一个 **运行时** 引擎 — 它审计渲染的 DOM，而不是您的源文件。要审计您正在构建的代码：
- **运行应用程序（最佳）：** 启动开发服务器（`npm run dev`），然后 `scan_url http://localhost:3000/...`，或 `scan_site http://localhost:3000` 以一次调用爬取每个路由。这测试用户在您的框架渲染后实际得到的内容。
- **静态构建输出：** `scan_file ./dist/index.html`。注意，单页应用构建通常是空壳，由 JS 填充，因此请扫描正在运行的服务器。
- **源级 linting（不同、互补的工具）：** `eslint-plugin-jsx-a11y`、`eslint-plugin-vuejs-accessibility` 等。
## 需求
- Node.js >= 18
- 由 Playwright 管理的 Chromium 浏览器。`npm install` 运行 `npx playwright install chromium` 自动；如果跳过了，请手动运行：
```bash
npx playwright install chromium
```
## 与 Claude Code 结合使用
使用 Claude Code CLI 注册服务器：
```bash
# 从 npm（发布后）
claude mcp add axe-devtools -- npx -y axe-devtools-mcp
# 或从本地克隆
claude mcp add axe-devtools -- node /absolute/path/to/axe-devtool-mcp/dist/index.js
```
然后在 Claude Code 中：
> 扫描 https://example.com 以查找无障碍问题。
## 与其他 MCP 客户端结合使用
这是一个标准的 stdio MCP 服务器，因此它适用于任何支持 MCP 的客户端。发布到 npm 后，每个客户端都使用相同的 `npx` 调用；发布前，请将其替换为 `node /absolute/path/to/axe-devtool-mcp/dist/index.js`。
### Claude Desktop
编辑 `claude_desktop_config.json`
（macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`，
Windows：`%APPDATA%\Claude\claude_desktop_config.json`），然后重启应用程序：
```json
{
"mcpServers": {
"axe-devtools": {
"command": "npx",
"args": ["-y", "axe-devtools-mcp"]
}
}
}
```
### VS Code / GitHub Copilot（Agent 模式）
在工作区中添加 `.vscode/mcp.json`（注意 `servers` 键），然后在 Agent 模式下从 Copilot Chat "Tools" 选择器中启用它：
```json
{
"servers": {
"axe-devtools": {
"type": "stdio",
"command": "npx",
"args": ["-y", "axe-devtools-mcp"]
}
}
}
```
### Cursor
添加到 `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（项目）：
```json
{
"mcpServers": {
"axe-devtools": {
"command": "npx",
"args": ["-y", "axe-devtools-mcp"]
}
}
}
```
> 提示：某些客户端（例如后台/无头运行器）不运行 npm 生命周期脚本，因此 Chromium 自动安装程序不会触发。如果扫描无法启动浏览器，请在该机器上运行 `npx playwright install chromium` 一次。
## 从源代码运行
```bash
git clone https://github.com/Ravindrabisht12/axe-devtool-mcp.git
cd axe-devtool-mcp
npm install
npm run build
node dist/index.js # 通过 stdio 发送 MCP
```
## 发布到 npm
```bash
npm login
npm publish --access public
```
发布后，任何人都可以使用 `npx -y axe-devtools-mcp` 运行它 — 无需克隆。
## 工作原理
```
MCP 客户端（Claude Code）
│ stdio（JSON-RPC）
▼
axe-devtools-mcp ──► Playwright（无头 Chromium） ──► axe-core 注入到页面
▲ │
└────────────── 格式化违规 + 修复 ◄──────────────┘
```
## 许可证
MIT
