@mcptoolshop/accessibility-suite 0.1.0

package/src/a11y-mcp-tools/package-lock.json

@@ -0,0 +1,189 @@
+{
+  "name": "a11y-mcp-tools",
+  "version": "0.2.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "a11y-mcp-tools",
+      "version": "0.2.0",
+      "license": "MIT",
+      "dependencies": {
+        "htmlparser2": "^9.1.0"
+      },
+      "bin": {
+        "a11y": "bin/cli.js",
+        "a11y-mcp": "bin/server.js"
+      },
+      "devDependencies": {
+        "ajv": "^8.17.1",
+        "ajv-formats": "^3.0.1"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/ajv": {
+      "version": "8.17.1",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz",
+      "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/ajv-formats": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz",
+      "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ajv": "^8.0.0"
+      },
+      "peerDependencies": {
+        "ajv": "^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "ajv": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/dom-serializer": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-2.0.0.tgz",
+      "integrity": "sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg==",
+      "license": "MIT",
+      "dependencies": {
+        "domelementtype": "^2.3.0",
+        "domhandler": "^5.0.2",
+        "entities": "^4.2.0"
+      },
+      "funding": {
+        "url": "https://github.com/cheeriojs/dom-serializer?sponsor=1"
+      }
+    },
+    "node_modules/domelementtype": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/domelementtype/-/domelementtype-2.3.0.tgz",
+      "integrity": "sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fb55"
+        }
+      ],
+      "license": "BSD-2-Clause"
+    },
+    "node_modules/domhandler": {
+      "version": "5.0.3",
+      "resolved": "https://registry.npmjs.org/domhandler/-/domhandler-5.0.3.tgz",
+      "integrity": "sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "domelementtype": "^2.3.0"
+      },
+      "engines": {
+        "node": ">= 4"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/domhandler?sponsor=1"
+      }
+    },
+    "node_modules/domutils": {
+      "version": "3.2.2",
+      "resolved": "https://registry.npmjs.org/domutils/-/domutils-3.2.2.tgz",
+      "integrity": "sha512-6kZKyUajlDuqlHKVX1w7gyslj9MPIXzIFiz/rGu35uC1wMi+kMhQwGhl4lt9unC9Vb9INnY9Z3/ZA3+FhASLaw==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "dom-serializer": "^2.0.0",
+        "domelementtype": "^2.3.0",
+        "domhandler": "^5.0.3"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/domutils?sponsor=1"
+      }
+    },
+    "node_modules/entities": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
+      "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/fast-deep-equal": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+      "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/fast-uri": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
+      "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/htmlparser2": {
+      "version": "9.1.0",
+      "resolved": "https://registry.npmjs.org/htmlparser2/-/htmlparser2-9.1.0.tgz",
+      "integrity": "sha512-5zfg6mHUoaer/97TxnGpxmbR7zJtPwIYFMZ/H5ucTlPZhKvtum05yiPK3Mgai3a0DyVxv7qYqoweaEd2nrYQzQ==",
+      "funding": [
+        "https://github.com/fb55/htmlparser2?sponsor=1",
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fb55"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "domelementtype": "^2.3.0",
+        "domhandler": "^5.0.3",
+        "domutils": "^3.1.0",
+        "entities": "^4.5.0"
+      }
+    },
+    "node_modules/json-schema-traverse": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+      "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    }
+  }
+}

package/src/a11y-mcp-tools/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@mcptoolshop/a11y-mcp-tools",
+  "version": "0.3.1",
+  "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-org/accessibility-suite#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcp-tool-shop-org/accessibility-suite.git",
+    "directory": "src/a11y-mcp-tools"
+  },
+  "bugs": {
+    "url": "https://github.com/mcp-tool-shop-org/accessibility-suite/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/a11y-mcp-tools/src/envelope.js

@@ -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/a11y-mcp-tools/src/index.js

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

package/src/a11y-mcp-tools/src/schemas/artifact.js

@@ -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,
+};

package/src/a11y-mcp-tools/src/schemas/diagnosis.schema.v0.1.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mcp-tool-shop.github.io/schemas/diagnosis.v0.1.json",
+  "title": "Accessibility Diagnosis",
+  "description": "Deterministic diagnosis output with findings and provenance",
+  "type": "object",
+  "required": ["findings", "summary", "provenance"],
+  "properties": {
+    "findings": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Finding" }
+    },
+    "summary": { "$ref": "#/$defs/Summary" },
+    "provenance": { "$ref": "#/$defs/Provenance" }
+  },
+  "$defs": {
+    "Finding": {
+      "type": "object",
+      "required": ["id", "severity", "targets"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^a11y\\.[a-z_]+\\.[a-z_]+$",
+          "description": "Finding ID (e.g., a11y.lang.missing)"
+        },
+        "wcag": {
+          "type": "string",
+          "pattern": "^wcag\\.[0-9]+\\.[0-9]+\\.[0-9]+$",
+          "description": "WCAG criterion reference"
+        },
+        "severity": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "critical"]
+        },
+        "message": { "type": "string" },
+        "targets": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/EvidenceAnchor" },
+          "minItems": 1
+        },
+        "fix": { "$ref": "#/$defs/FixGuidance" }
+      }
+    },
+    "EvidenceAnchor": {
+      "type": "object",
+      "required": ["artifact_id"],
+      "properties": {
+        "artifact_id": { "type": "string" },
+        "json_pointer": {
+          "type": "string",
+          "pattern": "^/.*$",
+          "description": "JSON Pointer (RFC 6901)"
+        },
+        "selector": {
+          "type": "string",
+          "description": "CSS selector"
+        },
+        "line_span": {
+          "type": "object",
+          "properties": {
+            "start": { "type": "integer", "minimum": 1 },
+            "end": { "type": "integer", "minimum": 1 }
+          }
+        },
+        "snippet": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Truncated source snippet"
+        }
+      }
+    },
+    "FixGuidance": {
+      "type": "object",
+      "required": ["safe"],
+      "properties": {
+        "safe": {
+          "type": "boolean",
+          "description": "True if fix is SAFE-only (intent patch, not direct write)"
+        },
+        "description": { "type": "string" },
+        "patch": {
+          "type": "object",
+          "description": "Intent patch for the fix",
+          "properties": {
+            "action": {
+              "type": "string",
+              "enum": ["add_attribute", "set_attribute", "add_element", "wrap_element"]
+            },
+            "target": { "type": "string" },
+            "value": { "type": "string" }
+          }
+        },
+        "wcag_ref": { "type": "string" }
+      }
+    },
+    "Summary": {
+      "type": "object",
+      "required": ["findings_total", "severity_counts"],
+      "properties": {
+        "findings_total": { "type": "integer", "minimum": 0 },
+        "severity_counts": {
+          "type": "object",
+          "properties": {
+            "critical": { "type": "integer", "minimum": 0 },
+            "high": { "type": "integer", "minimum": 0 },
+            "medium": { "type": "integer", "minimum": 0 },
+            "low": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "rules_applied": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "Provenance": {
+      "type": "object",
+      "required": ["record_id", "methods", "inputs", "outputs"],
+      "properties": {
+        "record_id": { "type": "string" },
+        "methods": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "inputs": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "outputs": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "timestamp": { "type": "string", "format": "date-time" }
+      }
+    }
+  }
+}