Accessibility MCP Server

# AI Coding Agent Instructions This file provides workspace-specific instructions for AI coding agents working in this repository. ## Project Overview This is an accessibility testing MCP (Model Context Protocol) server that enables AI agents to perform automated accessibility audits on websites using Playwright and axe-core against WCAG standards. ## Architecture Overview - **MCP Server**: Exposes accessibility testing tools to AI agents via stdio transport - **Accessibility Engine**: Playwright browser automation + axe-core WCAG compliance scanning - **File Output System**: Structured text and JSON result generation - **Type-Safe Implementation**: Full TypeScript with comprehensive interfaces ## Key Development Guidelines ### MCP Integration Patterns - Three main tools: `test_accessibility`, `get_test_results`, `list_test_results` - Uses @modelcontextprotocol/sdk with stdio transport for AI agent communication - All tools return structured CallToolResult with text content for LLM consumption - Error handling propagates meaningful messages back to requesting AI agents ### Accessibility Testing Approach - Playwright browser automation (Chromium/Firefox/WebKit support) - AxeBuilder integration with WCAG 2.1/2.2 tag-based rule selection - Real browser rendering ensures accurate accessibility state evaluation - Screenshot capture capability for visual context ### Development Workflow - Build with `npm run build` (TypeScript -> ESM JavaScript) - Development mode: `npm run dev` (nodemon + ts-node) - Production: `npm start` (runs compiled dist/server/index.js) - MCP server communicates via stdin/stdout - no HTTP endpoints ### Project Structure - `/src/server/` - MCP protocol handlers and main entry point - `/src/accessibility/` - Playwright + axe-core testing engine - `/src/types/` - TypeScript interfaces for all data structures - `/src/utils/` - File output management and input validation - `/outputs/` - Generated accessibility reports (text + JSON) ### Code Conventions - ESM modules with .js imports in TypeScript files - Comprehensive error handling with graceful degradation - Type-safe axe-core result processing with impact severity mapping - URL validation prevents testing localhost/private addresses for security ### Testing Strategy - Browser isolation through Playwright's context management - Configurable WCAG compliance levels (A/AA/AAA) and versions (2.1/2.2) - Structured violation reporting with remediation guidance - Raw JSON + human-readable text dual output formats ## Critical Implementation Notes - Uses `AxeBuilder` class from @axe-core/playwright (not legacy inject methods) - Target selectors from axe-core use complex types - handle as `any` in interfaces - MCP tool arguments require `as unknown as Type` casting due to SDK typing - Browser initialization must be called before each test and cleaned up after