A11y Devkit Deploy

A fully config-driven, cross-platform CLI for deploying accessibility skills and MCP servers across multiple IDEs: Claude Code, Cursor, Codex, VSCode, Windsurf, and Factory.

Add new skills, MCP servers, or entire IDEs without writing code - just edit the JSON config and re-run.

Install

npm install -g a11y-devkit-deploy
# or
npx a11y-devkit-deploy

Usage

a11y-devkit-deploy

Flags

--local / --global: Skip the scope prompt.
--yes: Use defaults (local scope, all IDEs, install skills).
--uninstall: Remove skills and MCP entries installed by this tool.

Note: MCP configs are always written globally (AppData/Application Support). The scope flag only affects skills.

After Installation

Once installation completes, you'll find a comprehensive usage guide in your IDE's skills directory:

Local install: .claude/skills/a11y/a11y-devkit-README.md (or .cursor/skills/a11y/, .codex/skills/a11y/ depending on your IDE)
Global install: ~/.claude/skills/a11y/a11y-devkit-README.md (or your IDE's global skills directory)

What's in the Guide

The bundled README includes:

70+ example prompts organized by complexity level (beginner to advanced)
Quick reference cheat sheet for common tasks
Skill descriptions explaining when to use each of the 7 skills
MCP server guides with verification steps and example queries
Combined workflows showing how to use skills and MCP servers together
Complete audit examples using the orchestrator for end-to-end accessibility testing

Preview the Guide

You can preview the guide here: templates/deploy-README.md

Next Steps

Open the README in your IDE's skills directory
Try the "Getting Started" prompts to verify everything is working
Explore the example prompts library to find workflows that match your needs
Use the MCP verification section to test all 5 MCP servers

MCP Servers

All MCP servers are configured to run via npx, which means:

No local installation or cloning required
Automatically fetches the latest version when needed
No disk space used for local copies
Just restart your IDE and the servers will be available

What It Does

This CLI automates the setup of accessibility tooling by:

Installing skills from npm - Downloads and installs accessibility skill packages (configurable in config/settings.json)
Configuring MCP servers - Updates each IDE's MCP config to enable accessibility-focused MCP servers (also configurable)

Default configuration includes:

7 accessibility skills - Testing, remediation, validation, documentation, and orchestration
5 MCP servers:
- wcag - WCAG 2.2 guidelines, success criteria, and techniques
- aria - WAI-ARIA roles, states, properties, and patterns
- magentaa11y - Component accessibility acceptance criteria
- a11y-personas - Accessibility personas for diverse user needs
- arc-issues - Format AxeCore violations into standardized issue templates

Fully customizable - add/remove skills, MCP servers, or entire IDEs by editing the config file.

Why This Tool?

Zero Hardcoded Values - Every aspect of the tool is driven by config/settings.json:

IDE paths and configuration files
Skills to install
MCP servers to configure
Even the IDE list itself

Adding Support for a New IDE takes just 5 lines of JSON:

{
  "id": "new-ide",
  "displayName": "New IDE",
  "mcpServerKey": "servers",
  "skillsFolder": ".new-ide/skills",
  "mcpConfigFile": ".new-ide/mcp.json"
}

Safe by Default - Won't overwrite your existing:

Custom MCP servers in your IDE configs
Other skills in your skills directories
Creates backups if it encounters JSON parsing errors

Skills Installed (Default)

The following skill packages are installed from npm by default. Add your own by editing config/settings.json:

Skill	Package	Description
a11y-base-web	`a11y-base-web-skill`	Foundational accessibility patterns for web code
a11y-issue-writer	`a11y-issue-writer-skill`	Write clear accessibility issue reports
a11y-tester	`a11y-tester-skill`	Automated testing with axe-core and Playwright
a11y-remediator	`a11y-remediator-skill`	Fix accessibility issues in code
a11y-validator	`a11y-validator-skill`	Validate accessibility compliance
web-standards	`web-standards-skill`	Web standards and best practices
a11y-audit-fix-agent-orchestrator	`a11y-audit-fix-agent-orchestrator-skill`	Orchestrate full audit and fix workflows

No Local MCP Installation Required!

MCP servers are configured to use npx, which means:

No cloning of MCP server repositories
No building or npm install steps
No disk space used for local copies
Always up-to-date - npx fetches the latest version automatically

The generated MCP config looks like this:

{
  "mcpServers": {
    "wcag": {
      "command": "npx",
      "args": ["-y", "wcag-mcp"]
    },
    "aria": {
      "command": "npx",
      "args": ["-y", "aria-mcp"]
    }
  }
}

Configuration

The entire tool is fully config-driven. Edit config/settings.json to customize everything without touching code.

Adding a New Skill

Simply add an object to the skills array with a name (npm package) and description:

{
  "skills": [
    {
      "name": "a11y-tester-skill",
      "description": "Run accessibility tests"
    },
    {
      "name": "your-custom-skill",
      "description": "Your custom skill description"
    }
  ]
}

Adding a New MCP Server

Add an object to the mcpServers array with name, description, command, and args:

{
  "mcpServers": [
    {
      "name": "wcag",
      "description": "WCAG guidelines reference",
      "command": "npx",
      "args": ["-y", "wcag-mcp"]
    },
    {
      "name": "your-custom-mcp",
      "description": "Your custom MCP server",
      "command": "npx",
      "args": ["-y", "your-mcp-package"]
    }
  ]
}

Adding a New Host Application

Add an object to the hostApplications array with the host application's configuration:

{
  "hostApplications": [
    {
      "id": "windsurf",
      "displayName": "Windsurf",
      "mcpServerKey": "servers",
      "skillsFolder": ".codeium/windsurf/skills",
      "mcpConfigFile": ".codeium/windsurf/mcp_config.json"
    },
    {
      "id": "vscode",
      "displayName": "VSCode",
      "mcpServerKey": "servers",
      "skillsFolder": ".github/skills",
      "mcpConfigFile": "Code/User/mcp.json"
    }
  ]
}

Host Application Configuration Properties:

id - Unique identifier for the host application
displayName - Human-readable name shown in prompts
mcpServerKey - MCP config key name ("servers", "mcpServers", or "mcp_servers" for TOML)
skillsFolder - Path to skills directory (relative to home/project root)
mcpConfigFile - Path to MCP config file (relative to AppData/Application Support). Supports both JSON (.json) and TOML (.toml) formats. TOML format is auto-detected by file extension (used by Codex):
- Windows: %APPDATA% (e.g., C:\Users\name\AppData\Roaming)
- macOS: ~/Library/Application Support
- Linux: $XDG_CONFIG_HOME or ~/.config

Note: Codex uses TOML format for its MCP configuration (~/.codex/config.toml), which requires the mcpServerKey to be "mcp_servers" and generates config entries like:

[mcp_servers.magentaa11y]
command = "npx"
args = ["-y", "magentaa11y-mcp"]

Config Structure

skillsFolder - Subfolder name to bundle skills under (e.g., "a11y")
readmeTemplate - README template file to copy into skills directories
skills - Array of skill objects with name (npm package) and description
hostApplications - Array of host application configuration objects
mcpServers - MCP server definitions with name, description, command, and args

All changes take effect immediately - just re-run the CLI to deploy your updated config.

Safe Merging

The CLI safely merges with existing configurations:

MCP configs - Adds/updates only the specified servers, preserves others
Skills - Installs only the configured skills, preserves other skills in the directory
Backups - Creates .bak files if JSON parsing fails

Directory Structure

Local Install (Project-Specific)

your-project/
├── .claude/
│   └── skills/             # Claude Code skills
├── .cursor/
│   └── skills/             # Cursor skills
├── .codex/
│   └── skills/             # Codex skills
├── .github/
│   └── skills/             # VSCode skills
├── .codeium/windsurf/
│   └── skills/             # Windsurf skills
└── .factory/
    └── skills/             # Factory skills

Global Install (User-Wide)

~/.claude/
  └── skills/               # Claude Code global skills
~/.cursor/
  └── skills/               # Cursor global skills
~/.codex/
  └── skills/               # Codex global skills
~/.github/
  └── skills/               # VSCode global skills
~/.codeium/windsurf/
  └── skills/               # Windsurf global skills
~/.factory/
  └── skills/               # Factory global skills

# MCP config files live in AppData/Application Support:
# Windows: %APPDATA%/.claude.json
# Windows: %APPDATA%/.cursor/mcp.json
# Windows: %APPDATA%/.codex/config.toml
# Windows: %APPDATA%/Code/User/mcp.json
# Windows: %APPDATA%/.codeium/windsurf/mcp_config.json
# Windows: %APPDATA%/.factory/mcp.json
# macOS:   ~/Library/Application Support/<same paths as above>
# Linux:   $XDG_CONFIG_HOME/<same paths as above> (or ~/.config)

Note: Paths are fully customizable per IDE in config/settings.json

MCP Servers Included (Default)

Add your own by editing config/settings.json:

Server	Package	Description
wcag	`wcag-mcp`	WCAG 2.2 guidelines, success criteria, techniques
aria	`aria-mcp`	WAI-ARIA roles, states, properties
magentaa11y	`magentaa11y-mcp`	Component accessibility acceptance criteria
a11y-personas	`a11y-personas-mcp`	Accessibility personas for diverse users
arc-issues	`arc-issues-mcp`	AxeCore violation formatting

Complete Config Example

Here's what a complete config/settings.json looks like:

{
  "skillsFolder": "a11y",
  "readmeTemplate": "deploy-README.md",
  "skills": [
    {
      "name": "a11y-base-web-skill",
      "description": "Core accessibility testing utilities"
    },
    {
      "name": "a11y-tester-skill",
      "description": "Run accessibility tests"
    }
  ],
  "hostApplications": [
    {
      "id": "claude",
      "displayName": "Claude Code",
      "mcpServerKey": "servers",
      "skillsFolder": ".claude/skills",
      "mcpConfigFile": ".claude/mcp.json"
    },
    {
      "id": "cursor",
      "displayName": "Cursor",
      "mcpServerKey": "mcpServers",
      "skillsFolder": ".cursor/skills",
      "mcpConfigFile": ".cursor/mcp.json"
    },
    {
      "id": "windsurf",
      "displayName": "Windsurf",
      "mcpServerKey": "servers",
      "skillsFolder": ".codeium/windsurf/skills",
      "mcpConfigFile": ".codeium/windsurf/mcp_config.json"
    }
  ],
  "mcpServers": [
    {
      "name": "wcag",
      "description": "WCAG guidelines reference",
      "command": "npx",
      "args": ["-y", "wcag-mcp"]
    },
    {
      "name": "aria",
      "description": "ARIA specification reference",
      "command": "npx",
      "args": ["-y", "aria-mcp"]
    }
  ]
}

Everything is customizable - add, remove, or modify any section to match your needs.

Name		Name	Last commit message	Last commit date
Latest commit History 70 Commits
bin		bin
config		config
src		src
templates		templates
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

A11y Devkit Deploy

Install

Usage

Flags

After Installation

What's in the Guide

Preview the Guide

Next Steps

MCP Servers

What It Does

Why This Tool?

Skills Installed (Default)

No Local MCP Installation Required!

Configuration

Adding a New Skill

Adding a New MCP Server

Adding a New Host Application

Config Structure

Safe Merging

Directory Structure

Local Install (Project-Specific)

Global Install (User-Wide)

MCP Servers Included (Default)

Complete Config Example

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

A11y Devkit Deploy

Install

Usage

Flags

After Installation

What's in the Guide

Preview the Guide

Next Steps

MCP Servers

What It Does

Why This Tool?

Skills Installed (Default)

No Local MCP Installation Required!

Configuration

Adding a New Skill

Adding a New MCP Server

Adding a New Host Application

Config Structure

Safe Merging

Directory Structure

Local Install (Project-Specific)

Global Install (User-Wide)

MCP Servers Included (Default)

Complete Config Example

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages