# A11y Expert MCP

[![PyPI version](https://img.shields.io/pypi/v/a11y-expert-mcp)](https://pypi.org/project/a11y-expert-mcp/)
[![Python 3.11+](https://img.shields.io/pypi/pyversions/a11y-expert-mcp)](https://pypi.org/project/a11y-expert-mcp/)

An accessibility expert for your AI coding assistant. This [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server gives AI tools like Claude, Cursor, and Windsurf real-time access to WAI-ARIA patterns, code review, contrast checking, and WCAG guidance — so the code they write is accessible from the start.

## What's Inside

### 🔧 Tools

| Tool                 | What it does                                                                                                                                                                                                                                    |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`get_pattern`**    | Get the full WAI-ARIA implementation pattern for any UI component — roles, states, keyboard interaction, and code examples.                                                                                                                     |
| **`review_code`**    | Paste HTML/JSX/TSX/Vue/Svelte code and get a list of accessibility issues with specific fixes and WCAG references. Detects 10+ anti-patterns including missing labels, click-on-divs, broken heading hierarchy, missing dialog roles, and more. |
| **`list_patterns`**  | See all 33 component patterns available in the knowledge base.                                                                                                                                                                                  |
| **`check_contrast`** | Check any two hex colors against WCAG AA and AAA contrast requirements for both normal and large text.                                                                                                                                          |

### 📚 Knowledge Base (33 Components)

Every pattern comes from the [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) and includes roles, states, properties, keyboard interaction, and code examples.

> **Canonical source:** The 33 pattern instruction files in this server are synced from [`a11y-skills`](https://github.com/Elizabeth1979/a11y-skills), the community-maintained source of truth. If you want to contribute a new pattern or improve an existing one, open the PR there.

|                         |                |                      |                 |
| ----------------------- | -------------- | -------------------- | --------------- |
| Accordion               | Alert          | Alert Dialog         | Breadcrumbs     |
| Buttons                 | Carousel       | Checkbox             | Combobox        |
| Dialog (Modal)          | Disclosure     | Feed                 | Grid            |
| Headings                | Image Labeling | Landmarks            | Link            |
| Listbox                 | Menu           | Menu Button          | Meter           |
| Radio                   | Slider         | Slider (Multi-thumb) | Spinbutton      |
| Switch                  | Tables         | Tabs                 | Toolbar         |
| Tooltip                 | Treeview       | Treegrid             | Window Splitter |
| Accessibility (General) |                |                      |                 |

### 💬 Prompts

Pre-built workflows your AI assistant can use:

| Prompt                         | What it does                                                                                                                                      |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`audit-component`**          | Step-by-step accessibility audit — checks ARIA, keyboard, focus, contrast, headings, touch targets. Provide code + optional component type.       |
| **`make-accessible`**          | Rewrites inaccessible code into a fully accessible implementation with WAI-ARIA patterns and comments explaining every change.                    |
| **`check-form-accessibility`** | Form-specific audit — labels, required fields, error handling, fieldsets, autocomplete, tab order, and submit feedback.                           |
| **`wcag-checklist`**           | Generates a WCAG 2.2 compliance checklist (AA or AAA) organized by principle, tailored to your page or component.                                 |
| **`aria-guide`**               | Complete ARIA implementation guide for a component — roles, attributes, keyboard table, focus management, screen reader script, and code example. |

### 📖 Resources

Browsable knowledge base for MCP clients:

- **`a11y://patterns`** — Index of all 33 component patterns
- **`a11y://patterns/{component}`** — Full pattern detail for any component

## Installation

### Prerequisites

- Python 3.11+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

### Option 1: Run directly with uvx (no install needed)

```bash
uvx a11y-expert-mcp
```

### Option 2: Install with pip

```bash
pip install a11y-expert-mcp
```

Then run:

```bash
a11y-expert-mcp
```

### Option 3: Run from source

```bash
git clone https://github.com/Elizabeth1979/a11y-expert-mcp.git
cd a11y-expert-mcp
uv run a11y-expert-mcp
```

## Configuration

### Claude Desktop / Claude Code

Add to your MCP config (`~/.claude/config.json` or Claude Desktop settings):

```json
{
  "mcpServers": {
    "a11y": {
      "command": "uvx",
      "args": ["a11y-expert-mcp"]
    }
  }
}
```

Or if running from source:

```json
{
  "mcpServers": {
    "a11y": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/a11y-expert-mcp",
        "a11y-expert-mcp"
      ]
    }
  }
}
```

### Cursor / Windsurf / Other MCP Clients

Use the same `command` and `args` — check your editor's MCP configuration docs for the exact config file location.

## Usage Examples

Once connected, your AI assistant can:

**Get an accessible pattern:**

> "How do I build an accessible tabs component?"
> → The assistant calls `get_pattern("tabs")` and gets the full WAI-ARIA pattern with keyboard interaction and code.

**Review code for issues:**

> "Check this modal for accessibility problems"
> → The assistant calls `review_code(code, component_type="modal")` and gets specific issues with fixes.

**Check color contrast:**

> "Does #666 on #fff pass WCAG?"
> → The assistant calls `check_contrast("#666", "#fff")` and gets AA/AAA results for normal and large text.

**Generate a WCAG checklist:**

> "Give me a WCAG AA checklist for my checkout page"
> → The assistant uses the `wcag-checklist` prompt to generate a tailored compliance checklist.

## How It Works

The server bundles 33 WAI-ARIA pattern documents as a knowledge base. When your AI assistant asks about a component, it gets the real specification — not hallucinated ARIA attributes. The `review_code` tool runs 10+ static checks for common anti-patterns (click handlers on divs, missing labels, broken heading hierarchy, positive tabindex, etc.) and cross-references relevant patterns.

No external API calls. No database. Everything runs locally.

## Tech Stack

- [MCP SDK](https://github.com/modelcontextprotocol/python-sdk) (FastMCP)
- Python 3.11+
- WAI-ARIA Authoring Practices knowledge base (bundled markdown files)

## Related tools

Part of a broader accessibility engineering toolkit. Pair this with:

- **[`screen-reader-cli`](https://github.com/Elizabeth1979/screen-reader-cli)** — CLI for screen-reader-driven testing. Where `a11y-expert-mcp` gives your AI assistant static guidance (patterns, code review), `screen-reader-cli` runs live screen-reader checks against real pages using Virtual Screen Reader + Playwright. Static + runtime = full coverage.
- **[`a11y-skills`](https://github.com/Elizabeth1979/a11y-skills)** — Canonical source for the pattern instruction files this server serves.
- **[`a11y-engineering-toolkit`](https://github.com/Elizabeth1979/a11y-engineering-toolkit)** — Umbrella repo with browser-side audit panel + UX widget, plus the full portfolio map.

## License

MIT

## Author

Elli ([@Elizabeth1979](https://github.com/Elizabeth1979))