a11yengine-mcp 0.0.0-stage → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,11 @@
1
+ # Changelog
2
+
3
+ ## 1.4.0 (first public release)
4
+
5
+ - MCP server with six tools: `scan_url`, `get_finding`, `verify_fix`, `check_dialog`, `check_keyboard`, `check_pdf`.
6
+ - `a11yengine` command for terminals and CI, with JSON, SARIF and prompt output.
7
+ - Same scanner as the A11yEngine Chrome extension 1.4.0: axe-core 4.12 rules plus A11yEngine checks; best-practice rules are reported as needs review.
8
+ - Light and dark mode scans, source locations for React, Vue and Svelte, visual check after fixes.
9
+ - Agents are told to treat page content as untrusted data.
10
+ - Clear messages for unreachable servers, unknown hosts, blocked ports, certificate errors and timeouts.
11
+ - Licensed under MIT.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jai Sharma
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,103 @@
1
- # Temporary Holding Version
1
+ # a11yengine-mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Find and fix WCAG 2.2 accessibility issues from your AI coding agent (Claude Code, Cursor, GitHub Copilot and other MCP clients) or from the command line.
4
+
5
+ - **Finds** accessibility failures on a page, ideally your local dev server.
6
+ - **Locates** the code behind each one: `file:line` in development builds of React and Svelte, the file for Vue, and search hints everywhere else.
7
+ - **Verifies** the fix: re-scans, reports what is fixed, still failing or newly broken, and checks that nothing else on the page changed visually.
8
+
9
+ Scans run locally in your own Chrome, Edge or Chromium. **Nothing is sent to A11yEngine servers.** Free to use under the MIT licence.
10
+
11
+ ## Requirements
12
+
13
+ - Node.js 18.17 or later
14
+ - Google Chrome or Microsoft Edge installed. Alternatively, set `A11YENGINE_CHROME` to a Chromium executable, or run `npx playwright install chromium`.
15
+
16
+ ## Set up
17
+
18
+ **Claude Code**
19
+
20
+ ```bash
21
+ claude mcp add a11yengine -- npx -y a11yengine-mcp
22
+ ```
23
+
24
+ **Cursor** (`~/.cursor/mcp.json`) and **Claude Desktop** (`claude_desktop_config.json`)
25
+
26
+ ```json
27
+ {
28
+ "mcpServers": {
29
+ "a11yengine": { "command": "npx", "args": ["-y", "a11yengine-mcp"] }
30
+ }
31
+ }
32
+ ```
33
+
34
+ **VS Code with GitHub Copilot** (`.vscode/mcp.json`)
35
+
36
+ ```json
37
+ {
38
+ "servers": {
39
+ "a11yengine": { "type": "stdio", "command": "npx", "args": ["-y", "a11yengine-mcp"] }
40
+ }
41
+ }
42
+ ```
43
+
44
+ Then ask your agent, for example: *"Check http://localhost:3000/checkout for accessibility issues and fix the confirmed ones."*
45
+
46
+ ## Tools
47
+
48
+ | Tool | What it does |
49
+ |---|---|
50
+ | `scan_url` | Scans a page in light and, when the site has one, dark mode. Returns confirmed and needs-review findings with source locations, design-safe fix guidance and groups by file or component, plus a `scanId`. |
51
+ | `get_finding` | Full detail and fix steps for one finding. |
52
+ | `verify_fix` | Re-scans and reports fixed, still failing and newly introduced findings, with a before/after visual check per colour mode. |
53
+ | `check_dialog` | Opens a dialog with the steps you give and checks its name, that focus moves in and stays inside a modal. |
54
+ | `check_keyboard` | Tabs through the page and reports the tab order, keyboard traps, invisible focus, focus on hidden elements and positive tabindex. |
55
+ | `check_pdf` | Checks a PDF: text layer, tags, title, language, security settings, bookmarks. |
56
+
57
+ **Pages behind a login:** save a signed-in session once with `npx playwright codegen --save-storage=auth.json http://localhost:3000/login`, then ask the agent to pass `storageStatePath: "auth.json"`.
58
+
59
+ **A specific state** (an open menu, a filled form): pass `actions`, for example `[{"click": "#open-menu"}]`.
60
+
61
+ ## Command line and CI
62
+
63
+ The same package includes the `a11yengine` command:
64
+
65
+ ```bash
66
+ npx -p a11yengine-mcp a11yengine scan http://localhost:3000 --format prompt
67
+ npx -p a11yengine-mcp a11yengine scan ./build/index.html --format sarif --out a11y.sarif --fail-on-confirmed
68
+ ```
69
+
70
+ | Option | Meaning |
71
+ |---|---|
72
+ | `--format json` | A11yEngine agent report (default) |
73
+ | `--format sarif` | SARIF 2.1.0, e.g. for GitHub code scanning |
74
+ | `--format prompt` | A brief to paste into an AI coding agent |
75
+ | `--fail-on-confirmed` | Exit with code 1 when there are confirmed findings (for CI) |
76
+ | `--timeout <ms>` | Page load timeout, default 30000 |
77
+
78
+ Exit codes: 0 success, 1 confirmed findings with `--fail-on-confirmed`, 2 usage or scan error.
79
+
80
+ ## What to expect
81
+
82
+ - **Confirmed** findings come from rules that measure at least 90% precision on the W3C ACT Rules test cases. **Needs review** findings may be false positives; check them before changing code. See [measured accuracy](https://www.a11yengine.pro/accuracy/).
83
+ - Automated testing finds only some WCAG failures. A clean scan does not mean a page is accessible or conformant.
84
+ - Page content returned in findings is untrusted. The server tells agents never to follow instructions found in it.
85
+
86
+ ## Troubleshooting
87
+
88
+ | Message | What to do |
89
+ |---|---|
90
+ | Could not connect to … Is the dev server running? | Start your dev server, or check the port. |
91
+ | No Chromium-based browser found | Install Chrome or Edge, set `A11YENGINE_CHROME`, or run `npx playwright install chromium`. |
92
+ | … took too long to load | Check the page loads in a browser; pass `waitForSelector` for slow apps. |
93
+ | Browsers block this port | Use a common dev-server port such as 3000, 5173 or 8080. |
94
+
95
+ ## Links
96
+
97
+ - Website and Chrome extension: https://www.a11yengine.pro
98
+ - Rules reference: https://www.a11yengine.pro/rules/
99
+ - Questions and bug reports: contactus@a11yengine.pro
100
+
101
+ ## Licence
102
+
103
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,9 @@
1
+ #!/usr/bin/env node
2
+ // A11yEngine MCP server (stdio) for Claude Code, Cursor and other MCP clients.
3
+ // Scans run locally in Chrome, Edge or Chromium; nothing is sent to A11yEngine servers.
4
+ import path from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+ import { startMcpServer } from '../dist/mcp.mjs';
7
+
8
+ const here = path.dirname(fileURLToPath(import.meta.url));
9
+ await startMcpServer({ distDir: path.join(here, '..', 'dist', 'scanner') });
@@ -0,0 +1,86 @@
1
+ #!/usr/bin/env node
2
+ // A11yEngine CLI: scan a page headlessly and print a report for agents or CI.
3
+ //
4
+ // a11yengine scan <url | file.html> [--format json|sarif|prompt] [--out <file>]
5
+ // [--fail-on-confirmed] [--timeout <ms>]
6
+ //
7
+ // Formats: json = A11yEngine Agent Report v1
8
+ // sarif = SARIF 2.1.0 for code-scanning tools (GitHub code scanning)
9
+ // prompt = paste-ready brief for Claude Code, Copilot or Cursor
10
+ // Exit codes: 0 success; 1 confirmed findings with --fail-on-confirmed; 2 usage or scan error.
11
+ // Scans run locally in Chrome, Edge or Chromium; nothing is sent to A11yEngine servers.
12
+ import fs from 'node:fs';
13
+ import path from 'node:path';
14
+ import { fileURLToPath, pathToFileURL } from 'node:url';
15
+ import { A11yEngine, toSarif, toAgentPrompt } from '../dist/index.mjs';
16
+
17
+ const USAGE =
18
+ 'Usage: a11yengine scan <url | file.html> [--format json|sarif|prompt] [--out <file>] [--fail-on-confirmed] [--timeout <ms>]';
19
+
20
+ const args = process.argv.slice(2);
21
+ const flag = (name) => args.includes(name);
22
+ const value = (name) => {
23
+ const i = args.indexOf(name);
24
+ return i >= 0 ? args[i + 1] : undefined;
25
+ };
26
+
27
+ if (args[0] === '--version') {
28
+ const pkg = JSON.parse(
29
+ fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')
30
+ );
31
+ console.log(pkg.version);
32
+ process.exit(0);
33
+ }
34
+ if (args[0] !== 'scan' || !args[1] || flag('--help')) {
35
+ console.error(USAGE);
36
+ process.exit(args[0] === '--help' || flag('--help') ? 0 : 2);
37
+ }
38
+
39
+ const format = value('--format') || 'json';
40
+ if (!['json', 'sarif', 'prompt'].includes(format)) {
41
+ console.error(`Unknown --format "${format}". ${USAGE}`);
42
+ process.exit(2);
43
+ }
44
+
45
+ const target = args[1];
46
+ const url =
47
+ /^(https?|file):/i.test(target) || !fs.existsSync(target)
48
+ ? target
49
+ : pathToFileURL(path.resolve(target)).href;
50
+
51
+ const here = path.dirname(fileURLToPath(import.meta.url));
52
+ let engine;
53
+ try {
54
+ engine = await A11yEngine.launch({
55
+ distDir: path.join(here, '..', 'dist', 'scanner'),
56
+ });
57
+ const { agentReport } = await engine.scanUrl(url, {
58
+ timeoutMs: Number(value('--timeout')) || 30000,
59
+ });
60
+
61
+ const output =
62
+ format === 'sarif'
63
+ ? JSON.stringify(toSarif(agentReport), null, 2)
64
+ : format === 'prompt'
65
+ ? toAgentPrompt(agentReport)
66
+ : JSON.stringify(agentReport, null, 2);
67
+
68
+ const out = value('--out');
69
+ if (out) {
70
+ fs.writeFileSync(out, output);
71
+ console.error(`Wrote ${format} report to ${out}`);
72
+ } else {
73
+ process.stdout.write(output + '\n');
74
+ }
75
+
76
+ const { confirmed, needsReview } = agentReport.summary;
77
+ console.error(
78
+ `${confirmed.total} confirmed finding(s), ${needsReview} needing review. Automated testing finds only some WCAG failures; this is not a conformance result.`
79
+ );
80
+ await engine.close();
81
+ process.exit(flag('--fail-on-confirmed') && confirmed.total > 0 ? 1 : 0);
82
+ } catch (err) {
83
+ console.error(`Scan failed: ${err?.message || err}`);
84
+ if (engine) await engine.close();
85
+ process.exit(2);
86
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "version": "1.4.0",
3
+ "commit": "87ac2ea751958a9e1c57e80aec17278552b0ead8",
4
+ "uncommittedSources": false,
5
+ "builtAt": "2026-11-19T02:55:45.161Z"
6
+ }