@mmerterden/multi-agent-toolkit-mcp 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -15,6 +15,39 @@ Releases before this file exists are recorded in the git tags and commit history
 
 ---
 
+## 3.2.0
+
+### Added
+
+- `ios_xcresult` gains `mode: "metrics"`: XCTMetric performance results straight
+  out of the `.xcresult` as JSON, via `xcresulttool get test-results metrics`.
+  The tool already shelled out to `xcresulttool` for `mode: "tests"`, so this is
+  a mode on an existing tool rather than a new integration, and Apple ships the
+  output's JSON Schema behind `--schema`, so the shape is documented rather than
+  inferred. Optional `test_id` scopes it to one case or suite.
+  Metrics exist only inside the bundle - there is no line in the build log to
+  fall back to - so a missing `.xcresult` returns an error instead of an empty
+  result that would read as "measured, nothing to report".
+
+## 3.1.1
+
+### Fixed
+
+- `android_launch_time` reported `cold_start: true` on every call. It force-stops
+  the package first, which kills the process but leaves the page cache warm, so
+  the start it measures is cold only some of the time. Android 10 replaced
+  `ThisTime` with `LaunchState` (COLD, WARM, HOT, UNKNOWN), which is the
+  platform's own verdict on the start it just performed, and the tool was
+  ignoring it while asserting the answer itself. The result now carries
+  `launch_state` and derives `cold_start` from it. Below Android 10 nothing
+  reports a launch state, so `cold_start` is `null` there rather than a claim
+  nothing checked. A failed launch now surfaces its `Error:` line instead of
+  returning null timings that read like a measurement.
+- The parser moved to `tools/launch-time/` with a suite covering the Android 10+
+  and pre-10 output shapes, a warm start, a failed launch and non-string input.
+  It could not be tested where it was: `index.js` connects its transport at
+  import time, so nothing in it is reachable from a test.
+
 ## Unreleased
 
 ## 3.1.0

package/index.js

@@ -28,6 +28,7 @@ import {
   validateApp,
 } from "./tools/ios-testflight/index.js";
 import { DESIGN_TOOLS, handleDesign } from "./tools/design-check/index.js";
+import { parseLaunchOutput } from "./tools/launch-time/index.js";
 import { interactiveElements } from "./tools/ui-inspect/index.js";
 import { selectCrashReports } from "./tools/crash-logs/index.js";
 import {
@@ -336,7 +337,7 @@ const IOS_TOOLS = [
   { name: "ios_testflight_validate", description: "Run Apple's own pre-submission validation on an .ipa via `xcrun altool --validate-app`, then map returned ITMS error codes onto the App Store rule each one implies. This is the authoritative gate: unlike the static ios_app_store_audit it can catch an unregistered bundle ID, a profile that does not match the App Store Connect app record, a version+build pair already used, and entitlements not provisioned for the app ID. Auth is a 3-tier chain: ASC API key (api_key_id + api_issuer_id), else Apple ID + app-specific password referenced indirectly through a keychain item or env var (never passed by value), else the gate returns verdict SKIPPED with a reason. SKIPPED is not a pass - it means Apple was never asked. Set list_providers=true for a pre-flight that reports which teams the credentials can deliver for (needed when a corporate Apple ID belongs to several).", inputSchema: { type: "object", properties: { ipa_path: { type: "string", description: "Absolute path to the .ipa" }, platform: { type: "string", description: "ios (default) | appletvos | visionos | macos" }, api_key_id: { type: "string", description: "App Store Connect API key ID (tier 1)" }, api_issuer_id: { type: "string", description: "App Store Connect issuer ID (tier 1)" }, p8_path: { type: "string", description: "Explicit path to AuthKey_<id>.p8; otherwise altool's search dirs are used" }, apple_id: { type: "string", description: "Apple ID (tier 2)" }, keychain_item: { type: "string", description: "Keychain item holding the app-specific password (tier 2, preferred)" }, password_env_var: { type: "string", description: "Env var holding the app-specific password (tier 2 fallback)" }, provider_public_id: { type: "string", description: "Required when the account belongs to multiple providers" }, list_providers: { type: "boolean", description: "Pre-flight only: list deliverable providers and return" }, timeout_sec: { type: "number", description: "Default 900" } }, required: [] } },
   { name: "ios_app_store_audit", description: "Deep App Store Review compliance audit for .xcarchive bundles. 18-rule catalog covering privacy manifest, code signing, embedded SDKs, entitlements, asset hygiene, IPv6 compliance, debug-tool leak detection, Swift ABI compatibility, SDK floor (ITMS-90725), and more. Returns structured JSON with severity-ranked violations and ITMS error code mappings. Replaces ios_archive_audit (deprecated). Pass rules='core' for the 6 baseline checks (code-signing, entitlements, info-plist, privacy-manifest, binary-size, sdk-floor); 'all'|'deep' for the full 18-rule scan; CSV like 'binary-size,ipv6-compliance' for an explicit subset.", inputSchema: { type: "object", properties: { archive_path: { type: "string", description: "Absolute path to the .xcarchive bundle" }, rules: { type: "string", description: "'all' (default) | 'core' | 'deep' | comma-separated ruleIDs" } }, required: ["archive_path"] } },
   { name: "ios_xcodebuild", description: "Build / test / clean an Xcode project with progressive disclosure. Returns one-line summary plus xcresult ID; drill in via ios_xcresult. Token-efficient - full log stays out of context unless requested.", inputSchema: { type: "object", properties: { project: { type: "string", description: "Path to .xcodeproj (mutually exclusive with workspace)" }, workspace: { type: "string", description: "Path to .xcworkspace (mutually exclusive with project)" }, scheme: { type: "string" }, configuration: { type: "string", description: "Debug / Release (default: Release)" }, destination: { type: "string", description: "Xcode destination string. Default: generic iOS Simulator" }, action: { type: "string", enum: ["build", "test", "clean", "archive", "clean-build"], description: "Default: build" }, derived_data_path: { type: "string" }, extra_args: { type: "string", description: "Additional raw xcodebuild args appended verbatim" }, timeout_sec: { type: "number", description: "Build timeout in seconds (default 600)" } }, required: ["scheme"] } },
-  { name: "ios_xcresult", description: "Drill into a previous ios_xcodebuild result by xcresult ID. Modes: summary (counts), errors (file:line + message), warnings, log (last N lines), tests (failed). Use this instead of dumping the whole build log into context.", inputSchema: { type: "object", properties: { id: { type: "string", description: "xcresult ID returned by ios_xcodebuild" }, mode: { type: "string", enum: ["summary", "errors", "warnings", "log", "tests"], description: "Default: summary" }, log_lines: { type: "number", description: "Lines of raw log to return when mode=log (default 200)" } }, required: ["id"] } },
+  { name: "ios_xcresult", description: "Drill into a previous ios_xcodebuild result by xcresult ID. Modes: summary (counts), errors (file:line + message), warnings, log (last N lines), tests (failed), metrics (XCTMetric performance results as JSON). Use this instead of dumping the whole build log into context.", inputSchema: { type: "object", properties: { id: { type: "string", description: "xcresult ID returned by ios_xcodebuild" }, mode: { type: "string", enum: ["summary", "errors", "warnings", "log", "tests", "metrics"], description: "Default: summary" }, log_lines: { type: "number", description: "Lines of raw log to return when mode=log (default 200)" }, test_id: { type: "string", description: "mode=metrics only: scope to one test case or suite instead of every measured test" } }, required: ["id"] } },
   { name: "ios_visual_diff", description: "Compare two PNG screenshots. Returns JSON with diff_pct, pass/fail vs threshold, and an optional diff image. Use for snapshot regression checks across light/dark, locale, dynamic type variants.", inputSchema: { type: "object", properties: { baseline: { type: "string", description: "Path to baseline PNG" }, current: { type: "string", description: "Path to current PNG" }, threshold: { type: "number", description: "Per-pixel color threshold 0..1 (default 0.1, lower = stricter)" }, max_diff_pct: { type: "number", description: "Fail if diff exceeds this percent (default 1.0)" }, output: { type: "string", description: "Path to write diff PNG (optional)" } }, required: ["baseline", "current"] } },
   { name: "ios_list_crashes", description: "List recent crash reports from the host's ~/Library/Logs/DiagnosticReports - where simulator app crashes land. Filter by process name, bound by age and count.", inputSchema: { type: "object", properties: { app: { type: "string", description: "Only reports whose file name (the crashed process) contains this substring" }, since_min: { type: "number", description: "Only reports newer than this many minutes" }, limit: { type: "number", description: "Max reports returned, newest first (default 20)" } } } },
 ];
@@ -730,6 +731,22 @@ async function handleIOS(name, args, ctx = {}) {
         const warns = (raw.match(/^.*warning:.*$/gim) || []).map(l => l.trim());
         return JSON.stringify({ id, count: warns.length, warnings: warns }, null, 2);
       }
+      if (mode === "metrics") {
+        // Performance results live only inside the .xcresult - there is no line
+        // in the text log to fall back to - so a missing bundle is an error, not
+        // an empty measurement. XCTMetric results land here only when the tests
+        // were built with performance diagnostics enabled.
+        if (!existsSync(xcresultPath)) {
+          return `ERROR: no .xcresult bundle for ${id} at ${xcresultPath}; performance metrics exist only in the bundle, not in the build log`;
+        }
+        const scope = args.test_id ? ` --test-id ${shq(args.test_id)}` : "";
+        const out = run(
+          `xcrun xcresulttool get test-results metrics --path ${shq(xcresultPath)}${scope} --compact 2>&1`,
+          { timeout: 20000 },
+        );
+        if (!out || out.startsWith("ERROR")) return out || `ERROR: xcresulttool returned nothing for ${id}`;
+        return out;
+      }
       if (mode === "tests") {
         if (existsSync(xcresultPath)) {
           const out = run(`xcrun xcresulttool get test-results tests --path ${shq(xcresultPath)} --format json 2>/dev/null`, { timeout: 20000 });
@@ -829,7 +846,7 @@ const ANDROID_TOOLS = [
   { name: "android_open_url", description: "Open URL or deep link on Android", inputSchema: { type: "object", properties: { url: { type: "string" }, device_id: { type: "string" } }, required: ["url"] } },
   { name: "android_clear_app_data", description: "Clear all data for Android app", inputSchema: { type: "object", properties: { package_name: { type: "string" }, device_id: { type: "string" } }, required: ["package_name"] } },
   { name: "android_accessibility_audit", description: "Audit Android app accessibility: missing contentDescription, small touch targets (<48dp), missing resource-id. Use scope to filter by resource-id prefix.", inputSchema: { type: "object", properties: { device_id: { type: "string" }, scope: { type: "string", description: "Filter: only audit elements whose resource-id contains this prefix (e.g. 'login_', 'com.example:id/login_'). Omit to audit all." } } } },
-  { name: "android_launch_time", description: "Measure Android app cold launch time (TotalTime in ms)", inputSchema: { type: "object", properties: { package_name: { type: "string" }, activity: { type: "string" }, device_id: { type: "string" } }, required: ["package_name"] } },
+  { name: "android_launch_time", description: "Measure Android app launch time: force-stops the package, starts it with am start -W, and reports TotalTime/WaitTime in ms plus the platform's own LaunchState (COLD/WARM/HOT). Below Android 10 there is no LaunchState and cold_start is null rather than assumed.", inputSchema: { type: "object", properties: { package_name: { type: "string" }, activity: { type: "string" }, device_id: { type: "string" } }, required: ["package_name"] } },
   { name: "android_apk_audit", description: "Audit APK/AAB for Play Store compliance: debug flag, target SDK, permissions, signing, ProGuard", inputSchema: { type: "object", properties: { apk_path: { type: "string", description: "Path to .apk file" } }, required: ["apk_path"] } },
   { name: "android_list_crashes", description: "Dump the Android crash log buffer (`adb logcat -b crash -d`), tail-bounded. Empty output means no crashes since the buffer was last cleared.", inputSchema: { type: "object", properties: { lines: { type: "number", description: "Max lines returned, from the end (default 200)" }, device_id: { type: "string" } } } },
   { name: "android_set_orientation", description: "Rotate the Android screen to portrait or landscape. Disables accelerometer rotation and pins user_rotation, so the device stays put until rotation is re-enabled. Accounts for the device's natural orientation (detected via wm size), so landscape-natural tablets rotate correctly too. No iOS counterpart: simctl exposes no rotation lever.", inputSchema: { type: "object", properties: { orientation: { type: "string", enum: ["portrait", "landscape"] }, device_id: { type: "string" } }, required: ["orientation"] } },
@@ -1020,9 +1037,19 @@ async function handleAndroid(name, args, ctx = {}) {
       run(`adb ${df} shell am force-stop ${sanitizeId(args.package_name)}`);
       const activity = sanitizeId(args.activity || `${args.package_name}/.MainActivity`);
       const result = run(`adb ${df} shell am start -W -n ${activity} 2>&1`);
-      const totalTime = result.match(/TotalTime:\s*(\d+)/)?.[1];
-      const waitTime = result.match(/WaitTime:\s*(\d+)/)?.[1];
-      return JSON.stringify({ package: args.package_name, cold_start: true, total_time_ms: totalTime ? parseInt(totalTime) : null, wait_time_ms: waitTime ? parseInt(waitTime) : null, raw: result }, null, 2);
+      const parsed = parseLaunchOutput(result);
+      return JSON.stringify({
+        package: args.package_name,
+        // The platform's own verdict, not ours: force-stop kills the process but
+        // leaves the page cache warm, so this is a cold start only sometimes.
+        // null means the device is below Android 10 and never reported one.
+        launch_state: parsed.launchState,
+        cold_start: parsed.coldStart,
+        total_time_ms: parsed.totalTimeMs,
+        wait_time_ms: parsed.waitTimeMs,
+        error: parsed.error,
+        raw: result,
+      }, null, 2);
     }
     case "android_apk_audit": {
       const p = args.apk_path;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-toolkit-mcp",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "MCP server for iOS Simulator, Android Emulator and headless web control. 84 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/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/launch-time/__tests__/launch-time.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/launch-time/index.js

@@ -0,0 +1,53 @@
+/**
+ * launch-time - parse `am start -W` output.
+ *
+ * Lives here rather than inline in index.js because index.js connects its
+ * transport at import time and cannot be loaded by a test.
+ *
+ * The handler force-stops the package first, which kills the process but leaves
+ * the page cache warm, so it produces a cold start only some of the time. The
+ * tool used to report `cold_start: true` unconditionally, which is an assertion
+ * about something the platform already measures: Android 10 replaced `ThisTime`
+ * with `LaunchState`, one of COLD, WARM, HOT or UNKNOWN, and that is the
+ * system's own verdict on the start it just performed. Below Android 10 there is
+ * no LaunchState line, and the honest answer there is "unknown" rather than a
+ * claim nothing checked.
+ */
+
+const LAUNCH_STATES = new Set(["COLD", "WARM", "HOT", "UNKNOWN"]);
+
+/**
+ * @param {string} raw - stdout+stderr of `am start -W -n <activity>`
+ * @returns {{status: string|null, launchState: string|null, coldStart: boolean|null,
+ *            activity: string|null, totalTimeMs: number|null, waitTimeMs: number|null,
+ *            error: string|null}}
+ */
+export function parseLaunchOutput(raw) {
+  const text = typeof raw === "string" ? raw : "";
+  const field = (name) => text.match(new RegExp(`^\\s*${name}:\\s*(.+?)\\s*$`, "m"))?.[1] ?? null;
+  const intField = (name) => {
+    const v = text.match(new RegExp(`^\\s*${name}:\\s*(\\d+)\\s*$`, "m"))?.[1];
+    return v === undefined ? null : parseInt(v, 10);
+  };
+
+  const rawState = field("LaunchState");
+  const launchState = rawState && LAUNCH_STATES.has(rawState.toUpperCase())
+    ? rawState.toUpperCase()
+    : null;
+
+  // `am start` reports a failure on a line of its own and still exits 0, so a
+  // missing TotalTime with an Error line is a failed launch, not a parse miss.
+  const errorLine = text.match(/^\s*Error:\s*(.+?)\s*$/m)?.[1] ?? null;
+
+  return {
+    status: field("Status"),
+    launchState,
+    // COLD is the only state that is a cold start. Below Android 10 nothing
+    // reports it, so null means "not measured", never "no".
+    coldStart: launchState === null ? null : launchState === "COLD",
+    activity: field("Activity"),
+    totalTimeMs: intField("TotalTime"),
+    waitTimeMs: intField("WaitTime"),
+    error: errorLine,
+  };
+}