mcp-accessibility-scanner 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JustasM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Readme.md

@@ -0,0 +1,81 @@
+# MCP Accessibility Scanner
+
+A Model Context Protocol (MCP) server for performing automated accessibility scans of web pages using Playwright and Axe-core.
+
+## Features
+
+✅ Full WCAG 2.1/2.2 compliance checking  
+🖼️ Automatic screenshot capture with violation highlighting  
+📄 Detailed JSON reports with remediation guidance
+
+## Installation
+
+```bash
+# Clone repository
+git clone https://github.com/JustasMonkev/mcp-accessibility-scanner.git
+cd mcp-accessibility-scanner
+
+# Install dependencies
+npm install
+
+# Build project (compiles TypeScript and installs Playwright browsers)
+npm run prepare
+```
+
+## Claude Desktop Configuration
+
+Add the following to your Claude Desktop settings to enable the Accessibility Scanner server:
+
+```json
+{
+  "mcpServers": {
+    "accessibility-checker": {
+      "command": "node",
+      "args": [
+        "path/build/server.js"
+      ]
+    }
+  }
+}
+```
+
+## Usage
+
+The scanner exposes a single tool `scan_accessibility` that accepts:
+
+- `url`: The webpage URL to scan
+- `violationsTag`: Array of accessibility violation tags to check
+
+Example usage in Claude:
+```
+Could you scan example.com for accessibility issues related to color contrast?
+```
+
+## Development
+
+Start the TypeScript compiler in watch mode:
+```bash
+npm run watch
+```
+
+Test the MCP server locally:
+```bash
+npm run inspector
+```
+
+## Project Structure
+
+- `src/`: Source code
+    - `index.ts`: MCP server setup and tool definitions
+    - `accessibilityChecker.ts`: Core scanning functionality
+- `dist/`: Compiled JavaScript output
+- `package.json`: Project dependencies and scripts
+- `tsconfig.json`: TypeScript configuration
+
+## Output
+
+The scanner provides:
+1. A visual report with numbered violations highlighted on the page
+2. A detailed JSON report of all found violations
+3. A full-page screenshot saved to Downloads
+

package/build/accessibilityChecker.js

@@ -0,0 +1,183 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanViolations = scanViolations;
+const playwright_1 = require("playwright");
+const playwright_2 = require("@axe-core/playwright");
+const node_path_1 = __importDefault(require("node:path"));
+const os = __importStar(require("node:os"));
+function scanViolations(url, violationsTag) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const browser = yield playwright_1.chromium.launch({
+            headless: true,
+            args: [
+                '--disable-blink-features=AutomationControlled',
+                '--disable-dev-shm-usage',
+                '--no-sandbox',
+                '--disable-setuid-sandbox',
+            ]
+        });
+        const context = yield browser.newContext({
+            viewport: { width: 1920, height: 1080 },
+            userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
+        });
+        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);
+        }
+    `
+        });
+        const axe = new playwright_2.AxeBuilder({ page })
+            .withTags(violationsTag);
+        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
+                    });
+                    violationCounter++;
+                }
+                catch (error) {
+                    console.log(`Failed to highlight element: ${error}`);
+                }
+            }
+        }
+        let reportCounter = 1;
+        const report = [];
+        for (const violation of results.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(', '),
+                });
+            }
+        }
+        const downloadsDir = node_path_1.default.join(os.homedir(), 'Downloads');
+        const filePath = node_path_1.default.join(downloadsDir, `a11y-report-${Date.now()}.png`);
+        const screenshot = yield page.screenshot({
+            path: filePath,
+            fullPage: true,
+        });
+        const base64Screenshot = screenshot.toString('base64');
+        yield browser.close();
+        return { report, base64Screenshot };
+    });
+}

package/build/index.js

@@ -0,0 +1,39 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const zod_1 = require("zod");
+const accessibilityChecker_1 = require("./accessibilityChecker");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const server = new mcp_js_1.McpServer({
+    name: "Accessibility Information",
+    version: "1.0.0"
+});
+server.tool("scan_accessibility", {
+    url: zod_1.z.string().url(),
+    violationsTag: zod_1.z.array(zod_1.z.string())
+}, (_a) => __awaiter(void 0, [_a], void 0, function* ({ url, violationsTag }) {
+    const { report, base64Screenshot } = yield (0, accessibilityChecker_1.scanViolations)(url, violationsTag);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(Object.assign({ message: 'The image has been saved to your downloads.' }, report), null, 2)
+            },
+            {
+                type: "image",
+                data: base64Screenshot,
+                mimeType: "image/png"
+            }
+        ],
+        isError: false
+    };
+}));
+exports.default = server;

package/build/server.js

@@ -0,0 +1,49 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = __importDefault(require("./index"));
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const transport = new stdio_js_1.StdioServerTransport();
+        yield index_1.default.connect(transport);
+        try {
+            console.error('Starting MCP Accessibility checker server...');
+            console.error('MCP server connected successfully');
+        }
+        catch (error) {
+            console.error('Error starting server:', error);
+            if (error instanceof Error) {
+                console.error('Error stack:', error.stack);
+            }
+            process.exit(1);
+        }
+        // Handle process events
+        process.on('disconnect', () => {
+            console.error('Process disconnected');
+            process.exit(0);
+        });
+        process.on('uncaughtException', (error) => {
+            console.error('Uncaught exception:', error);
+            process.exit(1);
+        });
+        // Keep the process running
+        process.stdin.resume();
+    });
+}
+// Start the server
+main().catch(error => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "mcp-accessibility-scanner",
+  "version": "1.0.0",
+  "description": "A Model Context Protocol (MCP) server for performing automated accessibility scans of web pages using Playwright and Axe-core",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "files": [
+    "build/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "inspector": "npx @modelcontextprotocol/inspector build/index.js"
+  },
+  "dependencies": {
+    "@axe-core/playwright": "^4.10.1",
+    "@modelcontextprotocol/sdk": "^1.4.1",
+    "mcp-accessibility-scanner": "file:"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.49.1",
+    "@types/node": "^22.10.7",
+    "typescript": "^5.5.3"
+  },
+  "keywords": [
+    "mcp",
+    "accessibility",
+    "a11y",
+    "wcag",
+    "axe-core",
+    "playwright",
+    "claude",
+    "model-context-protocol"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JustasMonkev/mcp-accessibility-scanner.git"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}