npm - @mcptoolshop/a11y-mcp-tools - Versions diffs - 0.3.0 - Mend

@mcptoolshop/a11y-mcp-tools 0.3.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.

Files changed (34) hide show

package/.github/workflows/ci.yml +53 -0
package/CODE_OF_CONDUCT.md +129 -0
package/CONTRIBUTING.md +136 -0
package/LICENSE +21 -0
package/PROV_METHODS_CATALOG.md +104 -0
package/README.md +168 -0
package/bin/cli.js +452 -0
package/bin/server.js +244 -0
package/fixtures/requests/a11y.diagnose.ok.json +27 -0
package/fixtures/requests/a11y.evidence.ok.json +25 -0
package/fixtures/responses/a11y.diagnose.ok.json +139 -0
package/fixtures/responses/a11y.diagnose.provenance_fail.json +13 -0
package/fixtures/responses/a11y.evidence.ok.json +88 -0
package/package.json +48 -0
package/src/envelope.js +197 -0
package/src/index.js +9 -0
package/src/schemas/artifact.js +85 -0
package/src/schemas/diagnosis.schema.v0.1.json +137 -0
package/src/schemas/envelope.schema.v0.1.json +108 -0
package/src/schemas/evidence.bundle.schema.v0.1.json +129 -0
package/src/schemas/evidence.js +97 -0
package/src/schemas/index.js +11 -0
package/src/schemas/provenance.js +140 -0
package/src/schemas/tools/a11y.diagnose.request.schema.v0.1.json +77 -0
package/src/schemas/tools/a11y.diagnose.response.schema.v0.1.json +50 -0
package/src/schemas/tools/a11y.evidence.request.schema.v0.1.json +120 -0
package/src/schemas/tools/a11y.evidence.response.schema.v0.1.json +50 -0
package/src/tools/diagnose.js +597 -0
package/src/tools/evidence.js +481 -0
package/src/tools/index.js +10 -0
package/test/contract.test.mjs +154 -0
package/test/diagnose.test.js +485 -0
package/test/evidence.test.js +183 -0
package/test/schema.test.js +327 -0

package/fixtures/requests/a11y.evidence.ok.json ADDED Viewed

@@ -0,0 +1,25 @@
+{
+  "mcp": {
+    "envelope": "mcp.envelope_v0_1",
+    "request_id": "req_fixture_evidence_001",
+    "tool": "a11y.evidence",
+    "client": {
+      "name": "a11y-cli",
+      "version": "0.2.0"
+    }
+  },
+  "input": {
+    "targets": [
+      { "kind": "file", "path": "html/index.html" },
+      { "kind": "file", "path": "html/contact.html" },
+      { "kind": "cli_log", "path": "runs/latest.log" }
+    ],
+    "capture": {
+      "html": { "canonicalize": true, "strip_dynamic": true },
+      "dom": { "snapshot": true, "include_css_selectors": true },
+      "environment": { "include": ["os", "node", "tool_versions"] }
+    },
+    "integrity": { "hash": "sha256" },
+    "labels": ["a11y", "baseline", "wcag-2.2-aa"]
+  }
+}

package/fixtures/responses/a11y.diagnose.ok.json ADDED Viewed

@@ -0,0 +1,139 @@
+{
+  "mcp": {
+    "envelope": "mcp.envelope_v0_1",
+    "request_id": "req_fixture_diagnose_001",
+    "tool": "a11y.diagnose",
+    "ok": true
+  },
+  "result": {
+    "diagnosis": {
+      "summary": {
+        "profile": "wcag-2.2-aa",
+        "targets": 2,
+        "findings_total": 4,
+        "severity_counts": {
+          "critical": 0,
+          "high": 3,
+          "medium": 1,
+          "low": 0
+        },
+        "rules_applied": ["lang", "alt", "button-name", "link-name", "label"]
+      },
+      "findings": [
+        {
+          "id": "a11y.lang.missing",
+          "wcag": "wcag.3.1.1",
+          "severity": "high",
+          "message": "Document is missing a lang attribute on <html>.",
+          "targets": [
+            {
+              "artifact_id": "artifact:dom:index",
+              "json_pointer": "/nodes/0",
+              "selector": "html",
+              "snippet": "<html>"
+            }
+          ],
+          "fix": {
+            "safe": true,
+            "description": "Add lang attribute to the html element",
+            "patch": {
+              "action": "add_attribute",
+              "target": "html",
+              "value": "lang=\"en\""
+            },
+            "wcag_ref": "https://www.w3.org/WAI/WCAG22/Understanding/language-of-page.html"
+          }
+        },
+        {
+          "id": "a11y.img.missing_alt",
+          "wcag": "wcag.1.1.1",
+          "severity": "high",
+          "message": "Image is missing alt attribute.",
+          "targets": [
+            {
+              "artifact_id": "artifact:dom:index",
+              "json_pointer": "/nodes/5",
+              "selector": "img",
+              "snippet": "<img src=\"hero.jpg\">"
+            }
+          ],
+          "fix": {
+            "safe": true,
+            "description": "Add descriptive alt text or alt=\"\" for decorative images",
+            "patch": {
+              "action": "add_attribute",
+              "target": "img",
+              "value": "alt=\"[describe image]\""
+            },
+            "wcag_ref": "https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html"
+          }
+        },
+        {
+          "id": "a11y.button.missing_name",
+          "wcag": "wcag.4.1.2",
+          "severity": "high",
+          "message": "Button has no accessible name.",
+          "targets": [
+            {
+              "artifact_id": "artifact:dom:contact",
+              "json_pointer": "/nodes/12",
+              "selector": "button",
+              "snippet": "<button><i class=\"icon-send\"></i></button>"
+            }
+          ],
+          "fix": {
+            "safe": true,
+            "description": "Add aria-label or visible text content",
+            "patch": {
+              "action": "add_attribute",
+              "target": "button",
+              "value": "aria-label=\"Send message\""
+            },
+            "wcag_ref": "https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html"
+          }
+        },
+        {
+          "id": "a11y.input.missing_label",
+          "wcag": "wcag.1.3.1",
+          "severity": "medium",
+          "message": "Form input has no associated label.",
+          "targets": [
+            {
+              "artifact_id": "artifact:dom:contact",
+              "json_pointer": "/nodes/8",
+              "selector": "input[type=\"email\"]",
+              "snippet": "<input type=\"email\" name=\"email\">"
+            }
+          ],
+          "fix": {
+            "safe": true,
+            "description": "Add label element with for attribute or aria-label",
+            "patch": {
+              "action": "add_attribute",
+              "target": "input",
+              "value": "aria-label=\"Email address\""
+            },
+            "wcag_ref": "https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html"
+          }
+        }
+      ],
+      "provenance": {
+        "record_id": "prov:record:fixture-diag-001",
+        "methods": [
+          "engine.diagnose.wcag_rules_v0_1",
+          "engine.extract.evidence.json_pointer_v0_1",
+          "engine.extract.evidence.selector_v0_1",
+          "engine.generate.fix_guidance_v0_1"
+        ],
+        "inputs": [
+          "bundle:fixture:9b6d3c01",
+          "artifact:dom:index",
+          "artifact:dom:contact"
+        ],
+        "outputs": ["diagnosis:fixture-diag-001"],
+        "verified": true,
+        "timestamp": "2026-01-27T04:13:10.000Z"
+      }
+    }
+  }
+}

package/fixtures/responses/a11y.diagnose.provenance_fail.json ADDED Viewed

@@ -0,0 +1,13 @@
+{
+  "mcp": {
+    "envelope": "mcp.envelope_v0_1",
+    "request_id": "req_fixture_diagnose_fail",
+    "tool": "a11y.diagnose",
+    "ok": false
+  },
+  "error": {
+    "code": "PROVENANCE_VERIFICATION_FAILED",
+    "message": "Evidence digest mismatch for artifact:dom:index. Expected sha256:a1b2c3..., got sha256:ffffff...",
+    "fix": "Re-run a11y.evidence to recapture evidence, or disable verify_provenance for local debugging."
+  }
+}

package/fixtures/responses/a11y.evidence.ok.json ADDED Viewed

@@ -0,0 +1,88 @@
+{
+  "mcp": {
+    "envelope": "mcp.envelope_v0_1",
+    "request_id": "req_fixture_evidence_001",
+    "tool": "a11y.evidence",
+    "ok": true
+  },
+  "result": {
+    "bundle": {
+      "bundle_id": "bundle:fixture:9b6d3c01",
+      "labels": ["a11y", "baseline", "wcag-2.2-aa"],
+      "artifacts": [
+        {
+          "artifact_id": "artifact:html:index",
+          "media_type": "text/html",
+          "locator": { "kind": "file", "path": "html/index.html" },
+          "size_bytes": 245,
+          "digest": {
+            "alg": "sha256",
+            "hex": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd"
+          },
+          "labels": ["source", "html", "a11y", "baseline", "wcag-2.2-aa"]
+        },
+        {
+          "artifact_id": "artifact:dom:index",
+          "media_type": "application/json",
+          "locator": { "kind": "derived", "from": "artifact:html:index" },
+          "size_bytes": 1024,
+          "digest": {
+            "alg": "sha256",
+            "hex": "b2c3d4e5f67890123456789012345678901234567890123456789012345abcde"
+          },
+          "labels": ["derived", "dom-snapshot", "a11y", "baseline", "wcag-2.2-aa"]
+        },
+        {
+          "artifact_id": "artifact:html:contact",
+          "media_type": "text/html",
+          "locator": { "kind": "file", "path": "html/contact.html" },
+          "size_bytes": 312,
+          "digest": {
+            "alg": "sha256",
+            "hex": "c3d4e5f678901234567890123456789012345678901234567890123456abcdef"
+          },
+          "labels": ["source", "html", "a11y", "baseline", "wcag-2.2-aa"]
+        },
+        {
+          "artifact_id": "artifact:dom:contact",
+          "media_type": "application/json",
+          "locator": { "kind": "derived", "from": "artifact:html:contact" },
+          "size_bytes": 1156,
+          "digest": {
+            "alg": "sha256",
+            "hex": "d4e5f6789012345678901234567890123456789012345678901234567abcdef0"
+          },
+          "labels": ["derived", "dom-snapshot", "a11y", "baseline", "wcag-2.2-aa"]
+        }
+      ],
+      "provenance": {
+        "record_id": "prov:record:fixture-001",
+        "methods": [
+          "engine.capture.html_canonicalize_v0_1",
+          "engine.capture.dom_snapshot_v0_1",
+          "adapter.integrity.sha256_v0_1",
+          "adapter.provenance.record_v0_1"
+        ],
+        "inputs": ["html/index.html", "html/contact.html"],
+        "outputs": [
+          "artifact:html:index",
+          "artifact:dom:index",
+          "artifact:html:contact",
+          "artifact:dom:contact"
+        ],
+        "verified": false,
+        "timestamp": "2026-01-27T04:12:00.000Z",
+        "agent": {
+          "name": "a11y-mcp-tools",
+          "version": "0.2.0"
+        }
+      },
+      "environment": {
+        "os": { "platform": "win32", "arch": "x64" },
+        "node": "v20.10.0",
+        "tool_versions": { "a11y-mcp-tools": "0.2.0" }
+      },
+      "created_at": "2026-01-27T04:12:00.000Z"
+    }
+  }
+}

package/package.json ADDED Viewed

@@ -0,0 +1,48 @@
+{
+  "name": "@mcptoolshop/a11y-mcp-tools",
+  "version": "0.3.0",
+  "description": "MCP tools for accessibility evidence capture and diagnosis",
+  "main": "src/index.js",
+  "bin": {
+    "a11y": "./bin/cli.js",
+    "a11y-mcp": "./bin/server.js"
+  },
+  "scripts": {
+    "start": "node bin/server.js",
+    "test": "node --test test/*.test.js test/*.test.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "accessibility",
+    "a11y",
+    "wcag",
+    "provenance",
+    "evidence",
+    "testing",
+    "audit"
+  ],
+  "author": "mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/mcp-tool-shop/a11y-mcp-tools#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcp-tool-shop/a11y-mcp-tools.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mcp-tool-shop/a11y-mcp-tools/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "htmlparser2": "^9.1.0"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/envelope.js ADDED Viewed

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * MCP Envelope utilities (v0.1).
+ *
+ * Wraps tool inputs/outputs in standard MCP envelopes with
+ * request IDs, client info, and structured error responses.
+ */
+const crypto = require("crypto");
+const ENVELOPE_VERSION = "mcp.envelope_v0_1";
+/**
+ * Generate a unique request ID.
+ */
+function generateRequestId() {
+  const bytes = crypto.randomBytes(12);
+  return `req_${bytes.toString("base64url")}`;
+}
+/**
+ * Create a request envelope.
+ *
+ * @param {string} tool - Tool name
+ * @param {Object} input - Tool input
+ * @param {Object} [client] - Client info
+ * @returns {Object} Request envelope
+ */
+function createRequestEnvelope(tool, input, client = null) {
+  return {
+    mcp: {
+      envelope: ENVELOPE_VERSION,
+      request_id: generateRequestId(),
+      tool,
+      ...(client && { client }),
+    },
+    input,
+  };
+}
+/**
+ * Create a success response envelope.
+ *
+ * @param {string} requestId - Original request ID
+ * @param {string} tool - Tool name
+ * @param {Object} result - Tool result
+ * @returns {Object} Response envelope
+ */
+function createResponseEnvelope(requestId, tool, result) {
+  return {
+    mcp: {
+      envelope: ENVELOPE_VERSION,
+      request_id: requestId,
+      tool,
+      ok: true,
+    },
+    result,
+  };
+}
+/**
+ * Create an error response envelope.
+ *
+ * @param {string} requestId - Original request ID
+ * @param {string} tool - Tool name
+ * @param {string} code - Error code
+ * @param {string} message - Error message
+ * @param {string} [fix] - Suggested fix
+ * @returns {Object} Error envelope
+ */
+function createErrorEnvelope(requestId, tool, code, message, fix = null) {
+  return {
+    mcp: {
+      envelope: ENVELOPE_VERSION,
+      request_id: requestId,
+      tool,
+      ok: false,
+    },
+    error: {
+      code,
+      message,
+      ...(fix && { fix }),
+    },
+  };
+}
+/**
+ * Error codes for a11y tools.
+ */
+const ERROR_CODES = {
+  // General errors
+  INVALID_INPUT: "INVALID_INPUT",
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+  // Evidence errors
+  FILE_NOT_FOUND: "FILE_NOT_FOUND",
+  CAPTURE_FAILED: "CAPTURE_FAILED",
+  // Diagnosis errors
+  BUNDLE_NOT_FOUND: "BUNDLE_NOT_FOUND",
+  ARTIFACT_NOT_FOUND: "ARTIFACT_NOT_FOUND",
+  INVALID_BUNDLE: "INVALID_BUNDLE",
+  // Integrity errors
+  PROVENANCE_VERIFICATION_FAILED: "PROVENANCE_VERIFICATION_FAILED",
+  DIGEST_MISMATCH: "DIGEST_MISMATCH",
+  // Schema errors
+  SCHEMA_VALIDATION_FAILED: "SCHEMA_VALIDATION_FAILED",
+};
+/**
+ * Wrap a tool execution with envelope handling.
+ *
+ * @param {string} tool - Tool name
+ * @param {Function} handler - Tool handler function
+ * @returns {Function} Wrapped handler
+ */
+function withEnvelope(tool, handler) {
+  return async (envelope) => {
+    const requestId = envelope?.mcp?.request_id || generateRequestId();
+    try {
+      // Validate envelope structure
+      if (!envelope?.input) {
+        return createErrorEnvelope(
+          requestId,
+          tool,
+          ERROR_CODES.INVALID_INPUT,
+          "Missing input in request envelope",
+          "Wrap your input in { mcp: { ... }, input: { ... } }"
+        );
+      }
+      // Execute handler
+      const result = await handler(envelope.input);
+      // Check for handler errors
+      if (result.ok === false) {
+        return createErrorEnvelope(
+          requestId,
+          tool,
+          result.error?.code || ERROR_CODES.INTERNAL_ERROR,
+          result.error?.message || "Unknown error",
+          result.error?.fix
+        );
+      }
+      // Return success envelope
+      return createResponseEnvelope(requestId, tool, result);
+    } catch (err) {
+      return createErrorEnvelope(
+        requestId,
+        tool,
+        ERROR_CODES.INTERNAL_ERROR,
+        err.message,
+        "Check tool input and try again"
+      );
+    }
+  };
+}
+/**
+ * Parse incoming request - supports both envelope and raw input.
+ *
+ * For backwards compatibility, accepts:
+ * 1. Full envelope: { mcp: { ... }, input: { ... } }
+ * 2. Raw input: { targets: [...], ... }
+ *
+ * @param {Object} request - Request (envelope or raw)
+ * @param {string} tool - Tool name
+ * @returns {Object} Normalized envelope
+ */
+function normalizeRequest(request, tool) {
+  // Already an envelope
+  if (request?.mcp?.envelope) {
+    return request;
+  }
+  // Raw input - wrap in envelope
+  return createRequestEnvelope(tool, request, {
+    name: "a11y-mcp-tools",
+    version: "0.1.0",
+  });
+}
+module.exports = {
+  ENVELOPE_VERSION,
+  ERROR_CODES,
+  generateRequestId,
+  createRequestEnvelope,
+  createResponseEnvelope,
+  createErrorEnvelope,
+  withEnvelope,
+  normalizeRequest,
+};

package/src/index.js ADDED Viewed

@@ -0,0 +1,9 @@
+"use strict";
+const tools = require("./tools/index.js");
+const schemas = require("./schemas/index.js");
+module.exports = {
+  ...tools,
+  schemas,
+};

package/src/schemas/artifact.js ADDED Viewed

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Artifact schema and utilities.
+ *
+ * An artifact is a captured piece of content with:
+ * - Unique ID
+ * - Media type
+ * - Locator (where it came from)
+ * - Size and digest
+ * - Labels for categorization
+ */
+const crypto = require("crypto");
+/**
+ * Create an artifact object.
+ *
+ * @param {Object} params
+ * @param {string} params.id - Artifact ID (e.g., "artifact:html:index")
+ * @param {string} params.mediaType - MIME type
+ * @param {Object} params.locator - { kind: "file"|"derived"|"url", path|from|url }
+ * @param {Buffer|string} params.content - Raw content for hashing
+ * @param {string[]} [params.labels] - Optional labels
+ * @returns {Object} Artifact object
+ */
+function createArtifact({ id, mediaType, locator, content, labels = [] }) {
+  const contentBuffer = Buffer.isBuffer(content)
+    ? content
+    : Buffer.from(content, "utf8");
+  const digest = crypto
+    .createHash("sha256")
+    .update(contentBuffer)
+    .digest("hex");
+  return {
+    artifact_id: id,
+    media_type: mediaType,
+    locator,
+    size_bytes: contentBuffer.length,
+    digest: {
+      alg: "sha256",
+      hex: digest,
+    },
+    labels,
+  };
+}
+/**
+ * Generate an artifact ID from kind and name.
+ *
+ * @param {string} kind - e.g., "html", "dom", "log"
+ * @param {string} name - e.g., "index", "contact"
+ * @returns {string} Artifact ID
+ */
+function artifactId(kind, name) {
+  return `artifact:${kind}:${name}`;
+}
+/**
+ * Verify an artifact's digest.
+ *
+ * @param {Object} artifact - Artifact object
+ * @param {Buffer|string} content - Content to verify
+ * @returns {boolean}
+ */
+function verifyArtifact(artifact, content) {
+  const contentBuffer = Buffer.isBuffer(content)
+    ? content
+    : Buffer.from(content, "utf8");
+  const computed = crypto
+    .createHash("sha256")
+    .update(contentBuffer)
+    .digest("hex");
+  return computed === artifact.digest.hex;
+}
+module.exports = {
+  createArtifact,
+  artifactId,
+  verifyArtifact,
+};