npm package: @mgs416/ps-a11y-mcp
Description: MCP server for comprehensive accessibility testing - Publicis Sapient Edition
Author: Michael Simla
Latest version: 1.8.2

# PS Accessibility Testing MCP Server

[![npm version](https://img.shields.io/npm/v/@mgs416/ps-a11y-mcp.svg)](https://www.npmjs.com/package/@mgs416/ps-a11y-mcp)
[![npm downloads](https://img.shields.io/npm/dm/@mgs416/ps-a11y-mcp.svg)](https://www.npmjs.com/package/@mgs416/ps-a11y-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Package Size](https://img.shields.io/bundlephobia/minzip/@mgs416/ps-a11y-mcp)](https://bundlephobia.com/package/@mgs416/ps-a11y-mcp)

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

```bash
# 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](https://www.npmjs.com/~mgs416))
- 🌐 **Repository**: [GitHub](https://github.com/publicis-sapient/ps-a11y-mcp)

### Build from Source

```bash
# 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](./docs/GETTING_STARTED.md).

### Using the NPM Package

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

```json
// 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:

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

### Claude Desktop/Code Integration (Development)

For local development or custom builds:

```json
// 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](./docs/future-plans/CLAUDE_INTEGRATION.md) 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](./docs/future-plans/VSCODE_AI_INTEGRATION.md) 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](./docs/future-plans/SSE_TRANSPORT.md) 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](./docs/API_REFERENCE.md).

## 📦 NPM Package Usage

### Programmatic Usage

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

```javascript
// 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

```bash
# 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

```yaml
# 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)

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

### WCAG Compliance Audit

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

### Form Accessibility Testing

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

### Multi-Device Testing

```javascript
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):**

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

**For Production:**

```json
{
  "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:

```bash
# 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:

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

**Claude Code Usage Examples:**

```bash
# 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:

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

**Gemini-Specific Usage:**

```bash
# 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`):

```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:

```json
{
  "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

```bash
# 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):

```json
{
  "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](./docs/API_REFERENCE.md).

## 🎯 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

```bash
# Run unit tests
npm test

# Run with coverage
npm run test:coverage

# Run linting
npm run lint

# Format code
npm run format
```

## 🐳 Docker Deployment

```bash
# 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](./docs/ARCHITECTURE.md).

### Adding New Tests

See [Contributing Guide](./CONTRIBUTING.md) 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](./docs/ARCHITECTURE.md).

## 📚 Documentation

- **[Getting Started Guide](./docs/GETTING_STARTED.md)** - Setup and installation
- **[Architecture Guide](./docs/ARCHITECTURE.md)** - System design and patterns
- **[API Reference](./docs/API_REFERENCE.md)** - Detailed tool documentation
- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute
- **[Performance Guide](./docs/PERFORMANCE_GUIDE.md)** - Optimization strategies

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) 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)**

```bash
npm run build
```

**Puppeteer browser launch failures**

```bash
# 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**

```bash
# 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](./docs/ARCHITECTURE.md) for the correct project structure.

### Debug Mode

```bash
LOG_LEVEL=debug npm start
```

For detailed troubleshooting, see [Getting Started Guide](./docs/GETTING_STARTED.md#troubleshooting).

## 📚 Documentation

- **[Documentation Index](./docs/DOCUMENTATION_INDEX.md)** - Central navigation hub
- **[Getting Started](./docs/GETTING_STARTED.md)** - Quick start guide
- **[API Reference](./docs/API_REFERENCE.md)** - Complete API documentation
- **[Architecture](./docs/ARCHITECTURE.md)** - System design and structure
- **[Performance Guide](./docs/PERFORMANCE_GUIDE.md)** - Optimization tips
- **[Contributing](./CONTRIBUTING.md)** - Contribution guidelines
- **[Claude Context](./CLAUDE.md)** - Current project state and context

## 🔗 Related Links

- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
- [Publicis Sapient Accessibility](https://www.publicissapient.com/accessibility)
- [Model Context Protocol](https://github.com/anthropics/mcp)
- [Puppeteer Documentation](https://pptr.dev/)

---

Built to make accessibility testing easier and faster.