@mmerterden/multi-agent-toolkit-mcp 3.11.0 → 3.13.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mmerterden/multi-agent-toolkit-mcp",
-  "version": "3.11.0",
-  "description": "MCP server for iOS Simulator, Android Emulator and headless web control. 99 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.",
+  "version": "3.13.0",
+  "description": "MCP server for iOS Simulator, Android Emulator and headless web control. 115 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": {
@@ -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/code-intel/__tests__/code-intel.test.mjs tools/pass-kit/__tests__/pass-kit.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",
+    "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/code-intel/__tests__/code-intel.test.mjs tools/pass-kit/__tests__/pass-kit.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 tools/context/__tests__/context.test.mjs __tests__/server-tools.test.mjs __tests__/injection.test.mjs",
     "gates": "bash scripts/gates.sh"
   },
   "keywords": [
@@ -73,6 +73,12 @@
     "CHANGELOG.md",
     "LICENSE"
   ],
+  "_overridesReadme": "Three advisories reach this tree only through @modelcontextprotocol/sdk, and all three are fixed inside the major their consumer already depends on. The upper bound on fast-uri is load-bearing: ajv@8 declares ^3, and an unbounded >=3.1.6 resolves to 4.x, which is a different major under a dependency that never asked for it.",
+  "overrides": {
+    "fast-uri": ">=3.1.6 <4",
+    "hono": ">=4.13.5 <5",
+    "qs": ">=6.16.0 <7"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "pixelmatch": "^7.2.0",

package/tools/context/index.js

@@ -0,0 +1,175 @@
+// Full-text index over offloaded payloads.
+//
+// The offload module already writes a large result to a file and hands back a
+// head+tail window plus the path, and `agent_query_output` greps that file.
+// Grep answers "which lines contain this string"; it cannot answer "which part
+// of this is about X", and it has no notion of one passage being a better match
+// than another. For a 40k-line log that is the difference between reading the
+// right 60 lines and reading the first 60 that happen to contain the word.
+//
+// So the same file is also indexed: chunked, stored in SQLite FTS5, and ranked
+// with bm25(). node:sqlite ships with Node, so this costs no dependency.
+//
+// Three layers, cheapest first:
+//   context_search  ranked snippets, ~50-100 tokens, enough to decide
+//   context_get     one chunk in full, by the id search returned
+//   the file path   everything, which is what the caller already had
+//
+// agent_query_output is untouched. It is in the cross-CLI contract and removing
+// it would be a breaking change; this sits beside it.
+
+import { DatabaseSync } from "node:sqlite";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+// Overridable so a gate can index a fixture corpus without writing into the
+// caller's real index, and so the ranking it asserts is over a known set rather
+// than over whatever that machine happened to offload last.
+export const INDEX_DIR =
+  process.env.MCP_TOOLKIT_INDEX_DIR ||
+  join(homedir(), ".claude", "logs", "multi-agent-toolkit", ".index");
+
+// Chunks are lines, not bytes: a log line cut in half matches nothing and reads
+// as nonsense. 40 lines is small enough that a hit points at a place and large
+// enough to carry its own context.
+export const CHUNK_LINES = 40;
+export const CHUNK_OVERLAP = 8;
+
+function dbPathFor(dir) {
+  return join(dir, "context.db");
+}
+
+export function openIndex(dir = INDEX_DIR) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const db = new DatabaseSync(dbPathFor(dir));
+  db.exec(`
+    create table if not exists docs (
+      id integer primary key,
+      path text not null,
+      mtime integer not null,
+      size integer not null,
+      unique(path)
+    );
+    create virtual table if not exists chunks using fts5(
+      body,
+      doc_id unindexed,
+      first_line unindexed,
+      last_line unindexed
+    );
+  `);
+  return db;
+}
+
+export function chunk(text, lines = CHUNK_LINES, overlap = CHUNK_OVERLAP) {
+  const all = String(text).split("\n");
+  const out = [];
+  const step = Math.max(1, lines - overlap);
+  for (let start = 0; start < all.length; start += step) {
+    const slice = all.slice(start, start + lines);
+    if (!slice.join("").trim()) continue;
+    out.push({ body: slice.join("\n"), firstLine: start + 1, lastLine: start + slice.length });
+    if (start + lines >= all.length) break;
+  }
+  return out;
+}
+
+// Re-indexing an unchanged file is wasted work AND duplicate hits, so the
+// (mtime, size) pair decides. It is not a hash: hashing a 40 MB log to learn
+// nothing changed costs more than the indexing it saves.
+export function indexFile(db, path) {
+  if (!existsSync(path)) return { indexed: false, reason: "no such file" };
+  const st = statSync(path);
+  const existing = db.prepare("select id, mtime, size from docs where path = ?").get(path);
+  if (existing && existing.mtime === Math.floor(st.mtimeMs) && existing.size === st.size) {
+    const n = db.prepare("select count(*) as n from chunks where doc_id = ?").get(existing.id);
+    return { indexed: false, reason: "unchanged", docId: existing.id, chunks: n?.n ?? 0 };
+  }
+  if (existing) {
+    db.prepare("delete from chunks where doc_id = ?").run(existing.id);
+    db.prepare("delete from docs where id = ?").run(existing.id);
+  }
+  db.prepare("insert into docs (path, mtime, size) values (?, ?, ?)").run(
+    path,
+    Math.floor(st.mtimeMs),
+    st.size,
+  );
+  const docId = db.prepare("select id from docs where path = ?").get(path).id;
+  const insert = db.prepare(
+    "insert into chunks (body, doc_id, first_line, last_line) values (?, ?, ?, ?)",
+  );
+  const pieces = chunk(readFileSync(path, "utf8"));
+  for (const p of pieces) insert.run(p.body, docId, p.firstLine, p.lastLine);
+  return { indexed: true, docId, chunks: pieces.length };
+}
+
+// FTS5 treats a bare `-` or an unbalanced quote as syntax, and a caller typing
+// a log line into the query gets a SQL error instead of results. Quoting each
+// term makes every query a literal phrase search, which is what a caller
+// searching a log actually means.
+export function toMatchQuery(query) {
+  const terms = String(query)
+    .split(/\s+/)
+    .map((t) => t.replace(/"/g, ""))
+    .filter(Boolean);
+  if (!terms.length) return null;
+  return terms.map((t) => `"${t}"`).join(" ");
+}
+
+export function search(db, query, { limit = 5, path = null } = {}) {
+  const match = toMatchQuery(query);
+  if (!match) return [];
+  const where = path
+    ? "where chunks match ? and doc_id = (select id from docs where path = ?)"
+    : "where chunks match ?";
+  const params = path ? [match, path] : [match];
+  const rows = db
+    .prepare(
+      `select chunks.rowid, doc_id, first_line, last_line, body,
+              (select path from docs where docs.id = chunks.doc_id) as path,
+              bm25(chunks) as score
+       from chunks ${where} order by score limit ?`,
+    )
+    .all(...params, limit);
+  return rows.map((r) => ({
+    id: r.rowid,
+    docId: r.doc_id,
+    path: r.path,
+    firstLine: r.first_line,
+    lastLine: r.last_line,
+    score: r.score,
+    snippet: snippetOf(r.body, query),
+  }));
+}
+
+// A window around the first matching line, not the head of the chunk: the
+// caller is deciding whether to open this, and the head of a 40-line chunk
+// often says nothing about why it matched.
+export function snippetOf(body, query, radius = 2) {
+  const lines = String(body).split("\n");
+  const needles = String(query).toLowerCase().split(/\s+/).filter(Boolean);
+  let hit = lines.findIndex((l) => needles.some((n) => l.toLowerCase().includes(n)));
+  if (hit < 0) hit = 0;
+  const from = Math.max(0, hit - radius);
+  return lines.slice(from, hit + radius + 1).join("\n");
+}
+
+export function getChunk(db, id) {
+  const row = db
+    .prepare(
+      `select c.rowid as id, c.body, c.first_line, c.last_line, d.path
+       from chunks c join docs d on d.id = c.doc_id where c.rowid = ?`,
+    )
+    .get(Number(id));
+  return row ?? null;
+}
+
+export function docPathId(path) {
+  return createHash("sha256").update(String(path)).digest("hex").slice(0, 12);
+}
+
+export function ensureParent(path) {
+  const parent = dirname(path);
+  if (!existsSync(parent)) mkdirSync(parent, { recursive: true });
+}

package/tools/ios-app-store-audit/context.js

@@ -3,14 +3,22 @@
  * 18 rules consume. Direct port of XCArchiveParser.swift +
  * InfoPlistParser.swift + PrivacyManifestParser.swift + EntitlementParser.swift.
  *
- * Plist parsing is delegated to `plutil -convert json` (system binary on
- * macOS, ships with the OS) - more reliable than any Node `plist` package
- * across the long tail of Apple plist quirks (binary plists, XML-with-DTD,
- * mixed array/dict roots).
+ * Plist parsing prefers `plutil -convert json` (system binary on macOS, ships
+ * with the OS) - more reliable than any Node `plist` package across the long
+ * tail of Apple plist quirks (binary plists, XML-with-DTD, mixed array/dict
+ * roots).
+ *
+ * When plutil is absent it falls back to a small XML reader, and when even that
+ * cannot apply - a binary plist off macOS - it records the miss rather than
+ * returning an empty object. That distinction is the whole point: every rule
+ * reads `infoPlist`, so a silent `{}` makes an unreadable archive audit exactly
+ * like a compliant one, and the tool answers PASS because it saw nothing. It
+ * shipped that way; a run with no plutil on PATH reported zero violations on a
+ * deliberately non-compliant fixture.
  */
 
 import { execSync } from "child_process";
-import { existsSync, readdirSync, statSync } from "fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
 import { shq } from "./models.js";
 import { join, basename } from "path";
 
@@ -23,16 +31,159 @@ function run(cmd) {
   }
 }
 
-/** Parse a binary or XML plist file into a JS object via `plutil`. */
+/** True when the `plutil` binary is on PATH. Probed once. */
+let _hasPlutil = null;
+export function hasPlutil() {
+  if (_hasPlutil === null) _hasPlutil = run("command -v plutil") !== "";
+  return _hasPlutil;
+}
+
+/**
+ * Plists this process could not read, as absolute paths. A rule that finds
+ * nothing in an unread plist is not evidence of compliance, and runAudit turns
+ * a non-empty list into a finding rather than letting the verdict stand.
+ */
+export const unreadablePlists = new Set();
+
+/**
+ * Empty the record. runAudit calls this before it parses anything, so the set
+ * describes the run being reported and not every run this process has done.
+ */
+export function resetUnreadablePlists() {
+  unreadablePlists.clear();
+}
+
+/** Decode the XML entities a plist can carry. */
+function unescapeXml(s) {
+  return s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#(\d+);/g, (_, d) => String.fromCharCode(Number(d)))
+    .replace(/&amp;/g, "&");
+}
+
+/**
+ * Minimal XML-plist reader for hosts without plutil.
+ *
+ * Deliberately small: it handles the element set an Info.plist, an entitlements
+ * file and a PrivacyInfo.xcprivacy actually use. It is not a general plist
+ * implementation and makes no attempt at binary plists - those return null and
+ * are recorded as unreadable, which is the honest answer.
+ *
+ * @param {string} xml
+ * @returns {object|Array|null}
+ */
+export function parseXmlPlist(xml) {
+  // <!DOCTYPE ...> and <?xml ...?> carry nothing we need and complicate the scan.
+  const body = xml.replace(/<\?xml[^>]*\?>/g, "").replace(/<!DOCTYPE[^>]*>/g, "");
+  const tokens = body.match(/<\/?[A-Za-z]+(?:\s[^>]*)?\/?>|[^<]+/g);
+  if (!tokens) return null;
+  let i = 0;
+
+  const next = () => tokens[i++];
+  const peek = () => tokens[i];
+
+  function readValue(tag) {
+    switch (tag) {
+      case "dict": {
+        const out = {};
+        for (;;) {
+          const t = peek();
+          if (t === undefined || t === "</dict>") {
+            next();
+            return out;
+          }
+          if (t === "<key>") {
+            next();
+            const k = unescapeXml(String(next() ?? "").trim());
+            next(); // </key>
+            const vt = String(next() ?? "").trim();
+            out[k] = readValue(vt.replace(/^<|\/?>$/g, "").split(/\s/)[0]);
+          } else {
+            next();
+          }
+        }
+      }
+      case "array": {
+        const out = [];
+        for (;;) {
+          const t = peek();
+          if (t === undefined || t === "</array>") {
+            next();
+            return out;
+          }
+          const vt = String(next() ?? "").trim();
+          if (!vt.startsWith("<")) continue;
+          out.push(readValue(vt.replace(/^<|\/?>$/g, "").split(/\s/)[0]));
+        }
+      }
+      case "string":
+      case "data":
+      case "date": {
+        const raw = peek() !== undefined && !String(peek()).startsWith("<") ? String(next()) : "";
+        if (String(peek() ?? "").startsWith("</")) next();
+        return unescapeXml(raw);
+      }
+      case "integer":
+      case "real": {
+        const raw = peek() !== undefined && !String(peek()).startsWith("<") ? String(next()) : "0";
+        if (String(peek() ?? "").startsWith("</")) next();
+        return Number(raw.trim());
+      }
+      case "true":
+        return true;
+      case "false":
+        return false;
+      default:
+        return null;
+    }
+  }
+
+  for (;;) {
+    const t = next();
+    if (t === undefined) return null;
+    const s = String(t).trim();
+    if (!s.startsWith("<plist")) continue;
+    for (;;) {
+      const u = next();
+      if (u === undefined) return null;
+      const v = String(u).trim();
+      if (!v.startsWith("<")) continue;
+      return readValue(v.replace(/^<|\/?>$/g, "").split(/\s/)[0]);
+    }
+  }
+}
+
+/** Parse a binary or XML plist file into a JS object. */
 export function parsePlist(plistPath) {
   if (!existsSync(plistPath)) return null;
-  const json = run(`plutil -convert json -o - ${shq(plistPath)} 2>/dev/null`);
-  if (!json) return null;
+  if (hasPlutil()) {
+    const json = run(`plutil -convert json -o - ${shq(plistPath)} 2>/dev/null`);
+    if (json) {
+      try {
+        return JSON.parse(json);
+      } catch {
+        /* fall through to the XML reader */
+      }
+    }
+  }
+  let raw;
   try {
-    return JSON.parse(json);
+    raw = readFileSync(plistPath, "utf-8");
   } catch {
+    unreadablePlists.add(plistPath);
+    return null;
+  }
+  // A binary plist starts with the magic "bplist"; there is no reading it here.
+  if (raw.startsWith("bplist")) {
+    unreadablePlists.add(plistPath);
     return null;
   }
+  const parsed = parseXmlPlist(raw);
+  if (parsed === null) unreadablePlists.add(plistPath);
+  return parsed;
 }
 
 /** Recursively measure total size of a directory in bytes. */

package/tools/ios-app-store-audit/index.js

@@ -21,7 +21,7 @@
  * the rest of the scan.
  */
 
-import { parseArchive } from "./context.js";
+import { hasPlutil, parseArchive, resetUnreadablePlists, unreadablePlists } from "./context.js";
 import { compareSeverity } from "./models.js";
 
 // ---------- Rule registry --------------------------------------------------
@@ -93,6 +93,7 @@ function resolveRuleSelection(rules) {
  * @returns {Promise<object>} structured audit report
  */
 export async function runAudit({ archivePath, rules = "all", options = {} } = {}) {
+  resetUnreadablePlists();
   const ctx = parseArchive(archivePath);
 
   const selectedIDs = new Set(resolveRuleSelection(rules));
@@ -134,6 +135,25 @@ export async function runAudit({ archivePath, rules = "all", options = {} } = {}
     }
   }
 
+  // A rule that found nothing in a plist nobody could read has not measured
+  // anything, and the audit must not let that reach the caller as compliance.
+  // Every rule reads infoPlist, so one unread plist can silence all eighteen:
+  // the tool answered PASS on a deliberately non-compliant fixture the first
+  // time it ran on a host without plutil. Reported as an error so the verdict
+  // is not PASS, with the cause named - this is the tool's reach, not the
+  // archive's fault.
+  const unreadable = [...unreadablePlists].sort();
+  if (unreadable.length > 0) {
+    violations.push({
+      ruleID: "archive-readable",
+      severity: "error",
+      message: `${unreadable.length} plist(s) could not be read, so the rules below them measured nothing: ${unreadable.join(", ")}`,
+      suggestion: hasPlutil()
+        ? "The files are present but neither plutil nor the XML reader could parse them. Re-export the archive, or open an issue with one of the files attached."
+        : "Binary plists need `plutil`, which ships with macOS. Run this audit on macOS, or convert the archive's plists to XML first (`plutil -convert xml1`).",
+    });
+  }
+
   // Sort: error → warning → info, then by ruleID alphabetically inside each.
   violations.sort((a, b) => {
     const c = compareSeverity(b.severity, a.severity);
@@ -156,6 +176,9 @@ export async function runAudit({ archivePath, rules = "all", options = {} } = {}
     app: ctx.appName,
     rulesRun: ranIDs,
     rulesSkipped: skippedIDs,
+    // Explicit, so a caller can tell "clean" from "could not look".
+    measurable: unreadable.length === 0,
+    unreadablePlists: unreadable,
     summary,
     verdict,
     violations,

package/tools/offload/index.js

@@ -58,15 +58,35 @@ function pruneEntries(dir, { keepFiles, keepDays, now, keep, match }) {
         }
       })
       .filter(Boolean)
-      .sort((a, b) => b.mtime - a.mtime);
-
-    for (let i = 0; i < entries.length; i++) {
-      if (keepSet.has(resolve(entries[i].full))) continue;
-      const tooOld = entries[i].mtime < cutoff;
-      const tooMany = i >= keepFiles;
-      if (!tooOld && !tooMany) continue;
+      // Name as the tie-break, because mtime ties are not a corner case. APFS
+      // records nanoseconds, so five files written in a loop have five distinct
+      // stamps; ext4 on a CI runner records one, so they have the same stamp and
+      // "the newest" is whatever order readdir happened to return. Without this
+      // the retained set differs per filesystem.
+      .sort((a, b) => b.mtime - a.mtime || (a.full < b.full ? 1 : a.full > b.full ? -1 : 0));
+
+    // keepFiles is the size of the directory after the prune, not the size of
+    // the part of it retention got to decide. A promised file is one of the
+    // survivors, so it takes one of the slots - reserved up front rather than
+    // counted as the loop reaches it, because otherwise the answer depends on
+    // where that file happens to sort. It used to be neither: a keepSet entry
+    // was skipped without consuming anything, so keepFiles: 1 plus one promised
+    // file left TWO files behind. On APFS the promised file is genuinely the
+    // newest and sorted first, which hid it; on a filesystem whose mtimes tie it
+    // sorted anywhere and the directory kept a stale file forever.
+    const reserved = entries.filter((e) => keepSet.has(resolve(e.full))).length;
+    const budget = Math.max(0, keepFiles - reserved);
+    let kept = 0;
+    for (const entry of entries) {
+      if (keepSet.has(resolve(entry.full))) continue;
+      const tooOld = entry.mtime < cutoff;
+      const tooMany = kept >= budget;
+      if (!tooOld && !tooMany) {
+        kept++;
+        continue;
+      }
       try {
-        rmSync(entries[i].full, { recursive: true, force: true });
+        rmSync(entry.full, { recursive: true, force: true });
         removed++;
       } catch {
         // A file another process holds open is skipped, not fatal.