@mmerterden/multi-agent-toolkit-mcp 3.0.0

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@mmerterden/multi-agent-toolkit-mcp",
+  "version": "3.0.0",
+  "description": "MCP server for iOS Simulator, Android Emulator and headless web control. 83 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",
+  "bin": {
+    "multi-agent-toolkit-mcp": "index.js",
+    "dev-toolkit-mcp": "index.js"
+  },
+  "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 __tests__/server-tools.test.mjs __tests__/injection.test.mjs",
+    "gates": "bash scripts/gates.sh"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ios",
+    "android",
+    "simulator",
+    "emulator",
+    "xcrun",
+    "simctl",
+    "adb",
+    "testing",
+    "screenshot",
+    "accessibility",
+    "ui-testing",
+    "mobile",
+    "claude",
+    "claude-code",
+    "copilot",
+    "cursor",
+    "antigravity",
+    "playwright",
+    "web-automation",
+    "browser-automation",
+    "agent-dsl",
+    "batch-execution",
+    "ios-simulator",
+    "android-emulator",
+    "appium-alternative",
+    "visual-regression",
+    "app-store",
+    "testflight",
+    "device-automation",
+    "xcode"
+  ],
+  "author": "Mert Erden",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmerterden/multi-agent-toolkit-mcp.git"
+  },
+  "homepage": "https://github.com/mmerterden/multi-agent-toolkit-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/mmerterden/multi-agent-toolkit-mcp/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "index.js",
+    "ui-tree-dumper.swift",
+    "tools/",
+    "!tools/**/__tests__",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "pixelmatch": "^7.2.0",
+    "pngjs": "^7.0.0"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.60.0 <2"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  }
+}

package/tools/crash-logs/index.js

@@ -0,0 +1,29 @@
+/**
+ * Selection logic for macOS DiagnosticReports crash files.
+ *
+ * Pure so it can be tested without a filesystem: the tool layer reads the
+ * directory and hands the entries here.
+ *
+ * @module tools/crash-logs
+ */
+
+const CRASH_EXTENSIONS = [".ips", ".crash", ".panic", ".hang", ".diag"];
+
+/**
+ * @param {Array<{name: string, mtimeMs: number, size: number}>} entries directory listing with stats
+ * @param {object} [opts]
+ * @param {string} [opts.app]     only files whose name contains this substring (case-insensitive)
+ * @param {number} [opts.sinceMs] only files modified at or after this epoch ms
+ * @param {number} [opts.limit]   max results (default 20)
+ * @returns {Array<{name: string, mtimeMs: number, size: number}>} newest first
+ */
+export function selectCrashReports(entries, opts = {}) {
+  const { app, sinceMs, limit = 20 } = opts;
+  const needle = app ? String(app).toLowerCase() : null;
+  return entries
+    .filter((e) => CRASH_EXTENSIONS.some((ext) => e.name.endsWith(ext)))
+    .filter((e) => (needle ? e.name.toLowerCase().includes(needle) : true))
+    .filter((e) => (sinceMs !== undefined ? e.mtimeMs >= sinceMs : true))
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)
+    .slice(0, Math.max(0, limit));
+}

package/tools/design-check/content-cardinality.js

@@ -0,0 +1,204 @@
+/**
+ * content-cardinality.js - suppress the geometry noise a fixture-count
+ * difference creates, WITHOUT suppressing a real defect.
+ *
+ * The problem (docs/design-check-gaps.md section 1). A live capture is compared
+ * against a screen frame, and a screen frame carries whatever the mock fixture
+ * produced. A design showing 5 passenger rows against an app rendering 3 makes
+ * every container height and every downstream position differ for a reason that
+ * is not a defect. On a real 109-target module that noise dominated the report.
+ *
+ * Why this is written defensively. The dangerous direction is not noise, it is a
+ * hidden defect: demote too eagerly and the engine silently stops reporting real
+ * deviations, in a report whose whole purpose is to surface them, and the mistake
+ * is invisible precisely because the finding is gone. So the rules below are
+ * deliberately narrow, and every one of them is a test in
+ * `__tests__/design-check.test.mjs`:
+ *
+ *   1. Nothing is ever DELETED. A demoted finding stays in the report with
+ *      `advisory: true` and a `rootCause`, so it renders under the existing
+ *      "DO NOT CHANGE (advisory / not a defect)" group with its reason attached.
+ *      `demoted` is returned as a count so a run can state what it demoted.
+ *   2. Only GEOMETRY findings are eligible. Copy, colour, typography, font-family
+ *      and tap-target findings are never touched: a row-count difference cannot
+ *      make a colour wrong or a string mistranslated, so it can never be the
+ *      explanation for one.
+ *   3. Nothing is demoted unless a mismatch is actually detected, from evidence,
+ *      in a repeated group. No mismatch -> the findings array is returned
+ *      unchanged, same objects.
+ *   4. Only findings AT OR BELOW the mismatched group are eligible. A count
+ *      difference shifts what follows it; it cannot explain a deviation above it.
+ *   5. A finding already marked advisory is left alone (idempotent), and a
+ *      `verified` finding is never demoted.
+ *
+ * FIELD VALIDATION STILL PENDING: the acceptance criterion in the gaps doc ("a
+ * screen whose fixture returns a different row count produces zero geometry
+ * findings") needs the real module, a live capture and Figma design context to
+ * confirm end to end. What is proven here is the safe direction - the rules above
+ * hold on synthetic fixtures in both directions. Treat the tuning constants as
+ * provisional until a real run is measured.
+ */
+
+/** Finding categories a cardinality difference can plausibly explain. */
+const GEOMETRY_CATEGORIES = new Set(["spacing", "size", "position", "alignment"]);
+
+/** Finding types it can explain. Narrower than the category set on purpose. */
+const GEOMETRY_TYPES = new Set(["spacing", "height", "inset", "gap", "position", "offset"]);
+
+/**
+ * Types that must NEVER be demoted, whatever their category says. Listed
+ * explicitly rather than relying on the allow-list above, so a future category
+ * rename cannot quietly make one of these eligible.
+ */
+const NEVER_DEMOTE_TYPES = new Set([
+  "copy",
+  "color",
+  "colour",
+  "font-size",
+  "font-family",
+  "typography",
+  "tap-target",
+  "icon-size",
+  "missing",
+  "extra",
+]);
+
+/**
+ * Strip the varying tail from an element name so repeated siblings collapse to
+ * one group key: `passengerRow_2` / `passenger row 3` / `PassengerRow-4` all
+ * become `passengerrow`.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function groupKey(name) {
+  return String(name || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_-]+/g, "")
+    .replace(/\d+$/, "")
+    .replace(/(item|row|cell|card)$/, "$1");
+}
+
+/**
+ * Count repeated siblings per group in a flat element list.
+ *
+ * @param {Array<object>} elements
+ * @returns {Map<string, {count: number, minY: number}>}
+ */
+function groupCounts(elements) {
+  const out = new Map();
+  for (const el of elements || []) {
+    const raw = el?.label ?? el?.text ?? el?.identifier ?? el?.name;
+    const key = groupKey(raw);
+    if (!key) continue;
+    const y = Number.isFinite(el?.y) ? el.y : Infinity;
+    const cur = out.get(key);
+    if (cur) {
+      cur.count += 1;
+      cur.minY = Math.min(cur.minY, y);
+    } else {
+      out.set(key, { count: 1, minY: y });
+    }
+  }
+  return out;
+}
+
+/**
+ * Detect a repeated-group cardinality difference between design and live.
+ *
+ * Requires a group to be genuinely REPEATED on at least one side (>= 2), because
+ * a 1-vs-0 difference is a missing element - a real defect, and exactly what this
+ * must not explain away.
+ *
+ * @param {Array<object>} figmaSpec
+ * @param {Array<object>} liveGeometry
+ * @param {{minRepeat?: number}} [opts]
+ * @returns {{mismatch: boolean, groups: Array<object>, boundaryY: number|null}}
+ */
+export function detectCardinalityMismatch(figmaSpec, liveGeometry, opts = {}) {
+  const minRepeat = opts.minRepeat ?? 2;
+  const design = groupCounts(figmaSpec);
+  const live = groupCounts(liveGeometry);
+  const groups = [];
+
+  for (const [key, d] of design) {
+    const l = live.get(key);
+    if (!l) continue; // absent entirely is a missing-element defect, not a count difference
+    if (d.count === l.count) continue;
+    if (Math.max(d.count, l.count) < minRepeat) continue; // 1 vs 0 is not a repeat
+    groups.push({
+      key,
+      designCount: d.count,
+      liveCount: l.count,
+      // The topmost occurrence on either side: everything at or below it can be
+      // shifted by the difference.
+      firstY: Math.min(d.minY, l.minY),
+    });
+  }
+
+  const boundaryY = groups.length
+    ? Math.min(...groups.map((g) => (Number.isFinite(g.firstY) ? g.firstY : Infinity)))
+    : null;
+
+  return {
+    mismatch: groups.length > 0,
+    groups,
+    boundaryY: Number.isFinite(boundaryY) ? boundaryY : null,
+  };
+}
+
+/** Is this finding the kind a cardinality difference could explain? */
+function isGeometryFinding(f) {
+  const type = String(f?.type || "").toLowerCase();
+  const category = String(f?.category || "").toLowerCase();
+  if (NEVER_DEMOTE_TYPES.has(type)) return false;
+  return GEOMETRY_TYPES.has(type) || GEOMETRY_CATEGORIES.has(category);
+}
+
+/** The finding's vertical position, or null when it cannot be established. */
+function findingY(f) {
+  const y = f?.region?.y ?? f?.y;
+  return Number.isFinite(y) ? y : null;
+}
+
+/**
+ * Demote the geometry findings a detected cardinality difference explains.
+ *
+ * @param {Array<object>} findings
+ * @param {{mismatch: boolean, groups: Array<object>, boundaryY: number|null}} detection
+ * @returns {{findings: Array<object>, demoted: number, rootCause: string|null}}
+ */
+export function demoteCardinalityNoise(findings, detection) {
+  const list = Array.isArray(findings) ? findings : [];
+  if (!detection?.mismatch) return { findings: list, demoted: 0, rootCause: null };
+
+  const summary = detection.groups
+    .map((g) => `${g.key}: design ${g.designCount} vs live ${g.liveCount}`)
+    .join("; ");
+  const rootCause =
+    `content count differs between the design fixture and the running app (${summary}). ` +
+    `Container heights and everything below the first differing group shift for that reason, ` +
+    `not because the layout is wrong. Re-run against a fixture with matching counts to measure these.`;
+
+  const boundary = detection.boundaryY;
+  let demoted = 0;
+
+  const out = list.map((f) => {
+    if (!f || f.advisory || f.status === "verified") return f;
+    if (!isGeometryFinding(f)) return f;
+
+    // Rule 4: only at or below the first differing group. An unknown position
+    // is NOT assumed to be below it - unplaceable findings keep full severity,
+    // because demoting on a guess is the failure mode this module must not have.
+    if (boundary !== null) {
+      const y = findingY(f);
+      if (y === null || y < boundary) return f;
+    }
+
+    demoted += 1;
+    return { ...f, advisory: true, rootCause, demotedBy: "content-cardinality" };
+  });
+
+  return { findings: out, demoted, rootCause };
+}

package/tools/design-check/geometry.js

@@ -0,0 +1,140 @@
+/**
+ * design_ui_geometry helpers - turn a live UI hierarchy into a flat list of
+ * element bounding boxes, so spacing/position deltas against a Figma spec can
+ * be measured in pixels. Generic: works off the iOS AX JSON dumper output and
+ * the Android uiautomator XML dump.
+ *
+ * Element shape: { role, label, text, identifier, x, y, w, h }
+ * Coordinates are in device points/pixels as reported by the platform.
+ */
+
+// iOS: parse the ui-tree-dumper.swift JSON (nested AXNode with frame {x,y,w,h}).
+export function flattenIosAxTree(json) {
+  let root;
+  try { root = typeof json === "string" ? JSON.parse(json) : json; } catch { return []; }
+  const out = [];
+  const visit = (node) => {
+    if (!node || typeof node !== "object") return;
+    const f = node.frame || {};
+    if (typeof f.w === "number" && typeof f.h === "number" && f.w > 0 && f.h > 0) {
+      out.push({
+        role: node.role || "",
+        label: node.title || node.description || "",
+        text: node.value || "",
+        identifier: node.identifier || "",
+        x: Math.round(f.x || 0), y: Math.round(f.y || 0),
+        w: Math.round(f.w), h: Math.round(f.h),
+      });
+    }
+    (node.children || []).forEach(visit);
+  };
+  visit(root);
+  return out;
+}
+
+// iOS via idb: parse `idb ui describe-all --json` output (array of AX elements,
+// each with frame {x,y,width,height} in points). Works headless (no Simulator GUI).
+export function flattenIdbDescribeAll(json) {
+  let arr;
+  try {
+    const raw = typeof json === "string" ? json.trim() : json;
+    arr = typeof raw === "string"
+      ? (raw.startsWith("[") ? JSON.parse(raw) : raw.split("\n").filter(Boolean).map((l) => JSON.parse(l)))
+      : raw;
+  } catch { return []; }
+  if (!Array.isArray(arr)) return [];
+  const out = [];
+  for (const e of arr) {
+    const f = e && e.frame;
+    if (!f || typeof f.width !== "number") continue;
+    if (f.width <= 0 || f.height <= 0) continue;
+    if ((e.type || e.role_description) === "Application") continue;
+    out.push({
+      role: e.role || e.type || "",
+      label: e.AXLabel || "",
+      text: e.AXValue || e.title || "",
+      identifier: e.AXUniqueId || "",
+      x: Math.round(f.x), y: Math.round(f.y),
+      w: Math.round(f.width), h: Math.round(f.height),
+    });
+  }
+  return out;
+}
+
+// Android: parse uiautomator XML. bounds="[x1,y1][x2,y2]".
+export function flattenAndroidUiXml(xml) {
+  if (!xml || typeof xml !== "string") return [];
+  const out = [];
+  const nodeRe = /<node\b([^>]*)\/?>/g;
+  const attr = (s, name) => {
+    const m = new RegExp(`${name}="([^"]*)"`).exec(s);
+    return m ? m[1] : "";
+  };
+  let m;
+  while ((m = nodeRe.exec(xml)) !== null) {
+    const a = m[1];
+    const bounds = attr(a, "bounds");
+    const bm = /\[(\d+),(\d+)\]\[(\d+),(\d+)\]/.exec(bounds);
+    if (!bm) continue;
+    const x1 = +bm[1], y1 = +bm[2], x2 = +bm[3], y2 = +bm[4];
+    const w = x2 - x1, h = y2 - y1;
+    if (w <= 0 || h <= 0) continue;
+    out.push({
+      role: attr(a, "class").split(".").pop() || "",
+      label: attr(a, "content-desc"),
+      text: attr(a, "text"),
+      identifier: attr(a, "resource-id"),
+      x: x1, y: y1, w, h,
+    });
+  }
+  return out;
+}
+
+// Normalize a Figma node subtree (from get_design_context / metadata) into the
+// same flat element shape, carrying style spec where present.
+// Accepts a node with absoluteBoundingBox / children / style / fills.
+export function flattenFigmaNode(node, originX = 0, originY = 0) {
+  const out = [];
+  const visit = (n) => {
+    if (!n || typeof n !== "object") return;
+    const bb = n.absoluteBoundingBox || n.boundingBox;
+    if (bb && typeof bb.width === "number") {
+      const style = n.style || {};
+      const fill = firstSolidColor(n.fills) || (style.fills && firstSolidColor(style.fills));
+      out.push({
+        role: n.type || "",
+        label: n.name || "",
+        text: n.characters || "",
+        identifier: n.id || "",
+        x: Math.round(bb.x - originX), y: Math.round(bb.y - originY),
+        w: Math.round(bb.width), h: Math.round(bb.height),
+        fontSize: style.fontSize || null,
+        fontFamily: style.fontFamily || style.fontPostScriptName || null,
+        color: fill || null,
+        itemSpacing: typeof n.itemSpacing === "number" ? n.itemSpacing : null,
+        paddings: {
+          top: n.paddingTop, right: n.paddingRight, bottom: n.paddingBottom, left: n.paddingLeft,
+        },
+      });
+    }
+    (n.children || []).forEach(visit);
+  };
+  visit(node);
+  return out;
+}
+
+function firstSolidColor(fills) {
+  if (!Array.isArray(fills)) return null;
+  for (const f of fills) {
+    if (f && f.type === "SOLID" && f.color) {
+      const { r, g, b } = f.color;
+      return rgbToHex(r * 255, g * 255, b * 255);
+    }
+  }
+  return null;
+}
+
+export function rgbToHex(r, g, b) {
+  const h = (v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, "0");
+  return `#${h(r)}${h(g)}${h(b)}`.toUpperCase();
+}