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.7.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
  • Jest (unit/component tests via @axe-devtools/browser)
  • 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

curl -fsSL https://raw.githubusercontent.com/dequelabs/axe-devtools-implementation-agent-public/main/setup.sh | bash

Windows (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

chmod +x axe-imp-agent-macos
xattr -d com.apple.quarantine axe-imp-agent-macos

Linux

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.

{
    "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.

{
    "mcpServers": {
        "axe-imp-agent": {
            "command": "/path/to/axe-imp-agent-executable",
            "args": ["mcp"]
        }
    }
}

Claude (Claude Code / Claude Desktop)

Claude uses the mcpServers format. For Claude Code, place the config in .mcp.json at the root of your project. For Claude Desktop, add the mcpServers block to claude_desktop_config.json.

{
    "mcpServers": {
        "axe-imp-agent": {
            "command": "/path/to/axe-imp-agent-executable",
            "args": ["mcp"]
        }
    }
}

Gemini CLI

Add the mcpServers block to .gemini/settings.json (project root) or ~/.gemini/settings.json (global).

{
    "mcpServers": {
        "axe-imp-agent": {
            "command": "/path/to/axe-imp-agent-executable",
            "args": ["mcp"]
        }
    }
}

ChatGPT Codex CLI

Codex uses TOML. Merge this block into ~/.codex/config.toml.

[mcp_servers.axe-imp-agent]
command = "/path/to/axe-imp-agent-executable"
args = ["mcp"]

Or register it via the CLI: codex mcp add axe-imp-agent -- /path/to/axe-imp-agent-executable mcp

opencode

opencode uses an mcp block where command is an array. Add this to opencode.json (project root) or ~/.config/opencode/opencode.json.

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "axe-imp-agent": {
            "type": "local",
            "command": ["/path/to/axe-imp-agent-executable", "mcp"],
            "enabled": true
        }
    }
}

Config formats for third-party agents can change between releases — if a template stops working, check that agent's current MCP docs.

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)