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

Capability	axe-core / Lighthouse / pa11y	a11y-toolkit
Text contrast over images/gradients (pixel sampling of the real background, hostile-zone grid)	✗	✓
Legal accessibility statements (EAA / RD 1112/2018), accessible HTML, es/en	✗	✓
Regression watch between builds: accessible names + real tab-order diff	✗	✓
Remediation text per finding, written for an agent to apply	✗	✓
Focus-order regression detection	✗	✓
Runs with zero dependencies (stdlib only; Playwright optional for the deep pass)	heavy runtimes	✓
Screen-reader aria-live announcement monitor	✗	✓
0-100 score computed from weighted findings	✓ (subset of axe rules)	✓ (weighted across 38 WCAG criteria)
Criterion explanations on demand for agents	✗	✓
Static core parity: ARIA validity, autocomplete 1.3.5, link purpose, list structure, duplicate ids	✓	✓
Output optimized for MCP/LLM consumption (JSON, severity-ranked, es/en)	✗	✓

The tools (17)

Tool	What it does
a11y_audit_url	Express static WCAG audit of a URL or raw HTML: 31+ signals — 38 WCAG criteria touched — with a weighted 0-100 score (alt, accessible names, labels, autocomplete 1.3.5, keyboard onclick, unknown ARIA roles, broken aria-labelledby, unnamed duplicated landmarks, meta refresh, skip mechanism, lang validity, title, headings, blocked zoom, captions, autoplay audio, generic/duplicated link text, target=_blank warnings, tabindex>0, aria-hidden-on-focusable, tables, duplicate ids, accesskeys). Per-finding remediation.
a11y_audit_dom	Rendered audit (local Playwright/Chromium): real computed text contrast vs effective backgrounds with alpha compositing (1.4.3), minimum target size 24×24 (2.5.8 — new in WCAG 2.2), focus-indicator heuristic (2.4.7), :focus/:hover state contrast, open shadow DOM traversed — all static checks on the live DOM.
a11y_contrast_pair	Exact ratio + verdicts 1.4.3/1.4.6/1.4.11. Accepts #hex, rgb(), hsl(), CSS color names; alpha composites over the background. Suggests the nearest passing color.
a11y_contrast_image	Text over images: pixel-level sampling of the actual background → worst/median/p95 ratio, % area passing AA, hostile-zone detection on a 3×3 grid.
(rendered audit)	adds :focus/:hover state contrast (disabled exempt) and same-origin iframes
a11y_suggest_color	Nearest opaque color (true RGB distance) reaching the target ratio (4.5 default).
a11y_generate_declaration	Legal accessibility statement in HTML: RD 1112/2018 art. 10 (Spanish public sector) or European Accessibility Act wording (Directive (EU) 2019/882 / Ley 11/2023). es/en. The document is itself accessible.
a11y_snapshot	Interactive elements (tag, role, accessible name, href) + real tab focus order + the computed accessibility tree (what a screen reader announces). Requires Playwright.
a11y_diff	Regression diff between two snapshots: added/removed/renamed interactives, focus-order changes.
a11y_diff_urls	Snapshot two URLs and diff in one call (staging vs production).
a11y_aria_live_snippet	Injectable monitor logging every aria-live announcement (time, politeness, role, text) — what a screen reader would say, visible on screen.
a11y_evidence	The countersignature-ready evidence pack: full criteria matrix (fail/review/not-flagged/manual-only), artifacts SHA-256-hashed, empty signature block referencing the pack's hash. The vendor-neutral machine→human handoff — any qualified human can countersign it. Spec: docs/evidence-pack-schema.md, real sample included.
a11y_criterion	Explains any WCAG 2.2 criterion in plain language: what it requires, typical failures, and which toolkit tool verifies it.
a11y_scroll	Infinite-scroll audit — the documented disaster nobody automates (Deque + APG Feed pattern): real scrolling batches, does focus SURVIVE, is new content ANNOUNCED, does the feed END or offer load-more.
a11y_keyboard	Keyboard-trap detection (2.1.2) with REAL Tab walking: up to 60 stops, cycle detection, and the decisive test — does Escape release? Correct modals are not reported.
a11y_autofix	Deterministic safe auto-fixes on HTML: unblock zoom (1.4.4), exact autocomplete tokens (1.3.5), missing lang, empty title. Everything requiring judgment is returned as no_aplicados with the reason — the honest anti-overlay.
a11y_reflow	Reflow at 320px (1.4.10) — the check axe and Lighthouse don't automate: real horizontal scroll + overflowing elements at 320px viewport.
a11y_badge	Returns an honest badge as accessible SVG: score, date, scope ("automated screening"), never "conformant" — the anti-overclaim seal.

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.