accessibility-server-mcp 1.0.0

package/README.md

@@ -0,0 +1,762 @@
+# Accessibility MCP Server
+
+A comprehensive Model Context Protocol (MCP) server for web accessibility testing and WCAG compliance analysis. This server provides automated accessibility testing capabilities for web pages, HTML snippets, and specific accessibility checks, designed to integrate seamlessly with MCP-compatible host applications.
+
+## 🚀 Key Features
+
+- **🌐 URL Testing**: Test any public URL for accessibility issues using Puppeteer and axe-core
+- **🕷️ Website-Wide Testing**: Crawl and test entire websites for comprehensive accessibility audits
+- **📝 HTML Snippet Testing**: Analyze raw HTML strings for accessibility compliance  
+- **📋 WCAG Compliance**: Support for WCAG 2.0, 2.1, and 2.2 standards (A, AA, AAA levels)
+- **🎨 Color Contrast Analysis**: Check color combinations for WCAG contrast requirements
+- **♿ ARIA Validation**: Validate proper usage of ARIA attributes and roles
+- **📱 Mobile Testing**: Orientation lock detection and mobile accessibility issues
+- **📊 Comprehensive Reports**: Detailed accessibility reports with actionable recommendations
+- **🔒 Local Execution**: All testing happens locally - no external API calls or data transmission
+- **🏗️ Enterprise Ready**: Built for CI/CD integration and production environments
+
+## 🔌 Integration with Host Applications
+
+### Supported MCP Host Applications
+
+This server is compatible with any application that supports the Model Context Protocol (MCP), including:
+
+- **Claude Desktop** - Anthropic's desktop application
+- **Cline VS Code Extension** - Development environment integration
+- **Custom MCP Clients** - Any application using the `@modelcontextprotocol/sdk`
+
+### Quick Integration Setup
+
+#### For MCP Clients (like Claude Desktop, VS Code Extensions)
+
+Add this configuration to your MCP client:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "accessibility-mcp-server"],
+  "env": {
+    "MCP_MODE": "true"
+  }
+}
+```
+
+#### For Local Development/Testing
+
+```json
+{
+  "command": "node",
+  "args": ["path/to/accessibility-mcp/dist/index.js"],
+  "env": {
+    "MCP_MODE": "true"
+  }
+}
+```
+
+#### Simple Mode (faster startup, core features only)
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "accessibility-mcp-server", "--simple"],
+  "env": {
+    "MCP_MODE": "true"
+  }
+}
+```
+
+> **Note**: The server will be published to NPM as `accessibility-mcp-server` for easy npx usage.
+
+#### For Claude Desktop
+
+1. **Install the server:**
+```bash
+npm install -g accessibility-mcp-server
+```
+
+2. **Configure Claude Desktop** by adding to your `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "accessibility": {
+      "command": "accessibility-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+3. **Restart Claude Desktop** and the accessibility tools will be available.
+
+#### For Cline VS Code Extension
+
+1. **Install the server globally:**
+```bash
+npm install -g accessibility-mcp-server
+```
+
+2. **Configure in VS Code settings** or Cline configuration:
+```json
+{
+  "mcpServers": {
+    "accessibility": {
+      "command": "accessibility-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+#### For Custom Applications
+
+Install the package as a dependency:
+```bash
+npm install accessibility-mcp-server
+```
+
+Then integrate programmatically:
+```javascript
+import { AccessibilityMCPServer } from 'accessibility-mcp-server';
+
+// Create and start the server
+const server = new AccessibilityMCPServer({
+  mode: 'full', // or 'simple' for basic features only
+  enableLogging: true
+});
+
+await server.run();
+```
+
+## 📦 Installation Options
+
+### 1. NPM Package (Recommended for Host Integration)
+
+```bash
+# For global command-line usage
+npm install -g accessibility-mcp-server
+
+# For local project integration
+npm install accessibility-mcp-server
+```
+
+### 2. From Source (Development)
+
+```bash
+# Clone the repository
+git clone https://github.com/nigamutkarsh/accessibility-mcp-server.git
+cd AccessibilityMCP
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Install globally
+npm install -g .
+```
+
+### 3. Docker Deployment
+
+```bash
+# Build Docker image
+docker build -t accessibility-mcp .
+
+# Run container
+docker run -d --name accessibility-mcp \
+  -p 3000:3000 \
+  accessibility-mcp
+```
+
+## 🛠️ Available MCP Tools
+
+The server provides four main tools for accessibility testing, with two operational modes:
+
+### Simple Mode Tools (Basic Features)
+- `test_accessibility` - Test URLs or HTML content
+- `test_website_accessibility` - Test entire websites (crawl multiple pages)
+- `check_color_contrast` - Validate color combinations
+
+### Full Mode Tools (All Features)  
+- `test_accessibility` - Test URLs or HTML content
+- `test_website_accessibility` - Test entire websites (crawl multiple pages)
+- `check_color_contrast` - Validate color combinations
+- `get_wcag_rules` - Retrieve WCAG rule information
+
+### Tool Usage Examples
+
+#### 1. Test Accessibility
+
+Test a website or HTML content for accessibility issues:
+
+**For URLs:**
+```json
+{
+  "name": "test_accessibility",
+  "arguments": {
+    "target": "https://example.com",
+    "type": "url",
+    "level": "basic",
+    "wcagLevel": "AA"
+  }
+}
+```
+
+**For HTML snippets:**
+```json
+{
+  "name": "test_accessibility",
+  "arguments": {
+    "target": "<button>Click me</button><div>Content without proper contrast</div>",
+    "type": "html", 
+    "level": "full",
+    "wcagLevel": "AAA"
+  }
+}
+```
+
+#### 2. Test Website Accessibility
+
+Test entire websites by crawling multiple pages:
+
+```json
+{
+  "name": "test_website_accessibility",
+  "arguments": {
+    "baseUrl": "https://example.com",
+    "wcagLevel": "AA",
+    "maxPages": 20,
+    "maxDepth": 3,
+    "concurrency": 3,
+    "excludePatterns": ["/admin/", "/api/", ".pdf"],
+    "continueOnError": true,
+    "delay": 1000
+  }
+}
+```
+
+**Key Features of Website Testing:**
+- 🕷️ **Automatic Crawling**: Discovers pages by following links
+- 📊 **Site-wide Reports**: Aggregated accessibility metrics across all pages  
+- 🎯 **Configurable Scope**: Control depth, page limits, and URL patterns
+- ⚡ **Parallel Testing**: Test multiple pages simultaneously
+- 🔍 **Common Issues**: Identifies violations that appear across multiple pages
+
+> 📖 **For detailed website testing documentation, see [WEBSITE_TESTING.md](./WEBSITE_TESTING.md)**
+
+#### 3. Check Color Contrast
+
+Validate color combinations for WCAG compliance:
+
+```json
+{
+  "name": "check_color_contrast",
+  "arguments": {
+    "foreground": "#333333",
+    "background": "#ffffff",
+    "fontSize": 16,
+    "isBold": false
+  }
+}
+```
+
+#### 4. Get WCAG Rules (Full Mode Only)
+
+Retrieve information about WCAG accessibility rules:
+
+```json
+{
+  "name": "get_wcag_rules",
+  "arguments": {
+    "wcagLevel": "AA",
+    "category": "color",
+    "search": "contrast",
+    "limit": 10
+  }
+}
+```
+
+## 🔧 MCP Client Integration
+
+### Using with @modelcontextprotocol/sdk
+
+```javascript
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+async function setupAccessibilityTesting() {
+  // Create transport to the accessibility server
+  const transport = new StdioClientTransport({
+    command: 'accessibility-mcp',
+    args: []
+  });
+
+  // Create MCP client
+  const client = new Client({
+    name: 'my-accessibility-client',
+    version: '1.0.0'
+  }, {
+    capabilities: {}
+  });
+
+  // Connect to the server
+  await client.connect(transport);
+
+  // List available tools
+  const tools = await client.listTools();
+  console.log('Available tools:', tools);
+
+  // Test a website
+  const result = await client.callTool('test_accessibility', {
+    target: 'https://example.com',
+    type: 'url',
+    level: 'basic',
+    wcagLevel: 'AA'
+  });
+
+  console.log('Accessibility test result:', result);
+
+  // Clean up
+  await client.close();
+}
+
+setupAccessibilityTesting().catch(console.error);
+```
+
+### Custom Host Application Integration
+
+```javascript
+import { spawn } from 'child_process';
+import { EventEmitter } from 'events';
+
+class AccessibilityMCPClient extends EventEmitter {
+  constructor() {
+    super();
+    this.process = null;
+    this.requestId = 0;
+  }
+
+  async connect() {
+    // Start the accessibility MCP server
+    this.process = spawn('accessibility-mcp', [], {
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    // Handle server responses
+    this.process.stdout.on('data', (data) => {
+      const responses = data.toString().split('\n').filter(Boolean);
+      responses.forEach(response => {
+        try {
+          const parsed = JSON.parse(response);
+          this.emit('response', parsed);
+        } catch (error) {
+          console.error('Failed to parse response:', error);
+        }
+      });
+    });
+
+    // Initialize the connection
+    await this.sendRequest('initialize', {
+      protocolVersion: '1.0.0',
+      capabilities: {},
+      clientInfo: {
+        name: 'custom-accessibility-client',
+        version: '1.0.0'
+      }
+    });
+  }
+
+  async sendRequest(method, params = {}) {
+    const request = {
+      jsonrpc: '2.0',
+      id: ++this.requestId,
+      method,
+      params
+    };
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('Request timeout'));
+      }, 30000);
+
+      const handler = (response) => {
+        if (response.id === request.id) {
+          clearTimeout(timeout);
+          this.removeListener('response', handler);
+          if (response.error) {
+            reject(new Error(response.error.message));
+          } else {
+            resolve(response.result);
+          }
+        }
+      };
+
+      this.on('response', handler);
+      this.process.stdin.write(JSON.stringify(request) + '\n');
+    });
+  }
+
+  async testAccessibility(target, options = {}) {
+    return this.sendRequest('tools/call', {
+      name: 'test_accessibility',
+      arguments: {
+        target,
+        type: options.type || 'url',
+        level: options.level || 'basic',
+        wcagLevel: options.wcagLevel || 'AA'
+      }
+    });
+  }
+
+  async checkColorContrast(foreground, background, options = {}) {
+    return this.sendRequest('tools/call', {
+      name: 'check_color_contrast', 
+      arguments: {
+        foreground,
+        background,
+        fontSize: options.fontSize || 16,
+        isBold: options.isBold || false
+      }
+    });
+  }
+
+  async close() {
+    if (this.process) {
+      this.process.kill();
+      this.process = null;
+    }
+  }
+}
+```
+
+## ⚙️ Configuration & Environment
+
+### Server Modes
+
+The server supports two operational modes:
+
+**Simple Mode:**
+- Basic accessibility testing
+- Color contrast analysis
+- Minimal resource usage
+- Faster startup time
+
+**Full Mode (Default):**
+- Complete accessibility testing suite
+- WCAG rules database access
+- Advanced analysis features
+- Comprehensive reporting
+
+```bash
+# Start in simple mode
+accessibility-mcp --simple
+
+# Start in full mode (default)
+accessibility-mcp
+```
+
+### Environment Variables
+
+```bash
+# Server mode configuration
+ACCESSIBILITY_MCP_MODE=full   # or 'simple'
+
+# Disable logging when running as MCP server
+MCP_MODE=true
+
+# Browser configuration
+PUPPETEER_HEADLESS=true
+PUPPETEER_TIMEOUT=30000
+
+# Performance settings
+NODE_ENV=production
+LOG_LEVEL=error
+```
+
+### Host Application Configuration
+
+Different host applications require different configuration approaches:
+
+**Claude Desktop (`claude_desktop_config.json`):**
+```json
+{
+  "mcpServers": {
+    "accessibility": {
+      "command": "accessibility-mcp",
+      "args": ["--simple"]
+    }
+  }
+}
+```
+
+**Cline/MCP Configuration:**
+```json
+{
+  "mcpServers": {
+    "accessibility-testing": {
+      "command": "accessibility-mcp",
+      "args": [],
+      "env": {
+        "ACCESSIBILITY_MCP_MODE": "full"
+      }
+    }
+  }
+}
+```
+
+## 📊 Response Format
+
+All tools return responses in a consistent format:
+
+```typescript
+interface ToolResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: {
+    type: string;
+    message: string;
+    details?: any;
+  };
+  processingTime: number;
+  timestamp: string;
+}
+```
+
+### Sample Accessibility Test Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "target": "https://example.com",
+    "type": "url",
+    "wcagLevel": "AA",
+    "violations": [
+      {
+        "id": "color-contrast",
+        "impact": "serious", 
+        "description": "Elements must have sufficient color contrast",
+        "help": "Ensure the contrast ratio is at least 4.5:1",
+        "helpUrl": "https://dequeuniversity.com/rules/axe/4.8/color-contrast",
+        "nodes": [
+          {
+            "html": "<p style=\"color: #999; background: #fff;\">Low contrast text</p>",
+            "target": ["p"],
+            "failureSummary": "Fix any of the following:\n  Element has insufficient color contrast"
+          }
+        ]
+      }
+    ],
+    "summary": {
+      "totalViolations": 1,
+      "violationsByImpact": {
+        "critical": 0,
+        "serious": 1,
+        "moderate": 0,
+        "minor": 0
+      },
+      "compliance": {
+        "A": false,
+        "AA": false, 
+        "AAA": false
+      },
+      "score": 75
+    },
+    "metadata": {
+      "testDuration": 2500,
+      "pageTitle": "Example Website",
+      "viewport": { "width": 1920, "height": 1080 }
+    }
+  },
+  "processingTime": 2500,
+  "timestamp": "2024-12-01T10:30:00.000Z"
+}
+```
+
+## 🚀 Production Deployment
+
+### Enterprise Environment Setup
+
+1. **Install as system service:**
+```bash
+# Install globally
+npm install -g accessibility-mcp-server
+
+# Create systemd service (Linux)
+sudo cat > /etc/systemd/system/accessibility-mcp.service << EOF
+[Unit]
+Description=Accessibility MCP Server
+After=network.target
+
+[Service]
+Type=simple
+User=accessibility
+ExecStart=/usr/local/bin/accessibility-mcp
+Restart=always
+Environment=NODE_ENV=production
+Environment=MCP_MODE=true
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# Enable and start service
+sudo systemctl enable accessibility-mcp
+sudo systemctl start accessibility-mcp
+```
+
+2. **Docker Production Setup:**
+```bash
+# Production Dockerfile
+FROM node:18-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY dist/ ./dist/
+COPY config/ ./config/
+EXPOSE 3000
+USER node
+CMD ["node", "dist/index.js"]
+```
+
+3. **CI/CD Integration:**
+```yaml
+# GitHub Actions example
+name: Accessibility Testing
+on: [push, pull_request]
+
+jobs:
+  accessibility:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+      
+      - name: Install Accessibility MCP Server
+        run: npm install -g accessibility-mcp-server
+      
+      - name: Test Website Accessibility
+        run: |
+          # Note: CLI interface would need to be implemented for CI/CD
+          # This is a conceptual example
+          echo "Accessibility testing would run here"
+```
+
+## 🔒 Security & Compliance
+
+### Security Features
+
+- **🔒 Local Processing**: All accessibility testing happens locally - no external API calls
+- **🛡️ Input Validation**: All inputs validated using Zod schemas
+- **🧹 Resource Management**: Automatic cleanup of browser instances and memory
+- **📦 Sandboxed Execution**: Puppeteer runs in sandboxed mode
+- **🚫 No Data Transmission**: Zero data leaves the customer environment
+
+### Privacy Compliance
+
+- **GDPR Compliant**: No personal data processing or storage
+- **SOC 2 Ready**: Designed for enterprise security requirements  
+- **Zero Trust**: No external dependencies or data transmission
+- **Audit Trail**: Comprehensive logging for security auditing
+
+## 🆘 Troubleshooting
+
+### Common Integration Issues
+
+**Issue: MCP server not starting**
+```bash
+# Check if Node.js version is compatible
+node --version  # Should be 18.0.0 or higher
+
+# Verify installation
+accessibility-mcp --version
+
+# Check for conflicting processes
+ps aux | grep accessibility-mcp
+```
+
+**Issue: Tools not appearing in host application**
+```bash
+# Verify MCP server is properly configured
+cat ~/.config/claude-desktop/claude_desktop_config.json
+
+# Test server manually
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | accessibility-mcp
+```
+
+**Issue: Browser automation failures**
+```bash
+# Install required dependencies (Linux)
+sudo apt-get install -y chromium-browser
+
+# Check browser permissions
+export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
+```
+
+### Performance Optimization
+
+**For high-volume testing:**
+```bash
+# Set environment variables for better performance
+export PUPPETEER_HEADLESS=true
+export NODE_ENV=production
+export ACCESSIBILITY_MCP_MODE=simple
+```
+
+**Memory management:**
+```bash
+# Monitor memory usage
+top -p $(pgrep -f accessibility-mcp)
+
+# Restart server if memory usage is high
+sudo systemctl restart accessibility-mcp
+```
+
+## 📝 API Reference
+
+### Tool: `test_accessibility`
+
+Tests websites or HTML content for accessibility violations.
+
+**Parameters:**
+- `target` (string, required): URL or HTML content to test
+- `type` (enum): `"url"` | `"html"` (default: `"url"`)
+- `level` (enum): `"basic"` | `"full"` (default: `"basic"`)
+- `wcagLevel` (enum): `"A"` | `"AA"` | `"AAA"` (default: `"AA"`)
+
+### Tool: `check_color_contrast`
+
+Analyzes color combinations for WCAG compliance.
+
+**Parameters:**
+- `foreground` (string, required): Foreground color (hex, rgb, hsl, or named)
+- `background` (string, required): Background color (hex, rgb, hsl, or named)
+- `fontSize` (number): Font size in pixels (default: 16)
+- `isBold` (boolean): Whether text is bold (default: false)
+
+### Tool: `get_wcag_rules` (Full Mode Only)
+
+Retrieves WCAG accessibility rule information.
+
+**Parameters:**
+- `wcagLevel` (enum, optional): `"A"` | `"AA"` | `"AAA"`
+- `category` (string, optional): Rule category filter
+- `search` (string, optional): Search term for rules
+- `limit` (number, optional): Maximum rules to return (1-50, default: 20)
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🤝 Support & Contributing
+
+- **Issues**: [GitHub Issues](https://github.com/nigamutkarsh/accessibility-mcp-server/issues)
+- **Documentation**: Check the `/docs` folder for additional guides
+- **Contributing**: Fork the repository and submit pull requests
+- **Discussions**: Use GitHub Discussions for questions and feature requests
+
+---
+
+**Built with ❤️ for web accessibility and inclusive design**