# WebAbility MCP

Accessibility checks your coding agent can act on: scan a page with two engines, get a structured fix for each issue, then re-check that the fix landed.

Free. Hosted at `https://mcp.webability.io/mcp`. No API key for scans. MIT.

## Install

**Claude Code** (plugin)

```text
/plugin marketplace add snayyar00/webability-mcp
/plugin install webability-accessibility@webability
```

or `claude mcp add --transport http webability https://mcp.webability.io/mcp`

**Cursor**: [Add to Cursor](https://cursor.com/install-mcp?name=webability&config=eyJ1cmwiOiJodHRwczovL21jcC53ZWJhYmlsaXR5LmlvL21jcCJ9)

**VS Code**: [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=webability&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.webability.io%2Fmcp%22%7D) · or run
`code --add-mcp '{"name":"webability","type":"http","url":"https://mcp.webability.io/mcp"}'`

**Claude.ai / ChatGPT / any MCP client**: add a custom connector with the URL `https://mcp.webability.io/mcp`.

**Local** (the browser runs on your machine, so it scans `localhost` directly): `npx -y -p @webability/mcp webability-mcp`

## What you get back

Real output, `scan_page` on https://demo.vercel.store (trimmed):

```text
Found 16 high-confidence issue(s): 0 critical, 4 serious, 8 moderate, 4 minor.
20 additional finding(s) need human review — see incomplete[]. Do NOT auto-fix these.

missing_label · serious · WCAG 1.3.1 · input.text-md.w-full.rounded-lg
  fix: { op: "add-attribute", attribute: "aria-label" }   fixability: contextual
missing_table_scope · moderate · WCAG 1.3.1 · thead > tr > th:nth-of-type(1)   (vite.dev/guide)
  fix: { op: "add-attribute", attribute: "scope", value: "col" }   fixability: mechanical

verify_fix input.text-md.w-full.rounded-lg wcag=4.1.2
  NOT RESOLVED: 1 violation still present → "verified": false
```

- **`fix.op`** is one of `add-attribute`, `set-attribute`, `remove-attribute`, `add-element`, `remove-element`, `add-text-content`, `suggest`.
- **`fixability`**: `mechanical` = apply as given. `contextual` = the op is known, the value (alt text, a label) needs judgment. `visual` = needs rendered output; propose, do not auto-apply.
- **`judged[]`** lists findings the scanner settled itself, each with a verdict and a reason (see Output below). Anything it cannot settle is dropped.
- **`source`**: on React ≤18 and Vue dev builds, each issue carries `{file, line, column, component}` from the live component tree.
- **`verify_fix`** re-scans one element and fails closed. **`diff_scan`** reports `fixed[]`, `new[]`, `remaining[]` for a page.

## Free

| | What you get |
|---|---|
| No account | Scan and check tools on the hosted server. Fair-use limits per IP: 30 browser scans/h, 10 AI fixes/h |
| Free account (OAuth prompt in your client, or `npx -y @webability/cli login` locally) | Adds `visual_audit` (vision pass), `start_audit` / `get_audit` (full report), and `webability-tunnel` (lets the hosted server scan your localhost) |

No trial, no credits, no paid tier on the MCP.

## What it does not do

It cannot judge if alt text is meaningful or if a custom widget makes sense with a screen reader. Use it to clear the automated layer in source, then test with assistive technology.

## Local vs hosted

| | **Lite** — local stdio (`npx` / `webability-mcp`) | **Full** — hosted (`https://mcp.webability.io/mcp`) |
|---|---|---|
| Account | None | None for scan tools; free account (OAuth sign-in) for visual and full audits |
| Scan / fix / verify | Yes (on your machine) | Yes |
| AI judge for uncertain findings | Off until you set `OPENROUTER_API_KEY` (your key) | On, nothing to set (our key) |
| `find_source` | Yes | No |
| `scan_history` / `generate_report_pdf` | Yes | No |
| `visual_audit` / `start_audit` / `get_audit` | Listed as stubs → connect Full (still free) | Yes — free with your account |
| PostHog / dashboard analytics | Optional env only | On by default on hosted |
| **`localhost` / private addresses** | **Yes** — the browser runs on your machine | **Via a tunnel** — see below |

### Scanning a local dev server

**Use Lite (stdio).** It runs the browser on your machine, so `http://localhost:3000` is just localhost:

```bash
claude mcp add webability-local -- npx -y -p @webability/mcp webability-mcp
```

Other clients: add `npx -y -p @webability/mcp webability-mcp` as a stdio server.

**Full (hosted) cannot reach your machine directly, by design.** It runs in our cloud, so `localhost` there means *our* localhost. Every URL is checked before any fetch and loopback / private / link-local addresses are refused: without that check, anyone could point the server at internal services or a cloud metadata endpoint. That check is not relaxed for anyone.

#### When you need hosted: `webability-tunnel`

CI, a remote agent, or a dashboard-triggered scan cannot run Lite, because there is no laptop in the loop. For those, open a tunnel:

```bash
WEBABILITY_API_KEY=<your-token> npx -y -p @webability/mcp webability-tunnel --port 3000
```

It prints a `https://tunnel.webability.io/t/<id>/` URL and a secret. Pass the URL as `url` and the secret as `tunnel_secret`:

> "Scan https://tunnel.webability.io/t/abc123.../ with tunnel_secret &lt;secret&gt;"

Your machine dials **out** to the relay, so the URL is an ordinary public hostname and the SSRF check above still applies unchanged — nothing is weakened to make this work. Same idea as ngrok, with three differences that matter when the thing on the far side is your dev machine:

- **The URL is not a credential.** Every request must carry the secret header; the URL alone returns 401. URLs leak into shell history, CI logs and screenshots.
- **Only `GET` and `HEAD` reach you**, on the one port you named, and `Authorization` / `Cookie` are stripped before anything crosses in.
- **It dies when you do.** 30 minutes, 5 minutes idle, or the moment you press Ctrl-C.

Anyone holding both the URL and the secret can read your dev server. Treat the pair like a password, and prefer Lite whenever there is a human at a keyboard.

Third-party tunnels (ngrok, cloudflared) also work — the hosted scanner treats their hostnames like any other public site — but they expose your dev server to anyone who learns the URL. Vite users, either way: add the tunnel hostname to `server.allowedHosts`, or it answers `403 Blocked request` to everything.

`start_audit` is the exception on both transports — its pipeline runs on our servers even under Lite, so it can never reach a localhost URL.

### Local options

Optional env:

- `WEBABILITY_API_URL` (default `https://api.webability.io`) for self-hosted backends.
- `POSTHOG_PROJECT_API_KEY` or `POSTHOG_API_KEY` to enable PostHog MCP Analytics for MCP initialize, tools/list, and tool-call usage events.
- `POSTHOG_HOST` (default `https://us.i.posthog.com`) for EU or self-hosted PostHog ingestion.
- `WEBABILITY_POSTHOG_MCP_ANALYTICS=off` to force-disable PostHog MCP Analytics even when a PostHog key is present.

## Scan engines

`scan_page` runs two engines in parallel and deduplicates the results:

| Engine | Rules | What it covers |
|--------|-------|----------------|
| WebAbility detectors | 60+ | Gradient-aware contrast, weak names, decorative icons, landmark hierarchy, ARIA correctness, link consistency, target size, keyboard traps |
| axe-core | 104 | Industry-standard WCAG 2.2 baseline |

## Output

Every scan returns:

- **`issues`** — violations the scanner stands behind, safe to surface as bugs
- **`summary`** — counts by severity

The scanner judges uncertain findings itself. Text on a gradient or image background is measured from rendered pixels. What the engines still cannot decide goes to an AI judge, which returns a violation with a concrete fix (alt text, a colour that meets the ratio) or a pass with its reason (listed in `judged[]`). Anything neither can settle is dropped — nothing is left for a human to review. Each judge call sends the page URL, the finding's markup and nearby text, and, when the page can take one, a PNG crop of the element.

**Hosted (`https://mcp.webability.io/mcp`): nothing to set.** The judge runs on our side with our models, for anonymous and signed-in callers alike: the server posts each uncertain finding to WebAbility's API. If our judge is unreachable, the findings it would have settled are dropped, never guessed.

**Local (`npx` / `webability-mcp`): the judge is off until you give it a key.** It is not local inference: your machine calls the model endpoint with your key (OpenRouter, or the `WEBABILITY_JUDGE_BASE_URL` you set). Set `OPENROUTER_API_KEY` to turn it on (vision `anthropic/claude-haiku-4.5`, text-only `deepseek/deepseek-v4-flash`; override with `WEBABILITY_JUDGE_BASE_URL`, `WEBABILITY_JUDGE_VISION_MODEL`, `WEBABILITY_JUDGE_TEXT_MODEL`, budget `WEBABILITY_JUDGE_TIMEOUT_MS`, default 20 s). `WEBABILITY_JUDGE=off` disables it in both modes. Without a key, the model-free verdicts still run (a measured contrast pass, a decorative or 1x1 image, a reduced-motion rule) and land in `judged[]`; findings they cannot settle are dropped.

## Structured fixes (since v1.6.0)

Every issue from `scan_page`, `flow_scan`, `diff_scan` and `scan_html` carries a machine-readable fix and a fixability tier, so an agent can act without parsing prose:

```json
{
  "id": "wa-missing_button_type-a1b2c3",
  "fixability": "mechanical",
  "fix": { "op": "add-attribute", "attribute": "type", "value": "button", "currentValue": "", "needsManualReview": false }
}
```

| Field | Values |
|-------|--------|
| `fix.op` | `add-attribute` · `set-attribute` · `remove-attribute` · `add-element` · `remove-element` · `add-text-content` · `suggest` |
| `fixability` | `mechanical` — value known, apply as given · `contextual` — op known, value needs judgment (alt text, a label) · `visual` — needs rendered output (contrast, focus ring, target size); propose, never auto-apply |

`fix.value` is present only when the engine already knows it. The legacy `fix.attribute` / `currentValue` / `suggestedValue` / `needsManualReview` fields are unchanged. `get_rules` lists the tier for every rule so you can pick the auto-fixable set up front.

## Source pointers (since v1.6.0)

On a React ≤18 or Vue dev build, `scan_page`, `flow_scan` and `diff_scan` read the component tree of the live page and attach the JSX call site to each finding:

```json
{ "selector": "img#hero", "source": { "framework": "react", "file": "/app/src/Hero.tsx", "line": 12, "column": 5, "component": "Hero" } }
```

Open that file — no `find_source` round-trip. React 19 dropped `_debugSource`; there you still get `component`. Production builds have no tree; pass `sourceRoot` (Lite only) and issues without a pointer get `sourceCandidates[]` from a token grep of the selector.

## Output controls (since v1.6.0)

`scan_page`, `flow_scan`, `scan_html` and `diff_scan` accept:

| Param | Effect |
|-------|--------|
| `minImpact` | `minor` · `moderate` · `serious` · `critical` — drop anything below |
| `rules[]` | keep only these rule ids (`missing_alt`, `image-alt`, …) |
| `wcag[]` | keep only these criteria; a prefix like `1.4` matches `1.4.3` |
| `format: "compact"` | one line per element, rule metadata printed once — a fraction of the JSON tokens |

Filters apply before the 50-item cap, so `minImpact: "serious"` returns every serious issue on a 300-issue page. The `scan_history` archive keeps the unfiltered result.

## In-process `scan_html` (since v1.6.0)

`scan_html` no longer launches a browser by default. It runs the WebAbility detectors and axe-core inside jsdom in the MCP process — milliseconds, no network — and returns the same `issues` / `judged` / `summary` shape as `scan_page`, with `fix.op` on every finding. Fragments are wrapped into a document automatically. jsdom has no layout, so visual-tier rules (contrast, target size, focus ring) are skipped and counted in `skippedVisual`; pass `engine: "browser"` for the previous headless-Chromium axe path.

## Tools

| Tool | Edition | What it does |
|------|---------|--------------|
| `scan_page` | Lite + Full | Scan a URL for WCAG accessibility issues (2 engines). `source` pointers on dev builds; `minImpact` / `rules` / `wcag` / `format` output controls |
| `flow_scan` | Lite + Full | Multi-page journey scan with deduplicated issues across pages |
| `scan_html` | Lite + Full | Scan a raw HTML snippet or fragment in-process (jsdom, ms, no browser); `engine: "browser"` for contrast |
| `detect_framework` | Lite + Full | Detect Tailwind / MUI / Bootstrap / Next.js / WP / plain CSS |
| `generate_ai_fix` | Lite + Full | Framework-aware fix alternatives. Auto-extracts brand palette from the live URL on contrast issues. |
| `verify_fix` | Lite + Full | Re-scan a fixed element and confirm the violation is gone — `verified: true/false`. Closes the find → fix → verify loop. |
| `diff_scan` | Lite + Full | Baseline vs current → `fixed[]` / `new[]` / `remaining[]`. Page-level regression check; baseline from `scan_history` (Lite) or a live URL. |
| `check_color_contrast` | Lite + Full | WCAG contrast check on a color pair; pass `url` to get brand-aligned suggestions from the live page |
| `check_aria` | Lite + Full | Validate ARIA attributes in an HTML snippet |
| `get_rules` | Lite + Full | List axe-core + WebAbility rules with `fixability` and a `fix` op template; filter by tag, tier, or engine |
| `find_source` | Lite only | Map a CSS selector back to local source files (fallback when the page has no framework `source` pointer) |
| `scan_history` | Lite only | Browse prior local scans under `~/.webability/scans/` |
| `generate_report_pdf` | Lite only | Turn scan findings into a branded WebAbility accessibility-report PDF saved next to the project — free, no account. Pass the `issues[]` from `scan_page`. For the full audit deliverable (Excel + evidence), use `start_audit`. |
| `visual_audit` | Full (free w/ account; stub on Lite) | Pixel-level audit via vision (icon contrast, focus visibility, looks-like-a-button-but-isn't) |
| `start_audit` | Full (free w/ account; stub on Lite) | Kick off the full server-side audit deliverable (report + Excel workbook). Returns an id to poll. |
| `get_audit` | Full (free w/ account; stub on Lite) | Check an audit's progress and, once complete, get the severity summary + report/workbook download URLs. |

## When to use this MCP

- Building a new component and want it accessible from day one
- Auditing a localhost / staging build before pushing
- Triaging a Lighthouse / axe report — `scan_page` consolidates both engines
- Generating fix suggestions that match the framework you're already using
- Checking color contrast against the user's actual brand palette (not generic suggestions)

## Examples

In Cursor / Claude Code:

> "Scan localhost:3000 for accessibility issues"

> "Walk login → dashboard → checkout and report unique issues across the flow"

> "Suggest a fix for the contrast issue on `.btn-primary` on https://example.com — match their brand colors"

> "What does WCAG 1.4.11 check?"

> "Turn the issues you just found on localhost:3000 into a branded PDF report"

## Privacy, scan logs & telemetry

Every scan is logged **locally** to `~/.webability/scans/` — a one-line-per-scan `index.jsonl` ledger plus the full result of your last 500 scans. Browse them with the `scan_history` tool ("what did we scan earlier?") or plain `jq`. Set `WEBABILITY_SCAN_LOG=off` to disable, `WEBABILITY_SCAN_LOG_DIR` to relocate.

The server also reports one small **telemetry event** per tool call (every tool, not just scans) to the WebAbility API: tool name, a short target label (URL, selector, issue type — never page content), pass/fail, duration, issue counts, and a persistent anonymous install ID. Full scan results, HTML, and generated fix code never leave your machine via telemetry. Set `WEBABILITY_SCAN_TELEMETRY=off` to opt out.

If `POSTHOG_PROJECT_API_KEY` or `POSTHOG_API_KEY` is configured, the server additionally enables PostHog MCP Analytics. This captures MCP usage metadata such as initialize, tools/list, tool name, duration, client name/version, and success/failure. WebAbility strips PostHog's `$mcp_parameters` and `$mcp_response` fields before send, so raw HTML snippets, screenshots, scan responses, and generated code are not sent to PostHog by this integration.

Two tools — `generate_ai_fix` and `visual_audit` — additionally send page content (an HTML snippet or a screenshot) to WebAbility's API so it can call a third-party LLM on your behalf; WebAbility doesn't store that content, but the LLM provider sees it in transit. `generate_report_pdf` (local only) sends the findings you pass it, with their HTML snippets, selectors and the page URL, to WebAbility's API to render the PDF. The AI judge (see Output above) also sends page content for uncertain findings: the page URL, the finding's markup and nearby text, and an element crop. Hosted, it goes to WebAbility's API; local, it goes only to the model endpoint you configured with your own key, and only once you set one. See [PRIVACY.md](./PRIVACY.md) for the full per-tool breakdown and WebAbility's [privacy policy](https://www.webability.io/privacy-policy).

## Links

- [WebAbility](https://www.webability.io) — platform, widget, dashboard
- [Documentation](https://www.webability.io/docs)
- [GitHub](https://github.com/snayyar00/webability-mcp)

## License

MIT