# a11y-mcp-server

An [MCP](https://modelcontextprotocol.io) server that exposes [axe-core](https://github.com/dequelabs/axe-core)
accessibility auditing as tools — so any MCP-compatible agent (Claude Desktop, Claude Code, or any other
MCP client) can audit HTML without a project-specific integration.

This grew out of [`agentic-design-tools`](https://github.com/aiuxmasters/agentic-design-tools)'s
`a11y-review` Claude Code skill: the skill is Claude Code-specific, this is the same auditing capability
as a standard protocol server any agent can call.

## Tools

| Tool | Description |
|---|---|
| `audit_html` | Audit an inline HTML string |
| `audit_file` | Audit a local `.html` file by path |
| `audit_url` | Fetch a URL and audit the raw (server-rendered) response HTML |

Each accepts an optional `tags` array to restrict which axe-core rule tags run, e.g. `["wcag2a", "wcag2aa"]`.

**Scope note:** audits run via [jsdom](https://github.com/jsdom/jsdom), which has no real layout engine. That
reliably catches structural/semantic issues — missing `alt` text, unlabeled form inputs, missing
`lang`/`<title>`, empty link text, and similar — but rules that depend on rendered geometry or computed
color (`color-contrast`, focus-order checks) won't reliably fire. For full WCAG coverage, run axe-core in a
real browser (Playwright/Puppeteer) against the rendered page.

**Security note:** `audit_html` and `audit_url` execute any `<script>` in the input inside a sandboxed jsdom
window (no Node.js API access). Only audit HTML/URLs you trust.

## Install & configure

```bash
npm install -g @aiuxmasters/a11y-mcp-server
```

Add to your MCP client config (e.g. Claude Desktop's `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "a11y": {
      "command": "npx",
      "args": ["-y", "@aiuxmasters/a11y-mcp-server"]
    }
  }
}
```

## Programmatic API

```ts
import { auditHtml } from "@aiuxmasters/a11y-mcp-server";

const result = await auditHtml("<img src='logo.png'>");
console.log(result.violations); // [{ id: "image-alt", impact: "critical", ... }]
```

## Development

```bash
npm install
npm test        # unit tests + a real end-to-end MCP client/server round trip over InMemoryTransport
npm run build
```

## License

MIT — see [LICENSE](./LICENSE).