🎯 Democratize Quality - Accessibility MCP Server

Comprehensive accessibility testing for modern web applications
Powered by axe-core, Playwright, and business-focused reporting

🚀 Quick Setup & First Scan

1. Install Prerequisites

Open Visual Studio Code and folder where youa re using GitHub Copilot. Open Terminal and follow step given below:

Install Playwright browsers (required for testing):

npx playwright install

2. Install & Configure in VS Code

One-Click Setup:

VS Code:

Manual Configuration:

For VS Code:

{
  "mcpServers": {
    "accessibility-mcp": {
      "command": "npx",
      "args": [
        "@democratize-quality/accessibility-mcp@latest",
        "--output-dir", "accessibility-reports", //add full path of your folder
        "--headless", "false"
      ]
    }
  }
}

For Claude Desktop:

{
  "mcpServers": {
    "accessibility-mcp": {
      "command": "npx",
      "args": [
        "@democratize-quality/accessibility-mcp@latest",
        "--output-dir", "accessibility-reports",//add full path of your folder
        "--headless", "false"
      ]
    }
  }
}

3. Run Your First Scan

Copy and paste this into GitHub Copilot Chat (make sure Agent mode is selected):

Scan these pages for WCAG AA level accessibility compliance and generate a comparison report:
- https://www.google.com/ (name it as Homepage)
- https://doodles.google (name it as Doodle page)
- https://doodles.google/about/ (name it as About page)
- Generate the HTML report for the scan
- Stop the scan at the end

That's it! You'll get:

• ✅ WCAG AA/AAA compliance analysis
• 📸 Visual evidence with annotated screenshots
• 🎯 Keyboard navigation testing
• 📊 Business impact assessments
• 🔧 Stakeholder-friendly recommendations
• 📋 Legal compliance references

🔥 How It Works

1. Natural Language → 2. Automated Testing → 3. Actionable Reports

Behind the Scenes

• Playwright automation for realistic user interactions
• axe-core integration for industry-standard rule coverage
• Smart screenshot capture showing exact problem locations
• Business impact calculation for prioritization
• Legal reference mapping by jurisdiction

📊 What You Get

🎯 Comprehensive Testing

• WCAG 2.1 AA/AAA compliance - Full axe-core rule coverage
• Keyboard navigation testing - Tab order, focus indicators, skip links
• Visual evidence - Annotated screenshots showing exact issues
• Legal compliance - Jurisdiction-specific standards and references

📈 Business-Focused Reports

• Stakeholder summaries - Non-technical explanations for decision makers
• User impact analysis - Who's affected and how severely
• Fix complexity scoring - Effort estimates for development teams
• Priority recommendations - Which issues to tackle first

🛠️ Developer-Friendly Output

• Issue-specific screenshots - Visual proof linked to each problem
• Manual testing steps - How to verify fixes
• Code examples - Suggested solutions
• Progress tracking - Multi-page comparison reports

🛠️ Available Tools

Core Testing Tools

| Tool | Description | Features | |------|-------------|----------| | 🔍 accessibility_scan | Complete WCAG compliance audit | axe-core testing • Business metrics • Legal references | | ⌨️ keyboard_test | Keyboard navigation testing | Tab order • Focus indicators • Skip links • Keyboard traps | | 📄 scan_current_page | Quick page accessibility check | Fast scan of active browser page | | 📊 generate_report | Comprehensive reporting | HTML/JSON reports • Visual evidence • Stakeholder summaries |

Specialized Tools (Coming Soon)

| Tool | Description | |------|-------------| | 🖼️ alt_text_check | Image accessibility validation | | 🎨 contrast_check | WCAG AA/AAA color standards | | 📝 form_accessibility | Form labels, validation, keyboard access | | 📖 heading_structure | Document structure analysis | | 🔊 screen_reader_test | ARIA/semantic compatibility |

💡 Example Prompts

Website Audits

Test https://example.com for WCAG AA compliance and generate a comprehensive report

Audit all images on https://portfolio.com for proper alternative text

Multi-Page Analysis

Scan these pages and generate a comparison report:
- https://www.google.com/ (homepage)
- https://doodles.google (doodle page)
- https://doodles.google/about/ (about page)
- Generate the HTML report for the Scan
- Stop the Scan at the end

Specialized Testing

Check keyboard navigation on https://app.example.com - verify tab order and focus management

Test the contact form at https://site.com/contact for accessibility compliance including labels and error handling

Jurisdiction-Specific

Run accessibility scan for New Zealand compliance on https://govt.nz

Automatically includes NZ-specific legal references and standards

Authenticated Pages

Test the dashboard at https://app.com/dashboard for accessibility. I'll authenticate manually first.

Uses headed browser mode for manual login

⚙️ Advanced Configuration

Manual Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "accessibility-mcp": {
      "command": "npx",
      "args": [
        "@democratize-quality/accessibility-mcp@latest",
        "--output-dir", "accessibility-reports"
      ]
    }
  }
}

Command Line Options

# Basic usage
npx @democratize-quality/accessibility-mcp

# With custom configuration
npx @democratize-quality/accessibility-mcp \
  --browser chromium \
  --headless false \
  --output-dir ./reports \
  --max-pages-per-session 20

# For authenticated pages (headed mode)
npx @democratize-quality/accessibility-mcp --headless false

# Using saved authentication
npx @democratize-quality/accessibility-mcp --storage-state ./auth.json

🌍 Global Compliance Support

Automatically includes jurisdiction-specific legal references:

| Region | Code | Key Standards | |--------|------|---------------| | 🇳🇿 New Zealand | NZ | Web Accessibility Standard 1.3, Human Rights Act 1993 | | 🇺🇸 United States | US | ADA, Section 508 | | 🇦🇺 Australia | AU | Disability Discrimination Act 1992 | | 🇨🇦 Canada | CA | Accessible Canada Act, AODA | | 🇪🇺 European Union | EU | EN 301 549, Web Accessibility Directive | | 🇬🇧 United Kingdom | UK | Equality Act 2010, Public Sector Bodies Regulations | | 🇯🇵 Japan | JP | JIS X 8341 |

Usage Examples:

Test for ADA compliance in the United States

Scan for Australian accessibility standards

Check EU accessibility directive compliance

🔧 Session Management

Multi-Page Sessions

The system automatically manages sessions when testing multiple pages:

Scan these pages in sequence:
1. https://site.com/home
2. https://site.com/products  
3. https://site.com/checkout

Generate a unified report comparing all pages.

Storage State Workflow

# 1. Start with manual authentication
npx @democratize-quality/accessibility-mcp --headless false

# 2. In Copilot: "Navigate to login page and authenticate"
# 3. Save authentication state
# 4. Use saved state for automated testing
npx @democratize-quality/accessibility-mcp --storage-state ./auth.json

Session Limits

• Maximum 10 pages per session (configurable with --max-pages-per-session)
• Use stop_scan to start fresh sessions
• Sessions automatically save state and artifacts

📊 Report Types

Single-Page Reports

• JSON data file with raw results
• Interactive HTML report with visualizations
• Screenshot evidence for violations
• Business impact metrics and recommendations

Multi-Page Reports

• Unified dashboard comparing all pages
• Individual page sections with detailed results
• Comparative analysis across pages
• Executive summary with overall compliance score

🎯 Advanced Usage

Custom WCAG Levels

Test https://example.com for WCAG AAA compliance with all rules enabled

Exclude Specific Rules

Scan https://site.com but exclude color-contrast checks

Focus on Specific Areas

Test only form accessibility on https://contact.site.com

Performance Considerations

Run a quick accessibility check on https://app.com (exclude screenshots)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/democratize-quality/accessibility-mcp
cd accessibility-mcp
npm install
npm run build
npm run test

Architecture

• MCP Server: Built with TypeScript and the MCP SDK
• Testing Engine: Playwright for browser automation
• Accessibility Rules: axe-core for WCAG compliance
• Reports: HTML generation with visual evidence

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• axe-core for accessibility testing engine
• Playwright for browser automation
• Model Context Protocol for LLM integration
• The accessibility community for guidance and feedback

📞 Support

• 🐛 Bug Reports: GitHub Issues
• 💬 Questions: GitHub Discussions
• 📧 Security: Security Policy
• 📖 Documentation: Wiki