@mmerterden/multi-agent-toolkit-mcp 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -15,6 +15,45 @@ Releases before this file exists are recorded in the git tags and commit history
 
 ---
 
+## 3.4.0
+
+### Fixed
+
+- **The accessibility audits reported a clean screen they had never read.** On a
+  tree that came back empty they returned `elements_scanned: 0, total_issues: 0,
+  critical: 0, important: 0, warning: 0` - a full clean bill of health,
+  indistinguishable from an accessible screen, and the first reading is the one
+  anyone believes. Both audits now carry `measurable` and a `reason`, and an
+  unmeasurable run reports `total_issues: null`, never 0. A count of zero is a
+  measurement; none was taken.
+
+- **The iOS tree was empty until the Simulator window had been activated.**
+  Measured on a live simulator: 1 node before activation, 28 after, and it stays
+  populated once the window is backgrounded again. The dumper now activates the
+  window itself. It also says what to do when Simulator.app is not running at
+  all, because booting a device with `simctl` is not enough - the accessibility
+  bridge lives in the UI app.
+
+- **The iOS audit scored Simulator.app's own chrome as app findings.** The
+  dumped window carries the hardware buttons, the toolbar and the title text
+  beside the device screen, so Apple's 17x65pt Volume Up button was reported as
+  an app tap-target violation. The audit now scopes to the device screen, the
+  largest AXGroup child of the window. On a live Home screen this took the
+  result from 23 findings over 23 elements to 1 finding over 13: 22 of the 23
+  were the simulator's own interface.
+
+- The scoring moved to `tools/a11y/` with a suite covering the degenerate tree,
+  the chrome exclusion, a scope that matches nothing, and the rule that an
+  element with no identifier is audited whatever the scope - you cannot scope
+  what you cannot identify, and skipping it would hide the finding that says so.
+
+### Note
+
+This is the first of four stages. It buys nothing new for a blind user yet; it
+makes the existing checks honest so the next stages can be trusted. Reading
+order, traits and hints come next, then Apple's own `XCUIAccessibilityAudit`
+(contrast, Dynamic Type, clipped text), then the Android side.
+
 ## 3.3.0
 
 ### Added

package/index.js

@@ -30,6 +30,7 @@ import {
 import { DESIGN_TOOLS, handleDesign } from "./tools/design-check/index.js";
 import { parseLaunchOutput } from "./tools/launch-time/index.js";
 import { parseLeaksOutput, parseMeminfoOutput, diffMeminfo } from "./tools/memory/index.js";
+import { auditIosTree, auditAndroidDump } from "./tools/a11y/index.js";
 import { interactiveElements } from "./tools/ui-inspect/index.js";
 import { selectCrashReports } from "./tools/crash-logs/index.js";
 import {
@@ -500,38 +501,27 @@ async function handleIOS(name, args, ctx = {}) {
       const script = join(__dirname, "ui-tree-dumper.swift");
       if (!existsSync(script)) return "ui-tree-dumper.swift not found";
       const depth = num(args.max_depth ?? 10, "max_depth");
-      const scope = args.scope || null;
-      const treeJson = run(`swift ${shq(script)} ${depth}`, { timeout: 15000 });
+      const treeJson = run(`swift ${shq(script)} ${depth}`, { timeout: 30000 });
+      let tree = null;
       try {
-        const issues = [];
-        let totalScanned = 0, totalSkipped = 0;
-        function auditNode(node, path = "") {
-          const loc = path ? `${path} > ${node.role}` : node.role;
-          const w = node.frame?.w || 0, h = node.frame?.h || 0;
-          const isInteractive = ["AXButton", "AXLink", "AXTextField", "AXTextArea", "AXCheckBox", "AXRadioButton", "AXSlider", "AXSwitch", "AXTab"].includes(node.role);
-          if (isInteractive) {
-            // Scope filter: skip elements outside scope
-            if (scope && node.identifier && !node.identifier.startsWith(scope)) { totalSkipped++; if (node.children) node.children.forEach(c => auditNode(c, loc)); return; }
-            if (scope && !node.identifier) { /* no identifier = can't scope, still audit */ }
-            totalScanned++;
-            if (!node.title && !node.description && !node.value) issues.push({ severity: "critical", issue: "Missing accessibility label", element: loc, identifier: node.identifier, frame: node.frame });
-            if (!node.identifier) issues.push({ severity: "warning", issue: "Missing accessibility identifier (UI testing)", element: loc });
-            if (w > 0 && h > 0 && (w < 44 || h < 44)) issues.push({ severity: "important", issue: `Tap target too small: ${w.toFixed(0)}x${h.toFixed(0)}pt (min 44x44)`, element: loc, identifier: node.identifier, frame: node.frame });
-          }
-          if (node.children) node.children.forEach(c => auditNode(c, loc));
-        }
-        const tree = JSON.parse(treeJson);
-        auditNode(tree);
-        return JSON.stringify({ scope: scope || "all", elements_scanned: totalScanned, elements_skipped: totalSkipped, total_issues: issues.length, critical: issues.filter(i => i.severity === "critical").length, important: issues.filter(i => i.severity === "important").length, warning: issues.filter(i => i.severity === "warning").length, issues }, null, 2);
-      } catch (e) { return `ERROR parsing UI tree: ${e.message}\n\nRaw output:\n${treeJson?.substring(0, 500)}`; }
+        tree = JSON.parse(treeJson);
+      } catch {
+        tree = null;
+      }
+      const r = auditIosTree({ tree, scope: args.scope || null });
+      return JSON.stringify({
+        scope: r.scope,
+        measurable: r.measurable,
+        reason: r.reason,
+        elements_scanned: r.elementsScanned,
+        elements_skipped: r.elementsSkipped,
+        total_issues: r.totalIssues,
+        critical: r.critical,
+        important: r.important,
+        warning: r.warning,
+        issues: r.issues,
+      }, null, 2);
     }
-    // `simctl keychain <device> biometric-enroll` / `biometric-match` do not
-    // exist -  `keychain` supports only add-root-cert/add-cert/reset. The only
-    // available lever is the (undocumented) BiometricKit notification, which is
-    // posted via notifyutil inside the simulator. notifyutil exits 0 even when
-    // it cannot set or post the name, so its output has to be inspected: a
-    // "Failed with code N" line means the notification did not land, and that
-    // must be reported as a failure rather than as a simulated success.
     case "ios_biometric": {
       const d = iosDevice(args.device_id);
       const action = args.match ? "match" : "nomatch";
@@ -1062,34 +1052,20 @@ async function handleAndroid(name, args, ctx = {}) {
       const f = join(SCREENSHOT_DIR, `a11y_${Date.now()}.xml`);
       run(`adb ${df} pull /sdcard/_mcp_a11y.xml ${shq(f)}`);
       run(`adb ${df} shell rm /sdcard/_mcp_a11y.xml`);
-      if (!existsSync(f)) return "ERROR: UI dump failed";
-      const xml = readFileSync(f, "utf-8");
-      const scope = args.scope || null;
-      const issues = [];
-      let totalScanned = 0, totalSkipped = 0;
-      const nodeRegex = /<node[^>]*>/g;
-      let match;
-      while ((match = nodeRegex.exec(xml)) !== null) {
-        const node = match[0];
-        const cls = node.match(/class="([^"]*)"/)?.[1] || "";
-        const desc = node.match(/content-desc="([^"]*)"/)?.[1] || "";
-        const rid = node.match(/resource-id="([^"]*)"/)?.[1] || "";
-        const text = node.match(/text="([^"]*)"/)?.[1] || "";
-        const clickable = node.includes('clickable="true"');
-        const bounds = node.match(/bounds="\[(\d+),(\d+)\]\[(\d+),(\d+)\]"/);
-        if (clickable) {
-          if (scope && rid && !rid.includes(scope)) { totalSkipped++; continue; }
-          totalScanned++;
-          if (!desc && !text) issues.push({ severity: "critical", issue: "Missing contentDescription", element: cls, resourceId: rid });
-          if (!rid) issues.push({ severity: "warning", issue: "Missing resource-id (UI testing)", element: cls });
-          if (bounds) {
-            const w = parseInt(bounds[3]) - parseInt(bounds[1]);
-            const h = parseInt(bounds[4]) - parseInt(bounds[2]);
-            if (w < 48 || h < 48) issues.push({ severity: "important", issue: `Touch target too small: ${w}x${h}dp (min 48x48)`, element: cls, resourceId: rid });
-          }
-        }
-      }
-      return JSON.stringify({ scope: scope || "all", elements_scanned: totalScanned, elements_skipped: totalSkipped, total_issues: issues.length, critical: issues.filter(i => i.severity === "critical").length, important: issues.filter(i => i.severity === "important").length, warning: issues.filter(i => i.severity === "warning").length, issues }, null, 2);
+      const xml = existsSync(f) ? readFileSync(f, "utf-8") : "";
+      const r = auditAndroidDump({ xml, scope: args.scope || null });
+      return JSON.stringify({
+        scope: r.scope,
+        measurable: r.measurable,
+        reason: r.reason,
+        elements_scanned: r.elementsScanned,
+        elements_skipped: r.elementsSkipped,
+        total_issues: r.totalIssues,
+        critical: r.critical,
+        important: r.important,
+        warning: r.warning,
+        issues: r.issues,
+      }, null, 2);
     }
     case "android_launch_time": {
       run(`adb ${df} shell am force-stop ${sanitizeId(args.package_name)}`);
@@ -1557,17 +1533,23 @@ const ISSUE_LIST = {
   },
 };
 
+// The counts are nullable on purpose. An audit that could not read the tree
+// reports null, never 0: a count of zero is a measurement, and none was taken.
+// `measurable` is the field to branch on; the counts are only meaningful when
+// it is true.
 const ACCESSIBILITY_AUDIT_SCHEMA = {
   type: "object",
-  required: ["total_issues", "critical", "important", "warning", "issues"],
+  required: ["measurable", "total_issues", "critical", "important", "warning", "issues"],
   properties: {
     scope: { type: "string" },
+    measurable: { type: "boolean" },
+    reason: { type: ["string", "null"] },
     elements_scanned: { type: "integer" },
     elements_skipped: { type: "integer" },
-    total_issues: { type: "integer" },
-    critical: { type: "integer" },
-    important: { type: "integer" },
-    warning: { type: "integer" },
+    total_issues: { type: ["integer", "null"] },
+    critical: { type: ["integer", "null"] },
+    important: { type: ["integer", "null"] },
+    warning: { type: ["integer", "null"] },
     issues: ISSUE_LIST,
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-toolkit-mcp",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "MCP server for iOS Simulator, Android Emulator and headless web control. 86 tools: device automation (tap/swipe/type), accessibility audits, visual diff, crash logs, App Store / Play Store pre-submission compliance. Runs standalone over stdio with any MCP client.",
   "type": "module",
   "main": "index.js",
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "start": "node index.js",
-    "test": "node --test tools/design-check/__tests__/design-check.test.mjs tools/design-check/__tests__/plan-determinism.test.mjs tools/ios-app-store-audit/__tests__/app-store-audit.test.mjs tools/ios-testflight/__tests__/testflight.test.mjs tools/ui-inspect/__tests__/ui-inspect.test.mjs tools/crash-logs/__tests__/crash-logs.test.mjs tools/launch-time/__tests__/launch-time.test.mjs tools/memory/__tests__/memory.test.mjs tools/offload/__tests__/offload.test.mjs __tests__/server-tools.test.mjs __tests__/injection.test.mjs",
+    "test": "node --test tools/design-check/__tests__/design-check.test.mjs tools/design-check/__tests__/plan-determinism.test.mjs tools/ios-app-store-audit/__tests__/app-store-audit.test.mjs tools/ios-testflight/__tests__/testflight.test.mjs tools/ui-inspect/__tests__/ui-inspect.test.mjs tools/crash-logs/__tests__/crash-logs.test.mjs tools/a11y/__tests__/a11y.test.mjs tools/launch-time/__tests__/launch-time.test.mjs tools/memory/__tests__/memory.test.mjs tools/offload/__tests__/offload.test.mjs __tests__/server-tools.test.mjs __tests__/injection.test.mjs",
     "gates": "bash scripts/gates.sh"
   },
   "keywords": [

package/tools/a11y/index.js

@@ -0,0 +1,236 @@
+/**
+ * a11y - accessibility audit scoring, split out of index.js so it can be tested.
+ *
+ * The audits used to return a full clean table for a tree they never read:
+ * `elements_scanned: 0, total_issues: 0, critical: 0, important: 0, warning: 0`.
+ * On iOS the tree comes from Simulator.app's host accessibility bridge, and that
+ * bridge stays empty until the Simulator window has been activated at least
+ * once, verified on a live simulator: 1 node before activation, 28 after. So
+ * "no issues" and "never looked" were the same answer, and the first is the one
+ * a reader believes.
+ *
+ * Every result therefore carries `measurable` and, when false, a `reason`. A
+ * result that could not be measured reports `totalIssues: null`, never 0.
+ */
+
+const IOS_INTERACTIVE_ROLES = new Set([
+  "AXButton",
+  "AXLink",
+  "AXTextField",
+  "AXTextArea",
+  "AXCheckBox",
+  "AXRadioButton",
+  "AXSlider",
+  "AXPopUpButton",
+  "AXMenuButton",
+  "AXSwitch",
+]);
+
+const IOS_MIN_TAP_PT = 44;
+const ANDROID_MIN_TAP_DP = 48;
+
+/**
+ * An accessibility tree with no children is not a screen without controls, it
+ * is a tree that was never populated. Callers must not score it.
+ *
+ * @param {object|null} tree - parsed ui-tree-dumper output
+ * @returns {boolean}
+ */
+export function isDegenerateTree(tree) {
+  if (!tree || typeof tree !== "object") return true;
+  if (tree.error) return true;
+  const kids = Array.isArray(tree.children) ? tree.children : [];
+  return kids.length === 0;
+}
+
+/**
+ * The device screen inside Simulator.app's window.
+ *
+ * The dumped window holds the simulator's own chrome as direct children -
+ * hardware buttons (Action, Volume Up, Sleep/Wake), the toolbar, the title
+ * text - and the iOS app underneath a single large AXGroup. Verified on a live
+ * simulator: seven chrome children beside one 402x873 AXGroup with the app in
+ * it. Auditing the window whole reports Apple's 17x35pt Volume button as an
+ * app tap-target violation, which is a false positive in exactly the place an
+ * accessibility report has to be trusted.
+ *
+ * @param {object} tree
+ * @returns {object|null} the screen subtree, or null when it cannot be found
+ */
+export function deviceScreenSubtree(tree) {
+  if (!tree || tree.role !== "AXWindow") return tree || null;
+  const groups = (tree.children || []).filter((c) => c && c.role === "AXGroup");
+  if (groups.length === 0) return null;
+  const area = (n) => (n.frame?.w || 0) * (n.frame?.h || 0);
+  return groups.reduce((best, c) => (area(c) > area(best) ? c : best), groups[0]);
+}
+
+/**
+ * @param {object} params
+ * @param {object|null} params.tree - parsed ui-tree-dumper output
+ * @param {string|null} [params.scope] - only audit identifiers with this prefix
+ * @returns {{measurable: boolean, reason: string|null, scope: string,
+ *            elementsScanned: number, elementsSkipped: number,
+ *            totalIssues: number|null, critical: number|null,
+ *            important: number|null, warning: number|null, issues: object[]}}
+ */
+export function auditIosTree({ tree, scope = null }) {
+  if (isDegenerateTree(tree)) {
+    return unmeasurable(
+      scope,
+      tree && tree.error
+        ? String(tree.error)
+        : "the accessibility tree came back empty; open Simulator.app and bring its window to the front, then retry - the host bridge does not populate until the window has been activated once",
+    );
+  }
+
+  const screen = deviceScreenSubtree(tree);
+  if (!screen) {
+    return unmeasurable(
+      scope,
+      "the window held no device screen group; the simulator may still be starting up",
+    );
+  }
+
+  const issues = [];
+  let elementsScanned = 0;
+  let elementsSkipped = 0;
+
+  const visit = (node, path = "") => {
+    if (!node || typeof node !== "object") return;
+    const loc = path ? `${path} > ${node.role}` : node.role;
+    const w = node.frame?.w || 0;
+    const h = node.frame?.h || 0;
+
+    if (IOS_INTERACTIVE_ROLES.has(node.role)) {
+      if (scope && node.identifier && !node.identifier.startsWith(scope)) {
+        elementsSkipped++;
+        (node.children || []).forEach((c) => visit(c, loc));
+        return;
+      }
+      elementsScanned++;
+      if (!node.title && !node.description && !node.value) {
+        issues.push({ severity: "critical", issue: "Missing accessibility label", element: loc, identifier: node.identifier || null });
+      }
+      if (!node.identifier) {
+        issues.push({ severity: "warning", issue: "Missing accessibility identifier (UI testing)", element: loc });
+      }
+      if (w > 0 && h > 0 && (w < IOS_MIN_TAP_PT || h < IOS_MIN_TAP_PT)) {
+        issues.push({ severity: "important", issue: `Tap target too small: ${Math.round(w)}x${Math.round(h)}pt (min ${IOS_MIN_TAP_PT}x${IOS_MIN_TAP_PT})`, element: loc, identifier: node.identifier || null });
+      }
+    }
+    (node.children || []).forEach((c) => visit(c, loc));
+  };
+  visit(screen);
+
+  // A populated window whose interactive elements were all filtered out is a
+  // scope that matched nothing, not a clean screen.
+  if (elementsScanned === 0) {
+    return unmeasurable(
+      scope,
+      scope
+        ? `no interactive element matched scope "${scope}"`
+        : "the tree was readable but held no interactive elements to audit",
+      elementsSkipped,
+    );
+  }
+
+  return {
+    measurable: true,
+    reason: null,
+    scope: scope || "all",
+    elementsScanned,
+    elementsSkipped,
+    ...tally(issues),
+  };
+}
+
+/**
+ * @param {object} params
+ * @param {string} params.xml - uiautomator dump output
+ * @param {string|null} [params.scope] - only audit resource-ids containing this
+ * @returns {object} same shape as auditIosTree
+ */
+export function auditAndroidDump({ xml, scope = null }) {
+  const text = typeof xml === "string" ? xml : "";
+  if (!/<node\b/.test(text)) {
+    return unmeasurable(scope, "the uiautomator dump held no nodes; the dump failed or the screen was not ready");
+  }
+
+  const issues = [];
+  let elementsScanned = 0;
+  let elementsSkipped = 0;
+
+  for (const match of text.matchAll(/<node[^>]*>/g)) {
+    const node = match[0];
+    const attr = (name) => node.match(new RegExp(`${name}="([^"]*)"`))?.[1] || "";
+    if (!node.includes('clickable="true"')) continue;
+
+    const cls = attr("class");
+    const desc = attr("content-desc");
+    const rid = attr("resource-id");
+    const label = attr("text");
+
+    if (scope && rid && !rid.includes(scope)) {
+      elementsSkipped++;
+      continue;
+    }
+    elementsScanned++;
+
+    if (!desc && !label) issues.push({ severity: "critical", issue: "Missing contentDescription", element: cls, resourceId: rid || null });
+    if (!rid) issues.push({ severity: "warning", issue: "Missing resource-id (UI testing)", element: cls });
+
+    const bounds = node.match(/bounds="\[(\d+),(\d+)\]\[(\d+),(\d+)\]"/);
+    if (bounds) {
+      const w = parseInt(bounds[3], 10) - parseInt(bounds[1], 10);
+      const h = parseInt(bounds[4], 10) - parseInt(bounds[2], 10);
+      if (w < ANDROID_MIN_TAP_DP || h < ANDROID_MIN_TAP_DP) {
+        issues.push({ severity: "important", issue: `Touch target too small: ${w}x${h}dp (min ${ANDROID_MIN_TAP_DP}x${ANDROID_MIN_TAP_DP})`, element: cls, resourceId: rid || null });
+      }
+    }
+  }
+
+  if (elementsScanned === 0) {
+    return unmeasurable(
+      scope,
+      scope ? `no clickable element matched scope "${scope}"` : "the dump was readable but held no clickable elements to audit",
+      elementsSkipped,
+    );
+  }
+
+  return {
+    measurable: true,
+    reason: null,
+    scope: scope || "all",
+    elementsScanned,
+    elementsSkipped,
+    ...tally(issues),
+  };
+}
+
+function tally(issues) {
+  const by = (s) => issues.filter((i) => i.severity === s).length;
+  return {
+    totalIssues: issues.length,
+    critical: by("critical"),
+    important: by("important"),
+    warning: by("warning"),
+    issues,
+  };
+}
+
+function unmeasurable(scope, reason, elementsSkipped = 0) {
+  return {
+    measurable: false,
+    reason,
+    scope: scope || "all",
+    elementsScanned: 0,
+    elementsSkipped,
+    // null rather than 0: a count of zero is a measurement, and none was taken.
+    totalIssues: null,
+    critical: null,
+    important: null,
+    warning: null,
+    issues: [],
+  };
+}

package/ui-tree-dumper.swift

@@ -86,10 +86,22 @@ func dumpElement(_ element: AXUIElement, depth: Int, maxDepth: Int) -> AXNode? {
     )
 }
 
+// The host accessibility bridge does not populate the iOS app's elements until
+// the Simulator window has been activated at least once. Measured on a live
+// simulator: 1 node before activation, 28 after, and it stays populated once
+// the window has been backgrounded again. Without this the tree comes back
+// holding only the window, which reads as a screen with no controls.
+func activateSimulator(_ app: NSRunningApplication) {
+    if app.isActive { return }
+    app.activate(options: [])
+    Thread.sleep(forTimeInterval: 1.2)
+}
+
 func findSimulatorWindow() -> AXUIElement? {
     let apps = NSWorkspace.shared.runningApplications
     for app in apps {
         if app.bundleIdentifier == "com.apple.iphonesimulator" {
+            activateSimulator(app)
             let axApp = AXUIElementCreateApplication(app.processIdentifier)
             var windows: AnyObject?
             AXUIElementCopyAttributeValue(axApp, kAXWindowsAttribute as CFString, &windows)
@@ -105,7 +117,7 @@ func findSimulatorWindow() -> AXUIElement? {
 let maxDepth = CommandLine.arguments.count > 1 ? Int(CommandLine.arguments[1]) ?? 10 : 10
 
 guard let simWindow = findSimulatorWindow() else {
-    let error = ["error": "Simulator not running or no window found"]
+    let error = ["error": "Simulator.app is not running or has no window. Booting a device with simctl is not enough - the accessibility bridge lives in the Simulator UI app. Run: open -a Simulator"]
     let data = try! JSONSerialization.data(withJSONObject: error)
     FileHandle.standardOutput.write(data)
     exit(1)