Accessibility Audit MCP Guide

How the Accessibility Audit MCP fits your workflow, what to expect, and how we use LLM-oriented WCAG A/AA coverage in audit_accessibility_violations and fix_accessibility_violations.

Overview

The Accessibility Audit MCP helps you scan and fix web accessibility issues in your codebase. It checks for compliance with WCAG 2.0 / 2.1 / 2.2 Level A and AA — the standard most teams use for web accessibility.

This guide walks you through using it effectively: auditing, reading the report, and applying fixes.

What can it do?

Audit accessibility violations

Scans your codebase (folder or files you specify) for accessibility problems
Checks against WCAG Level A and AA requirements used in the audit instruction set
Flags images, color contrast, keyboard use, semantic HTML, and related issues
Can add inline comments in code marking each violation (per your workflow)
Produces a detailed report — typically accessibility-report.md

Fix accessibility violations

Reads the generated report and remediates issues the tool knows how to fix
Applies WCAG-aligned fixes in your source files when you run the fix flow
Removes violation comments after successful fixes (where applicable)
Produces a summary of changes

Getting started: 3 simple steps

Step 1: Run an audit

Tell the tool where your code lives and which file types to include.

Tool name: audit_accessibility_violations

Required parameters

target_path — folder or file to scan (for example /path/to/your/project/src)

Optional parameters

file_extensions — list of extensions to check. Default often includes .html, .vue, .jsx, .tsx, .js, .ts. Example: [".vue", ".html", ".jsx"]

What happens

Files under target_path are scanned
Violations may be annotated with inline comments (depending on configuration)
A report file such as accessibility-report.md is generated

Example comments in code

<!-- VIOLATION 1.1.1: Image missing alt attribute -->
<img src="logo.png">

<!-- VIOLATION 1.4.3: Insufficient color contrast (2.5:1, needs 4.5:1) -->
<p style="color: #777;">Low contrast text</p>

Step 2: Review the report

Open accessibility-report.md. You should see:

Total violations by severity (Level A vs AA framing as used in the report)
Locations (file path and line references)
Short description of what is wrong
Remediation hints aligned with WCAG

Step 3: Apply fixes

Tool name: fix_accessibility_violations

Required parameters

report_path — path to the report from Step 1
target_path — same root you audited in Step 1

Optional parameters

auto_fix — true (default) to apply fixes, or false to review suggestions only

What happens

The tool reads the report
Applies fixes it supports, in a WCAG-aligned way
Strips violation comments where fixes landed
Writes a summary of changes

What violations does it check for?

Audits are organized around the four WCAG principles (Level A and AA scope in this MCP flow):

Perceivable

Missing alternative text on images
Missing or insufficient captions / alternatives for media (where applicable)
Poor color contrast
Text sizing and readability issues surfaced by rules

Operable

Keyboard access and focus
Interactive components that fail keyboard or focus expectations
Motion / flashing content rules where checked
Skip links and navigation patterns (where applicable)

Understandable

Labels, instructions, and predictable behavior
Form inputs and naming
Consistent navigation and identification (where rules apply)

Robust

Valid, parseable markup patterns the rules target
ARIA usage and roles where checked
Compatibility with assistive technology expectations in scope

Common violations and how they are fixed

Issue	WCAG rule (typical)	Fix direction
Image with no alt text	1.1.1	Add a descriptive `alt` (or appropriate pattern for decorative images)
Low color contrast	1.4.3	Adjust foreground/background to meet contrast ratio (commonly 4.5:1 for normal text)
Button with no accessible name	4.1.2	Add visible text, `aria-label`, or associated labelling
Form input without label	1.3.1	Associate `<label>` with `for`/`id` or equivalent
Non-semantic controls	1.3.1 / 4.1.2	Prefer native elements (`<button>`, headings, landmarks) where possible
Missing keyboard support	2.1.1	Ensure operability via keyboard; add handlers only when needed

Tips for best results

Start small

Run the audit on one folder (for example /src/components) before scanning the whole repo.

Review before bulk fixes

Read accessibility-report.md first. Use auto_fix: false when you want suggestions without writing files.

Iterate

Re-run the audit after fixes. Some items stay manual (context-heavy or design decisions).

Learn WCAG

The report and inline comments tie back to criteria. Understanding “why” helps you avoid repeats. Authoritative reference: WCAG Quick Reference.

Verify with assistive tech

Spot-check with a screen reader (NVDA, VoiceOver) and keyboard-only navigation after meaningful changes.

File support

Format	Typically supported
HTML	Yes
Vue	Yes
React (JSX)	Yes
TypeScript (TSX)	Yes
JavaScript / TypeScript	Yes (when templates or a11y patterns appear in scope)
Other	Add extensions via `file_extensions` if your MCP tool supports them

Important notes

Limitations

Some failures need human judgment (copy, design, complex widgets).
Auto-fix works best for clear, structural issues.
Always review diffs — tools do not replace design or QA.
Accessibility is also UX; compliance is necessary but not sufficient alone.

Safety

The audit flow primarily annotates and reports; review before committing.
The fix flow modifies source files — use version control and CI review.
Prefer staging or a branch when trying auto_fix for the first time.

Compliance levels (reminder)

Level A — baseline, must-fix items for many policies
Level AA — common organizational target for web content
Level AAA — stricter; not required for most general sites

This MCP guide focuses on A and AA coverage in the audit instruction set.

Next steps

Run your first audit on a bounded path
Read accessibility-report.md and triage by severity
Apply fixes (manually, via MCP, or mixed)
Re-audit to confirm
Automate repeats in CI where your team allows (report-only is a safe start)

Need more help?

Use inline comments and the report for criterion-level detail
Cross-check WCAG documentation for edge cases
Engage accessibility specialists for high-risk or regulated experiences

Remember: Accessibility is for everyone using your product — good patterns improve clarity and resilience for all users.

← Back to Quality Engineering Tools Suite

↑ Top of page