# mcp-a11y-service

MCP server that audits Figma designs and webpages for accessibility compliance.

Accepts two input types:

- **Figma designs** — via Figma MCP's `get_design_context` output
- **Webpages** — any `http://`, `https://`, or `localhost` URL

Both produce a markdown audit report grouped by severity, with per-violation criterion references, concrete fix recommendations, a compliance gap analysis, and a manual review checklist.

## Tools

| Tool | Input | Description |
|------|-------|-------------|
| `audit_webpage(url, standard?)` | URL | Launches headless Chromium, injects axe-core, returns a structured audit report |
| `audit_figma_data(design_context, standard?)` | Figma MCP JSON | Analyzes Figma design JSON for contrast, touch targets, alt text, and more |

Both tools default to WCAG 2.2 AA. Pass the `standard` parameter to target a different standard.

## Supported Standards

### WCAG

| Identifier | Standard |
|------------|----------|
| `wcag22aa` *(default)* | WCAG 2.2 Level AA |
| `wcag22a` | WCAG 2.2 Level A |
| `wcag22aaa` | WCAG 2.2 Level AAA |
| `wcag21aa` | WCAG 2.1 Level AA |
| `wcag21a` | WCAG 2.1 Level A |
| `wcag21aaa` | WCAG 2.1 Level AAA |

### Legal and regulatory

| Identifier | Standard | WCAG basis |
|------------|----------|------------|
| `section508` | Section 508 (U.S. federal ICT law) | WCAG 2.0 AA, audited as WCAG 2.1 AA |
| `en301549` | EN 301 549 v3.2.1 (EU ICT standard) | WCAG 2.1 AA |
| `iso30071` | ISO/IEC 30071-1 (accessibility process standard) | WCAG 2.1 AA + process checklist |

Legal standard audits run the full WCAG automated checks against the underlying basis, then append a manual review checklist covering the standard's additional requirements (functional performance criteria, support documentation, organisational processes, etc.) that axe-core cannot verify automatically.

## Report structure

Every audit report includes:

1. **Summary** — issue counts by severity (Critical / Serious / Moderate / Minor)
2. **Violations** — grouped by severity, each with the criterion reference, affected element, issue description, and fix
3. **Manual review** — checks that cannot be automated (screen reader testing, keyboard navigation, process requirements for legal standards)
4. **Compliance gap analysis** — which conformance levels the page/design passes or fails at, and what's needed to reach the target

## Prompts

| Prompt | Arguments | Description |
|--------|-----------|-------------|
| `audit-figma` | `url`, `standard?` | Orchestrates the two-step flow: Figma MCP → `audit_figma_data` |
| `audit-webpage` | `url`, `standard?` | Runs `audit_webpage` and presents findings by severity |

## Requirements

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

## Installation

```bash
pip install -r requirements.txt
playwright install chromium
```

`axe-core` is downloaded from the CDN on first run and cached locally as `axe.min.js`. No manual download needed.

No `.env` required — webpage audits run locally via Playwright, and Figma credentials live in the Figma MCP configuration.

## Conda environment

This project runs inside a conda environment. Create one and install the dependencies:

```bash
conda create -n <your-env-name> python=3.11
conda activate <your-env-name>
pip install -r requirements.txt
playwright install chromium
```

> The configs below use `myenv` as a placeholder — replace it with your environment name.

## Usage with Claude Code

Run once to register the server:

```bash
claude mcp add a11y /path/to/anaconda3/envs/myenv/bin/python -- /path/to/mcp-a11y-service/server.py
```

Or add it manually to your `.claude/settings.json`:

```json
{
  "mcpServers": {
    "a11y": {
      "command": "/path/to/anaconda3/envs/myenv/bin/python",
      "args": ["/path/to/mcp-a11y-service/server.py"]
    }
  }
}
```

## Usage with Cursor

1. Open **Cursor Settings** → **MCP**
2. Click **Add new global MCP server**
3. Add the following to your `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "a11y": {
      "command": "/path/to/anaconda3/envs/myenv/bin/python",
      "args": ["/path/to/mcp-a11y-service/server.py"]
    }
  }
}
```

4. Restart Cursor. The `a11y` server will appear under **Available Tools** in the MCP panel.

## Usage with VS Code

1. Install the [Claude extension](https://marketplace.visualstudio.com/items?itemName=Anthropic.claude-code) if you haven't already
2. Open your VS Code `settings.json` (`Cmd+Shift+P` → **Preferences: Open User Settings (JSON)**)
3. Add:

```json
{
  "claude.mcpServers": {
    "a11y": {
      "command": "/path/to/anaconda3/envs/myenv/bin/python",
      "args": ["/path/to/mcp-a11y-service/server.py"]
    }
  }
}
```

4. Reload VS Code.

## Running Tests

```bash
pytest
```