Content
# Axe DevTools Implementation Agent
> **⚠️ Disclaimer:** This software is a pre-release and is not officially supported by Deque Systems, Inc. It is provided "as is" without warranty of any kind. Deque shall not be held responsible for any issues, damages, or losses caused by the use of this tool. **Do not run this tool against production branches of your projects.** Always use a dedicated development or feature branch when working with this agent.
**Note:** This is the public facing repository with release binaries only.
The implementation agent is an MCP server that can be installed on a developer's workstation and will help with the implementation of Deque's Axe DevTools for Web products using the IDE's AI chat agent.
As of version 0.5.0 the agent supports the implementation of:
- **axe-watcher** (results → axe Developer Hub)
- Java Selenium
- Cypress
- Playwright (library)
- Playwright Test
- Puppeteer
- WebdriverIO (coming soon)
- **axe DevTools API** (local scan results + reporter)
- Playwright
- Cypress
- Puppeteer
- Java Selenium
- Python Robot Framework
- **axe DevTools CLI** — standalone page/workflow testing
- **Linter Pre-commit Hook** — block commits with accessibility defects
- **axe-linter.yml** (`#adt-linter-yml`) — map custom components, set `exclude` paths, and configure `global-libraries` for DevTools Linter (starter file written only if none exists)
- **axe MCP Server** — AI-powered accessibility analysis in your IDE
- **Multi-language support** — all responses can be displayed in your preferred language
The agent also automatically detects:
- Testing frameworks in your project (JavaScript, Python, Java, and more)
- CDP-enabled browsers (Chrome for Testing or Chromium) needed for axe-watcher
- Docker and Podman (when present, for axe MCP Server setup guidance)
- Package access to Deque's Agora artifact repository (npm, Maven, pip)
- Existing axe DevTools integrations already in your project
The MCP server itself is a single self-contained executable that does not have any external dependencies like network access or Docker.
## Quick Setup
**macOS / Linux**
```bash
curl -fsSL https://raw.githubusercontent.com/dequelabs/axe-devtools-implementation-agent-public/main/setup.sh | bash
```
**Windows** (PowerShell)
```powershell
irm https://raw.githubusercontent.com/dequelabs/axe-devtools-implementation-agent-public/main/setup.ps1 | iex
```
The script downloads the binary, detects your IDE (VS Code or Cursor), and writes the MCP config automatically.
---
## Manual Installation Instructions
1. Download the release for your operating system from the Releases section.
2. Once downloaded, place the executable someplace that would be accessible to your IDE.
3. Add MCP configuration to the IDE (see below).
### macOS and Linux Instructions
The downloaded executables will need an extra step on macOS and Linux to make them executable.
**macOS**
```shell
chmod +x axe-imp-agent-macos
xattr -d com.apple.quarantine axe-imp-agent-macos
```
**Linux**
```shell
chmod +x axe-imp-agent-linux
```
## MCP Configurations
### VS Code
Place `mcp.json` in the `.vscode` directory in the root of your project or root of your home directory.
```json
{
"servers": {
"axe-imp-agent": {
"command": "/path/to/axe-imp-agent-executable",
"args": ["mcp"]
}
}
}
```
### Cursor
Place `mcp.json` in the `.cursor` directory in the root of your project or root of your home directory.
```json
{
"mcpServers": {
"axe-imp-agent": {
"command": "/path/to/axe-imp-agent-executable",
"args": ["mcp"]
}
}
}
```
## Using in IDE AI Chat
Before starting, confirm you are in the project you wish to implement Axe DevTools in.
⚠️ It is recommended to run the Implementation Agent on a non-production branch. The `#adt-start` command will check the branch before continuing with the implementation.
🤖 Make sure your IDE's AI chat is in **Agent mode**.
Once configured, use these commands in your IDE's AI chat:
### Complete Workflow (Recommended)
```
#adt-start → Step 1: Welcome, language selection & Git branch management
#adt-discovery → Step 2: Scan frameworks, detect browser & environment
#adt-solution → Step 3: Get personalized recommendations
#adt-agora-access → Step 4: Set up Agora registry access (required for @axe-devtools packages)
#adt-watcher → Step 5a: Implement axe-watcher (results → Developer Hub)
#adt-api → Step 5b: Implement axe DevTools API (local scan results)
#adt-reporter → Step 5c: Add HTML/CSV/XML report generation (after API only)
#adt-setup-precommit → Step 6a: Complete pre-commit hook integration (web frameworks)
#adt-linter-yml → Step 6b: Customize axe-linter.yml for your project's components
#adt-axe-mcp → Step 7: Add AI-powered accessibility analysis and remediation in your IDE
```
### Individual Commands
| Command | Description |
|---------|-------------|
| `#adt-hello` | Test the MCP server connection |
| `#adt-start` | Welcome intro, choose your preferred language, and Git branch management |
| `#adt-discovery` | Scan your project for testing frameworks, detect CDP browser (Chrome for Testing / Chromium), verify package access, and detect environment |
| `#adt-agora-access` | Set up access to Deque's Agora artifact repository (NPM/Yarn, Maven, pip) — credentials never pass through chat |
| `#adt-solution` | Get personalized accessibility integration recommendations based on your project |
| `#adt-watcher` | Implement axe-watcher with framework-specific instructions — results go to axe Developer Hub |
| `#adt-api` | Implement axe DevTools API with framework-specific instructions — produces local scan results |
| `#adt-reporter` | Add HTML/CSV/XML report generation (only after `#adt-api` — not used with `#adt-watcher`) |
| `#adt-cli` | Standalone page/workflow accessibility testing without framework changes |
| `#adt-setup-precommit` | Set up pre-commit hook integration for web frameworks |
| `#adt-linter-yml` | Generate or customize axe-linter.yml with component mappings, exclusions, and library configs |
| `#adt-axe-mcp` | Set up axe MCP Server for AI-powered accessibility analysis (requires Docker or Podman) |
| `#adt-set-python-venv` | Set or change the Python virtual environment path and test pip access |
| `#adt-implementations` | Show available implementation options based on your project's discovery data, with install status |
| `#adt-set-language` | Change the language for all responses (e.g., `#adt-set-language language: "es"` for Spanish) |
> **Note:** Choose either `#adt-watcher` OR `#adt-api` for a given test suite — do not implement both on the same test files.
### Language Support
The `#adt-start` command will ask you to choose your preferred language before proceeding. You can also change the language at any time by running `#adt-set-language` with a locale code or language name (e.g., `es`, `French`, `日本語`).
### Browser Requirements for axe-watcher
axe-watcher requires a CDP-enabled browser — either **Chrome for Testing** or **Chromium**. The `#adt-discovery` command will check if one is already available in your environment. During watcher setup (`#adt-watcher`), the agent will offer you the choice to:
1. **Install Chrome for Testing** (recommended) — `npx @puppeteer/browsers install chrome@stable`
2. **Install Chromium** — `npx playwright install chromium`
3. **Use an already-installed browser** — provide the path
4. **Install it yourself** — download manually and supply the path
> **Java Selenium note:** Selenium 4.x CDP only supports up to ~v122, so you must use Chrome for Testing v122 or Chromium ~v122 (not the latest).
## Video Demo
▶️ [Watch the Demo on YouTube (v 0.2.0)](https://www.youtube.com/watch?v=PkagCwknrfA)
