a11y-test-mcp 1.0.0

package/README.md

@@ -0,0 +1,50 @@
+# a11y test MCP
+An MCP (Model Context Protocol) server for performing a11y test on webpages using playwright axe-core. The results are then used in an agent loop with your favorite AI assistant (Cline/Cursor/GH Copilot) to find problems with a11y and suggest improvements.
+
+## Features
+
+* Perform detailed accessibility testing on any web pages
+* Get an overview of accessibility issues
+  * Violations
+    * Provides information on which DOM was at fault
+  * Passes
+  * Incomplete
+  * Inapplicable
+* Can specify specific WCAG criteria
+
+## Installation
+
+```
+# Global install
+npm install -g a11y-test-mcp
+
+# With npx command
+npx a11y-test-mcp
+```
+
+## Configuration
+
+Add the following to the mcpServers object:
+
+```json
+{
+  "servers": {
+    "a11y-test": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["a11y-test-mcp"]
+    }
+  }
+}
+```
+
+## Example prompt
+
+```
+Please perform accessibility testing on the following sites.
+Tests should be performed at WCAG Level A.
+If there are problems, please indicate which HTML elements are at fault.
+
+* https://example.com
+* https://example.com/home
+```

package/build/functions.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertTestResultToText = exports.execTest = void 0;
+const playwright_1 = __importDefault(require("playwright"));
+const playwright_2 = __importDefault(require("@axe-core/playwright"));
+/**
+ * Enhance WCAG tag conversion
+ * @param {string[]} tags - Array of WCAG tags
+ * @returns {string[]} Converted array of WCAG tags
+ */
+const convertWcagTag = (tags) => {
+    return tags.map(tag => {
+        const lowerTag = tag.toLowerCase().replace(/[\s.]/g, '');
+        switch (lowerTag) {
+            case 'wcag2a':
+            case 'a':
+            case 'wcag20a':
+                return 'wcag2a';
+            case 'wcag2aa':
+            case 'aa':
+            case 'wcag20aa':
+                return 'wcag2aa';
+            case 'wcag21a':
+                return 'wcag21a';
+            case 'wcag21aa':
+                return 'wcag21aa';
+            case 'wcag22a':
+                return 'wcag22a';
+            case 'wcag22aa':
+                return 'wcag22aa';
+            default:
+                if (lowerTag.startsWith('wcag') || ['best-practice', 'section508'].includes(lowerTag)) {
+                    return lowerTag;
+                }
+                console.warn(`Unrecognized WCAG tag: ${tag}`);
+                return '';
+        }
+    }).filter(tag => tag !== '');
+};
+/**
+ * Execute a11y test
+ * @param {string[]} urls - URLs
+ * @param {string[] | undefined} wcagStandards - WCAG standards to apply
+ * @returns {AccessibilityTestOutput[]} - Results of the accessibility tests
+ */
+const execTest = async (urls, wcagStandards) => {
+    const results = [];
+    const browser = await playwright_1.default.chromium.launch();
+    const context = await browser.newContext();
+    try {
+        for (const url of urls) {
+            let page;
+            try {
+                page = await context.newPage();
+                await page.goto(url, { waitUntil: 'networkidle' });
+                const axeBuilder = new playwright_2.default({ page });
+                const tagsToUse = (wcagStandards && wcagStandards.length > 0)
+                    ? convertWcagTag(wcagStandards)
+                    : ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"];
+                if (tagsToUse.length > 0) {
+                    axeBuilder.withTags(tagsToUse);
+                }
+                else {
+                    console.warn("No valid WCAG tags specified, running Axe with default rules.");
+                }
+                const axeResults = await axeBuilder.analyze();
+                // Summarize results, handling null impact
+                const summarizedViolations = axeResults.violations.map(v => ({
+                    id: v.id,
+                    // Handle null impact from axe-core
+                    impact: v.impact === null ? undefined : v.impact,
+                    description: v.description,
+                    helpUrl: v.helpUrl,
+                    nodes: v.nodes
+                }));
+                results.push({
+                    url: url,
+                    violations: summarizedViolations,
+                    passesCount: axeResults.passes.length,
+                    incompleteCount: axeResults.incomplete.length,
+                    inapplicableCount: axeResults.inapplicable.length,
+                });
+            }
+            catch (error) {
+                results.push({
+                    url: url,
+                    error: `Failed to test: ${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+            finally {
+                if (page) {
+                    await page.close();
+                }
+            }
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    return results;
+};
+exports.execTest = execTest;
+/**
+ * Convert structured results to text format
+ * @param {AccessibilityTestOutput[]} structuredResults - Structured results from the tests
+ * @returns {string} - Text representation of the results
+ */
+const convertTestResultToText = (structuredResults) => {
+    return structuredResults
+        .map((result) => {
+        const resultTextList = [`URL: ${result.url}`];
+        if (result.error) {
+            resultTextList.push(`  Error: ${result.error}`);
+        }
+        else {
+            resultTextList.push(`  Violations: ${result.violations?.length ?? 0}`);
+            const resultViolationText = result.violations?.map((v) => {
+                return [
+                    `    - [${v.impact?.toUpperCase()}] ${v.id}: ${v.description} (Nodes: ${v.nodes.length}, Help: ${v.helpUrl})`,
+                    v.nodes
+                        .map((node, index) => {
+                        return `      Node ${index + 1}: ${node.html}`;
+                    })
+                        .join('\n')
+                ].join('\n');
+            });
+            if (resultViolationText !== undefined) {
+                resultTextList.push(...resultViolationText);
+            }
+            resultTextList.push(`  Passes: ${result.passesCount ?? 0}`);
+            resultTextList.push(`  Incomplete: ${result.incompleteCount ?? 0}`);
+            resultTextList.push(`  Inapplicable: ${result.inapplicableCount ?? 0}`);
+        }
+        return resultTextList.join('\n');
+    })
+        .join('\n')
+        .trim();
+};
+exports.convertTestResultToText = convertTestResultToText;

package/build/index.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const functions_1 = require("./functions");
+/** Create an MCP server instance */
+const server = new mcp_js_1.McpServer({
+    name: 'accessibility-tester',
+    version: '0.1.1',
+});
+server.tool('exec-a11y-test', 'Obtains a list of specified list of URL and a list of WCAG indicators and returns the results', { urls: zod_1.z.array(zod_1.z.string().url()), wcagStandards: zod_1.z.array(zod_1.z.string()).optional() }, async ({ urls, wcagStandards }) => {
+    const structuredResults = await (0, functions_1.execTest)(urls, wcagStandards);
+    return {
+        content: [{
+                type: 'text',
+                text: (0, functions_1.convertTestResultToText)(structuredResults)
+            }]
+    };
+});
+/**
+ * Main function to start the server
+ */
+const main = async () => {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error('A11y Accessibility MCP server running on stdio');
+};
+process.on('SIGINT', async () => {
+    await server.close();
+    process.exit(0);
+});
+main().catch(console.error);

package/build/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "a11y-test-mcp",
+  "version": "1.0.0",
+  "main": "build/index.js",
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "start": "node build/index.js"
+  },
+  "bin": {
+    "a11y-mcp": "build/index.js"
+  },
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "mcp",
+    "playwright",
+    "axe-core"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:noriyuki-shimizu/a11y-test-mcp.git"
+  },
+  "author": "Noriyuki Shimizu",
+  "license": "ISC",
+  "type": "commonjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "build"
+  ],
+  "description": "",
+  "homepage": "https://github.com/noriyuki-shimizu/a11y-test-mcp/blob/main/README.md",
+  "dependencies": {
+    "@axe-core/playwright": "^4.10.1",
+    "@modelcontextprotocol/sdk": "^1.10.2",
+    "playwright": "^1.52.0",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.2",
+    "typescript": "^5.8.3"
+  },
+  "volta": {
+    "node": "22.15.0",
+    "npm": "10.9.2"
+  }
+}