mcp-accessibility-scanner 1.0.9 → 1.0.11

package/Readme.md

@@ -2,13 +2,27 @@
 
 # MCP Accessibility Scanner 🔍
 
-A Model Context Protocol (MCP) server that provides automated web accessibility scanning using Playwright and Axe-core. This server enables LLMs to perform WCAG compliance checks, capture annotated screenshots, and generate detailed accessibility reports.
+A powerful Model Context Protocol (MCP) server that provides automated web accessibility scanning and browser automation using Playwright and Axe-core. This server enables LLMs to perform WCAG compliance checks, interact with web pages, manage persistent browser sessions, and generate detailed accessibility reports with visual annotations.
 
 ## Features
 
-✅ Full WCAG 2.1/2.2 compliance checking  
+### Accessibility Scanning
+✅ Full WCAG 2.0/2.1/2.2 compliance checking (A, AA, AAA levels)  
 🖼️ Automatic screenshot capture with violation highlighting  
-📄 Detailed JSON reports with remediation guidance
+📄 Detailed JSON reports with remediation guidance  
+🎯 Support for specific violation categories (color contrast, ARIA, forms, keyboard navigation, etc.)  
+
+### Browser Automation
+🖱️ Click elements by CSS selector or visible text  
+⌨️ Type text into inputs by selector or label  
+🔍 Analyze pages to discover all interactive elements  
+📸 Capture screenshots after each interaction  
+
+### Session Management
+🔄 Create persistent browser sessions for multi-step workflows  
+⏱️ Automatic session cleanup after 3 minutes of inactivity  
+🌐 Navigate between pages while maintaining session state  
+📊 Run accessibility scans within active sessions
 
 ## Installation
 
@@ -67,29 +81,111 @@ Here's the Claude Desktop configuration:
 }
 ```
 
-## Usage
+## Available Tools
+
+The MCP server exposes 18 tools for accessibility scanning and browser automation:
+
+### Accessibility Scanning
 
-The scanner exposes a single tool `scan_accessibility` that accepts:
+#### `accessibility-scan`
+Performs a comprehensive accessibility scan on a webpage.
 
+**Parameters:**
 - `url`: The webpage URL to scan (required)
-- `violationsTag`: Array of accessibility violation tags to check (required)
-- `viewport`: Optional object to customize the viewport size
-  - `width`: number (default: 1920)
-  - `height`: number (default: 1080)
-- `shouldRunInHeadless`: Optional boolean to control headless mode (default: true)
+- `violationsTag`: Array of WCAG/violation tags to check (required)
+- `viewport`: Optional viewport size (default: 1920x1080)
+- `shouldRunInHeadless`: Optional headless mode control (default: true)
+
+**Supported Violation Tags:**
+- WCAG levels: `wcag2a`, `wcag2aa`, `wcag2aaa`, `wcag21a`, `wcag21aa`, `wcag21aaa`, `wcag22a`, `wcag22aa`, `wcag22aaa`
+- Section 508: `section508`
+- Categories: `cat.color` (contrast), `cat.aria`, `cat.forms`, `cat.keyboard`, `cat.language`, `cat.structure`, etc.
+
+### Browser Automation
+
+#### `click-element`
+Clicks an element by CSS selector.
+- Parameters: `url`, `selector`, `viewport`, `shouldRunInHeadless`
+
+#### `click-element-by-text`
+Clicks elements by their visible text content.
+- Parameters: `url`, `text`, `elementType` (optional), `viewport`, `shouldRunInHeadless`
+
+#### `type-text`
+Types text into an input field by CSS selector.
+- Parameters: `url`, `selector`, `text`, `viewport`, `shouldRunInHeadless`
+
+#### `type-text-by-label`
+Types text into input fields by their label text.
+- Parameters: `url`, `labelText`, `text`, `viewport`, `shouldRunInHeadless`
+
+#### `analyze-page`
+Analyzes page to identify all interactive elements.
+- Parameters: `url`, `viewport`, `shouldRunInHeadless`
+- Returns: Lists of all buttons, links, and inputs on the page
+
+### Session Management
+
+#### `create-session`
+Creates a persistent browser session for multiple operations.
+- Parameters: `sessionId`, `viewport`, `shouldRunInHeadless`
+- Sessions auto-expire after 3 minutes of inactivity
+
+#### `navigate-session`
+Navigates to a URL in an existing session.
+- Parameters: `sessionId`, `url`
+
+#### `click-session` / `click-session-by-text`
+Click elements within a session.
 
-**Note: When running a scan, an annotated screenshot highlighting any accessibility violations will be automatically saved to your downloads folder.**
+#### `type-session` / `type-session-by-label`
+Type text within a session.
 
-Example usage in Claude:
+#### `scan-session`
+Run accessibility scan on current page in session.
+
+#### `analyze-session`
+Analyze current page in session.
+
+#### `close-session`
+Close a browser session.
+
+#### `list-sessions`
+List all active browser sessions.
+
+## Usage Examples
+
+### Basic Accessibility Scan
+```
+Could you scan example.com for WCAG 2.1 AA compliance issues?
+```
+
+### Color Contrast Check
 ```
-Could you scan example.com for accessibility issues related to color contrast?
+Please check example.com for color contrast accessibility issues (cat.color).
 ```
 
-Advanced example with custom options:
+### Multi-step Workflow with Sessions
 ```
-Could you scan example.com for accessibility issues with a viewport of 1280x720 and show the browser window?
+1. Create a session and navigate to example.com
+2. Click the "Sign In" button
+3. Type "user@example.com" into the email field
+4. Run an accessibility scan on the login page
+5. Close the session
 ```
 
+### Page Analysis
+```
+Can you analyze example.com and tell me what interactive elements are available?
+```
+
+### Smart Element Interaction
+```
+Navigate to example.com and click the button that says "Get Started"
+```
+
+**Note:** All tools automatically save annotated screenshots to your downloads folder, with accessibility violations highlighted in red and numbered badges.
+
 ## Development
 
 Clone and set up the project:

package/build/accessibilityChecker.js

@@ -12,136 +12,368 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessibilityScanner = void 0;
 exports.scanViolations = scanViolations;
 const playwright_1 = require("playwright");
 const playwright_2 = require("@axe-core/playwright");
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
-function scanViolations(url_1, violationsTags_1) {
-    return __awaiter(this, arguments, void 0, function* (url, violationsTags, viewport = { width: 1920, height: 1080 }, shouldRunInHeadless = true) {
-        var _a;
-        const browser = yield playwright_1.chromium.launch({
-            headless: shouldRunInHeadless,
-            args: [
-                "--disable-blink-features=AutomationControlled",
-                "--disable-dev-shm-usage",
-                "--no-sandbox",
-                "--disable-setuid-sandbox",
-            ],
+class AccessibilityScanner {
+    constructor() {
+        this.browser = null;
+        this.context = null;
+        this.page = null;
+        this.defaultViewport = { width: 1920, height: 1080 };
+        this.userAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+    }
+    initialize() {
+        return __awaiter(this, arguments, void 0, function* (shouldRunInHeadless = true) {
+            this.browser = yield playwright_1.chromium.launch({
+                headless: shouldRunInHeadless,
+                args: [
+                    "--disable-blink-features=AutomationControlled",
+                    "--disable-dev-shm-usage",
+                    "--no-sandbox",
+                    "--disable-setuid-sandbox",
+                ],
+            });
         });
-        const context = yield browser.newContext({
-            viewport,
-            userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+    }
+    createContext() {
+        return __awaiter(this, arguments, void 0, function* (viewport = this.defaultViewport) {
+            if (!this.browser) {
+                throw new Error("Browser not initialized. Call initialize() first.");
+            }
+            this.context = yield this.browser.newContext({
+                viewport,
+                userAgent: this.userAgent,
+            });
         });
-        const page = yield context.newPage();
-        yield page.goto(url);
-        yield page.addStyleTag({
-            content: `
-        .a11y-violation {
-            position: relative !important;
-            outline: 4px solid #FF4444 !important;
-            margin: 2px !important;
-        }
-        .violation-number {
-            position: absolute !important;
-            top: -12px !important;
-            left: -12px !important;
-            background: #FF4444;
-            color: white !important;
-            width: 25px;
-            height: 25px;
-            border-radius: 50%;
-            display: flex !important;
-            align-items: center;
-            justify-content: center;
-            font-weight: bold;
-            font-size: 14px;
-            z-index: 10000;
-        }
-        .a11y-violation-info {
-            position: absolute !important;
-            background: #333333 !important;
-            color: white !important;
-            padding: 12px !important;
-            border-radius: 4px !important;
-            font-size: 14px !important;
-            max-width: 300px !important;
-            z-index: 9999 !important;
-            box-shadow: 0 2px 10px rgba(0,0,0,0.3);
-        }
-    `,
+    }
+    createPage() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.context) {
+                throw new Error("Context not created. Call createContext() first.");
+            }
+            this.page = yield this.context.newPage();
         });
-        const axe = new playwright_2.AxeBuilder({ page }).withTags(violationsTags);
-        const results = yield axe.analyze();
-        let violationCounter = 1;
-        for (const violation of results.violations) {
-            for (const node of violation.nodes) {
-                try {
-                    const targetSelector = node.target[0];
-                    const selector = Array.isArray(targetSelector)
-                        ? targetSelector.join(" ")
-                        : targetSelector;
-                    yield page.evaluate(({ selector, violationData, counter }) => {
-                        const elements = document.querySelectorAll(selector);
-                        elements.forEach((element) => {
-                            // Create number badge directly on the element
-                            const numberBadge = document.createElement("div");
-                            numberBadge.className = "violation-number";
-                            numberBadge.textContent = counter.toString();
-                            // Add violation styling
-                            element.classList.add("a11y-violation");
-                            element.appendChild(numberBadge);
-                            // Create info box
-                            const listItem = document.createElement("div");
-                            listItem.style.marginBottom = "15px";
-                            listItem.innerHTML = `
-                    <div style="color: #FF4444; font-weight: bold;">
-                        Violation #${counter}: ${violationData.impact.toUpperCase()}
-                    </div>
-                    <div style="margin: 5px 0; font-size: 14px;">
-                        ${violationData.description}
-                    </div>
-                `;
-                            // Position info box relative to element
-                            document.body.appendChild(listItem);
-                            const rect = element.getBoundingClientRect();
-                            listItem.style.left = `${rect.left + window.scrollX}px`;
-                            listItem.style.top = `${rect.bottom + window.scrollY + 10}px`;
-                        });
-                    }, {
-                        selector: selector,
-                        violationData: {
-                            impact: violation.impact,
-                            description: violation.description,
-                        },
-                        counter: violationCounter,
+    }
+    navigateToUrl(url) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.page) {
+                throw new Error("Page not created. Call createPage() first.");
+            }
+            yield this.page.goto(url);
+        });
+    }
+    clickElement(selector) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.page) {
+                throw new Error("Page not created. Call createPage() first.");
+            }
+            yield this.page.click(selector);
+            yield this.page.waitForLoadState('load');
+        });
+    }
+    typeText(selector, text) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.page) {
+                throw new Error("Page not created. Call createPage() first.");
+            }
+            yield this.page.fill(selector, text);
+            yield this.page.waitForLoadState('load');
+        });
+    }
+    getElementByText(text, elementType) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.page) {
+                throw new Error("Page not created. Call createPage() first.");
+            }
+            const elements = yield this.page.locator(elementType || '*', { hasText: text }).all();
+            if (elements.length === 0) {
+                return null;
+            }
+            if (elements.length === 1) {
+                return yield elements[0].evaluate(el => {
+                    if (el.id)
+                        return `#${el.id}`;
+                    if (el.className)
+                        return `.${el.className.split(' ')[0]}`;
+                    return el.tagName.toLowerCase();
+                });
+            }
+            for (let i = 0; i < elements.length; i++) {
+                const element = elements[i];
+                const isExactMatch = yield element.evaluate((el, searchText) => {
+                    var _a, _b;
+                    return ((_a = el.textContent) === null || _a === void 0 ? void 0 : _a.trim()) === searchText ||
+                        ('innerText' in el && ((_b = el.innerText) === null || _b === void 0 ? void 0 : _b.trim()) === searchText) ||
+                        el.value === searchText;
+                }, text);
+                if (isExactMatch) {
+                    return yield element.evaluate(el => {
+                        var _a;
+                        if (el.id)
+                            return `#${el.id}`;
+                        if (el.className)
+                            return `.${el.className.split(' ')[0]}`;
+                        return `:nth-of-type(${Array.from(((_a = el.parentElement) === null || _a === void 0 ? void 0 : _a.children) || []).indexOf(el) + 1})`;
                     });
-                    violationCounter++;
                 }
-                catch (error) {
-                    console.log(`Failed to highlight element: ${error}`);
+            }
+            return yield elements[0].evaluate(el => {
+                if (el.id)
+                    return `#${el.id}`;
+                if (el.className)
+                    return `.${el.className.split(' ')[0]}`;
+                return el.tagName.toLowerCase();
+            });
+        });
+    }
+    analyzePage() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.page) {
+                throw new Error("Page not created. Call createPage() first.");
+            }
+            return yield this.page.evaluate(() => {
+                const getElementInfo = (el) => {
+                    const text = (el.textContent || '').trim();
+                    const ariaLabel = el.getAttribute('aria-label');
+                    const title = el.getAttribute('title');
+                    const value = el.value;
+                    const placeholder = el.placeholder;
+                    return text || ariaLabel || title || value || placeholder || 'No text';
+                };
+                const buttons = Array.from(document.querySelectorAll('button, [role="button"], input[type="button"], input[type="submit"]'))
+                    .map(el => getElementInfo(el))
+                    .filter(text => text !== 'No text');
+                const links = Array.from(document.querySelectorAll('a[href]'))
+                    .map(el => getElementInfo(el))
+                    .filter(text => text !== 'No text');
+                const inputs = Array.from(document.querySelectorAll('input:not([type="button"]):not([type="submit"]), textarea, select'))
+                    .map(el => {
+                    var _a, _b, _c;
+                    const label = (_c = (_b = (_a = el.labels) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.textContent) === null || _c === void 0 ? void 0 : _c.trim();
+                    const placeholder = el.placeholder;
+                    const name = el.getAttribute('name');
+                    const id = el.getAttribute('id');
+                    return label || placeholder || name || id || 'Unnamed input';
+                });
+                return { buttons, links, inputs };
+            });
+        });
+    }
+    clickElementByText(text, elementType) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.page) {
+                throw new Error("Page not created. Call createPage() first.");
+            }
+            const selector = yield this.getElementByText(text, elementType);
+            if (!selector) {
+                const analysis = yield this.analyzePage();
+                throw new Error(`Element with text "${text}" not found. Available elements:\nButtons: ${analysis.buttons.join(', ')}\nLinks: ${analysis.links.join(', ')}`);
+            }
+            yield this.page.click(selector);
+            yield this.page.waitForLoadState('load');
+        });
+    }
+    typeTextByLabel(labelText, text) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.page) {
+                throw new Error("Page not created. Call createPage() first.");
+            }
+            const inputSelector = yield this.page.evaluate((label) => {
+                const labels = Array.from(document.querySelectorAll('label'));
+                const matchingLabel = labels.find(l => { var _a; return (_a = l.textContent) === null || _a === void 0 ? void 0 : _a.trim().includes(label); });
+                if (matchingLabel) {
+                    const forAttr = matchingLabel.getAttribute('for');
+                    if (forAttr)
+                        return `#${forAttr}`;
+                    const input = matchingLabel.querySelector('input, textarea, select');
+                    if (input && input.id)
+                        return `#${input.id}`;
+                    if (input)
+                        return null;
+                }
+                const inputsWithPlaceholder = Array.from(document.querySelectorAll(`input[placeholder*="${label}"], textarea[placeholder*="${label}"]`));
+                if (inputsWithPlaceholder.length > 0) {
+                    const input = inputsWithPlaceholder[0];
+                    if (input.id)
+                        return `#${input.id}`;
                 }
+                return null;
+            }, labelText);
+            if (!inputSelector) {
+                const analysis = yield this.analyzePage();
+                throw new Error(`Input field with label "${labelText}" not found. Available inputs: ${analysis.inputs.join(', ')}`);
             }
-        }
+            yield this.page.fill(inputSelector, text);
+            yield this.page.waitForLoadState('load');
+        });
+    }
+    addViolationStyles() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.page) {
+                throw new Error("Page not created.");
+            }
+            yield this.page.addStyleTag({
+                content: `
+				.a11y-violation {
+					position: relative !important;
+					outline: 4px solid #FF4444 !important;
+					margin: 2px !important;
+				}
+				.violation-number {
+					position: absolute !important;
+					top: -12px !important;
+					left: -12px !important;
+					background: #FF4444;
+					color: white !important;
+					width: 25px;
+					height: 25px;
+					border-radius: 50%;
+					display: flex !important;
+					align-items: center;
+					justify-content: center;
+					font-weight: bold;
+					font-size: 14px;
+					z-index: 10000;
+				}
+				.a11y-violation-info {
+					position: absolute !important;
+					background: #333333 !important;
+					color: white !important;
+					padding: 12px !important;
+					border-radius: 4px !important;
+					font-size: 14px !important;
+					max-width: 300px !important;
+					z-index: 9999 !important;
+					box-shadow: 0 2px 10px rgba(0,0,0,0.3);
+				}
+			`,
+            });
+        });
+    }
+    highlightViolations(violations) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.page) {
+                throw new Error("Page not created.");
+            }
+            let violationCounter = 1;
+            for (const violation of violations) {
+                for (const node of violation.nodes) {
+                    try {
+                        const targetSelector = node.target[0];
+                        const selector = Array.isArray(targetSelector)
+                            ? targetSelector.join(" ")
+                            : targetSelector;
+                        yield this.page.evaluate(({ selector, violationData, counter }) => {
+                            const elements = document.querySelectorAll(selector);
+                            elements.forEach((element) => {
+                                const numberBadge = document.createElement("div");
+                                numberBadge.className = "violation-number";
+                                numberBadge.textContent = counter.toString();
+                                element.classList.add("a11y-violation");
+                                element.appendChild(numberBadge);
+                                const listItem = document.createElement("div");
+                                listItem.style.marginBottom = "15px";
+                                listItem.innerHTML = `
+									<div style="color: #FF4444; font-weight: bold;">
+										Violation #${counter}: ${violationData.impact.toUpperCase()}
+									</div>
+									<div style="margin: 5px 0; font-size: 14px;">
+										${violationData.description}
+									</div>
+								`;
+                                document.body.appendChild(listItem);
+                                const rect = element.getBoundingClientRect();
+                                listItem.style.left = `${rect.left + window.scrollX}px`;
+                                listItem.style.top = `${rect.bottom + window.scrollY + 10}px`;
+                            });
+                        }, {
+                            selector: selector,
+                            violationData: {
+                                impact: violation.impact,
+                                description: violation.description,
+                            },
+                            counter: violationCounter,
+                        });
+                        violationCounter++;
+                    }
+                    catch (error) {
+                        console.log(`Failed to highlight element: ${error}`);
+                    }
+                }
+            }
+        });
+    }
+    generateReport(violations) {
+        var _a;
         let reportCounter = 1;
         const report = [];
-        for (const violation of results.violations) {
+        for (const violation of violations) {
             for (const node of violation.nodes) {
                 report.push({
                     index: reportCounter++,
                     element: node.target[0],
                     impactLevel: violation.impact,
                     description: violation.description,
-                    wcagCriteria: (_a = violation.tags) === null || _a === void 0 ? void 0 : _a.join(", "),
+                    wcagCriteria: ((_a = violation.tags) === null || _a === void 0 ? void 0 : _a.join(", ")) || "",
                 });
             }
         }
-        const filePath = node_path_1.default.join(node_path_1.default.join(node_os_1.default.homedir(), "Downloads"), `a11y-report-${Date.now()}.png`);
-        const screenshot = yield page.screenshot({
-            path: filePath,
+        return report;
+    }
+    takeScreenshot() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.page) {
+                throw new Error("Page not created.");
+            }
+            const filePath = node_path_1.default.join(node_path_1.default.join(node_os_1.default.homedir(), "Downloads"), `a11y-report-${Date.now()}.png`);
+            const screenshot = yield this.page.screenshot({
+                path: filePath,
+            });
+            return screenshot.toString("base64");
+        });
+    }
+    scanViolations(violationsTags) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.page) {
+                throw new Error("Page not created.");
+            }
+            yield this.addViolationStyles();
+            const axe = new playwright_2.AxeBuilder({ page: this.page }).withTags(violationsTags);
+            const results = yield axe.analyze();
+            yield this.highlightViolations(results.violations);
+            const report = this.generateReport(results.violations);
+            const base64Screenshot = yield this.takeScreenshot();
+            return { report, base64Screenshot };
+        });
+    }
+    cleanup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.browser) {
+                yield this.browser.close();
+                this.browser = null;
+                this.context = null;
+                this.page = null;
+            }
         });
-        const base64Screenshot = screenshot.toString("base64");
-        yield browser.close();
-        return { report, base64Screenshot };
+    }
+}
+exports.AccessibilityScanner = AccessibilityScanner;
+function scanViolations(url_1, violationsTags_1) {
+    return __awaiter(this, arguments, void 0, function* (url, violationsTags, viewport = { width: 1920, height: 1080 }, shouldRunInHeadless = true) {
+        const scanner = new AccessibilityScanner();
+        try {
+            yield scanner.initialize(shouldRunInHeadless);
+            yield scanner.createContext(viewport);
+            yield scanner.createPage();
+            yield scanner.navigateToUrl(url);
+            return yield scanner.scanViolations(violationsTags);
+        }
+        finally {
+            yield scanner.cleanup();
+        }
     });
 }