# 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