@mmerterden/multi-agent-toolkit-mcp 3.12.0 → 3.13.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mmerterden/multi-agent-toolkit-mcp",
-  "version": "3.12.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.1",
+  "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": [
@@ -85,11 +85,24 @@
     "pngjs": "^7.0.0"
   },
   "peerDependencies": {
-    "playwright": ">=1.60.0 <2"
+    "@mozilla/readability": "^0.6.0",
+    "playwright": ">=1.60.0 <2",
+    "turndown": "^7.2.0"
   },
   "peerDependenciesMeta": {
     "playwright": {
       "optional": true
+    },
+    "@mozilla/readability": {
+      "optional": true
+    },
+    "turndown": {
+      "optional": true
     }
+  },
+  "devDependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "playwright": "^1.63.0",
+    "turndown": "^7.2.4"
   }
 }

package/tools/context/index.js

@@ -0,0 +1,192 @@
+// 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.
+//
+// Space between two FTS5 terms is AND. That is right for a log line, where
+// every word is a fact about the one entry being looked for, and wrong for a
+// question: "pack numbers into a bytes object using a format string" demands
+// all nine words from a single chunk and returns nothing at all rather than
+// the page that carries seven of them. `mode: "or"` builds the same query
+// with OR, which is what `search` falls back to; bm25 then ranks by how many
+// of the terms a chunk carries and how rare each one is.
+export function toMatchQuery(query, { mode = "and" } = {}) {
+  const terms = String(query)
+    .split(/\s+/)
+    .map((t) => t.replace(/"/g, ""))
+    .filter(Boolean);
+  if (!terms.length) return null;
+  return terms.map((t) => `"${t}"`).join(mode === "or" ? " OR " : " ");
+}
+
+export function search(db, query, { limit = 5, path = null } = {}) {
+  const where = path
+    ? "where chunks match ? and doc_id = (select id from docs where path = ?)"
+    : "where chunks match ?";
+  const sql = 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 ?`,
+  );
+  const run = (match) => {
+    const params = path ? [match, path] : [match];
+    return sql.all(...params, limit);
+  };
+  // Every term first, because a caller who typed all of them meant all of
+  // them. Any term second, so a question that no single chunk answers word
+  // for word still comes back ranked instead of empty.
+  let rows = [];
+  for (const mode of ["and", "or"]) {
+    const match = toMatchQuery(query, { mode });
+    if (!match) return [];
+    rows = run(match);
+    if (rows.length) break;
+  }
+  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/offload/index.js

@@ -142,6 +142,60 @@ export function offloadedErrorSummary(text, path, headChars = 400, tailChars = 2
   );
 }
 
+// What a payload IS decides what is worth keeping out of it.
+//
+// A head-plus-tail window keeps the two places a large payload is least likely
+// to carry its answer. A logcat's meaning is one FATAL line somewhere in the
+// middle; a build log's is its `error:` lines; a UI dump's is the handful of
+// nodes you can actually tap. The tool name is already here, so the window can
+// be chosen rather than fixed - and the lines it surfaces come with their line
+// numbers, so the caller can go straight to them in the saved file.
+//
+// Patterns only, no model: the cost of being wrong is a few extra lines in a
+// window that already exists, which is the right trade for a dependency-free
+// check that runs on every offload.
+const SIGNAL_FAMILIES = [
+  {
+    when: /logcat|crash|crashes/i,
+    label: "crash",
+    rx: /\b(FATAL|AndroidRuntime|Exception|SIGABRT|SIGSEGV|SIGILL|Thread \d+ Crashed|Abort trap)\b/,
+  },
+  {
+    when: /xcodebuild|xcresult|build|test/i,
+    label: "failure",
+    rx: /(^|\s)(error:|FAILED|failed:|XCTAssert\w*|Undefined symbol|linker command failed|\*\* BUILD FAILED)/,
+  },
+  {
+    when: /ui_tree|accessibility|inspect/i,
+    label: "interactive",
+    rx: /\b(AXButton|AXTextField|AXSwitch|clickable=true|enabled=true|focusable=true)\b/,
+  },
+  { when: /leaks|meminfo|memory/i, label: "measurement", rx: /\b(Leak|leaked|TOTAL|Total PSS|bytes)\b/ },
+];
+
+export const SIGNAL_LINE_CAP = 20;
+const SIGNAL_LINE_CHARS = 200;
+
+// Lines from the part the window hides, that carry what this kind of payload is
+// read for. Returns "" when the family is unknown or nothing matched, so the
+// window is exactly what it was before.
+export function signalLines(tool, lines, headCount, tailCount, cap = SIGNAL_LINE_CAP) {
+  const family = SIGNAL_FAMILIES.find((f) => f.when.test(String(tool)));
+  if (!family) return "";
+  const from = headCount;
+  const to = Math.max(headCount, lines.length - tailCount);
+  const hits = [];
+  for (let i = from; i < to && hits.length < cap; i++) {
+    if (family.rx.test(lines[i])) {
+      const body = lines[i].length > SIGNAL_LINE_CHARS ? `${lines[i].slice(0, SIGNAL_LINE_CHARS)}...` : lines[i];
+      hits.push(`  ${i + 1}: ${body}`);
+    }
+  }
+  if (!hits.length) return "";
+  const more = hits.length === cap ? ` (first ${cap})` : "";
+  return `\n\n[${family.label} lines from the hidden middle${more}]\n${hits.join("\n")}`;
+}
+
 export function offloadLargeText(tool, text, opts = {}) {
   const dir = opts.dir ?? OFFLOAD_DIR;
   const minChars = opts.minChars ?? OFFLOAD_MIN_CHARS;
@@ -166,13 +220,15 @@ export function offloadLargeText(tool, text, opts = {}) {
   const head = lines.slice(0, HEAD_LINES).join("\n");
   const tail = lines.slice(-TAIL_LINES).join("\n");
   const hidden = Math.max(0, lines.length - HEAD_LINES - TAIL_LINES);
+  const signal = signalLines(tool, lines, HEAD_LINES, TAIL_LINES);
   return {
     offloaded: true,
     path,
     text:
       `${head}\n\n[... ${hidden} line(s) not shown. Full output (${lines.length} lines, ` +
       `${text.length} bytes) saved to ${path} - search it with ` +
-      `agent_query_output {pattern: "..."} instead of re-running this tool ...]\n\n${tail}`,
+      `agent_query_output {pattern: "..."} instead of re-running this tool ...]` +
+      `${signal}\n\n${tail}`,
   };
 }