PS Accessibility Testing MCP Server

An MCP server that runs thorough accessibility tests on websites. It combines automated testing (Axe-core), browser automation (Puppeteer), and manual testing guidance to check WCAG compliance. The modular design makes it easy to extend, and smart filtering reduces output size by up to 99%.

🚀 Quick Start

Install from NPM

# Install globally
npm install -g @mgs416/ps-a11y-mcp

# Or install locally in your project
npm install @mgs416/ps-a11y-mcp

# Or use with npx (no installation needed)
npx @mgs416/ps-a11y-mcp

Package Details:

• 📦 Size: ~350KB compressed (1.7MB unpacked)
• 🔧 Node: Requires Node.js 18.0.0 or higher
• 📄 License: MIT
• 🏢 Publisher: Michael Simla (@mgs416)
• 🌐 Repository: GitHub

Build from Source

# Clone and setup
git clone https://github.com/publicis-sapient/ps-a11y-mcp.git
cd ps-a11y-mcp
npm install

# Build the project (required - no hot reloading)
npm run build

# Run the server (STDIO mode - default)
npm start

# Run with SSE transport for HTTP/web clients
npm start -- --transport sse --api-key your-secret-key

For detailed setup instructions, see Getting Started Guide.

Using the NPM Package

If you installed via NPM, you can reference the package directly:

// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "ps-accessibility": {
      "command": "npx",
      "args": ["@mgs416/ps-a11y-mcp"],
      "env": { "NODE_ENV": "production" }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "ps-accessibility": {
      "command": "ps-a11y-mcp",
      "args": [],
      "env": { "NODE_ENV": "production" }
    }
  }
}

Claude Desktop/Code Integration (Development)

For local development or custom builds:

// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "ps-accessibility": {
      "command": "node",
      "args": ["/path/to/ps-a11y-mcp/dist/index.js"],
      "env": { "NODE_ENV": "production" }
    }
  }
}

See Claude Integration Guide for SSE configuration options.

VS Code AI Assistant Integration

For VS Code AI assistants that support MCP servers:

• Use the SSE transport with ./scripts/start-sse.sh
• See VS Code AI Integration Guide for complete setup
• Example configuration available in examples/vscode-ai-config.json

🎯 Key Features

Clean Code & Quality

• Production Ready: 0 any types in production code, 716 tests passing (98.9%)
• Modular: 12 separate test runners with domain-driven architecture
• Type Safe: Full TypeScript with strict mode, centralized configuration
• Error Handling: Consistent BaseErrorHandler pattern, Result types
• Fast: Smart mode reduces output by 99% while keeping important info
• Quality Gates: Pre-commit hooks enforce type safety and standards
• Well Documented: Comprehensive docs with proper archival structure

What It Tests

• 12 Different Tools: Each checks a specific accessibility area
• Three Testing Layers: Automated checks, browser testing, and manual guidance
• WCAG 2.1: Tests all compliance levels (A, AA, AAA)
• Dynamic Sites: Handles SPAs, live regions, and interactive content
• Multiple Devices: Tests across different screen sizes

Transport Options

• STDIO (Default): Standard input/output for CLI and desktop clients
• SSE (New): Server-Sent Events for web and HTTP clients with API key authentication
• See SSE Transport Documentation for HTTP/web integration

📋 Available Tools

The server has 12 tools for testing different accessibility aspects. Each tool supports query modes to control how much data you get back:

Query Modes (All Tools)

• full - Everything, unfiltered (default)
• smart - Groups similar issues together (99% smaller) ⭐ Recommended
• failures - Just the problems
• statistics - Numbers only (~150 tokens)
• sample - 3 examples of each issue type

Core Testing Tools

test_comprehensive_accessibility

Runs a complete accessibility audit combining all test types.

• Options: Enhanced forms, media, responsive, SPA, user preferences, WCAG compliance
• Performance: Use queryMode: 'smart' for 99% token reduction

test_keyboard_navigation

Tests keyboard navigation flow, tab order, and identifies keyboard traps.

test_focus_management

Tests focus indicators, restoration, and programmatic focus handling.

• Advanced: Supports pagination, grouping by category/type, compression

test_screen_reader_compatibility

Tests ARIA usage, accessible names, and landmark structure.

test_color_contrast_dynamic

Tests color contrast including hover, focus, and other dynamic states.

test_content_structure

Tests semantic HTML structure, heading hierarchy, and landmarks.

Specialized Testing Tools

test_wcag_compliance

Comprehensive WCAG 2.1 compliance testing with enhanced detection capabilities.

• Coverage: Tests 32 WCAG success criteria (29 via axe-core + 3 additional enhanced criteria)
• Enhanced Autoplay Detection: Detects 125+ violation patterns including JavaScript timers, CSS animations, and modern carousel libraries
• Real Zoom Testing: Actual 200% zoom validation for text resize compliance (WCAG 1.4.4)
• Advanced Image Analysis: Heuristic detection of text content within images (WCAG 1.4.5)
• Compliance Modes: STRICT (legal compliance), RECOMMENDED (+ best practices), COMPREHENSIVE (all checks)
• Export: JSON or text format with manual testing guidance

test_enhanced_forms

Advanced form testing with dual-layer approach (Axe-core + Puppeteer).

• Features: Field-level analysis, validation testing, error handling

test_media_accessibility

Tests video/audio elements for captions, transcripts, and controls.

test_responsive_accessibility

Tests accessibility across multiple viewports and device types.

• Viewports: Mobile (375x667), Tablet (768x1024), Desktop (1920x1080)

test_user_preferences

Tests with user preferences like dark mode, reduced motion, high contrast.

test_spa_navigation

Tests single-page app navigation, route announcements, and dynamic content.

For detailed API documentation, see API Reference.

📦 NPM Package Usage

Programmatic Usage

When installed as an NPM package, you can integrate the accessibility testing into your Node.js applications:

// Using with MCP SDK
import { Client } from '@modelcontextprotocol/sdk';

// Initialize MCP client with the ps-a11y-mcp server
const client = new Client({
  name: 'my-app',
  version: '1.0.0',
});

// Connect to the accessibility server
await client.connect({
  transport: {
    type: 'subprocess',
    command: 'npx',
    args: ['@mgs416/ps-a11y-mcp'],
  },
});

// Run accessibility tests
const result = await client.callTool('test_comprehensive_accessibility', {
  url: 'https://example.com',
  options: { queryMode: 'smart' },
});

CLI Usage

# Run directly with npx
npx @mgs416/ps-a11y-mcp

# Or if installed globally
ps-a11y-mcp

# With SSE transport
ps-a11y-mcp --transport sse --port 3000 --api-key your-key

Integration in CI/CD

# GitHub Actions example
- name: Run Accessibility Tests
  run: |
    npx @mgs416/ps-a11y-mcp test https://mysite.com \
      --output-format json \
      --output-file accessibility-report.json

🚀 Quick Examples

Basic Accessibility Check (Recommended)

// Use smart mode for 99% token reduction
await mcp.callTool('test_comprehensive_accessibility', {
  url: 'https://example.com',
  options: { queryMode: 'smart' },
});

WCAG Compliance Audit

await mcp.callTool('test_wcag_compliance', {
  url: 'https://example.com',
  options: {
    level: 'AA',
    complianceMode: 'recommended',
    includeRecommendations: true,
  },
});

Form Accessibility Testing

await mcp.callTool('test_enhanced_forms', {
  url: 'https://example.com/signup',
  options: {
    queryMode: 'smart',
    maxFormsToTest: 5,
  },
});

Multi-Device Testing

await mcp.callTool('test_responsive_accessibility', {
  url: 'https://example.com',
  options: {
    queryMode: 'failures', // Only show issues
    viewports: [
      { name: 'Mobile', width: 375, height: 667, deviceType: 'mobile' },
      { name: 'Desktop', width: 1920, height: 1080, deviceType: 'desktop' },
    ],
  },
});

🎯 Intelligent Prompt Templates

The server includes 20+ sophisticated prompt templates that transform raw testing data into business-ready insights:

Business-Focused Templates

• accessibility-audit-comprehensive - Full audit with business impact analysis
• accessibility-competitive-analysis - Compare against competitors
• accessibility-business-impact - ROI and business case analysis
• accessibility-credibility-check - Validate accessibility leadership claims
• accessibility-executive-briefing - C-suite ready strategic assessment

Technical Deep-Dive Templates

• accessibility-technical-architecture - Code and framework analysis
• accessibility-dynamic-content-testing - Interactive element testing
• accessibility-mobile-responsive-audit - Cross-device accessibility
• accessibility-technical-roadmap - Implementation planning

Specialized Use Cases

• accessibility-vendor-evaluation - Assess potential partners/vendors
• accessibility-enterprise-readiness - Enterprise service capability
• accessibility-crisis-assessment - Rapid risk evaluation
• accessibility-innovation-assessment - Identify cutting-edge opportunities

Example prompt usage:

Use accessibility-credibility-check with:
- url: https://www.publicissapient.com/
- accessibility_claims: VP of Technology & Accessibility, thought leadership
- evaluation_perspective: potential-client

See prompts/USAGE_EXAMPLES.md for complete prompt documentation and real-world scenarios.

🔧 Configuration

Claude Desktop Setup

For Development (with hot reloading):

{
  "mcpServers": {
    "ps-accessibility-testing": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "<PROJECT_PATH>"
    }
  }
}

For Production:

{
  "mcpServers": {
    "ps-accessibility-testing": {
      "command": "node",
      "args": ["<PROJECT_PATH>/dist/index.js"],
      "cwd": "<PROJECT_PATH>"
    }
  }
}

Replace <PROJECT_PATH> with the full path to your ps-accessibility-mcp directory. Example:

• Windows: C:\\Users\\YourName\\Projects\\ps-accessibility-mcp
• macOS/Linux: /home/username/projects/ps-accessibility-mcp

💡 Development Tip: Use the development configuration for faster iteration - the server will automatically restart when you modify code files!

Claude Code CLI Setup

Claude Code automatically discovers and integrates MCP servers. For the PS Accessibility Testing MCP server:

# Install Claude Code CLI
npm install -g @anthropic/claude-cli

# Navigate to your project directory
cd ps-accessibility-mcp

# Ensure the MCP server is built and ready
npm run build

# Claude Code will automatically detect the MCP server
claude-code --help

Claude Code Configuration (Optional):

Create a .claude-code/config.json file in your project root:

{
  "mcpServers": {
    "ps-accessibility-testing": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": ".",
      "autoStart": true,
      "description": "Comprehensive accessibility testing for web applications"
    }
  }
}

Claude Code Usage Examples:

# Interactive mode with accessibility testing
claude-code

# Then use natural language:
# "Test the accessibility of https://www.publicissapient.com/ and provide a detailed report"
# "Run keyboard navigation tests on our homepage"
# "Check color contrast compliance for our design system"

Claude Code Integration Benefits:

• Seamless Integration: No manual server management required
• Natural Language Interface: Describe what you want to test
• File Context: Automatically understands your project structure
• Code Generation: Can generate accessibility fixes based on test results
• Interactive Mode: Real-time accessibility testing and debugging

Google Gemini CLI Setup

The MCP server is fully compatible with Google's Gemini CLI. Add to your Gemini configuration:

{
  "mcpServers": {
    "ps-accessibility-testing": {
      "command": "node",
      "args": ["<PROJECT_PATH>/dist/index.js"],
      "cwd": "<PROJECT_PATH>",
      "env": {
        "DEBUG": "accessibility:*"
      }
    }
  }
}

Gemini-Specific Usage:

# Install Gemini CLI
npm install -g @google/generative-ai-cli

# Configure with MCP server (from your project directory)
cd ps-accessibility-mcp
gemini config set mcp.servers.ps-accessibility-testing.command node
gemini config set mcp.servers.ps-accessibility-testing.args "$(pwd)/dist/index.js"

# Use with Gemini
gemini chat "Test the accessibility of https://www.publicissapient.com/ using comprehensive analysis"

GitHub Copilot Integration

For GitHub Copilot users, the MCP server can be integrated into your development workflow:

Copilot Chat Integration

Add to your VS Code settings (settings.json):

{
  "github.copilot.chat.mcpServers": {
    "ps-accessibility-testing": {
      "command": "node",
      "args": ["<PROJECT_PATH>/dist/index.js"],
      "cwd": "<PROJECT_PATH>"
    }
  }
}

Copilot Workspace Integration

Create a .copilot/mcp-servers.json file in your project root:

{
  "servers": {
    "ps-accessibility-testing": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": ".",
      "description": "Comprehensive accessibility testing for web applications"
    }
  }
}

Copilot Usage Examples

@copilot /mcp ps-accessibility-testing test_comprehensive_accessibility https://mywebsite.com

@copilot Using the ps-accessibility-testing MCP server, analyze the keyboard navigation of our homepage and provide specific code fixes for any issues found.

@copilot Run accessibility testing on our component library using the MCP server and generate a report showing WCAG compliance status.

Environment Variables

# Optional: Enable debug logging
export DEBUG=accessibility:*

# Optional: Set custom timeout
export PUPPETEER_TIMEOUT=30000

# Optional: Configure for Gemini CLI
export GEMINI_MCP_SERVER_PATH="$(pwd)"

# Optional: Configure for GitHub Copilot
export COPILOT_MCP_ENABLED=true

📊 Sample Output

Example output with queryMode: 'smart' (99% token reduction):

{
  "summary": {
    "totalIssues": 14,
    "critical": 3,
    "serious": 5,
    "moderate": 6
  },
  "violations": {
    "missing-alt-text": {
      "count": 8,
      "examples": ["img#logo", "img.hero", "img.product-1"],
      "impact": "critical",
      "wcag": ["1.1.1"],
      "fix": "Add descriptive alt text to all images"
    },
    "insufficient-contrast": {
      "count": 6,
      "examples": ["button.secondary", "a.nav-link", "p.caption"],
      "impact": "serious",
      "wcag": ["1.4.3"],
      "fix": "Increase contrast ratio to at least 4.5:1"
    }
  }
}

For full output examples, see API Reference.

🎯 Example Prompts for Publicis Sapient

Using Raw Tools

Comprehensive Analysis

Test the accessibility of https://www.publicissapient.com/ and compare it against their stated commitment to accessibility. They have Alison Walden as VP of Technology & Accessibility Lead and publish content about accessibility being "a human right." How well does their own website practice what they preach?

Keyboard Navigation Focus

Focus specifically on the main navigation menu at https://www.publicissapient.com/ and test:
- Can users navigate through all menu items using only the keyboard?
- Do dropdown/mobile menus work with keyboard navigation?
- Are there proper escape mechanisms for any expandable menus?
- Do focus indicators meet WCAG contrast requirements?

Business Impact Analysis

Create accessibility business case analysis for Publicis Sapient:
- What\'s the business impact of accessibility issues on their lead generation?
- How might accessibility improvements affect their client acquisition?
- Could accessibility be a differentiator in competitive proposals?

Using Intelligent Prompt Templates

Executive Strategic Assessment

Use accessibility-executive-briefing with:
- url: https://www.publicissapient.com/
- business_context: digital transformation consulting, accessibility thought leadership
- stakeholder_audience: C-suite executives
- strategic_focus: competitive advantage and market positioning

Competitive Intelligence

Use accessibility-competitive-analysis with:
- primary_url: https://www.publicissapient.com/
- competitor_urls: https://www.accenture.com/, https://www.deloitte.com/
- industry: consulting
- focus_metrics: accessibility innovation and client credibility

Credibility Validation

Use accessibility-credibility-check with:
- url: https://www.publicissapient.com/
- accessibility_claims: Alison Walden as VP of Technology & Accessibility, "accessibility is a human right" messaging
- client_type: enterprise
- evaluation_perspective: potential-client

These prompt templates transform raw testing data into strategic business intelligence, competitive analysis, and actionable recommendations tailored to specific stakeholder needs and business contexts.

🧪 Testing

# Run unit tests
npm test

# Run with coverage
npm run test:coverage

# Run linting
npm run lint

# Format code
npm run format

🐳 Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

# Build Docker image
docker build -f docker/Dockerfile -t ps-accessibility-mcp .

# Run container
docker run -p 3000:3000 ps-accessibility-mcp

📈 Development

For a detailed breakdown of the project structure, see the Architecture Guide.

Adding New Tests

See Contributing Guide for detailed instructions on adding new test runners.

Key Metrics

• 716 tests passing (98.9% pass rate, 2 failures under investigation)
• 0 any types in production code (eliminated all from production)
• 4,206 lines of legacy code removed
• 99% token reduction with smart query mode
• Pre-commit hooks enforce code standards automatically

🏗️ Architecture

The system is built in layers following Domain-Driven Design principles.

How It Works

+-------------------------+
|   MCP Tool Request      |
+-------------------------+
             |
             v
+-------------------------+
|   Infrastructure Layer  |
| (MCP Server, Browser)   |
+-------------------------+
             |
             v
+-------------------------+
|      Domain Layer       |
| (Test Runners, WCAG)    |
+-------------------------+
             |
             v
+-------------------------+
|       Core Layer        |
| (Base Runner, DI)       |
+-------------------------+
             |
             v
+-------------------------+
|    Contracts Layer      |
| (Types, Interfaces)     |
+-------------------------+

Shared utilities available to all layers

Design Choices

• Domain-Driven Design: Clear separation between business logic and infrastructure
• Dependency Injection: Service container manages dependencies and lifecycle
• Base Runner Pattern: Common functionality in BaseRunner, specific logic in domain runners
• Result Pattern: Functions return Result<T> for type-safe error handling
• Build-time Generation: Axe-core rules extracted at build time for zero runtime overhead

Performance

• Smart Mode: Reduces output size by up to 99% for faster processing and lower token usage.
• Browser Reuse: A browser pool is used to avoid the overhead of launching a new browser for each test.

For more details, see Architecture Guide.

📚 Documentation

• Getting Started Guide - Setup and installation
• Architecture Guide - System design and patterns
• API Reference - Detailed tool documentation
• Contributing Guide - How to contribute
• Performance Guide - Optimization strategies

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Code style and standards
• Adding new test runners
• Testing requirements
• Pull request process

📄 License

MIT License - see LICENSE file for details.

🆘 Troubleshooting

Common Issues

Build required after changes (no hot reloading)

npm run build

Puppeteer browser launch failures

# Install required dependencies
npx puppeteer browsers install chrome

Large site performance issues

• Use queryMode: 'smart' or 'statistics'
• Enable pagination for large datasets
• Increase timeout: waitForLoad: 15000

Memory issues

# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" npm start

Code Duplication or Inconsistent Naming

• Run the linter (npm run lint) to check for inconsistencies.
• Refer to the Architecture Guide for the correct project structure.

Debug Mode

LOG_LEVEL=debug npm start

For detailed troubleshooting, see Getting Started Guide.

📚 Documentation

• Documentation Index - Central navigation hub
• Getting Started - Quick start guide
• API Reference - Complete API documentation
• Architecture - System design and structure
• Performance Guide - Optimization tips
• Contributing - Contribution guidelines
• Claude Context - Current project state and context

🔗 Related Links

• WCAG 2.1 Guidelines
• Publicis Sapient Accessibility
• Model Context Protocol
• Puppeteer Documentation

Built to make accessibility testing easier and faster.