@mcptoolshop/accessibility-suite 0.1.0

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

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mcp-tool-shop.github.io/schemas/mcp.envelope.v0.1.json",
+  "title": "MCP Envelope v0.1",
+  "description": "Standard request/response envelope for MCP tools",
+  "oneOf": [
+    { "$ref": "#/$defs/Request" },
+    { "$ref": "#/$defs/Response" },
+    { "$ref": "#/$defs/ErrorResponse" }
+  ],
+  "$defs": {
+    "EnvelopeHeader": {
+      "type": "object",
+      "required": ["envelope", "request_id", "tool"],
+      "properties": {
+        "envelope": {
+          "type": "string",
+          "const": "mcp.envelope_v0_1"
+        },
+        "request_id": {
+          "type": "string",
+          "pattern": "^req_[a-zA-Z0-9]+$",
+          "description": "Unique request identifier"
+        },
+        "tool": {
+          "type": "string",
+          "description": "Tool name (e.g., a11y.evidence, a11y.diagnose)"
+        },
+        "client": {
+          "type": "object",
+          "properties": {
+            "name": { "type": "string" },
+            "version": { "type": "string" }
+          }
+        }
+      }
+    },
+    "Request": {
+      "type": "object",
+      "required": ["mcp", "input"],
+      "properties": {
+        "mcp": { "$ref": "#/$defs/EnvelopeHeader" },
+        "input": {
+          "type": "object",
+          "description": "Tool-specific input parameters"
+        }
+      }
+    },
+    "Response": {
+      "type": "object",
+      "required": ["mcp", "result"],
+      "properties": {
+        "mcp": {
+          "allOf": [
+            { "$ref": "#/$defs/EnvelopeHeader" },
+            {
+              "type": "object",
+              "required": ["ok"],
+              "properties": {
+                "ok": { "type": "boolean", "const": true }
+              }
+            }
+          ]
+        },
+        "result": {
+          "type": "object",
+          "description": "Tool-specific result"
+        }
+      }
+    },
+    "ErrorResponse": {
+      "type": "object",
+      "required": ["mcp", "error"],
+      "properties": {
+        "mcp": {
+          "allOf": [
+            { "$ref": "#/$defs/EnvelopeHeader" },
+            {
+              "type": "object",
+              "required": ["ok"],
+              "properties": {
+                "ok": { "type": "boolean", "const": false }
+              }
+            }
+          ]
+        },
+        "error": {
+          "type": "object",
+          "required": ["code", "message"],
+          "properties": {
+            "code": {
+              "type": "string",
+              "description": "Machine-readable error code"
+            },
+            "message": {
+              "type": "string",
+              "description": "Human-readable error message"
+            },
+            "fix": {
+              "type": "string",
+              "description": "Suggested fix for the error"
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,129 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mcp-tool-shop.github.io/schemas/evidence.bundle.v0.1.json",
+  "title": "Evidence Bundle",
+  "description": "Tamper-evident bundle with artifacts and provenance",
+  "type": "object",
+  "required": ["bundle_id", "artifacts", "provenance"],
+  "properties": {
+    "bundle_id": {
+      "type": "string",
+      "pattern": "^bundle:[a-z0-9_-]+:[a-f0-9]{8}$",
+      "description": "Unique bundle identifier"
+    },
+    "artifacts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Artifact" },
+      "minItems": 1
+    },
+    "provenance": { "$ref": "#/$defs/Provenance" },
+    "environment": {
+      "type": "object",
+      "description": "Optional capture environment info",
+      "properties": {
+        "os": {
+          "oneOf": [
+            { "type": "string" },
+            {
+              "type": "object",
+              "properties": {
+                "platform": { "type": "string" },
+                "arch": { "type": "string" }
+              }
+            }
+          ]
+        },
+        "node": { "type": "string" },
+        "browser": { "type": "string" },
+        "tool_versions": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "labels": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "User-supplied classification labels"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Bundle creation timestamp"
+    }
+  },
+  "$defs": {
+    "Artifact": {
+      "type": "object",
+      "required": ["artifact_id", "media_type", "digest"],
+      "properties": {
+        "artifact_id": {
+          "type": "string",
+          "pattern": "^artifact:[a-z]+:[a-z0-9_-]+$"
+        },
+        "media_type": { "type": "string" },
+        "locator": {
+          "oneOf": [
+            { "type": "string", "format": "uri" },
+            {
+              "type": "object",
+              "properties": {
+                "kind": { "type": "string", "enum": ["file", "derived", "url"] },
+                "path": { "type": "string" },
+                "from": { "type": "string" },
+                "url": { "type": "string", "format": "uri" }
+              }
+            }
+          ]
+        },
+        "size_bytes": { "type": "integer", "minimum": 0 },
+        "digest": { "$ref": "#/$defs/Digest" },
+        "labels": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "Digest": {
+      "type": "object",
+      "required": ["alg", "hex"],
+      "properties": {
+        "alg": { "type": "string", "enum": ["sha256"] },
+        "hex": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    },
+    "Provenance": {
+      "type": "object",
+      "required": ["record_id", "methods", "inputs", "outputs"],
+      "properties": {
+        "record_id": {
+          "type": "string",
+          "pattern": "^prov:[a-z]+:[a-z0-9_-]+$"
+        },
+        "methods": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "inputs": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "outputs": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "timestamp": { "type": "string", "format": "date-time" },
+        "verified": { "type": "boolean" },
+        "agent": {
+          "type": "object",
+          "properties": {
+            "name": { "type": "string" },
+            "version": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,97 @@
+"use strict";
+
+/**
+ * Evidence anchor schema and utilities.
+ *
+ * An evidence anchor points to a specific location within an artifact:
+ * - JSON Pointer for structured data
+ * - CSS selector for DOM elements
+ * - Line span for source files
+ * - Snippet for context
+ */
+
+/**
+ * Create an evidence anchor.
+ *
+ * @param {Object} params
+ * @param {string} params.artifactId - Reference to artifact
+ * @param {string} [params.jsonPointer] - JSON Pointer (RFC 6901)
+ * @param {string} [params.selector] - CSS selector
+ * @param {Object} [params.lineSpan] - { start, end }
+ * @param {string} [params.snippet] - Context snippet
+ * @returns {Object} Evidence anchor
+ */
+function createEvidenceAnchor({
+  artifactId,
+  jsonPointer,
+  selector,
+  lineSpan,
+  snippet,
+}) {
+  const anchor = {
+    artifact_id: artifactId,
+  };
+
+  if (jsonPointer) anchor.json_pointer = jsonPointer;
+  if (selector) anchor.selector = selector;
+  if (lineSpan) anchor.line_span = lineSpan;
+  if (snippet) anchor.snippet = snippet;
+
+  return anchor;
+}
+
+/**
+ * Create a JSON Pointer from a node index.
+ *
+ * @param {number} index - Node index in flat array
+ * @returns {string} JSON Pointer
+ */
+function nodePointer(index) {
+  return `/nodes/${index}`;
+}
+
+/**
+ * Create a JSON Pointer for a DOM path.
+ *
+ * @param {string[]} path - Array of element names/indices
+ * @returns {string} JSON Pointer
+ */
+function domPointer(path) {
+  return "/dom/" + path.map(escapePointerSegment).join("/");
+}
+
+/**
+ * Escape a JSON Pointer segment.
+ */
+function escapePointerSegment(str) {
+  return String(str).replace(/~/g, "~0").replace(/\//g, "~1");
+}
+
+/**
+ * Extract a snippet from content around a position.
+ *
+ * @param {string} content - Full content
+ * @param {number} start - Start position
+ * @param {number} [maxLength=100] - Maximum snippet length
+ * @returns {string} Snippet
+ */
+function extractSnippet(content, start, maxLength = 100) {
+  const halfLen = Math.floor(maxLength / 2);
+  const snippetStart = Math.max(0, start - halfLen);
+  const snippetEnd = Math.min(content.length, start + halfLen);
+
+  let snippet = content.slice(snippetStart, snippetEnd);
+
+  if (snippetStart > 0) snippet = "..." + snippet;
+  if (snippetEnd < content.length) snippet = snippet + "...";
+
+  return snippet;
+}
+
+module.exports = {
+  createEvidenceAnchor,
+  nodePointer,
+  domPointer,
+  escapePointerSegment,
+  extractSnippet,
+};

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

@@ -0,0 +1,11 @@
+"use strict";
+
+const artifact = require("./artifact.js");
+const evidence = require("./evidence.js");
+const provenance = require("./provenance.js");
+
+module.exports = {
+  ...artifact,
+  ...evidence,
+  ...provenance,
+};

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

@@ -0,0 +1,140 @@
+"use strict";
+
+/**
+ * Provenance record utilities.
+ *
+ * Creates prov-spec compatible records for evidence capture and diagnosis.
+ */
+
+const crypto = require("crypto");
+
+/**
+ * Create a provenance record for evidence capture.
+ *
+ * @param {Object} params
+ * @param {string[]} params.methods - Method IDs applied
+ * @param {string[]} params.inputs - Input paths/IDs
+ * @param {string[]} params.outputs - Output artifact IDs
+ * @param {string} [params.agentName] - Agent name
+ * @param {string} [params.agentVersion] - Agent version
+ * @returns {Object} Provenance record
+ */
+function createProvenanceRecord({
+  methods,
+  inputs,
+  outputs,
+  agentName = "a11y-mcp-tools",
+  agentVersion = "0.1.0",
+}) {
+  const recordId = `prov:record:${crypto.randomUUID()}`;
+
+  return {
+    record_id: recordId,
+    methods,
+    inputs,
+    outputs,
+    verified: false,
+    timestamp: new Date().toISOString(),
+    agent: {
+      name: agentName,
+      version: agentVersion,
+    },
+  };
+}
+
+/**
+ * Create a full prov.record.v0.1 structure.
+ *
+ * @param {Object} params
+ * @param {string} params.methodId - Primary method ID
+ * @param {Object[]} params.inputArtifacts - Input artifact refs
+ * @param {Object[]} params.outputArtifacts - Output artifact refs
+ * @param {string} [params.agentName]
+ * @param {string} [params.agentVersion]
+ * @returns {Object} prov.record.v0.1 structure
+ */
+function createProvRecordV01({
+  methodId,
+  inputArtifacts,
+  outputArtifacts,
+  agentName = "a11y-mcp-tools",
+  agentVersion = "0.1.0",
+}) {
+  return {
+    "prov.record.v0.1": {
+      method_id: methodId,
+      timestamp: new Date().toISOString(),
+      inputs: inputArtifacts.map((a) => ({
+        "artifact.v0.1": {
+          name: a.name || a.artifact_id,
+          uri: a.uri || `artifact://${a.artifact_id}`,
+          digest: a.digest,
+        },
+      })),
+      outputs: outputArtifacts.map((a) => ({
+        "artifact.v0.1": {
+          name: a.name || a.artifact_id,
+          content: a.content,
+          digest: a.digest,
+        },
+      })),
+      agent: {
+        name: agentName,
+        version: agentVersion,
+      },
+    },
+  };
+}
+
+/**
+ * Locked Method ID Catalog (v0.1)
+ *
+ * These IDs are stable and MUST NOT change within a major version.
+ * See: https://github.com/mcp-tool-shop-org/prov-spec
+ */
+
+/**
+ * Method IDs for envelope/adapter operations.
+ */
+const ADAPTER_METHODS = {
+  // Wrap request/response in MCP envelope
+  WRAP_ENVELOPE: "adapter.wrap.envelope_v0_1",
+};
+
+/**
+ * Method IDs for evidence capture.
+ */
+const EVIDENCE_METHODS = {
+  // Capture raw HTML with canonicalization
+  CAPTURE_HTML: "engine.capture.html_canonicalize_v0_1",
+  // Extract DOM snapshot for analysis
+  CAPTURE_DOM: "engine.capture.dom_snapshot_v0_1",
+  // Generic file capture
+  CAPTURE_FILE: "engine.capture.file_v0_1",
+  // SHA-256 integrity verification
+  INTEGRITY_SHA256: "adapter.integrity.sha256_v0_1",
+  // Provenance record creation
+  PROVENANCE_RECORD: "adapter.provenance.record_v0_1",
+};
+
+/**
+ * Method IDs for diagnosis.
+ */
+const DIAGNOSE_METHODS = {
+  // WCAG rule evaluation engine
+  WCAG_RULES: "engine.diagnose.wcag_rules_v0_1",
+  // JSON Pointer evidence extraction
+  EXTRACT_POINTER: "engine.extract.evidence.json_pointer_v0_1",
+  // CSS selector evidence extraction
+  EXTRACT_SELECTOR: "engine.extract.evidence.selector_v0_1",
+  // Fix guidance generation
+  GENERATE_FIX: "engine.generate.fix_guidance_v0_1",
+};
+
+module.exports = {
+  createProvenanceRecord,
+  createProvRecordV01,
+  ADAPTER_METHODS,
+  EVIDENCE_METHODS,
+  DIAGNOSE_METHODS,
+};

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

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mcp-tool-shop.github.io/schemas/tools/a11y.diagnose.request.schema.v0.1.json",
+  "title": "Tool Request Schema: a11y.diagnose v0.1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["mcp", "input"],
+  "properties": {
+    "mcp": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["envelope", "request_id", "tool", "client"],
+      "properties": {
+        "envelope": { "const": "mcp.envelope_v0_1" },
+        "request_id": { "type": "string", "minLength": 1 },
+        "tool": { "const": "a11y.diagnose" },
+        "client": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["name", "version"],
+          "properties": {
+            "name": { "type": "string", "minLength": 1 },
+            "version": { "type": "string", "minLength": 1 }
+          }
+        }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["ok"] }
+        ]
+      }
+    },
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["bundle_id", "artifacts", "profile"],
+      "properties": {
+        "bundle_id": { "type": "string", "minLength": 1 },
+        "artifacts": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "profile": { "type": "string", "minLength": 1 },
+        "rules": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "include": { "type": "array", "items": { "type": "string" }, "default": [] },
+            "exclude": { "type": "array", "items": { "type": "string" }, "default": [] }
+          }
+        },
+        "output": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "include_fix_guidance": { "type": "boolean", "default": true },
+            "include_evidence": { "type": "boolean", "default": true }
+          }
+        },
+        "integrity": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "verify_provenance": { "type": "boolean", "default": true }
+          }
+        }
+      }
+    }
+  },
+  "not": {
+    "anyOf": [
+      { "required": ["result"] },
+      { "required": ["error"] }
+    ]
+  }
+}

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

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mcp-tool-shop.github.io/schemas/tools/a11y.diagnose.response.schema.v0.1.json",
+  "title": "Tool Response Schema: a11y.diagnose v0.1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["mcp"],
+  "properties": {
+    "mcp": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["envelope", "request_id", "tool", "ok"],
+      "properties": {
+        "envelope": { "const": "mcp.envelope_v0_1" },
+        "request_id": { "type": "string", "minLength": 1 },
+        "tool": { "const": "a11y.diagnose" },
+        "ok": { "type": "boolean" }
+      },
+      "not": { "required": ["client"] }
+    },
+    "result": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["diagnosis"],
+      "properties": {
+        "diagnosis": { "$ref": "https://mcp-tool-shop.github.io/schemas/diagnosis.v0.1.json" }
+      }
+    },
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message", "fix"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "fix": { "type": "string", "minLength": 1 }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "mcp": { "properties": { "ok": { "const": true } } } } },
+      "then": { "required": ["result"], "not": { "required": ["error"] } }
+    },
+    {
+      "if": { "properties": { "mcp": { "properties": { "ok": { "const": false } } } } },
+      "then": { "required": ["error"], "not": { "required": ["result"] } }
+    }
+  ]
+}