npm package: @joshteravest/mcp-accessibility-audit-server
Description: MCP Server for comprehensive website accessibility auditing using axe-core and Puppeteer
Author: JoshTerAvest
Latest version: 2.1.1

# MCP Accessibility Audit Server

A comprehensive Model Context Protocol (MCP) server for website accessibility auditing using industry-standard tools like axe-core and Puppeteer. This server enables AI assistants to evaluate websites for WCAG compliance and provide detailed accessibility reports.

## Features

- **Comprehensive Accessibility Audits**: Full WCAG 2.1 compliance checking (A, AA, AAA levels)
- **Specialized Checks**:
  - Color contrast analysis
  - Image accessibility (alt text, decorative vs informative)
  - Keyboard navigation testing
- **Batch Processing**: Audit multiple pages at once
- **Detailed Reports**: Human-readable markdown reports with prioritized issues and remediation guidance
- **Industry Standards**: Built on axe-core (used by Microsoft, Google) and Puppeteer

## Installation

### Prerequisites

- Node.js 18 or higher
- Chrome/Chromium browser installed on your system

### Option 1: Install from npm (Recommended)

**Global installation:**
```bash
npm install -g @joshteravest/mcp-accessibility-audit-server
```

**Local installation:**
```bash
npm install @joshteravest/mcp-accessibility-audit-server
```

**Using npx (no installation needed):**
```bash
npx @joshteravest/mcp-accessibility-audit-server
```

### Option 2: Install from Source

```bash
git clone https://github.com/JoshTerAvest/a11y-mcp.git
cd a11y-mcp
npm install
npm run build
```

## Configuration

Add this server to your MCP settings file:

### Claude Desktop

On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%/Claude/claude_desktop_config.json`

**If installed globally via npm:**

```json
{
  "mcpServers": {
    "accessibility-audit": {
      "command": "mcp-accessibility-audit"
    }
  }
}
```

**If installed via npx:**

```json
{
  "mcpServers": {
    "accessibility-audit": {
      "command": "npx",
      "args": ["@joshteravest/mcp-accessibility-audit-server"]
    }
  }
}
```

**If installed from source:**

```json
{
  "mcpServers": {
    "accessibility-audit": {
      "command": "node",
      "args": ["/absolute/path/to/a11y-mcp/build/index.js"]
    }
  }
}
```

### Cline / Other MCP Clients

Same configuration as above - use the appropriate command based on your installation method.

## Available Tools

### 1. `audit_page`

Run a comprehensive accessibility scan on a webpage.

**Parameters:**
- `url` (string, required): The URL of the webpage to audit
- `wcag_level` (string, optional): WCAG conformance level - 'A', 'AA', or 'AAA' (default: 'AA')

**Example:**
```
Please audit https://example.com for WCAG AA compliance
```

**Returns:**
- Violations categorized by severity (critical, serious, moderate, minor)
- Passes and incomplete checks
- Summary statistics
- Raw axe-core results

### 2. `check_contrast`

Analyze color contrast issues on a webpage.

**Parameters:**
- `url` (string, required): The URL of the webpage to analyze

**Example:**
```
Check the color contrast on https://example.com
```

**Returns:**
- All text/background combinations that fail WCAG contrast requirements
- Contrast ratios and required ratios
- Element selectors for each issue

### 3. `check_images`

Check images for accessibility issues.

**Parameters:**
- `url` (string, required): The URL of the webpage to check

**Example:**
```
Check all images on https://example.com for accessibility issues
```

**Returns:**
- Images missing alt text
- Images with potentially incorrect alt text usage
- Recommendations for decorative vs informative images

### 4. `check_keyboard_navigation`

Test keyboard navigation on a webpage.

**Parameters:**
- `url` (string, required): The URL of the webpage to test

**Example:**
```
Test keyboard navigation on https://example.com
```

**Returns:**
- Tab order issues
- Keyboard traps
- Missing focus indicators
- Problematic tabindex usage

### 5. `batch_audit`

Scan multiple pages and aggregate results.

**Parameters:**
- `urls` (array of strings, required): Array of URLs to audit
- `wcag_level` (string, optional): WCAG conformance level (default: 'AA')

**Example:**
```
Audit these pages: https://example.com, https://example.com/about, https://example.com/contact
```

**Returns:**
- Individual audit results for each URL
- Aggregated statistics
- Pages ranked by number of issues

### 6. `generate_accessibility_report`

Generate a detailed markdown report from audit results.

**Parameters:**
- `results` (object, required): Results from `audit_page` or `batch_audit`

**Example:**
```
Generate a detailed report from the previous audit results
```

**Returns:**
- Comprehensive markdown report
- Issues prioritized by severity
- Remediation guidance
- Code examples

## Usage Examples

### Example 1: Single Page Audit

**User:** "Can you check if communityactionnapavalley.org meets accessibility standards?"

**Claude (using MCP):**

I'll run an accessibility audit on that site.

*[calls audit_page('https://communityactionnapavalley.org', 'AA')]*

I found 23 accessibility issues:

**Critical Issues (5):**
- Missing alt text on 3 images (WCAG 1.1.1)
- Color contrast failures on navigation links (WCAG 1.4.3)
- Form inputs missing labels (WCAG 3.3.2)

**Serious Issues (12):**
- Heading levels skip from h1 to h3 (WCAG 1.3.1)
- Missing ARIA landmarks for main regions
...

Would you like detailed remediation steps for these issues?

### Example 2: Batch Site Audit

**User:** "Audit all the main pages of my website"

**Claude:**

*[calls batch_audit(['https://example.com', 'https://example.com/about', 'https://example.com/services', 'https://example.com/contact'])]*

I've completed the audit of 4 pages:

**Executive Summary:**
- Total Issues: 47
- Most problematic page: /services (18 issues)
- Common issues across all pages: missing alt text, heading structure

*[calls generate_accessibility_report(results)]*

Here's your detailed report...

### Example 3: Specific Check

**User:** "Check if the images on my homepage have proper alt text"

**Claude:**

*[calls check_images('https://example.com')]*

I found 5 image accessibility issues:

**Critical (3):**
1. Hero image missing alt attribute
2. Logo missing alt text
3. Team photo without description

**Warnings (2):**
1. Decorative border image should have `role="presentation"`
2. Chart image has very long alt text (consider aria-describedby)

## Development

### Project Structure

```
a11y-mcp/
├── src/
│   ├── index.ts                    # Main MCP server
│   ├── accessibility-auditor.ts    # Core audit functionality
│   └── report-generator.ts         # Report generation
├── build/                          # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
```

### Building

```bash
npm run build
```

### Development Mode

```bash
npm run watch
```

## Technical Details

### Technology Stack

- **MCP SDK**: `@modelcontextprotocol/sdk` for MCP server implementation
- **axe-core**: Industry-standard accessibility testing engine
- **Puppeteer**: Headless Chrome for running tests in real browser
- **TypeScript**: Type-safe implementation

### WCAG Compliance

This tool tests for:

- **WCAG 2.1 Level A**: Basic accessibility features
- **WCAG 2.1 Level AA**: Enhanced accessibility (recommended standard)
- **WCAG 2.1 Level AAA**: Highest level of accessibility

### Limitations

- **Automated Testing**: This tool provides automated testing, which catches ~30-40% of accessibility issues
- **Manual Testing Required**: Human testing is still needed for:
  - Screen reader compatibility
  - Actual keyboard navigation flow
  - Content clarity and readability
  - Context-specific accessibility concerns
- **JavaScript Required**: Requires pages to have JavaScript enabled
- **Browser Dependency**: Requires Chrome/Chromium to be installed

## Interview Preparation Tips

### Key Points to Discuss

1. **Why MCP?**
   - Enables AI assistants to perform accessibility audits automatically
   - Provides structured, consistent results
   - Can be integrated into development workflows

2. **Why axe-core?**
   - Industry standard (used by Microsoft, Google, government sites)
   - Comprehensive WCAG coverage
   - Actively maintained and updated
   - Free and open source

3. **Architecture Decisions**
   - Separation of concerns (auditor, reporter, server)
   - Reusable browser instance for efficiency
   - Comprehensive error handling
   - Extensible design for adding new tools

4. **Future Enhancements**
   - PDF report generation
   - Historical tracking of audit results
   - Integration with CI/CD pipelines
   - Custom rule definitions
   - Screenshot capture of violations
   - Accessibility score calculation

### Demo Script

1. Show a simple audit of a public website
2. Demonstrate contrast checking
3. Run a batch audit on multiple pages
4. Generate a comprehensive report
5. Discuss remediation strategies

## Resources

- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
- [axe-core Documentation](https://github.com/dequelabs/axe-core)
- [MCP Documentation](https://modelcontextprotocol.io)
- [WebAIM Resources](https://webaim.org/resources/)
- [A11y Project](https://www.a11yproject.com/)

## License

MIT

## Contributing

This is a proof of concept for interview preparation. Contributions and suggestions are welcome!

## Troubleshooting

### Puppeteer Browser Not Found

If you see errors about Chrome not being found:

```bash
# Install Chrome/Chromium on your system
# Ubuntu/Debian
sudo apt-get install chromium-browser

# MacOS
brew install chromium

# Or set custom Chrome path
export PUPPETEER_EXECUTABLE_PATH=/path/to/chrome
```

### Timeout Errors

If pages take too long to load:
- The default timeout is 30 seconds
- Check your internet connection
- Try auditing the page manually to confirm it loads

### Memory Issues

For batch audits of many pages:
- Process URLs in smaller batches
- The browser instance is reused but can consume memory
- Restart the MCP server if needed

## Contact

For questions or feedback about this project, please open an issue on GitHub.