Metadata-Version: 2.4
Name: a11y-mcp
Version: 0.1.0
Summary: MCP server for accessibility testing with Cloudflare bypass using Camoufox and axe-core
Project-URL: Homepage, https://github.com/antonio-rmrz/a11y-mcp
Project-URL: Repository, https://github.com/antonio-rmrz/a11y-mcp
Project-URL: Documentation, https://github.com/antonio-rmrz/a11y-mcp#readme
Project-URL: Issues, https://github.com/antonio-rmrz/a11y-mcp/issues
Project-URL: Changelog, https://github.com/antonio-rmrz/a11y-mcp/blob/main/CHANGELOG.md
Author: Antonio Ramirez
License: MIT
License-File: LICENSE
Keywords: a11y,accessibility,automation,axe-core,cloudflare,deque,mcp,model-context-protocol,testing,wcag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: camoufox[geoip]>=0.4.0
Requires-Dist: jinja2>=3.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# a11y-mcp

[![PyPI](https://img.shields.io/pypi/v/a11y-mcp)](https://pypi.org/project/a11y-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

MCP server for running [axe-core](https://github.com/dequelabs/axe-core) accessibility audits. Uses [Camoufox](https://github.com/daijro/camoufox) to bypass Cloudflare and other bot protection.

## Install

```bash
# Claude Code
claude mcp add a11y -- uvx a11y-mcp

# Or with pip
pip install a11y-mcp
```

## Configuration

For Claude Desktop, add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

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

<details>
<summary>Other editors (Cursor, VS Code, Zed, etc.)</summary>

Most editors use the same format. Add to your MCP config:

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

Config locations:
- **Cursor**: `~/.cursor/mcp.json`
- **VS Code (Continue)**: `.continue/config.json` under `experimental.modelContextProtocolServers`
- **VS Code (Cline)**: Cline MCP settings
- **Zed**: `~/.config/zed/settings.json` under `context_servers`

</details>

## Tools

| Tool | Description |
|------|-------------|
| `scan_page` | Scan a URL for WCAG violations |
| `scan_element` | Scan a specific CSS selector |
| `get_violations` | Get detailed violation info from last scan |
| `get_full_report` | Full axe results (violations, passes, incomplete) |
| `export_report` | Export as JSON, HTML, or CSV |
| `set_wcag_level` | Set WCAG level (A, AA, AAA, 21A, 21AA, 22AA) |
| `configure_rules` | Enable/disable specific axe rules |

## Usage

```
> Scan https://example.com for accessibility issues

> Export an HTML report for the last scan

> Check WCAG 2.2 AA compliance for https://adobe.com
```

## WCAG Levels

| Level | Standard |
|-------|----------|
| `A`, `AA`, `AAA` | WCAG 2.0 |
| `21A`, `21AA` | WCAG 2.1 |
| `22AA` | WCAG 2.2 |

Default is `AA`.

## Cloudflare Bypass

This uses Camoufox, an anti-detect browser with fingerprint spoofing at the C++ level. It handles JavaScript challenges, Turnstile, and most bot detection automatically.

On first run, Camoufox downloads a browser binary (~300MB).

## Requirements

- Python 3.10+
- macOS, Linux, or Windows

## Troubleshooting

**Browser won't launch**: Run `python -c "import camoufox; camoufox.install()"`

**Cloudflare still blocking**: Some sites have aggressive detection. The first visit may require manual verification.

**axe-core won't inject**: Likely a strict CSP. Try a different page on the same domain.

## Development

```bash
git clone https://github.com/antonio-rmrz/a11y-mcp
cd a11y-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
python -m camoufox fetch
pytest
```

Debug with the MCP inspector:
```bash
npx @modelcontextprotocol/inspector uvx a11y-mcp
```

## License

MIT. Bundles [axe-core](https://github.com/dequelabs/axe-core) (MPL-2.0).
