♿ Accessibility MCP Server

A Model Context Protocol (MCP) server that provides conversational, actionable accessibility testing. This server exposes accessibility auditing tools that can be used by AI agents and chat interfaces.

✨ Features

• Conversational Results: Results formatted for natural language understanding, not raw data
• Session Management: Reusable authenticated sessions for testing protected pages
• Tag Filtering: Filter results by specific WCAG levels (wcag2a, wcag2aa, wcag21a, etc.)
• Educational Focus: Tools that explain issues in plain language with code examples
• Code-Level Fixes: Actual before/after code examples, not just descriptions
• Progress Updates: Streaming progress for long-running batch operations
• Smart Prioritization: AI-powered issue prioritization with quick wins identification
• Compliance Reports: Automated VPAT/WCAG/ADA compliance documentation
• Trend Tracking: Historical data and predictions for accessibility improvements

📋 Prerequisites

• Node.js 18+
• Playwright browsers (installed automatically)

🚀 Installation & Setup

Step 1: Install Dependencies

cd mcp-server
npm install

Step 2: Install Playwright Browsers

npx playwright install --with-deps chromium

Step 3: Build the Project

npm run build

Step 4: Verify accessibility script

The wave.min.js file should be present in the mcp-server directory. This file contains the accessibility engine and is required for all audits. If it's missing, copy it from the project root:

cp ../wave.min.js ./wave.min.js

🔧 Running the MCP Server

Development Mode (with watch)

npm run dev

Production Mode

npm start

⚙️ MCP Client Configuration

Add this server to your MCP client configuration (e.g., Claude Desktop, Cursor):

Claude Desktop Configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "accessibility-audit": {
      "command": "node",
      "args": ["/absolute/path/to/wave-accessibility-audit/mcp-server/dist/server.js"]
    }
  }
}

Cursor Configuration

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "accessibility-audit": {
      "command": "node",
      "args": ["/absolute/path/to/wave-accessibility-audit/mcp-server/dist/server.js"]
    }
  }
}

Note: Use absolute paths in your configuration. Replace /absolute/path/to/ with the actual path to your project.

🛠️ Available Tools

Tier 1: Core Audit Tools

audit_url - Single URL Audit

Test a single URL for accessibility issues with conversational, actionable results.

Inputs:

• url (required): Full URL or relative path
• domain (optional): Base domain if URL is relative
• tags (optional): Array of accessibility tags to check (e.g., ["wcag2a", "wcag2aa", "wcag21a", "best-practice"]). If not provided, all tags are checked.
• waitForLoad (optional): Wait strategy - "networkidle" (default) | "load" | "domcontentloaded"
• timeout (optional): Timeout in seconds (default: 30)

Example:

{
  "url": "https://example.com",
  "tags": ["wcag21aa"],
  "timeout": 45
}

Output: Structured JSON with summary, prioritized violations, WCAG compliance breakdown, quick fix suggestions, and conversational explanation.

audit_multiple_urls - Batch Audit

Test multiple URLs efficiently with progress updates.

Inputs:

• urls (required): Array of URLs or comma-separated string
• domain (optional): Base domain
• tags (optional): Array of accessibility tags
• parallel (optional): Number of parallel tests (default: 1)
• continueOnError (optional): Continue if one fails (default: true)

Example:

{
  "urls": ["/home", "/about", "/contact"],
  "domain": "https://example.com",
  "tags": ["wcag2aa"],
  "parallel": 2
}

Output: Per-URL results, aggregated summary, and progress updates (streaming).

audit_site - Smart Site Audit

Intelligent site-wide audit with prioritization.

Inputs:

• domain (required): Base domain
• tags (optional): Array of accessibility tags. Applied to all pages.
• strategy (optional): "critical" | "comprehensive" | "custom" (default: "comprehensive")
• maxPages (optional): Maximum pages to test (default: 50)
• priorityPaths (optional): Array of high-priority paths to test first

Example:

{
  "domain": "https://example.com",
  "strategy": "critical",
  "priorityPaths": ["/", "/login", "/checkout"],
  "tags": ["wcag21aa"],
  "maxPages": 20
}

Output: Prioritized results (critical pages first), site-wide score, and trend analysis if previous audits exist.

Tier 2: Session Management

create_session - Authenticated Session

Create a reusable authenticated session for testing protected pages.

Inputs:

• domain (required): Base domain
• username (required): Login username
• password (required): Login password
• loginUrl (optional): Custom login URL (default: {domain}/login)
• loginSelectors (optional): Custom selectors for login form:
  • usernameSelector (default: "input[type='email'], input[name='username'], input[id='username']")
  • passwordSelector (default: "input[type='password']")
  • submitSelector (default: "button[type='submit'], input[type='submit']")
• sessionId (optional): Custom session identifier (auto-generated if not provided)

Example:

{
  "domain": "https://app.example.com",
  "username": "[email protected]",
  "password": "password123",
  "loginUrl": "https://app.example.com/auth/login"
}

Output:

• sessionId: Reusable session identifier
• expiresAt: Session expiration time (ISO 8601)
• testUrl: Test URL to verify session

Differentiator: Only MCP with reusable session management for authenticated pages.

audit_with_session - Authenticated Audit

Run an audit using an existing authenticated session.

Inputs:

• sessionId (required): Session from create_session
• url (required): URL to test (can be relative)
• domain (optional): Base domain
• tags (optional): Array of accessibility tags
• waitForLoad (optional): Wait strategy (default: "networkidle")
• timeout (optional): Timeout in seconds (default: 30)

Example:

{
  "sessionId": "session-abc123",
  "url": "/dashboard",
  "domain": "https://app.example.com",
  "tags": ["wcag21aa"]
}

Output: Same as audit_url but for authenticated pages.

Tier 3: Analysis & Reporting

get_accessibility_score - Calculate Score

Calculate accessibility score (0-100) with detailed breakdowns.

Inputs:

• results (required): Audit result object or URL string
• weights (optional): Custom weights for different issue types:
  • errors (default: 10)
  • contrast (default: 8)
  • alerts (default: 5)
  • features (default: 3)
  • structural (default: 6)

Example:

{
  "results": "https://example.com",
  "weights": {
    "errors": 15,
    "contrast": 10
  }
}

Output:

• Overall score (0-100)
• Breakdown by category (contrast, navigation, forms, etc.)
• WCAG level compliance (A, AA, AAA)
• Trend if historical data available

prioritize_issues - Smart Prioritization

Intelligently prioritize issues, identifying quick wins and critical blockers.

Inputs:

• results (required): Audit result object
• criteria (optional): "impact" | "wcag" | "fixability" | "user-impact" (default: "impact")
• limit (optional): Top N issues to return (default: 10)

Example:

{
  "results": { /* audit result object */ },
  "criteria": "fixability",
  "limit": 5
}

Output:

• Prioritized list with reasoning
• Quick wins (easy fixes with high impact)
• Critical blockers

explain_issue - Educational Tool

Explain what an accessibility issue means in plain language.

Inputs:

• ruleId (required): Accessibility rule ID (e.g., "alt_missing", "contrast", "label_missing")
• context (optional): Additional context about the issue (HTML element, page URL, etc.)

Example:

{
  "ruleId": "alt_missing",
  "context": "Image on homepage hero section"
}

Output:

• Plain language explanation
• Why it matters (user impact)
• How to fix (with code examples)
• WCAG reference
• Common mistakes

Differentiator: Educational focus - helps users learn accessibility.

get_quick_fixes - Actionable Fixes

Get specific fix suggestions with before/after code examples.

Inputs:

• results (required): Audit result object or URL string
• format (optional): "markdown" | "html" | "json" (default: "json")
• includeCode (optional): Include code examples (default: true)

Example:

{
  "results": "https://example.com",
  "format": "markdown",
  "includeCode": true
}

Output:

• List of fixes with:
  • Current code (if available)
  • Fixed code
  • Explanation
  • Impact estimate

Differentiator: Code-level fixes, not just descriptions.

generate_compliance_report - Compliance Documentation

Generate compliance reports in various formats.

Inputs:

• results (required): Audit result object
• format (optional): "VPAT" | "WCAG" | "ADA" | "Section508" (default: "WCAG")
• level (optional): "A" | "AA" | "AAA" (default: "AA")
• includeRemediation (optional): Include fix suggestions (default: true)

Example:

{
  "results": { /* audit result object */ },
  "format": "VPAT",
  "level": "AA",
  "includeRemediation": true
}

Output:

• Formatted compliance report
• WCAG mapping
• Remediation plan
• Executive summary

get_wcag_compliance - WCAG Status

Check WCAG compliance status with per-criterion breakdown.

Inputs:

• results (required): Audit result object or URL string
• level (optional): "A" | "AA" | "AAA" (default: "AA")

Example:

{
  "results": "https://example.com",
  "level": "AA"
}

Output:

• Compliance status (pass/fail/partial)
• Per-criterion breakdown
• Missing requirements
• Compliance percentage

Tier 4: Comparison & Tracking

compare_accessibility - Before/After Comparison

Compare two audits to track improvements.

Inputs:

• before (required): Previous audit result or URL
• after (required): Current audit result or URL
• format (optional): "summary" | "detailed" | "diff" (default: "summary")

Example:

{
  "before": "https://example.com/v1",
  "after": "https://example.com/v2",
  "format": "detailed"
}

Output:

• Issues fixed
• Issues introduced
• Score improvement
• Remaining issues
• Visual diff (if applicable)

track_accessibility - Historical Tracking

Track accessibility over time with trend analysis.

Inputs:

• url (required): URL to track
• timeframe (optional): "7d" | "30d" | "90d" | "all" (default: "30d")
• metric (optional): "score" | "issues" | "wcag-compliance" (default: "score")

Example:

{
  "url": "https://example.com",
  "timeframe": "90d",
  "metric": "score"
}

Output:

• Historical data
• Trend visualization (text-based)
• Predictions
• Recommendations

Tier 5: Export & Data Management

export_to_csv - Export to CSV

Export audit results to CSV format for spreadsheet analysis, including metadata and violation rows.

Inputs:

• results (required): Audit result object or URL string
• includeMetadata (optional): Include test information and environment data (default: true)
• includeViolations (optional): Include detailed violation rows (default: true)
• format (optional): "standard" | "detailed" | "minimal" (default: "standard")

Example:

{
  "results": "https://example.com",
  "format": "detailed",
  "includeMetadata": true,
  "includeViolations": true
}

Output:

• CSV content as string with metadata section and violation rows
• Format type used
• Total issues count

Use case: Import into Excel, share with stakeholders, data analysis

export_to_excel - Export to Excel

Export audit results to Excel/XLSX format with formatting. Requires xlsx package.

Inputs:

• results (required): Audit result object or URL string
• includeCharts (optional): Generate charts for score trends and category breakdown (default: false)
• formatting (optional): Apply colors, headers, and styling (default: true)

Example:

{
  "results": { /* audit result object */ },
  "includeCharts": true,
  "formatting": true
}

Output:

• Excel file content (base64 encoded)
• Format type (xlsx)
• Total issues count

Use case: Professional reports, presentations, stakeholder sharing

Note: Requires xlsx package. Install with npm install xlsx.

export_to_json - Export to JSON

Export audit results as structured JSON with optional raw results.

Inputs:

• results (required): Audit result object or URL string
• pretty (optional): Pretty-print JSON (default: true)
• includeRaw (optional): Include raw accessibility engine results (default: false)

Example:

{
  "results": "https://example.com",
  "pretty": true,
  "includeRaw": false
}

Output:

• JSON string with audit results
• Pretty-print status
• Raw results inclusion status

Use case: API integration, data processing, backup

export_to_html_report - Generate HTML Report

Generate standalone HTML report with styling and optional visual charts.

Inputs:

• results (required): Audit result object or URL string
• template (optional): "default" | "minimal" | "detailed" (default: "default")
• includeCharts (optional): Include visual charts (default: true)

Example:

{
  "results": "https://example.com",
  "template": "detailed",
  "includeCharts": true
}

Output:

• HTML string with embedded CSS/JS
• Template used
• Charts inclusion status

Use case: Web sharing, email reports, documentation

Tier 6: Filtering & Search

filter_issues - Filter Issues

Filter issues from audit results by various criteria (rule IDs, categories, impact levels, WCAG levels, etc.). Supports include/exclude modes.

Inputs:

• results (required): Audit result object
• filters (required): Object with filter criteria:
  • ruleIds (optional): Array of rule IDs to include/exclude
  • categories (optional): Array of categories (error, contrast, etc.)
  • impactLevels (optional): Array of impact levels ("critical", "serious", "moderate", "minor")
  • wcagLevels (optional): Array of WCAG levels ("A", "AA", "AAA")
  • minCount (optional): Minimum occurrence count
  • elementTypes (optional): Filter by HTML element types (e.g., ["img", "input", "button"])
• mode (optional): "include" | "exclude" (default: "include")

Example:

{
  "results": { /* audit result object */ },
  "filters": {
    "impactLevels": ["critical", "serious"],
    "wcagLevels": ["A", "AA"]
  },
  "mode": "include"
}

Output:

• Filtered audit result object
• Original issue count
• Filtered issue count
• Filters applied

Use case: Focus on specific issue types, exclude false positives

search_issues - Search Issues

Search issues by text content, selector, XPath, or description. Supports case-sensitive and case-insensitive search.

Inputs:

• results (required): Audit result object
• query (required): Search query string
• fields (optional): Array of fields to search ("description", "element", "xpath", "selector", "ruleId", "userImpact", "fix", "all") (default: ["all"])
• caseSensitive (optional): Case-sensitive search (default: false)

Example:

{
  "results": { /* audit result object */ },
  "query": "missing alt",
  "fields": ["description", "userImpact"],
  "caseSensitive": false
}

Output:

• Array of matching issues
• Total matches count
• Fields searched

Use case: Find specific issues, locate elements

Tier 7: Aggregation & Statistics

aggregate_audit_results - Aggregate Results

Combine and aggregate multiple audit results. Groups issues by URL, category, rule, or none, and provides aggregated summary statistics.

Inputs:

• results (required): Array of audit result objects
• groupBy (optional): "url" | "category" | "rule" | "none" (default: "url")
• includeSummary (optional): Include aggregated summary statistics (default: true)

Example:

{
  "results": [
    { /* audit result 1 */ },
    { /* audit result 2 */ }
  ],
  "groupBy": "category",
  "includeSummary": true
}

Output:

• Aggregated audit result with combined statistics
• Grouping strategy used
• Total results aggregated
• Grouped issues (if applicable)

Use case: Site-wide reports, batch analysis, trend identification

get_statistics - Generate Statistics

Generate detailed statistics from audit results with breakdowns by category, impact, WCAG level, or rule ID. Supports single or multiple audit results.

Inputs:

• results (required): Audit result object or array of audit results
• breakdown (optional): Array of breakdown dimensions ("category", "impact", "wcag", "rule") (default: all dimensions)

Example:

{
  "results": [
    { /* audit result 1 */ },
    { /* audit result 2 */ }
  ],
  "breakdown": ["category", "impact", "wcag"]
}

Output:

• Total issues count
• Average accessibility score
• WCAG compliance breakdown
• Statistics by category, impact, WCAG level, and rule ID
• Counts, percentages, and distributions

Use case: Dashboard data, reporting, analysis

Tier 8: Visualization & Reporting

generate_dashboard - Generate Dashboard

Create a visual dashboard summary of audit results with key metrics, charts, and summaries. Supports multiple formats and optional charts.

Inputs:

• results (required): Audit result object, array of audit results, URL string, or array of URL strings
• format (optional): "text" | "markdown" | "html" | "json" (default: "markdown")
• includeCharts (optional): Include ASCII/text charts (default: true)

Example:

{
  "results": ["https://example.com/page1", "https://example.com/page2"],
  "format": "markdown",
  "includeCharts": true
}

Output:

• Formatted dashboard with key metrics, charts, and summaries
• Format used
• Total results processed

Use case: Quick overview, presentations, status reports

generate_summary_report - Generate Summary Report

Generate executive summary report with key findings and recommendations. Supports multiple formats and detail levels.

Inputs:

• results (required): Audit result object, array of audit results, URL string, or array of URL strings
• format (optional): "text" | "markdown" | "html" (default: "markdown")
• level (optional): "executive" | "detailed" | "technical" (default: "executive")

Example:

{
  "results": "https://example.com",
  "format": "markdown",
  "level": "executive"
}

Output:

• Summary report with key findings and recommendations
• Format used
• Detail level used
• Total results processed

Use case: Stakeholder communication, documentation

🏷️ Supported Accessibility Tags

Filter results by specific WCAG levels or best practices:

• wcag2a - WCAG 2.0 Level A
• wcag2aa - WCAG 2.0 Level AA
• wcag2aaa - WCAG 2.0 Level AAA
• wcag21a - WCAG 2.1 Level A
• wcag21aa - WCAG 2.1 Level AA (most common requirement)
• wcag21aaa - WCAG 2.1 Level AAA
• best-practice - Best practice recommendations

Example Usage:

// Only check WCAG 2.1 AA compliance
{
  "url": "https://example.com",
  "tags": ["wcag21aa"]
}

// Check multiple WCAG levels
{
  "url": "https://example.com",
  "tags": ["wcag2a", "wcag2aa", "best-practice"]
}

📊 Result Format

All audit tools return structured results in the following format:

{
  summary: {
    totalIssues: number
    score: number
    wcagCompliance: { A: number, AA: number, AAA: number }
    byCategory: Record<string, number>
    byImpact: Record<string, number>
  }
  prioritizedIssues: Array<{
    ruleId: string
    impact: 'critical' | 'serious' | 'moderate' | 'minor'
    description: string
    wcagLevel: string
    tags: string[] // Array of tags this violation matches
    element: string
    xpath: string
    fix: {
      current: string
      suggested: string
      explanation: string
    }
    userImpact: string
    priority: number
  }>
  conversationalSummary: string
  quickWins: Array<{
    ruleId: string
    description: string
    impact: string
    fix: string
  }>
  criticalBlockers: Array<{
    ruleId: string
    description: string
    impact: string
  }>
  appliedFilters?: {
    tags?: string[]
    originalIssueCount?: number
  }
}

📝 Usage Examples

Basic URL Audit

{
  "tool": "audit_url",
  "arguments": {
    "url": "https://example.com",
    "tags": ["wcag21aa"]
  }
}

Authenticated Audit Flow

Step 1: Create Session

{
  "tool": "create_session",
  "arguments": {
    "domain": "https://app.example.com",
    "username": "[email protected]",
    "password": "password123"
  }
}

Step 2: Audit Protected Page

{
  "tool": "audit_with_session",
  "arguments": {
    "sessionId": "<session-id-from-step-1>",
    "url": "/dashboard",
    "tags": ["wcag21aa"]
  }
}

Batch Audit with Progress

{
  "tool": "audit_multiple_urls",
  "arguments": {
    "urls": ["/home", "/about", "/contact", "/products"],
    "domain": "https://example.com",
    "parallel": 2,
    "tags": ["wcag2aa"]
  }
}

Get Quick Fixes

{
  "tool": "get_quick_fixes",
  "arguments": {
    "results": "https://example.com",
    "format": "markdown",
    "includeCode": true
  }
}

Compare Before/After

{
  "tool": "compare_accessibility",
  "arguments": {
    "before": "https://example.com/v1",
    "after": "https://example.com/v2",
    "format": "detailed"
  }
}

Generate Compliance Report

{
  "tool": "generate_compliance_report",
  "arguments": {
    "results": { /* audit result object */ },
    "format": "VPAT",
    "level": "AA",
    "includeRemediation": true
  }
}

Export to CSV

{
  "tool": "export_to_csv",
  "arguments": {
    "results": "https://example.com",
    "format": "detailed",
    "includeMetadata": true,
    "includeViolations": true
  }
}

Export to Excel

{
  "tool": "export_to_excel",
  "arguments": {
    "results": { /* audit result object */ },
    "includeCharts": true,
    "formatting": true
  }
}

Export to JSON

{
  "tool": "export_to_json",
  "arguments": {
    "results": "https://example.com",
    "pretty": true,
    "includeRaw": false
  }
}

Generate HTML Report

{
  "tool": "export_to_html_report",
  "arguments": {
    "results": "https://example.com",
    "template": "detailed",
    "includeCharts": true
  }
}

Filter Issues

{
  "tool": "filter_issues",
  "arguments": {
    "results": { /* audit result object */ },
    "filters": {
      "impactLevels": ["critical", "serious"],
      "wcagLevels": ["A", "AA"]
    },
    "mode": "include"
  }
}

Search Issues

{
  "tool": "search_issues",
  "arguments": {
    "results": { /* audit result object */ },
    "query": "missing alt",
    "fields": ["description", "userImpact"],
    "caseSensitive": false
  }
}

Aggregate Audit Results

{
  "tool": "aggregate_audit_results",
  "arguments": {
    "results": [
      { /* audit result 1 */ },
      { /* audit result 2 */ }
    ],
    "groupBy": "category",
    "includeSummary": true
  }
}

Get Statistics

{
  "tool": "get_statistics",
  "arguments": {
    "results": [
      { /* audit result 1 */ },
      { /* audit result 2 */ }
    ],
    "breakdown": ["category", "impact", "wcag"]
  }
}

Generate Dashboard

{
  "tool": "generate_dashboard",
  "arguments": {
    "results": ["https://example.com/page1", "https://example.com/page2"],
    "format": "markdown",
    "includeCharts": true
  }
}

Generate Summary Report

{
  "tool": "generate_summary_report",
  "arguments": {
    "results": "https://example.com",
    "format": "markdown",
    "level": "executive"
  }
}

🐛 Error Handling

The server includes comprehensive error handling:

• Graceful degradation: Partial results on batch failures
• Clear error messages: Human-readable error descriptions
• Retry logic: Automatic retries for transient failures
• Validation: Input validation with helpful error messages

Common error scenarios:

• Invalid URLs or unreachable pages
• Session expiration (for authenticated audits)
• Timeout errors (configurable)
• Invalid tag combinations

🏗️ Project Structure

mcp-server/
├── src/
│   ├── server.ts           # Main MCP server entry point
│   ├── tools/              # Tool implementations
│   │   ├── audit.ts       # Core audit tools
│   │   ├── session.ts     # Session management
│   │   ├── analysis.ts    # Analysis & reporting
│   │   ├── comparison.ts  # Comparison tools
│   │   ├── export.ts      # Export tools (CSV, Excel, JSON, HTML)
│   │   ├── filter.ts      # Filtering and search tools
│   │   ├── aggregate.ts   # Aggregation and statistics tools
│   │   └── visualize.ts   # Visualization and dashboard tools
│   ├── core/              # Core accessibility functionality
│   │   ├── accessibility-runner.ts      # Accessibility execution
│   │   ├── session-manager.ts  # Session handling
│   │   ├── result-processor.ts # Result formatting
│   │   ├── error-handler.ts    # Error handling
│   │   └── progress-streamer.ts # Progress updates
│   └── types/             # TypeScript types
├── dist/                  # Compiled JavaScript
├── wave.min.js           # Accessibility engine script (required)
├── package.json
├── tsconfig.json
└── README.md

🔨 Development

Building

npm run build

Development Mode (with watch)

npm run dev

TypeScript Configuration

The project uses TypeScript with ES modules. See tsconfig.json for configuration details.

🔑 Key Differentiators

1. Conversational Interface: Results formatted for natural language understanding
2. Session Management: Only MCP with reusable authenticated sessions
3. Educational: explain_issue teaches accessibility concepts
4. Code-Level Fixes: Actual code examples, not just descriptions
5. Progress Updates: Streaming progress for long operations
6. Smart Prioritization: AI-powered issue prioritization
7. Compliance Reports: Automated VPAT/WCAG documentation
8. Tag Filtering: Filter by specific WCAG levels to reduce noise

📄 License

MIT License - feel free to use in your projects!

🤝 Contributing

Contributions are welcome! Please ensure all code follows the existing style and includes appropriate tests.

🆘 Support

For issues, questions, or contributions, please open an issue on the repository.

Happy accessibility testing! ♿✨