Accessibility MCP Server

A Model Context Protocol (MCP) server for automated accessibility testing using Playwright and axe-core against WCAG standards.

Overview

This server provides AI agents (LLMs) with the ability to perform comprehensive accessibility audits on websites. It leverages industry-standard tools to deliver detailed reports on WCAG compliance violations and recommendations.

Features

🔍 Comprehensive Accessibility Testing

• Full WCAG 2.1/2.2 compliance checking (A, AA, AAA levels)
• Cross-browser testing (Chromium, Firefox, WebKit)
• Real browser automation with Playwright
• axe-core accessibility engine integration

🤖 MCP Integration

• Three main tools exposed to AI agents:
  • test_accessibility: Run accessibility tests
  • get_test_results: Retrieve saved test results
  • list_test_results: List all available test files

📊 Rich Reporting

• Human-readable text reports
• Raw JSON data for programmatic access
• Screenshot capture capability
• Detailed violation summaries with remediation guidance

🛡️ Security & Validation

• URL validation and sanitization
• Configuration parameter validation
• Graceful error handling
• Safe browser isolation

Installation

# Clone and install dependencies
npm install

# Install Playwright browsers
npx playwright install

# Build the project
npm run build

Usage

Starting the MCP Server

# Development mode
npm run dev

# Production mode
npm run build && npm start

The server communicates via stdin/stdout following the MCP protocol specification.

Available Tools

test_accessibility

Run an accessibility test on a website.

Parameters:

• url (required): Website URL to test
• wcagLevel (optional): 'A', 'AA', or 'AAA' (default: 'AA')
• wcagVersion (optional): '2.1' or '2.2' (default: '2.1')
• browser (optional): 'chromium', 'firefox', or 'webkit' (default: 'chromium')
• includeScreenshot (optional): boolean (default: false)

Example:

{
  "url": "https://example.com",
  "wcagLevel": "AA",
  "wcagVersion": "2.1",
  "browser": "chromium",
  "includeScreenshot": true
}

get_test_results

Retrieve saved accessibility test results.

Parameters:

• fileName (required): Name of the test result file

list_test_results

List all available test result files.

No parameters required.

Architecture

src/
├── server/           # MCP server implementation
│   ├── index.ts      # Main entry point
│   └── mcpServer.ts  # MCP protocol handlers
├── accessibility/    # Core testing engine
│   └── tester.ts     # Playwright + axe-core integration
├── types/           # TypeScript type definitions
│   └── index.ts     # Interface definitions
└── utils/           # Utility modules
    ├── fileOutput.ts    # Result file management
    └── validation.ts    # Input validation and sanitization

Development

Project Structure

• src/server/: MCP server implementation and entry points
• src/accessibility/: Core accessibility testing logic
• src/types/: TypeScript type definitions
• src/utils/: Utility functions for validation and file I/O
• outputs/: Generated test results and screenshots
• tests/: Test suites (planned)

Configuration

The server accepts various configuration options:

• WCAG Levels: A, AA, AAA
• WCAG Versions: 2.1, 2.2
• Browsers: Chromium, Firefox, WebKit
• Timeouts: 1s to 5 minutes
• Viewports: 320x200 to 4000x4000 pixels

Error Handling

The server implements comprehensive error handling:

• URL validation and sanitization
• Browser initialization failures
• Network timeout handling
• File I/O error recovery
• Graceful MCP protocol error responses

Output Formats

Text Reports

Human-readable accessibility reports including:

• Executive summary with violation counts
• Detailed violation descriptions with remediation steps
• Element-specific failure information
• WCAG success criteria references

JSON Data

Machine-readable results containing:

• Complete axe-core results
• Test metadata and configuration
• Structured violation data
• Performance metrics

Security Considerations

• URL validation prevents testing of local/private addresses
• Browser sandboxing through Playwright
• Input sanitization for all parameters
• Safe file I/O operations
• Process isolation

Cloud Deployment (Future)

This server is designed for eventual cloud deployment with:

• Container support (Docker)
• Environment-based configuration
• Database integration for result storage
• API rate limiting
• Authentication and authorization

Dependencies

• @modelcontextprotocol/sdk: MCP protocol implementation
• playwright: Browser automation framework
• @axe-core/playwright: Accessibility testing integration
• axe-core: Accessibility rules engine
• typescript: Type safety and development tooling

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Support

For issues and questions:

1. Check the documentation
2. Review existing GitHub issues
3. Create a new issue with detailed information