Accessibility MCP Server

# 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 ```bash # Clone and install dependencies npm install # Install Playwright browsers npx playwright install # Build the project npm run build ``` ## Usage ### Starting the MCP Server ```bash # 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:** ```json { "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