@mcptoolshop/accessibility-suite 0.1.0

package/src/a11y-mcp-tools/bin/server.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * MCP Server for a11y tools.
+ *
+ * Implements the Model Context Protocol for:
+ * - a11y.evidence: Evidence capture
+ * - a11y.diagnose: Accessibility diagnosis
+ *
+ * Supports MCP envelope v0.1 for requests/responses.
+ */
+
+const readline = require("readline");
+const { evidence, diagnose, tools } = require("../src/tools/index.js");
+const {
+  ENVELOPE_VERSION,
+  ERROR_CODES,
+  generateRequestId,
+  createResponseEnvelope,
+  createErrorEnvelope,
+  normalizeRequest,
+} = require("../src/envelope.js");
+
+// In-memory bundle store for the session
+const bundleStore = {};
+
+/**
+ * Handle incoming MCP request.
+ */
+async function handleRequest(request) {
+  const { id, method, params } = request;
+
+  try {
+    switch (method) {
+      case "initialize":
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            protocolVersion: "2024-11-05",
+            capabilities: {
+              tools: {},
+            },
+            serverInfo: {
+              name: "a11y-mcp-tools",
+              version: "0.2.0",
+            },
+          },
+        };
+
+      case "tools/list":
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            tools: tools.map((t) => ({
+              name: t.name,
+              description: t.description,
+              inputSchema: t.inputSchema,
+            })),
+          },
+        };
+
+      case "tools/call":
+        return await handleToolCall(id, params);
+
+      default:
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: {
+            code: -32601,
+            message: `Method not found: ${method}`,
+          },
+        };
+    }
+  } catch (err) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      error: {
+        code: -32603,
+        message: err.message,
+      },
+    };
+  }
+}
+
+/**
+ * Handle tool call with envelope support.
+ */
+async function handleToolCall(id, params) {
+  const { name, arguments: args } = params;
+
+  // Normalize to envelope format (supports both raw and envelope input)
+  const envelope = normalizeRequest(args, name);
+  const requestId = envelope.mcp?.request_id || generateRequestId();
+  const input = envelope.input || args;
+
+  let result;
+  let responseEnvelope;
+
+  try {
+    switch (name) {
+      case "a11y.evidence":
+        result = await evidence.execute(input);
+        if (result.ok) {
+          // Store bundle for later diagnosis
+          if (result.bundle) {
+            bundleStore[result.bundle.bundle_id] = result.bundle;
+          }
+          responseEnvelope = createResponseEnvelope(requestId, name, {
+            bundle: result.bundle,
+          });
+        } else {
+          responseEnvelope = createErrorEnvelope(
+            requestId,
+            name,
+            result.error?.code || ERROR_CODES.CAPTURE_FAILED,
+            result.error?.message || "Evidence capture failed",
+            result.error?.fix
+          );
+        }
+        break;
+
+      case "a11y.diagnose":
+        // Check if bundle_id is provided and resolve from store
+        if (input.bundle_id && !input.bundle) {
+          const storedBundle = bundleStore[input.bundle_id];
+          if (!storedBundle) {
+            responseEnvelope = createErrorEnvelope(
+              requestId,
+              name,
+              ERROR_CODES.BUNDLE_NOT_FOUND,
+              `Bundle not found: ${input.bundle_id}`,
+              "Capture evidence first using a11y.evidence, or provide bundle inline."
+            );
+            break;
+          }
+          input.bundle = storedBundle;
+        }
+
+        result = await diagnose.execute(input, bundleStore);
+        if (result.ok) {
+          responseEnvelope = createResponseEnvelope(requestId, name, {
+            diagnosis: result.diagnosis,
+          });
+        } else {
+          responseEnvelope = createErrorEnvelope(
+            requestId,
+            name,
+            result.error?.code || ERROR_CODES.INTERNAL_ERROR,
+            result.error?.message || "Diagnosis failed",
+            result.error?.fix
+          );
+        }
+        break;
+
+      default:
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: {
+            code: -32602,
+            message: `Unknown tool: ${name}`,
+          },
+        };
+    }
+
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(responseEnvelope, null, 2),
+          },
+        ],
+      },
+    };
+  } catch (err) {
+    const errorEnvelope = createErrorEnvelope(
+      requestId,
+      name,
+      ERROR_CODES.INTERNAL_ERROR,
+      err.message
+    );
+
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(errorEnvelope, null, 2),
+          },
+        ],
+      },
+    };
+  }
+}
+
+/**
+ * Main entry point.
+ */
+async function main() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false,
+  });
+
+  console.error("a11y-mcp-tools server started (v0.2.0, envelope: " + ENVELOPE_VERSION + ")");
+
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+
+    try {
+      const request = JSON.parse(line);
+      const response = await handleRequest(request);
+      console.log(JSON.stringify(response));
+    } catch (err) {
+      console.error("Parse error:", err.message);
+      console.log(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          id: null,
+          error: {
+            code: -32700,
+            message: "Parse error",
+          },
+        })
+      );
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/src/a11y-mcp-tools/fixtures/requests/a11y.diagnose.ok.json

@@ -0,0 +1,27 @@
+{
+  "mcp": {
+    "envelope": "mcp.envelope_v0_1",
+    "request_id": "req_fixture_diagnose_001",
+    "tool": "a11y.diagnose",
+    "client": {
+      "name": "a11y-cli",
+      "version": "0.2.0"
+    }
+  },
+  "input": {
+    "bundle_id": "bundle:fixture:9b6d3c01",
+    "artifacts": ["artifact:dom:index", "artifact:dom:contact"],
+    "profile": "wcag-2.2-aa",
+    "rules": {
+      "include": ["lang", "alt", "button-name", "link-name", "label"],
+      "exclude": []
+    },
+    "output": {
+      "include_fix_guidance": true,
+      "include_evidence": true
+    },
+    "integrity": {
+      "verify_provenance": true
+    }
+  }
+}

package/src/a11y-mcp-tools/fixtures/requests/a11y.evidence.ok.json

@@ -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/src/a11y-mcp-tools/fixtures/responses/a11y.diagnose.ok.json

@@ -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/src/a11y-mcp-tools/fixtures/responses/a11y.diagnose.provenance_fail.json

@@ -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/src/a11y-mcp-tools/fixtures/responses/a11y.evidence.ok.json

@@ -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"
+    }
+  }
+}