Back to Details

wire-up-mcp

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Wire up Real A11y MCP

连接Real A11y MCP

Gives an AI agent a real browser and the accessibility tree — audit, inspect, checkpoint/diff, and act by role+name. Source of truth: https://real-a11y.dev/packages/mcp
为AI Agent提供真实浏览器和可访问性树——支持审计、检查、checkpoint/diff（检查点/差异对比），以及按角色+名称执行操作。权威文档：https://real-a11y.dev/packages/mcp

Prerequisites

前置条件

  • Node.js 20+
  • A Chromium binary: 
    npx real-a11y install
    (or 
    npx playwright install chromium
    )
  • An MCP-capable client
  • Node.js 20+
  • Chromium二进制文件：
    npx real-a11y install
    （或
    npx playwright install chromium
    ）
  • 支持MCP的客户端

Client config

客户端配置

Point the client at 
npx -y @real-a11y-dev/mcp
(no global install required).
Claude Code
sh
claude mcp add real-a11y -- npx -y @real-a11y-dev/mcp
VS Code
sh
code --add-mcp '{"name":"real-a11y","command":"npx","args":["-y","@real-a11y-dev/mcp"]}'
Config file (Cursor 
~/.cursor/mcp.json
or project 
.cursor/mcp.json
, Claude Desktop 
claude_desktop_config.json
, Windsurf, etc.):
json
{
  "mcpServers": {
    "real-a11y": {
      "command": "npx",
      "args": ["-y", "@real-a11y-dev/mcp"]
    }
  }
}
Then once:
sh
npx real-a11y install
To pin a version, install locally (
npm i -D @real-a11y-dev/mcp@beta playwright
) and point 
command
/
args
at the local binary instead of 
npx -y
.
将客户端指向
npx -y @real-a11y-dev/mcp
（无需全局安装）。
Claude Code
sh
claude mcp add real-a11y -- npx -y @real-a11y-dev/mcp
VS Code
sh
code --add-mcp '{"name":"real-a11y","command":"npx","args":["-y","@real-a11y-dev/mcp"]}'
配置文件（Cursor的
~/.cursor/mcp.json
或项目目录下的
.cursor/mcp.json
、Claude Desktop的
claude_desktop_config.json
、Windsurf等）：
json
{
  "mcpServers": {
    "real-a11y": {
      "command": "npx",
      "args": ["-y", "@real-a11y-dev/mcp"]
    }
  }
}
然后执行一次：
sh
npx real-a11y install
如需固定版本，可本地安装（
npm i -D @real-a11y-dev/mcp@beta playwright
），并将
command
/
args
指向本地二进制文件，而非
npx -y
。

Auth (pages behind login)

身份验证（需登录的页面）

Never pass credentials as MCP tool arguments. Human logs in once; agent reuses the session:
  1. npx real-a11y login <url> --save ./auth.json
    (keep 
    auth.json
    out of VCS)
  2. Set env for the MCP server process: 
    • REAL_A11Y_MCP_STORAGE_STATE
      — absolute path to the storage-state file
    • REAL_A11Y_MCP_ALLOWED_ORIGINS
      — comma-separated trusted origins (required with storage state)
REAL_A11Y_MCP_CDP
(attach to an existing browser) and storage-state are mutually exclusive. A bad storage-state path or an invalid origins value refuses to start — do not work around that. Loading storage-state without 
REAL_A11Y_MCP_ALLOWED_ORIGINS
only prints a startup warning; still set the pin — without it, redirects can leave trusted origins.
file://
is blocked by default; only enable if the docs’ allow-file flag is appropriate for the user’s threat model.
切勿将凭证作为MCP工具参数传递。人工登录一次后，Agent可复用会话：
  1. npx real-a11y login <url> --save ./auth.json
    （请勿将
    auth.json
    纳入版本控制系统）
  2. 为MCP服务器进程设置环境变量： 
    • REAL_A11Y_MCP_STORAGE_STATE
      —— storage-state文件的绝对路径
    • REAL_A11Y_MCP_ALLOWED_ORIGINS
      —— 逗号分隔的可信源（使用storage state时必填）
REAL_A11Y_MCP_CDP
（连接至现有浏览器）与storage-state互斥。若storage-state路径错误或origins值无效，服务将拒绝启动——请勿绕过此限制。加载storage-state但未设置
REAL_A11Y_MCP_ALLOWED_ORIGINS
仅会在启动时打印警告；仍需设置该参数——否则重定向可能离开可信源范围。
默认阻止
file://
协议；仅当文档中的allow-file标志符合用户的威胁模型时，才启用该协议。

Smoke test

冒烟测试

  1. Confirm the client lists Real A11y tools.
  2. Ask: “Audit https://example.com for accessibility problems.”
  3. Expected tool sequence: 
    open_page
    → 
    audit_page
    (or 
    inspect_page
    ) → explain findings → 
    close_browser
    when done.
Discover tools from their descriptions — do not invent tool names or parameter shapes. Full reference: https://real-a11y.dev/packages/mcp/tools
  1. 确认客户端已列出Real A11y工具。
  2. 发起请求：“检查https://example.com的可访问性问题。”
  3. 预期工具执行流程：
    open_page
    → 
    audit_page
    （或
    inspect_page
    ）→ 解释检测结果 → 完成后执行
    close_browser
    。
请根据工具描述了解可用工具——请勿自行编造工具名称或参数格式。完整参考文档：https://real-a11y.dev/packages/mcp/tools

Next skills

后续技能

  • First audit workflows → 
    audit-a-page
  • Interact then re-check → 
    a11y-act-loop
  • 首次审计工作流 → 
    audit-a-page
  • 交互后重新检查 → 
    a11y-act-loop