a11y-toolkit — the accessibility layer for AI coding agents

17 MCP tools + 5 prompts + a skill that give any AI agent (Claude, Cursor, Windsurf, Codex…) the full WCAG 2.2 loop: audit → fix → document → watch. Zero dependencies at its core; every finding ships with a concrete remediation your agent can apply.

Accessibility is not optional anymore: the European Accessibility Act is in force since June 2025, ADA suits keep landing, and AI agents now write most of the web. This toolkit makes "is it accessible?" a one-question ask — and "then fix it" a one-command job.

What no other a11y tool gives an agent

The tools (17)

5 prompts (slash-commands in supporting clients): audit-page (full audit workflow + what automation can't check), fix-contrast, pre-deploy-check (audit + diff → GO/NO-GO), declaration-eaa (collects legal fields, generates), conformance-wcagem (the three-tier WCAG-EM ladder).

Install

Registry name: mcp-name: io.github.kinti/a11y-toolkit · PyPI: a11y-toolkit

Works with any MCP-capable client — Claude Code/Desktop, Cursor, Windsurf, VS Code, Codex CLI, OpenCode, ZCode, Zed, Cline, Continue, Kimi Code… See docs/clients.md for every verified config format.

Claude Code (one command):

claude mcp add a11y-toolkit -- uvx --from a11y-toolkit a11y-toolkit-mcp

Any MCP client with JSON config (Claude Desktop, Cursor, Windsurf, VS Code…):

{
  "mcpServers": {
    "a11y-toolkit": {
      "command": "uvx",
      "args": ["--from", "a11y-toolkit", "a11y-toolkit-mcp"],
      "timeoutMs": 60000
    }
  }
}

Or from the repo without publishing:

{ "mcpServers": { "a11y-toolkit": {
    "command": "uvx", "args": ["--from", "git+https://github.com/kinti/a11y-toolkit", "a11y-toolkit-mcp"] } } }

The rendered audit, snapshots and diffs use Playwright if present (pip install playwright && playwright install chromium); everything else works with zero dependencies.

The skill (teaches your agent when/how to use all of this)

git clone https://github.com/kinti/a11y-toolkit && cd a11y-toolkit
./skill/install-skill.sh     # → ~/.zcode/skills and ~/.claude/skills

CLI — same engine, one command

a11ytoolkit pair "#1f2328" "#fbfaf7"                     # contrast, per-criterion verdicts
a11ytoolkit image hero.jpg --text "#ffffff" --region 120,40,420,90
a11ytoolkit audit --url https://example.com --lang en    # express static audit
a11ytoolkit declaration --entidad "Acme" --url https://acme.example \
       --estado parcial --marco eaa --lang en --output decl.html
a11ytoolkit snapshot https://mysite --out before.json    # before deploy (needs Playwright)
a11ytoolkit diff before.json after.json                  # after deploy

Run from a clone with python3 a11y.py <subcommand>; from PyPI with uvx --from a11y-toolkit a11ytoolkit ….

Watch it continuously (the deployment gate)

a11ytoolkit audit --url https://mysite --pages 5 > audit.json        # light crawl
python3 -m a11ybudget --init < audit.json > budget.json       # accept today's baseline
a11ytoolkit budget --budget budget.json --audit audit.json           # only NEW findings block (exit 2)
a11ytoolkit sarif --from-audit audit.json -o a11y.sarif              # GitHub code scanning format

examples/a11y-watch.yml turns this into a weekly scheduled check that fails on regressions and publishes the SARIF to code scanning.

Validated against real pages, not just fixtures

Before shipping the current rule set we benchmarked against axe-core 4.10 on real pages (methodology and results) — same Chromium, same Playwright. That pass caught a real WCAG failure on gov.uk that axe does not report (blue button text at 3.91:1, manually verified) and drove out five of our own false positives (hidden skip links reported as tiny targets, honeypot fields, non-tabbable aria-hidden controls, single-context generic links). Every divergence has a regression fixture.

Honesty, built in

Automation covers ~1/3 of WCAG — every audit says so. The audit-page prompt and the bundled skill then have the agent check what it can (keyboard operability, focus visibility, zoom reflow, announced errors) using the manual checklist, and recommend a screen-reader pass for the rest. A filter, not a verdict.

Security & scope

A local tool: runs on your machine as your user. path (image) and output_path (statement) read/write local paths — use it in MCP clients you trust. Nothing leaves your machine except the URL you explicitly audit.

Development

python3 test_contrast.py && python3 test_audit.py && python3 test_v32.py && python3 test_dom.py && python3 test_cli.py && python3 test_mcp.py

test_dom.py self-skips without Playwright. Releases: tag vX.Y.Z → CI publishes to PyPI (trusted publishing); server.json is the official MCP Registry manifest. Contributions welcome — see CONTRIBUTING.md (the golden rules: zero dependencies at the core, es/en strings everywhere, honest scope notes).

Roadmap

• Rendered audit (computed contrast, target size 2.5.8, focus indicator)
• 0-100 weighted score · ARIA validity · criterion explanations
• Computed accessibility tree in snapshots + tree diff
• SARIF export → findings as GitHub code-scanning / PR annotations (a11ytoolkit sarif)
• Honest dated badge as accessible SVG (a11y_badge)
• Accessibility error budget: only NEW findings block (a11ytoolkit budget + examples/a11y-watch.yml)
• Multi-page same-domain crawl with aggregated scores (pages parameter)
• Scheduled surveillance recipe (weekly audit + budget gate as a GitHub Action)
• WCAG-EM conformance ladder (conformance-wcagem prompt + guided protocol)
• Same-origin iframes in the rendered audit + :focus/:hover state contrast

Author

Jesús Quintana Fernández (jquin.net) — SEO/GEO consultant and web-accessibility practitioner since 2003. MIT © 2026.