# Playwright Accessibility Testing MCP Server
A production-ready Model Context Protocol (MCP) server for comprehensive accessibility testing using Playwright and axe-core. Test web applications for WCAG 2.0/2.1 compliance with ease.
## Features
- **Comprehensive WCAG Testing**: Tests WCAG 2.0/2.1 Level A/AA compliance plus best practices
- **Natural Language Testing**: Find elements by visible text - no CSS selectors needed
- **Auto-Discovery**: Automatically discover and test all interactive elements
- **Interactive Component Testing**: Test across different states (dropdowns, modals, etc.)
- **Screenshot Capture**: Visual documentation of tested areas
- **Predefined Prompts**: Quick-start templates for common testing scenarios
- **Production-Ready**: Modular architecture, TypeScript, comprehensive error handling
## Installation
```bash
npm install
npm run build
```
## Configuration
Add to your MCP client configuration file:
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"playwright-a11y": {
"command": "node",
"args": ["/absolute/path/to/playwright-axe-mcp/dist/server.js"]
}
}
}
```
**Claude Code** (`.claude/config.json` in your project):
```json
{
"mcpServers": {
"playwright-a11y": {
"command": "node",
"args": ["/absolute/path/to/playwright-axe-mcp/dist/server.js"]
}
}
}
```
Restart your MCP client after configuration.
## Quick Start
### Using the Predefined Prompt (Easiest!)
The fastest way to test is with the **comprehensive-a11y-test** prompt:
```
Use comprehensive-a11y-test prompt:
- url: https://example.com
- block: Rewards account
- steps: open menu, select provider, input value, click apply
```
**Parameters:**
- `url` (required): URL to test
- `block` (optional): Section name (e.g., "Navigation", "User Profile")
- `steps` (optional): Comma-separated interaction steps
**What it does:**
1. Navigates to the URL
2. Runs full accessibility audit
3. Tests specified section with auto-discovery or custom steps
4. Generates human-readable report with:
- Executive summary
- Critical/serious/moderate/minor issues
- Prioritized fix recommendations
## Available Tools
### 1. `a11y_scanUrl`
Scan a URL for accessibility violations.
**Parameters:**
```typescript
{
url: string; // Required: URL to scan
selector?: string; // Optional: CSS selector to scan specific element
waitForSelector?: string; // Optional: Wait for this element before scanning
captureScreenshot?: boolean; // Optional: Capture screenshot (default: false)
timeout?: number; // Optional: Navigation timeout in ms (default: 30000)
}
```
**Example:**
```json
{
"url": "https://example.com",
"selector": "header nav",
"captureScreenshot": true
}
```
### 2. `a11y_scanInteractiveByText`
Test components using natural language - no CSS selectors needed!
**Parameters:**
```typescript
{
url: string; // Required: URL to navigate to
containerText: string; // Required: Visible text to find section (e.g., "Rewards")
autoDiscover?: boolean; // Optional: Auto-discover interactions (default: true)
customInteractions?: Array<{
stateName: string; // Name for this interaction
elementText: string; // Visible text of element to interact with
action: "click" | "hover" | "focus";
waitAfter?: number; // Wait time in ms (default: 500)
}>;
captureScreenshots?: boolean; // Optional: Screenshot each state
timeout?: number; // Optional: Navigation timeout in ms
}
```
**Example: Auto-discover everything**
```json
{
"url": "https://example.com",
"containerText": "User Menu",
"autoDiscover": true,
"captureScreenshots": true
}
```
**Example: Custom interactions**
```json
{
"url": "https://example.com",
"containerText": "Rewards",
"customInteractions": [
{
"stateName": "After opening menu",
"elementText": "View Details",
"action": "click"
}
]
}
```
## Response Format
### Scan Result
```json
{
"url": "https://example.com",
"timestamp": "2025-01-28T...",
"summary": {
"violations": 3,
"passes": 12,
"incomplete": 1
},
"violations": [
{
"id": "color-contrast",
"impact": "serious",
"description": "Elements must have sufficient color contrast",
"help": "Ensure contrast ratio is at least 4.5:1",
"helpUrl": "https://dequeuniversity.com/rules/axe/4.4/color-contrast",
"tags": ["wcag2aa", "wcag21aa"],
"nodes": [
{
"html": "<button class=\"btn\">Submit</button>",
"target": [".btn"],
"failureSummary": "..."
}
]
}
],
"screenshotPath": "/path/to/screenshot.png"
}
```
### Interactive Scan Result
```json
{
"url": "https://example.com",
"containerText": "Rewards",
"totalStates": 3,
"states": [
{
"stateName": "Initial State",
"summary": {"violations": 0, "passes": 5, "incomplete": 0},
"violations": []
},
{
"stateName": "After interacting with buttons: \"View Details\"",
"action": "click",
"elementText": "View Details",
"summary": {"violations": 2, "passes": 8, "incomplete": 1},
"violations": [...]
}
]
}
```
## Project Structure
```
server/
├── constants/ # Configuration and constants
│ ├── config.ts # Application configuration
│ ├── selectors.ts # Interactive element selectors
│ └── wcag-tags.ts # WCAG compliance tags
├── types/ # TypeScript type definitions
│ └── scan-result.ts # Scan result interfaces
├── utils/ # Utility functions
│ ├── axe-scanner.ts # Axe configuration and scanning
│ ├── browser.ts # Browser management
│ ├── container-finder.ts # Find elements by text
│ └── screenshot.ts # Screenshot utilities
├── tools/ # Tool implementations
│ ├── scan-url.ts # URL scanning tool
│ └── scan-interactive-by-text.ts # Interactive testing tool
├── prompts/ # Prompt templates
│ └── comprehensive-a11y-test.ts # Predefined test prompt
└── server.ts # Main MCP server entry point
```
## WCAG Compliance
This server tests for:
- **WCAG 2.0 Level A** (`wcag2a`)
- **WCAG 2.0 Level AA** (`wcag2aa`)
- **WCAG 2.1 Level A** (`wcag21a`)
- **WCAG 2.1 Level AA** (`wcag21aa`)
- **Best Practices** (`best-practice`)
## Impact Levels
Violations are categorized by severity:
- **Critical**: Blocks access completely - fix immediately
- **Serious**: Creates significant barriers - fix before release
- **Moderate**: Noticeable issues - fix soon
- **Minor**: Small improvements - can be backlogged
## Output Files
All screenshots are saved to: `./accessibility-screenshots/`
- `scan-{timestamp}.png` - Full page screenshots
- `{name}-{timestamp}.png` - Named screenshots
## Usage Examples
### Test a simple page
```
User: "Check accessibility of https://example.com"
Claude: → Calls a11y_scanUrl
→ Returns: 3 violations (2 serious, 1 moderate)
```
### Test specific section by name
```
User: "Test the Navigation menu on https://example.com"
Claude: → Calls a11y_scanInteractiveByText with containerText="Navigation"
→ Auto-discovers all interactive elements
→ Returns: Issues found in different states
```
### Test with custom interactions
```
User: "Test the Rewards section - click 'View Details' then 'Redeem'"
Claude: → Parses your request
→ Calls a11y_scanInteractiveByText with custom interactions
→ Returns: Accessibility analysis for each state
```
## Development
```bash
# Build TypeScript
npm run build
# Watch mode for development
npm run watch
# Start server directly (for testing)
npm start
```
### Adding New Tools
1. Create tool file in `server/tools/`
2. Define schema and execution function
3. Register in `server/server.ts`
### Adding New Utilities
1. Create utility file in `server/utils/`
2. Export functions
3. Import where needed
## Best Practices
1. **Always test with screenshots** during initial development:
```json
{"captureScreenshot": true}
```
2. **Wait for dynamic content** on SPAs:
```json
{"waitForSelector": ".content-loaded"}
```
3. **Test interactive components** in different states:
- Initial state
- After user interaction
- Error states
- Success states
4. **Use natural language testing** when you don't know selectors:
```json
{"containerText": "User Menu", "autoDiscover": true}
```
## Troubleshooting
### Server not starting
```bash
npm run build
# Check config path is absolute
# Restart MCP client
```
### Element not found
- Verify the text exists on the page
- Try a shorter, more specific text
- Check if content is loaded (use `waitForSelector`)
### Timeout errors
```json
{"timeout": 60000} // Increase to 60 seconds
```
## Requirements
- Node.js 18+
- Playwright (browsers installed automatically)
## License
ISC
## Contributing
1. Follow the modular architecture
2. Add TypeScript types for new features
3. Document new tools in README
4. Update constants instead of hardcoding values
---
**Built for production use with modular, maintainable architecture.**
