# webability [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/snayyar00/webability-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1593  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/webability

## Description
WCAG/ADA/508 accessibility scanner + framework-aware fixes + vision audit for AI coding agents

## Tools
Capabilities this server exposes over MCP:

- **scan_page** — Scan a web page for WCAG accessibility issues. Works on any URL — deployed sites, localhost, staging. Returns `issues` (violations the scanner stands behind; findings the engines cannot decide are settled by the AI judge — a violation with a fix, or a pass recorded in `judged[]` with its reason — and anything unsettled is dropped, never listed for review) and a `summary`. On React ≤18 / Vue dev builds each issue carries `source` ({file, line, column, component}) read from the live component tree. Every issue carries a structured `fix.op` (add-attribute | set-attribute | remove-attribute | add-element | remove-element | add-text-content | suggest) with `fix.attribute` / `fix.value` when known, and a `fixability` tier (mechanical = apply as given; contextual = op known, value needs judgment; visual = needs rendered output, propose only).
- **verify_fix** — Re-scan a specific element after applying an accessibility fix and confirm the violation is gone. After you edit the code and serve it (deployed, staging, or http://localhost:3000), call this with the URL and the selector you fixed to get a machine-checked verified: true|false (DOM engines only — visual_audit findings are out of scope). Pass the WCAG criterion (e.g. "1.1.1") or axe rule id (e.g. "color-contrast") to check just that criterion; omit it to require the element be clean of ALL violations. A blocked page (bot-challenge / HTTP error) is reported as unverified, never a pass — verification fails closed. verified: true is only returned when the selector matched at least one element AND the criterion is one the DOM engines check; if the selector matches no element the result is verified: false with reason "not-found" ("selector matched no elements"), a criterion outside the coverage set returns reason "not-verifiable" ("not checked by any WebAbility tool"); a finding in scope that only the AI judge can settle, when the judge did not run or gave no verdict, also returns "not-verifiable", and shadow-DOM (>>>) / iframe selectors return "unsupported-selector" — pass the element's current selector, or re-run scan_page if your fix removed the element. Pair with scan_page → generate_ai_fix → verify_fix for a full find-fix-verify cycle.
- **diff_scan** — Compare two scans of the same page and report what changed: `fixed[]` (in the baseline, gone now), `new[]` (regressions — not in the baseline, present now), `remaining[]` (still there). Page-level complement to verify_fix (one element). Baseline is a scan_history id (`baselineId`, local installs) or a live scan of `baselineUrl`; current is `url` (scanned live now) or another history id (`currentId`). Findings are matched by issue id (rule + element), so a changed class/id on a fixed element reads as fixed AND new — check `new[]` before calling it a regression. Typical loop: scan_page → edit → diff_scan(baselineId=<that scan id>, url=<same url>) → confirm new[] is empty.
- **start_audit** — [Full — FREE with a WebAbility account. Not runnable in Lite. Connect hosted MCP at https://mcp.webability.io/mcp (dashboard or Smithery: webability/accessibility), authenticate, then call `start_audit`.] Kick off a FULL accessibility audit deliverable for a URL — a persistent, timestamped artifact, not an inline scan. Runs the server-side pipeline (axe + advanced checks + mobile viewports + annotated screenshots + optional agent spot-check) and produces a downloadable report and a formatted Excel workbook (Cover / Status / Barriers / ADA context sheets) stored durably. Returns immediately with an audit `id`; poll `get_audit` for progress and, when complete, download URLs. Use this when someone needs a durable artifact to attach as evidence of testing effort for a compliance officer or legal response — for iterating on code, use scan_page + verify_fix instead. Needs a free WebAbility account (sign in by connecting https://mcp.webability.io/mcp/auth, or run `webability login`). Set includeAgent:true to add the slower agentic manual-audit pass. To audit a local dev server, open a tunnel (`webability-tunnel --port 3000`) and pass its URL as `url` with the printed secret as `tunnel_secret`; keep the tunnel open until get_audit reports complete (about 5 minutes) — the pipeline loads the page several times.
- **add_site** — Add a website to the signed-in WebAbility account. The site gets the full widget for its first 30 days and a first scan. Returns the site id and plan tier. Next: put the get_install_snippet tag on the site, and use create_upgrade_link to get a payment link for the WebAbility Pro plan. Needs a free WebAbility account (an AI agent can sign itself up with "Sign in with AgentID").
- **list_sites** — List the sites on the signed-in WebAbility account with each site id, plan tier and the date the current plan ends. Use it to check that a payment activated WebAbility Pro on a site. Needs a free WebAbility account.
- **get_install_snippet** — Get the one-line script tag that installs the WebAbility accessibility widget. Put it in the <head> or before </body> of every page of a site added with add_site. The widget finds the site by its domain, so the same tag works on every site. No account needed.
- **create_upgrade_link** — Get a Stripe Checkout link that puts one site on the WebAbility Pro plan (the widget subscription). Give the link to the human who pays (your owner). When they pay, the plan activates on that site automatically; check with list_sites. You never handle card details. The site must be on the account (add_site first). Needs a free WebAbility account.
- **get_audit** — [Full — FREE with a WebAbility account. Not runnable in Lite. Connect hosted MCP at https://mcp.webability.io/mcp (dashboard or Smithery: webability/accessibility), authenticate, then call `get_audit`.] Check an audit started with start_audit: returns overall status, per-step progress (scan → viewports → screenshots → agent → excel → publish), and — once complete — a severity summary plus short-lived download URLs for the report (JSON) and the Excel workbook. Poll every ~15s while status is pending/running. Only the account that started an audit can read it. Free with a WebAbility account.
- **flow_scan** — Scan a multi-page user journey. Walks startUrl plus the `autoNavigate` URLs sequentially (deterministic — one page fully rendered and scanned before the next), then returns ONE consolidated report with issues deduplicated across pages, each carrying the same fix payload as scan_page. Every requested URL gets an explicit outcome in `pages[]` (scanned / nav_failed / scan_failed / redirected_duplicate / duplicate_request / skipped_cap / blocked — bot-challenge, not a clean page) — a page is never silently dropped. Better than per-page scans for journeys (login → checkout etc). Without `autoNavigate` it scans only startUrl, exactly like scan_page.
- **detect_framework** — Detect a page's stack as two separate fields: `framework` — the application framework, CMS or site builder (e.g. nextjs, nuxt, sveltekit, vitepress, astro, gatsby, wordpress, shopify, mediawiki, vue, react; "unknown" when no signal) — and `cssToolkit` (tailwind, bootstrap, mui, plain-css). Lists the evidence it used and the value to pass as generate_ai_fix `framework`. scan_page reports the same two fields from the same detection.
- **generate_ai_fix** — Generate framework-aware fix alternatives for a specific accessibility issue. For color contrast issues, returns 3 alternatives (minimal, brand-aligned, high contrast); brand palette is auto-extracted from the live URL using our scanner if `brandColors` is omitted. For label/ARIA issues, returns 1-2 alternatives. Each alternative includes ready-to-paste code for the detected framework.
- **visual_audit** — [Full — FREE with a WebAbility account. Not runnable in Lite. Connect hosted MCP at https://mcp.webability.io/mcp (dashboard or Smithery: webability/accessibility), authenticate, then call `visual_audit`.] Pixel-level accessibility audit using Claude vision. Catches issues that DOM scanners miss: icon contrast (1.4.11), focus visibility (2.4.7), "looks like a button but isn't" (4.1.2), text rendered as images (1.4.5), visual hierarchy mismatches. Takes a URL, opens it in a headless browser, screenshots, and runs vision-based detection. Complements scan_page — run both for full coverage. Sign in with a free WebAbility account for vision and full audits (sign in by connecting https://mcp.webability.io/mcp/auth, or run `webability login`). Fair-use rate limits apply.
- **find_source** — Find source files in the local project that contain a given CSS selector. Maps DOM selectors back to source code so you can edit the right file. Searches React/Vue/Svelte/HTML/PHP/Astro files.
- **scan_html** — Scan a raw HTML snippet or component markup without serving it — IN-PROCESS by default (jsdom + WebAbility detectors + axe-core): milliseconds, no browser, no network, so it fits inside a tight edit loop. Fragments are auto-wrapped into a document. Returns scan_page's shape (issues / summary) with `fix.op` + `fixability` on every finding. jsdom has no layout, so visual-tier rules (contrast, target size, focus ring) are NOT evaluated — the dropped count is reported as `skippedVisual`; pass `engine: "browser"` to run the axe-core headless-browser path for those (slower, axe rules only, returns axe `violations`).
- **get_rules** — List accessibility rules from both engines — axe-core (104) and the WebAbility detectors (90+) — with optional filters. Every rule carries `fixability` (mechanical | contextual | visual) and a `fix` op template, so you can pick the rules worth auto-fixing before scanning. Returns ruleId, engine, description, help, helpUrl, tags/wcag, fixability, fix.
- **check_color_contrast** — Check text contrast against the WCAG AA threshold (4.5:1, or 3:1 for large text); the AAA verdict is shown only when you pass level: "AAA". Either pass a `foreground` / `background` color pair, or pass `url` + `selector` to read the element's own text color, background (composited from the nearest painted ancestors), font size and weight from the live page; explicit colors win over the page. A gradient or image background is reported as an error, never a guessed ratio. When it fails, suggests BRAND-aligned replacements — extracts the actual brand palette from the `url` page using our scanner (CSS vars + most-used colors), or use a provided `brandColors` array. No `url` and no `brandColors` = ratio + pass/fail only.
- **check_aria** — Validate ARIA attribute + accessible name/role/value usage — in an HTML snippet (`html`) or on a live page (`url`), optionally limited to one element and its descendants (`selector`). Runs axe-core `cat.aria` and `cat.name-role-value` rules (aria-* attribute correctness, role validity, required parents/children, aria-hidden-focus, accessible names). Returns `violations`. A selector that matches nothing, or a page that answers an HTTP error, is an error — never "no violations". Nodes cap at 5 per rule by default — every rule reports nodesTotal + truncated; raise nodeLimit (max 50) or use scan_history(id) for the full set.
- **scan_history** — Browse past scans run through this MCP server. Every scan_page / flow_scan / scan_html / visual_audit / check_aria / verify_fix call is logged locally (~/.webability/scans; local installs only — the hosted server keeps no history). Without arguments, lists recent scans (when, what target, result summary). Pass `id` to retrieve the FULL stored result of one past scan, or `filter` to match a URL/tool substring.
- **generate_report_pdf** — Turn scan findings into a branded WebAbility accessibility-report PDF, saved next to the project (local installs only). Pass the `issues[]` array a scan_page call returned plus the page `url`; the tool groups findings by functionality (Low Vision / Mobility / Navigation / Content / Cognitive), computes the WCAG score with the same penalty ladder as the platform, and renders a shareable PDF — free, no account. Use it when the user wants a deliverable to attach to an email, ticket, or compliance thread. Capped at 500 findings. For the full audit deliverable (Excel workbook + evidence screenshots), use start_audit instead.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "webability": {
    "command": "npx",
    "args": ["-y","-p","@webability/mcp","webability-mcp"]
  }
}
```

## Documentation

## What webability does

webability brings accessibility checks into an MCP-compatible coding workflow. Its scanning tools inspect URLs, raw HTML, and multi-page journeys for WCAG issues, combining WebAbility detectors with axe-core and deduplicating overlapping findings. Results include issue summaries, selectors, severity, WCAG references, and structured fix operations such as adding, changing, or removing attributes and elements.

The server covers automated checks including contrast, labels, landmarks, ARIA, link consistency, target size, keyboard traps, and other WCAG 2.2 baseline rules. It can also inspect rendered output for visual concerns such as icon contrast, focus visibility, and controls that look interactive without behaving like buttons.

## How it works

`scan_page` runs both scanning engines in parallel. Browser-based scans can expose source locations from React and Vue development builds, including the file, line, column, and component. `scan_html` handles an HTML snippet in process with jsdom; selecting its browser engine enables contrast checks that depend on rendering.

A typical workflow is find, fix, and verify. Use framework detection to identify Tailwind, MUI, Bootstrap, Next.js, WordPress, or plain CSS, then ask `generate_ai_fix` for alternatives appropriate to that framework. `verify_fix` rescans a selected element and reports whether the violation remains. `diff_scan` compares a baseline with the current page and separates fixed, new, and remaining findings.

The hosted endpoint is `https://mcp.webability.io/mcp`. It can scan public URLs without an API key. The local package runs through stdio, launches the browser on the developer’s machine, and can reach localhost and private addresses. Hosted scans cannot directly access those addresses; a tunnel is available for remote or hosted workflows.

## Setup and configuration

For Claude Code, install the WebAbility plugin or add the hosted endpoint with an HTTP MCP transport. Cursor and VS Code provide install links, and other MCP clients can add the hosted URL as a custom connector. A local setup uses `npx -y -p @webability/mcp webability-mcp` as a stdio server.

Basic local scans do not require an account. Local AI judging is disabled until `OPENROUTER_API_KEY` is set; the hosted service performs that judging on its side. `WEBABILITY_JUDGE_BASE_URL`, model variables, timeout settings, and `WEBABILITY_JUDGE=off` control local judging. Optional PostHog variables enable or disable MCP usage analytics, and `WEBABILITY_API_URL` can point local operation at another backend.

## Tools and capabilities

- Scan URLs, HTML fragments, and multi-page journeys with configurable WCAG, rule, impact, and output filters.
- Detect common frontend frameworks and generate fixes with mechanical, contextual, or visual fixability guidance.
- Check color contrast and ARIA attributes independently.
- List available rules and map selectors to local source files when framework source pointers are unavailable.
- Keep local scan history and create a branded PDF from scan findings.
- Run visual audits and start or poll full report and Excel workbook audits on the hosted service with a free account.

## Limitations and notes

Automated results cannot determine whether alt text is meaningful or whether a custom widget is usable with a screen reader. Assistive technology testing is still needed. The server drops findings it cannot settle rather than presenting them as confirmed violations.

The hosted service applies fair-use limits of 30 browser scans per hour and 10 AI fixes per hour per IP. `start_audit` runs on the service and cannot reach a localhost URL, including when invoked through the local transport. Tunnel URLs require a separate secret, accept only GET and HEAD requests on the selected port, and expire after 30 minutes, five minutes of inactivity, or process termination.

_Full upstream README: https://allmcps.com/mcp/webability/readme_