# mcp-a11y-tools

Web accessibility analysis tools for AI agents, served over the Model Context Protocol (MCP).

## Tools

### check_alt_text
Analyze images in HTML for missing, empty, or low-quality alt text.
- Detects missing `alt` attributes
- Identifies decorative images (`alt=""` with `role="presentation"`)
- Flags low-quality alt text (e.g., "image", "photo", filenames)
- Checks linked images, `<input type="image">`, and `<area>` elements

### check_heading_hierarchy
Validate heading structure for proper nesting and content quality.
- Verifies h1-h6 order with no skipped levels
- Ensures a single `<h1>` per page
- Detects empty, too-short, or too-long headings
- Supports `role="heading"` with `aria-level`
- Returns a visual tree of the heading outline

### check_color_contrast
Check WCAG 2.x contrast ratio for foreground/background color pairs.
- Calculates precise contrast ratio per WCAG relative luminance formula
- Reports AA and AAA compliance for normal and large text
- Accepts hex (`#fff`, `#ffffff`), `rgb(r,g,b)`, and named colors

### validate_aria
Validate ARIA attributes on HTML elements.
- Detects invalid ARIA roles
- Checks for missing required ARIA properties per role
- Flags redundant ARIA roles that match native semantics
- Warns about `aria-label` on non-interactive elements
- Catches `aria-hidden="true"` on focusable elements

### check_form_accessibility
Audit form elements for accessibility compliance.
- Verifies every input has an associated label (explicit, implicit, or ARIA)
- Checks radio/checkbox groups for `<fieldset>` and `<legend>`
- Flags placeholder text used as the only label
- Suggests `autocomplete` attributes for personal info fields
- Detects duplicate IDs that break label association

## Setup

```bash
npm install
npm run build
```

## Usage with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "a11y-tools": {
      "command": "node",
      "args": ["D:/products/mcp-servers/mcp-a11y-tools/dist/index.js"]
    }
  }
}
```

## License

MIT