@buoy-gg/mcp 4.0.1 → 5.0.0

package/dist/index.js

@@ -36,15 +36,28 @@ __export(src_exports, {
   DASHBOARD_NAME: () => DASHBOARD_NAME,
   DEFAULT_ACTION_TIMEOUT_MS: () => DEFAULT_ACTION_TIMEOUT_MS,
   DEFAULT_SNAPSHOT_TIMEOUT_MS: () => DEFAULT_SNAPSHOT_TIMEOUT_MS,
+  PACKAGE_NAME: () => PACKAGE_NAME,
   SyncClient: () => SyncClient,
+  VERSION: () => VERSION,
   buildAutomationConfig: () => buildAutomationConfig,
   compareReportStats: () => compareReportStats,
   createMcpServer: () => createMcpServer,
   estimateBatchMs: () => estimateBatchMs,
   formatRankingMarkdown: () => formatRankingMarkdown,
+  getUpdateNotice: () => getUpdateNotice,
   rankBatchFromIndex: () => rankBatchFromIndex,
+  registerConsoleTools: () => registerConsoleTools,
+  registerEventsTools: () => registerEventsTools,
   registerGenericTools: () => registerGenericTools,
-  registerPerfMonitorTools: () => registerPerfMonitorTools
+  registerJotaiTools: () => registerJotaiTools,
+  registerPerfMonitorTools: () => registerPerfMonitorTools,
+  registerReactQueryTools: () => registerReactQueryTools,
+  registerReduxTools: () => registerReduxTools,
+  registerRoutesTools: () => registerRoutesTools,
+  registerScreenshotTools: () => registerScreenshotTools,
+  registerStorageTools: () => registerStorageTools,
+  registerZustandTools: () => registerZustandTools,
+  runInit: () => runInit
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -347,10 +360,85 @@ var delay = (ms) => new Promise((r) => setTimeout(r, ms));
 
 // src/server.ts
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
-var import_zod3 = require("zod");
+var import_zod13 = require("zod");
 
 // src/tools/generic.ts
 var import_zod = require("zod");
+
+// src/update/checkForUpdate.ts
+var import_node_fs = require("fs");
+var import_node_os = __toESM(require("os"));
+var import_node_path = __toESM(require("path"));
+
+// src/version.ts
+var VERSION = "5.0.0" ? "5.0.0" : "0.0.0-dev";
+var PACKAGE_NAME = "@buoy-gg/mcp";
+
+// src/update/checkForUpdate.ts
+var CHECK_TTL_MS = 24 * 60 * 60 * 1e3;
+var FETCH_TIMEOUT_MS = 1500;
+var REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+var CACHE_FILE = import_node_path.default.join(import_node_os.default.tmpdir(), "buoy-mcp-update-check.json");
+function isNewer(a, b) {
+  const parse = (v) => v.split("-")[0].split(".").map((n) => Number(n) || 0);
+  const pa = parse(a);
+  const pb = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] ?? 0;
+    const y = pb[i] ?? 0;
+    if (x > y) return true;
+    if (x < y) return false;
+  }
+  return false;
+}
+async function readCache() {
+  try {
+    const raw = await import_node_fs.promises.readFile(CACHE_FILE, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.checkedAt === "number" && typeof parsed.latest === "string") {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+async function fetchLatest(now) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(REGISTRY_URL, { signal: controller.signal });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const latest = typeof body.version === "string" ? body.version : null;
+    if (latest) {
+      await import_node_fs.promises.writeFile(CACHE_FILE, JSON.stringify({ checkedAt: now, latest })).catch(() => {
+      });
+    }
+    return latest;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function resolveLatest(now) {
+  const cache = await readCache();
+  if (cache && now - cache.checkedAt < CHECK_TTL_MS) return cache.latest;
+  return fetchLatest(now);
+}
+async function getUpdateNotice(now = Date.now()) {
+  if (VERSION === "0.0.0-dev") return null;
+  try {
+    const latest = await resolveLatest(now);
+    if (latest && isNewer(latest, VERSION)) {
+      return `A newer buoy-mcp is available (${latest}; you're on ${VERSION}). Update by re-running: npx -y ${PACKAGE_NAME}@latest init \u2014 then restart your editor.`;
+    }
+  } catch {
+  }
+  return null;
+}
+
+// src/tools/generic.ts
 function json(value) {
   return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
 }
@@ -365,11 +453,13 @@ function registerGenericTools(server, sync) {
       inputSchema: {}
     },
     async () => {
+      const updateNotice = await getUpdateNotice();
       const devices = sync.listDevices();
       if (devices.length === 0) {
         return json({
           devices: [],
-          hint: "No devices connected. Open the app with Buoy devtools running, then retry."
+          hint: "No devices connected. Open the app with Buoy devtools running, then retry.",
+          ...updateNotice ? { updateAvailable: updateNotice } : {}
         });
       }
       const anyPro = devices.some((d) => d.isConnected && d.isPro);
@@ -377,7 +467,8 @@ function registerGenericTools(server, sync) {
         devices,
         ...anyPro ? {} : {
           hint: "The Buoy MCP is a Pro feature \u2014 no connected device has an active Buoy Pro license, so data/action tools are blocked. Upgrade to Buoy Pro in the app to enable them."
-        }
+        },
+        ...updateNotice ? { updateAvailable: updateNotice } : {}
       });
     }
   );
@@ -1147,14 +1238,925 @@ ${JSON.stringify(saved ?? settings, null, 2)}
   );
 }
 
+// src/tools/packs/events.ts
+var import_zod3 = require("zod");
+var EVENTS_TOOL_ID = "events";
+var text2 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail3 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg3 = (e) => e instanceof Error ? e.message : String(e);
+var SOURCE_ALIASES = {
+  storage: ["storage-async", "storage-mmkv"],
+  "react-query": ["react-query", "react-query-query", "react-query-mutation"]
+};
+function expandSources(sources) {
+  if (!sources || sources.length === 0) return void 0;
+  return [...new Set(sources.flatMap((s) => SOURCE_ALIASES[s] ?? [s]))];
+}
+function registerEventsTools(server, sync) {
+  server.registerTool(
+    "get_events",
+    {
+      description: "The UNIVERSAL, token-bounded activity reader for what's happening in the app across ALL Buoy tools. The events tool aggregates every source \u2014 network requests, redux/zustand/jotai actions, react-query query/mutation updates, storage writes, route changes, renders \u2014 so filter to one with `sources`: ['network'] lists HTTP requests, ['redux'] dispatched actions, ['react-query'] query updates, ['storage'] writes, ['route'] navigation. Returns a compact one-line summary per event (source \xB7 status \xB7 title \xB7 timing) by DEFAULT \u2014 not the heavy raw payloads \u2014 so it's cheap. Re-call with includeData:true, a bigger limit, or specific sources only when you need detail. PREFER this over get_snapshot (and over reading source code) for any 'what happened' / 'show me the requests/actions' question; get_snapshot is the raw heavy current-state escape hatch.",
+      inputSchema: {
+        limit: import_zod3.z.number().optional().describe("Most-recent N events to include. Default 25."),
+        sources: import_zod3.z.array(import_zod3.z.string()).optional().describe('Only these sources. Coarse names accepted: "network", "redux", "react-query", "storage", "route", "render", "zustand", "jotai". Omit for all.'),
+        status: import_zod3.z.enum(["all", "errors", "success", "pending"]).optional().describe("Filter by status. Default all."),
+        includeData: import_zod3.z.boolean().optional().describe("Include each event's full raw payload (HEAVY \u2014 network bodies, state trees). Default false (compact)."),
+        format: import_zod3.z.enum(["markdown", "json", "text", "mermaid"]).optional().describe("Output format. Default markdown."),
+        preset: import_zod3.z.enum(["llm", "bugReport", "json", "errors", "minimal", "mermaid"]).optional().describe("Start from a named Copy-Settings preset (then your other args override it)."),
+        deviceId: import_zod3.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const settings = {};
+        const sources = expandSources(args.sources);
+        if (sources) settings.filterSources = sources;
+        if (args.status) settings.filterMode = args.status;
+        if (args.includeData !== void 0) settings.includeEventData = args.includeData;
+        if (args.format) settings.format = args.format === "text" ? "plaintext" : args.format;
+        const res = await sync.callAction(
+          EVENTS_TOOL_ID,
+          "exportEvents",
+          { preset: args.preset, settings, limit: args.limit ?? 25 },
+          target
+        );
+        if (!res || typeof res.output !== "string") {
+          return fail3(
+            "No events result from the device. The events tool may be inactive, or the app needs a newer Buoy (get_events requires the exportEvents action)."
+          );
+        }
+        const more = res.includedData ? "" : " \u2014 compact view; pass includeData:true, a specific source, or a bigger limit for full payloads";
+        const note = `
+
+_Showing ${res.returned} of ${res.totalAvailable} captured event(s)${more}._`;
+        return text2((res.output || "(no events captured)") + note);
+      } catch (e) {
+        return fail3(errMsg3(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/reactQuery.ts
+var import_zod4 = require("zod");
+var RQ_TOOL_ID = "react-query";
+var text3 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail4 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg4 = (e) => e instanceof Error ? e.message : String(e);
+var STATUS_ICON = {
+  fresh: "\u{1F7E2}",
+  stale: "\u{1F7E1}",
+  fetching: "\u{1F504}",
+  error: "\u{1F534}",
+  inactive: "\u26AA\uFE0F",
+  paused: "\u23F8\uFE0F",
+  disabled: "\u{1F6AB}"
+};
+function relTime(ts) {
+  if (!ts) return "\u2014";
+  const s = Math.round((Date.now() - ts) / 1e3);
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.round(s / 60)}m ago`;
+  if (s < 86400) return `${Math.round(s / 3600)}h ago`;
+  return `${Math.round(s / 86400)}d ago`;
+}
+function registerReactQueryTools(server, sync) {
+  server.registerTool(
+    "get_react_query",
+    {
+      description: "Read the app's CURRENT React Query cache \u2014 every query with its status (fresh/stale/fetching/error), staleness, observer count, last-updated time, and any error. Compact by DEFAULT (no cached payloads) so it's token-cheap; pass includeData:true for the actual cached data, or staleOnly:true to see just stale queries. Use this for 'what's in the cache / why is this stale / which queries errored'. (For the history of query updates over time, use get_events with sources:['react-query'].) Each row's hash is what you pass to react_query_action.",
+      inputSchema: {
+        includeData: import_zod4.z.boolean().optional().describe("Include each query's full cached data payload (HEAVY). Default false."),
+        staleOnly: import_zod4.z.boolean().optional().describe("Only stale queries. Default false."),
+        limit: import_zod4.z.number().optional().describe("Most-recently-updated N queries. Default 25."),
+        deviceId: import_zod4.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const res = await sync.callAction(
+          RQ_TOOL_ID,
+          "listQueries",
+          { includeData: args.includeData ?? false, staleOnly: args.staleOnly ?? false, limit: args.limit ?? 25 },
+          target
+        );
+        if (!res || !Array.isArray(res.queries)) {
+          return fail4(
+            "No react-query result from the device. The react-query tool may be inactive, or the app needs a newer Buoy (get_react_query requires the listQueries action)."
+          );
+        }
+        if (res.queries.length === 0) {
+          return text3(`React Query cache is empty (0 of ${res.total} queries${args.staleOnly ? " match staleOnly" : ""}).`);
+        }
+        const lines = res.queries.map((q, i) => {
+          const icon = STATUS_ICON[q.status] ?? "\u2022";
+          const base = `${i + 1}. ${icon} ${q.status} \xB7 \`${q.queryHash}\` \xB7 ${q.observers} obs \xB7 ${relTime(q.updatedAt)}`;
+          const errSuffix = q.error ? ` \u2014 \u26A0\uFE0F ${q.error}` : "";
+          const dataSuffix = res.includedData ? `
+   data: ${JSON.stringify(q.data)}` : "";
+          return base + errSuffix + dataSuffix;
+        });
+        const staleCount = res.queries.filter((q) => q.isStale).length;
+        const header = `**React Query cache \u2014 ${res.total} queries (showing ${res.returned}, ${staleCount} stale):**`;
+        const note = res.includedData ? "" : "\n\n_Compact view. Pass includeData:true for cached payloads, staleOnly:true to narrow. Act on one with react_query_action using the `hash` in backticks._";
+        return text3(`${header}
+
+${lines.join("\n")}${note}`);
+      } catch (e) {
+        return fail4(errMsg4(e));
+      }
+    }
+  );
+  server.registerTool(
+    "react_query_action",
+    {
+      description: "Mutate the app's React Query cache: invalidate / refetch / reset / remove a single query (by queryHash, from get_react_query), or clear the entire query cache. Use this to fix stale data, force a refetch, or reset state during debugging.",
+      inputSchema: {
+        action: import_zod4.z.enum(["invalidate", "refetch", "reset", "remove", "clear"]).describe("invalidate/refetch/reset/remove a single query (needs queryHash); clear empties the whole query cache."),
+        queryHash: import_zod4.z.string().optional().describe("The target query's hash (from get_react_query, shown in backticks). Required for all actions except clear."),
+        deviceId: import_zod4.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        if (args.action === "clear") {
+          await sync.callAction(RQ_TOOL_ID, "clearQueryCache", {}, target);
+          return text3("Cleared the entire React Query cache.");
+        }
+        if (!args.queryHash) {
+          return fail4(`'${args.action}' needs a queryHash. Call get_react_query first and use a row's hash (in backticks).`);
+        }
+        await sync.callAction(RQ_TOOL_ID, args.action, { queryHash: args.queryHash }, target);
+        return text3(`Ran ${args.action} on query \`${args.queryHash}\`.`);
+      } catch (e) {
+        return fail4(errMsg4(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/zustand.ts
+var import_zod5 = require("zod");
+var ZUSTAND_TOOL_ID = "zustand";
+var text4 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail5 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg5 = (e) => e instanceof Error ? e.message : String(e);
+function registerZustandTools(server, sync) {
+  server.registerTool(
+    "get_zustand_state",
+    {
+      description: "Read the app's CURRENT Zustand store state \u2014 each registered store with its name, change count, persistence, and (by default) just its top-level keys so it's token-cheap. Pass includeValues:true for the full state objects. Use this for 'what's in my zustand stores / what's the current count'. (For the history of state changes over time, use get_events with sources:['zustand'].)",
+      inputSchema: {
+        includeValues: import_zod5.z.boolean().optional().describe("Include each store's full current state object (HEAVY). Default false (keys only)."),
+        limit: import_zod5.z.number().optional().describe("First N stores. Default all."),
+        deviceId: import_zod5.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const res = await sync.callAction(
+          ZUSTAND_TOOL_ID,
+          "listStores",
+          { includeValues: args.includeValues ?? false, limit: args.limit },
+          target
+        );
+        if (!res || !Array.isArray(res.stores)) {
+          return fail5(
+            "No zustand result from the device. The zustand tool may be inactive, or the app needs a newer Buoy (get_zustand_state requires the listStores action)."
+          );
+        }
+        if (res.stores.length === 0) {
+          return text4("No Zustand stores are registered (call watchStores to register them).");
+        }
+        const lines = res.stores.map((s, i) => {
+          const persist = s.isPersisted ? ` \xB7 persisted${s.persistName ? ` (${s.persistName})` : ""}` : "";
+          const body = res.includedValues ? `
+   ${JSON.stringify(s.currentState)}` : ` \xB7 keys: ${(s.keys ?? []).join(", ") || "\u2014"}`;
+          return `${i + 1}. **${s.name}** \xB7 ${s.changes} changes${persist}${body}`;
+        });
+        const note = res.includedValues ? "" : "\n\n_Compact view (keys only). Pass includeValues:true for full state. Mutate with zustand_action({store, state})._";
+        return text4(`**Zustand stores \u2014 ${res.total} (showing ${res.returned}):**
+
+${lines.join("\n")}${note}`);
+      } catch (e) {
+        return fail5(errMsg5(e));
+      }
+    }
+  );
+  server.registerTool(
+    "zustand_action",
+    {
+      description: "Set the state of a Zustand store (time-travel / reset / tweak during debugging). Targets a store by name (from get_zustand_state). By default replaces the whole state; pass replace:false to merge a partial.",
+      inputSchema: {
+        store: import_zod5.z.string().describe("Store name to target (from get_zustand_state)."),
+        state: import_zod5.z.record(import_zod5.z.string(), import_zod5.z.unknown()).describe("The new state object."),
+        replace: import_zod5.z.boolean().optional().describe("Replace the whole state (default true) or merge a partial (false)."),
+        deviceId: import_zod5.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        await sync.callAction(
+          ZUSTAND_TOOL_ID,
+          "setState",
+          { storeName: args.store, state: args.state, replace: args.replace ?? true },
+          target
+        );
+        return text4(`Set state on Zustand store "${args.store}" (${args.replace === false ? "merged" : "replaced"}).`);
+      } catch (e) {
+        return fail5(errMsg5(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/jotai.ts
+var import_zod6 = require("zod");
+var JOTAI_TOOL_ID = "jotai";
+var text5 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail6 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg6 = (e) => e instanceof Error ? e.message : String(e);
+function registerJotaiTools(server, sync) {
+  server.registerTool(
+    "get_jotai_state",
+    {
+      description: "Read the app's CURRENT Jotai atom values \u2014 each watched atom with its label, change count, and whether it's writable. Compact by DEFAULT (no values) so it's token-cheap; pass includeValues:true for the actual current values. Use this for 'what are my jotai atoms / what's the current value'. (For the history of atom changes over time, use get_events with sources:['jotai'].)",
+      inputSchema: {
+        includeValues: import_zod6.z.boolean().optional().describe("Include each atom's current value (HEAVY). Default false."),
+        limit: import_zod6.z.number().optional().describe("First N atoms. Default all."),
+        deviceId: import_zod6.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const res = await sync.callAction(
+          JOTAI_TOOL_ID,
+          "listAtoms",
+          { includeValues: args.includeValues ?? false, limit: args.limit },
+          target
+        );
+        if (!res || !Array.isArray(res.atoms)) {
+          return fail6(
+            "No jotai result from the device. The jotai tool may be inactive, or the app needs a newer Buoy (get_jotai_state requires the listAtoms action)."
+          );
+        }
+        if (res.atoms.length === 0) {
+          return text5("No Jotai atoms are being watched (call watchAtoms to register them).");
+        }
+        const lines = res.atoms.map((a, i) => {
+          const kind = a.writable ? "writable" : "read-only";
+          const value = res.includedValues ? `
+   ${JSON.stringify(a.currentValue)}` : "";
+          return `${i + 1}. **${a.label}** \xB7 ${a.changes} changes \xB7 ${kind}${value}`;
+        });
+        const note = res.includedValues ? "" : "\n\n_Compact view. Pass includeValues:true for current values. Set a writable atom with jotai_action({atom, value})._";
+        return text5(`**Jotai atoms \u2014 ${res.total} (showing ${res.returned}):**
+
+${lines.join("\n")}${note}`);
+      } catch (e) {
+        return fail6(errMsg6(e));
+      }
+    }
+  );
+  server.registerTool(
+    "jotai_action",
+    {
+      description: "Set the value of a writable Jotai atom (by label, from get_jotai_state). Read-only/derived atoms cannot be set (you'll get a clear error). Use for tweaking state during debugging.",
+      inputSchema: {
+        atom: import_zod6.z.string().describe("Atom label to set (from get_jotai_state; must be writable)."),
+        value: import_zod6.z.unknown().describe("The new value (any JSON \u2014 number, string, object, etc.)."),
+        deviceId: import_zod6.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        await sync.callAction(JOTAI_TOOL_ID, "setAtom", { label: args.atom, value: args.value }, target);
+        return text5(`Set Jotai atom "${args.atom}" to ${JSON.stringify(args.value)}.`);
+      } catch (e) {
+        return fail6(errMsg6(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/redux.ts
+var import_zod7 = require("zod");
+var REDUX_TOOL_ID = "redux";
+var text6 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail7 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg7 = (e) => e instanceof Error ? e.message : String(e);
+var NO_STORE = "No instrumented Redux store found. Open the app with Buoy redux devtools active (auto-instrumentation), then retry.";
+function registerReduxTools(server, sync) {
+  server.registerTool(
+    "get_redux_state",
+    {
+      description: "Read the app's CURRENT Redux state. Compact by DEFAULT \u2014 just the top-level slice names \u2014 so it's token-cheap; pass includeValues:true for the full state tree. Use this for 'what's in my redux store / current auth state'. (For the history of dispatched actions over time, use get_events with sources:['redux'].)",
+      inputSchema: {
+        includeValues: import_zod7.z.boolean().optional().describe("Include the full current state tree (HEAVY). Default false (slice names only)."),
+        deviceId: import_zod7.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const res = await sync.callAction(
+          REDUX_TOOL_ID,
+          "getState",
+          { includeValues: args.includeValues ?? false },
+          target
+        );
+        if (!res) {
+          return fail7(
+            "No redux result from the device. The redux tool may be inactive, or the app needs a newer Buoy (get_redux_state requires the getState action)."
+          );
+        }
+        if (!res.available) return text6(NO_STORE);
+        const slices = res.slices.length ? res.slices.join(", ") : "(none)";
+        if (args.includeValues) {
+          return text6(`**Redux store \u2014 slices: ${slices}**
+
+\`\`\`json
+${JSON.stringify(res.state, null, 2)}
+\`\`\``);
+        }
+        return text6(
+          `**Redux store \u2014 slices: ${slices}**
+
+_Compact view. Pass includeValues:true for the full state tree. Dispatch with redux_dispatch({type, payload})._`
+        );
+      } catch (e) {
+        return fail7(errMsg7(e));
+      }
+    }
+  );
+  server.registerTool(
+    "redux_dispatch",
+    {
+      description: "Dispatch a Redux action to the app's store (e.g. to trigger a state change while debugging). Provide the action type and optional payload \u2014 they're sent as { type, payload }.",
+      inputSchema: {
+        type: import_zod7.z.string().describe('The action type, e.g. "counter/increment" or "auth/logout".'),
+        payload: import_zod7.z.unknown().optional().describe("Optional action payload (any JSON)."),
+        deviceId: import_zod7.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const action = { type: args.type };
+        if (args.payload !== void 0) action.payload = args.payload;
+        const res = await sync.callAction(REDUX_TOOL_ID, "dispatch", { action }, target);
+        if (!res || !res.dispatched) return fail7(NO_STORE);
+        return text6(`Dispatched \`${args.type}\`${args.payload !== void 0 ? ` with payload ${JSON.stringify(args.payload)}` : ""}.`);
+      } catch (e) {
+        return fail7(errMsg7(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/storage.ts
+var import_zod8 = require("zod");
+var STORAGE_TOOL_ID = "storage";
+var text7 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail8 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg8 = (e) => e instanceof Error ? e.message : String(e);
+function truncate(v, n = 200) {
+  if (v === null || v === void 0) return "(null)";
+  const s = typeof v === "string" ? v : JSON.stringify(v);
+  return s.length > n ? `${s.slice(0, n)}\u2026(+${s.length - n} chars)` : s;
+}
+function registerStorageTools(server, sync) {
+  server.registerTool(
+    "get_storage",
+    {
+      description: "Read the app's AsyncStorage keys. Compact by DEFAULT \u2014 keys only \u2014 so it's token-cheap; pass includeValues:true for the values (truncated), or a `pattern` substring to narrow. Buoy's own internal keys are already filtered out. Use for 'what's in storage / read this key'.",
+      inputSchema: {
+        pattern: import_zod8.z.string().optional().describe("Only keys containing this substring (case-insensitive)."),
+        includeValues: import_zod8.z.boolean().optional().describe("Include each key's value (truncated). Default false (keys only)."),
+        limit: import_zod8.z.number().optional().describe("Max keys to return. Default 100."),
+        deviceId: import_zod8.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const allKeys = await sync.callAction(STORAGE_TOOL_ID, "async.getAllKeys", {}, target);
+        if (!Array.isArray(allKeys)) {
+          return fail8("No storage result from the device. The storage tool may be inactive.");
+        }
+        const pattern = args.pattern?.toLowerCase();
+        const matched = pattern ? allKeys.filter((k) => k.toLowerCase().includes(pattern)) : allKeys;
+        const limit = typeof args.limit === "number" && args.limit > 0 ? args.limit : 100;
+        const keys = matched.slice(0, limit);
+        if (keys.length === 0) {
+          return text7(`No storage keys${pattern ? ` matching "${args.pattern}"` : ""} (${allKeys.length} total).`);
+        }
+        let lines;
+        if (args.includeValues) {
+          const pairs = await sync.callAction(STORAGE_TOOL_ID, "async.multiGet", { keys }, target);
+          const map = new Map((pairs ?? []).map(([k, v]) => [k, v]));
+          lines = keys.map((k) => `- \`${k}\` = ${truncate(map.get(k) ?? null)}`);
+        } else {
+          lines = keys.map((k) => `- \`${k}\``);
+        }
+        const filteredNote = pattern ? ` matching "${args.pattern}"` : "";
+        const header = `**Storage \u2014 ${allKeys.length} keys (showing ${keys.length}${filteredNote}):**`;
+        const note = args.includeValues ? "" : "\n\n_Keys only. Pass includeValues:true for values, or a pattern to filter. Modify with storage_action._";
+        return text7(`${header}
+
+${lines.join("\n")}${note}`);
+      } catch (e) {
+        return fail8(errMsg8(e));
+      }
+    }
+  );
+  server.registerTool(
+    "storage_action",
+    {
+      description: "Modify the app's AsyncStorage: set a key, remove a key, or clear all app storage (Buoy's own devtool keys are preserved). Values are stored as strings \u2014 JSON-encode objects yourself.",
+      inputSchema: {
+        action: import_zod8.z.enum(["set", "remove", "clear"]).describe("set/remove a key, or clear all app storage."),
+        key: import_zod8.z.string().optional().describe("The key (required for set and remove)."),
+        value: import_zod8.z.string().optional().describe("The string value to store (required for set; JSON-encode objects)."),
+        deviceId: import_zod8.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        if (args.action === "clear") {
+          await sync.callAction(STORAGE_TOOL_ID, "clearAppStorage", {}, target);
+          return text7("Cleared all app storage (Buoy's own devtool keys preserved).");
+        }
+        if (!args.key) {
+          return fail8(`'${args.action}' needs a key.`);
+        }
+        if (args.action === "remove") {
+          await sync.callAction(STORAGE_TOOL_ID, "async.removeItem", { key: args.key }, target);
+          return text7(`Removed storage key "${args.key}".`);
+        }
+        if (args.value === void 0) {
+          return fail8("'set' needs a value (a string).");
+        }
+        await sync.callAction(STORAGE_TOOL_ID, "async.setItem", { key: args.key, value: args.value }, target);
+        return text7(`Set storage key "${args.key}".`);
+      } catch (e) {
+        return fail8(errMsg8(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/routes.ts
+var import_zod9 = require("zod");
+var ROUTES_TOOL_ID = "route-events";
+var text8 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail9 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg9 = (e) => e instanceof Error ? e.message : String(e);
+function flattenRoutes(routes, acc = []) {
+  for (const r of routes ?? []) {
+    if (r.path) acc.push(r.path);
+    if (r.children?.length) flattenRoutes(r.children, acc);
+  }
+  return acc;
+}
+function registerRoutesTools(server, sync) {
+  server.registerTool(
+    "get_routes",
+    {
+      description: "Read the app's CURRENT route + navigation stack (where the user is and how they got there). Compact by DEFAULT; pass includeSitemap:true to also list every route path the app defines (useful before navigate). Use for 'what screen am I on / what's the nav stack / what routes exist'. (For navigation history over time, use get_events with sources:['route'].)",
+      inputSchema: {
+        includeSitemap: import_zod9.z.boolean().optional().describe("Also list all defined route paths (can be long). Default false."),
+        deviceId: import_zod9.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const { payload } = await sync.getSnapshot(ROUTES_TOOL_ID, target);
+        const p = Array.isArray(payload) ? { events: payload } : payload ?? {};
+        const stack = Array.isArray(p.stack) ? p.stack : [];
+        const focused = stack.find((s) => s.isFocused) ?? stack[stack.length - 1];
+        const current = focused?.pathname ?? "(unknown)";
+        const parts = [`**Current route:** \`${current}\``];
+        if (stack.length) {
+          const stackLines = stack.map(
+            (s, i) => `${i + 1}. \`${s.pathname ?? s.name ?? "?"}\`${s.isFocused ? " \u2190 focused" : ""}`
+          );
+          parts.push(`
+**Navigation stack** (top last):
+${stackLines.join("\n")}`);
+        }
+        const allPaths = flattenRoutes(p.sitemap?.routes);
+        if (args.includeSitemap) {
+          const shown = allPaths.slice(0, 200);
+          parts.push(
+            `
+**Sitemap (${allPaths.length} routes${shown.length < allPaths.length ? `, showing ${shown.length}` : ""}):**
+${shown.map((r) => `- \`${r}\``).join("\n")}`
+          );
+        } else {
+          parts.push(`
+**Sitemap:** ${allPaths.length} routes _(pass includeSitemap:true to list them)_`);
+        }
+        parts.push("\n_Navigate with navigate({ path })._");
+        return text8(parts.join("\n"));
+      } catch (e) {
+        return fail9(errMsg9(e));
+      }
+    }
+  );
+  server.registerTool(
+    "navigate",
+    {
+      description: "Navigate the app to a route path (e.g. '/pokemon/25' or '/settings'). Use a concrete path \u2014 resolve any dynamic segments (like [id]) to real values first. See get_routes with includeSitemap:true for valid paths.",
+      inputSchema: {
+        path: import_zod9.z.string().describe("The concrete path to navigate to, e.g. '/pokemon/25'."),
+        deviceId: import_zod9.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        await sync.callAction(ROUTES_TOOL_ID, "navigate", { path: args.path }, target);
+        return text8(`Navigated to \`${args.path}\`.`);
+      } catch (e) {
+        return fail9(errMsg9(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/console.ts
+var import_zod10 = require("zod");
+var CONSOLE_TOOL_ID = "console";
+var text9 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail10 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg10 = (e) => e instanceof Error ? e.message : String(e);
+var SEVERITY = { verbose: 0, info: 1, warning: 2, error: 3 };
+var TAG = { verbose: "\xB7", info: "info", warning: "warn", error: "ERR" };
+function hhmmss(ts) {
+  const d = new Date(ts);
+  const p = (n, l = 2) => String(n).padStart(l, "0");
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${p(d.getMilliseconds(), 3)}`;
+}
+function registerConsoleTools(server, sync) {
+  server.registerTool(
+    "get_console",
+    {
+      description: "Read the app's captured console logs (console.log/warn/error/\u2026) as a compact tail \u2014 time \xB7 level \xB7 message. Token-cheap (uses each entry's pre-rendered message, not raw args). Filter by minimum level (e.g. level:'warning' for warnings+errors) or a message substring. Use for 'what's logging / any console errors'. For full args/stack of an entry, fall back to get_snapshot('console').",
+      inputSchema: {
+        level: import_zod10.z.enum(["verbose", "info", "warning", "error"]).optional().describe("Minimum level to include (severity threshold). e.g. 'warning' = warnings + errors. Default all."),
+        limit: import_zod10.z.number().optional().describe("Most-recent N entries. Default 50."),
+        pattern: import_zod10.z.string().optional().describe("Only entries whose message contains this substring (case-insensitive)."),
+        deviceId: import_zod10.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const { payload } = await sync.getSnapshot(CONSOLE_TOOL_ID, target);
+        const p = Array.isArray(payload) ? { entries: payload } : payload ?? {};
+        const all = Array.isArray(p.entries) ? p.entries : [];
+        const minSev = args.level ? SEVERITY[args.level] : 0;
+        const pattern = args.pattern?.toLowerCase();
+        const filtered = all.filter(
+          (e) => SEVERITY[e.level] >= minSev && (!pattern || (e.message ?? "").toLowerCase().includes(pattern))
+        );
+        const sorted = [...filtered].sort((a, b) => a.id - b.id);
+        const limit = typeof args.limit === "number" && args.limit > 0 ? args.limit : 50;
+        const shown = sorted.slice(-limit);
+        if (shown.length === 0) {
+          return text9(`No console entries${args.level ? ` at level \u2265 ${args.level}` : ""}${pattern ? ` matching "${args.pattern}"` : ""} (${all.length} total captured).`);
+        }
+        const lines = shown.map((e) => `${hhmmss(e.timestamp)} [${TAG[e.level] ?? e.level}] ${e.message}`);
+        const levelNote = args.level ? `, level \u2265 ${args.level}` : "";
+        const header = `**Console \u2014 ${all.length} entries (showing ${shown.length}${levelNote}):**`;
+        return text9(`${header}
+
+\`\`\`
+${lines.join("\n")}
+\`\`\`
+
+_Tail of recent logs. Use get_snapshot('console') for full args/stacks._`);
+      } catch (e) {
+        return fail10(errMsg10(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/screenshot.ts
+var import_zod11 = require("zod");
+
+// src/capture/simctl.ts
+var import_node_child_process = require("child_process");
+var import_node_util = require("util");
+var import_node_fs2 = require("fs");
+var import_node_os2 = __toESM(require("os"));
+var import_node_path2 = __toESM(require("path"));
+var import_node_crypto2 = require("crypto");
+var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
+var clamp2 = (n, lo, hi) => Math.min(Math.max(n, lo), hi);
+function humanizeSimctlError(err) {
+  const e = err;
+  if (e?.code === "ENOENT") {
+    return "Xcode command-line tools (xcrun) not found. Install Xcode to capture the iOS Simulator.";
+  }
+  const msg = String(e?.stderr || e?.message || err);
+  if (/No devices are booted|Unable to find device|current device/i.test(msg)) {
+    return "No booted iOS Simulator found. Boot the Simulator with your app running, then try again.";
+  }
+  return msg.trim() || "Failed to capture the iOS Simulator.";
+}
+function pngSize(buf) {
+  const SIG = [137, 80, 78, 71, 13, 10, 26, 10];
+  if (buf.length < 24 || !SIG.every((b, i) => buf[i] === b)) return null;
+  return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+}
+async function captureIosFramebuffer() {
+  if (process.platform !== "darwin") {
+    return {
+      ok: false,
+      error: "Screenshotting a component requires macOS with Xcode's iOS Simulator (uses `xcrun simctl`)."
+    };
+  }
+  const out = import_node_path2.default.join(import_node_os2.default.tmpdir(), `buoy-mcp-sim-${(0, import_node_crypto2.randomUUID)()}.png`);
+  try {
+    await execFileAsync("xcrun", ["simctl", "io", "booted", "screenshot", "--type=png", out], {
+      timeout: 15e3
+    });
+  } catch (err) {
+    return { ok: false, error: humanizeSimctlError(err) };
+  }
+  try {
+    const buf = await import_node_fs2.promises.readFile(out);
+    const size = pngSize(buf);
+    if (!size) return { ok: false, error: "Captured file wasn't a valid PNG." };
+    return { ok: true, srcPath: out, width: size.width, height: size.height };
+  } catch (err) {
+    return { ok: false, error: `Failed to read screenshot: ${err.message}` };
+  }
+}
+async function cropToBuffer(srcPath, full, region) {
+  const x = clamp2(Math.round(region.x), 0, Math.max(0, full.width - 1));
+  const y = clamp2(Math.round(region.y), 0, Math.max(0, full.height - 1));
+  const width = clamp2(Math.round(region.width), 1, full.width - x);
+  const height = clamp2(Math.round(region.height), 1, full.height - y);
+  const out = import_node_path2.default.join(import_node_os2.default.tmpdir(), `buoy-mcp-crop-${(0, import_node_crypto2.randomUUID)()}.png`);
+  try {
+    await execFileAsync(
+      "sips",
+      ["-c", String(height), String(width), "--cropOffset", String(y), String(x), srcPath, "--out", out],
+      { timeout: 1e4 }
+    );
+    const buf = await import_node_fs2.promises.readFile(out);
+    return { ok: true, buffer: buf, width, height };
+  } catch (err) {
+    const e = err;
+    return { ok: false, error: `Crop failed: ${e?.stderr || e?.message || err}` };
+  } finally {
+    await import_node_fs2.promises.unlink(out).catch(() => {
+    });
+    await import_node_fs2.promises.unlink(srcPath).catch(() => {
+    });
+  }
+}
+
+// src/tools/packs/screenshot.ts
+var TOOL_ID = "highlight-updates";
+var MARGIN_PT = 12;
+var CAPTURE_PADDING_PT = 6;
+var fail11 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+var errMsg11 = (e) => e instanceof Error ? e.message : String(e);
+function reasonMessage(res, query) {
+  switch (res.reason) {
+    case "no-renders":
+      return "No components are tracked yet. Navigate to the screen with the target component in the running app (it needs to render at least once), then retry.";
+    case "no-match":
+      return query ? `Nothing matched "${query}".` : "No query or nativeTag given \u2014 pass one, or a testID/name to search for.";
+    case "no-measurement":
+      return "Found the component but couldn't measure it \u2014 it may have just unmounted. Re-navigate to it and retry.";
+    default:
+      return res.reason ? `Locate failed: ${res.reason}` : "Couldn't locate that component.";
+  }
+}
+function candidatesText(candidates) {
+  if (!candidates || candidates.length === 0) return "";
+  const lines = candidates.map((c) => {
+    const id = c.testID || c.nativeID;
+    return `- ${c.componentName || c.viewType}${id ? ` (${id})` : ""} \u2014 nativeTag ${c.nativeTag}, rendered \xD7${c.renderCount}`;
+  });
+  return `
+
+Closest matches (retry with a more precise query, or pass nativeTag directly):
+${lines.join("\n")}`;
+}
+function registerScreenshotTools(server, sync) {
+  server.registerTool(
+    "screenshot_component",
+    {
+      description: "Take a tight, cropped screenshot of a single React Native component running in the iOS Simulator \u2014 no manual coordinates needed. Give a testID, nativeID, accessibilityLabel, or component name in `query` (or an exact `nativeTag` from a previous call's candidates) and it locates the live component on-device (scrolling it into view), then captures + crops the Simulator framebuffer to just that component. The component must have rendered at least once since the app opened for it to be trackable \u2014 if nothing matches, navigate to the screen that renders it and retry. iOS Simulator only, and the MCP server must be running on the same Mac as the booted Simulator (uses `xcrun simctl` + `sips`). Requires Buoy Pro.",
+      inputSchema: {
+        query: import_zod11.z.string().optional().describe('Fuzzy match against testID, nativeID, accessibilityLabel, component name, or view type \u2014 e.g. "submit-button".'),
+        nativeTag: import_zod11.z.number().optional().describe("An exact nativeTag (from a previous call's candidates) to skip fuzzy matching."),
+        scrollIntoView: import_zod11.z.boolean().optional().describe("Scroll the component into view before capturing, if it's off-screen. Default true."),
+        deviceId: import_zod11.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        await sync.callAction(TOOL_ID, "setSilentTracking", { enabled: true }, target).catch(() => {
+        });
+        const res = await sync.callAction(
+          TOOL_ID,
+          "locateComponent",
+          {
+            query: args.query,
+            nativeTag: args.nativeTag,
+            scrollIntoView: args.scrollIntoView ?? true,
+            margin: MARGIN_PT
+          },
+          target
+        );
+        if (!res.matched || !res.rect || !res.screen) {
+          return fail11(reasonMessage(res, args.query) + candidatesText(res.candidates));
+        }
+        const shot = await captureIosFramebuffer();
+        if (!shot.ok || !shot.srcPath || !shot.width || !shot.height) {
+          return fail11(shot.error ?? "Screenshot capture failed.");
+        }
+        const pxScale = shot.width / res.screen.width;
+        const r = res.rect;
+        const pad = CAPTURE_PADDING_PT;
+        const crop = await cropToBuffer(
+          shot.srcPath,
+          { width: shot.width, height: shot.height },
+          {
+            x: (r.x - pad) * pxScale,
+            y: (r.y - pad) * pxScale,
+            width: (r.width + pad * 2) * pxScale,
+            height: (r.height + pad * 2) * pxScale
+          }
+        );
+        if (!crop.ok || !crop.buffer) {
+          return fail11(crop.error ?? "Crop failed.");
+        }
+        const label = res.componentName || "component";
+        const idPart = res.testID ? ` (testID: "${res.testID}")` : "";
+        const warn = res.inView === false ? "\n\nNote: the component is partly off-screen even after scrolling, so the crop is clamped to the screen edge." : "";
+        const summary = `Captured "${label}"${idPart} \u2014 ${crop.width}\xD7${crop.height}px.${warn}`;
+        return {
+          content: [
+            { type: "image", data: crop.buffer.toString("base64"), mimeType: "image/png" },
+            { type: "text", text: summary }
+          ]
+        };
+      } catch (e) {
+        return fail11(errMsg11(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/interact.ts
+var import_zod12 = require("zod");
+var TOOL_ID2 = "highlight-updates";
+var text10 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail12 = (message) => ({
+  isError: true,
+  content: [{ type: "text", text: message }]
+});
+var errMsg12 = (e) => e instanceof Error ? e.message : String(e);
+function formatElement(e) {
+  let line = e.interactive ? "\u2022 " : "  ";
+  line += e.name;
+  const display = e.text ?? e.label;
+  if (display) line += ` "${display}"`;
+  if (e.role) line += ` <${e.role}>`;
+  if (e.control) line += ` {${e.control}${e.value !== void 0 ? `=${JSON.stringify(e.value)}` : ""}}`;
+  if (e.testID) line += ` [testID=${e.testID}]`;
+  if (e.tap) line += ` (tap: ${e.tap.x},${e.tap.y})`;
+  if (e.nativeTag != null) line += ` #${e.nativeTag}`;
+  return line;
+}
+function registerInteractTools(server, sync) {
+  server.registerTool(
+    "describe_screen",
+    {
+      description: "List the interactive / labeled elements currently on screen \u2014 the app's live accessibility-style tree walked from the React fiber tree. Each row shows the component name, visible text/label, role, testID, a normalized tap point (tap: x,y in 0\u20131), and its #nativeTag. Rows marked with \u2022 are tappable (have an onPress). Use this to see what's on screen and pick something to tap with tap_element \u2014 no screenshot needed. Re-run after navigating or when the screen changes, since positions move. Requires Buoy Pro.",
+      inputSchema: {
+        interactiveOnly: import_zod12.z.boolean().optional().describe("Only return tappable (onPress) elements. Default false (include labels/text for context)."),
+        deviceId: import_zod12.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const res = await sync.callAction(TOOL_ID2, "describeScreen", {}, target);
+        const all = res?.elements ?? [];
+        const elements = args.interactiveOnly ? all.filter((e) => e.interactive) : all;
+        if (elements.length === 0) {
+          return text10(
+            "No elements found on screen. If the app just navigated, wait a moment and retry; make sure highlight-updates is enabled in the app."
+          );
+        }
+        const header = `Screen ${res.screen.width}\xD7${res.screen.height} \u2014 ${elements.length} element${elements.length === 1 ? "" : "s"} (\u2022 = tappable). Tap with tap_element({ testID | query | nativeTag }).`;
+        return text10(`${header}
+
+${elements.map(formatElement).join("\n")}`);
+      } catch (e) {
+        return fail12(errMsg12(e));
+      }
+    }
+  );
+  server.registerTool(
+    "tap_element",
+    {
+      description: "Interact with an on-screen element by invoking its handler directly in JS (no screenshot, no coordinate math, works on real devices). Handles buttons (onPress), toggles/switches and sliders (onValueChange), and text inputs (onChangeText) \u2014 see each element's `control` in describe_screen. Identify the target with an exact `nativeTag` or `testID`, or a fuzzy `query`. For a toggle, pass `value:true/false` (omit to flip); for a slider, pass a numeric `value` (omit to jump to the far end); for a text input, pass `text`. If the element is off-screen it's scrolled into view first (scrollIntoView:false to skip). Call describe_screen first to see options + current values. Requires Buoy Pro.",
+      inputSchema: {
+        nativeTag: import_zod12.z.number().optional().describe("Exact nativeTag from describe_screen (most precise)."),
+        testID: import_zod12.z.string().optional().describe("Exact testID of the element."),
+        query: import_zod12.z.string().optional().describe('Fuzzy match against testID / label / visible text / component name \u2014 e.g. "Sign in".'),
+        value: import_zod12.z.union([import_zod12.z.number(), import_zod12.z.boolean()]).optional().describe("For a toggle: true/false (omit to flip). For a slider: the numeric value (omit to jump to the far end)."),
+        text: import_zod12.z.string().optional().describe("For a text input: the string to set via onChangeText."),
+        scrollIntoView: import_zod12.z.boolean().optional().describe("Scroll the target into view first if it's off-screen. Default true."),
+        deviceId: import_zod12.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        if (args.nativeTag == null && !args.testID && !args.query) {
+          return fail12("Provide one of: nativeTag, testID, or query (from describe_screen).");
+        }
+        const target = sync.requireProDevice(args.deviceId);
+        const res = await sync.callAction(
+          TOOL_ID2,
+          "tapElement",
+          {
+            nativeTag: args.nativeTag,
+            testID: args.testID,
+            query: args.query,
+            value: args.value,
+            text: args.text,
+            scrollIntoView: args.scrollIntoView
+          },
+          target
+        );
+        if (res?.tapped && res.matched) {
+          const m = res.matched;
+          const label = m.text ?? m.label ?? m.name;
+          const id = m.testID ? ` [testID=${m.testID}]` : m.nativeTag != null ? ` #${m.nativeTag}` : "";
+          const scrolledNote = res.scrolled ? " (scrolled into view)" : "";
+          const verb = m.via === "onValueChange" ? `Set "${label}"${id} \u2192 ${JSON.stringify(m.value)}` : m.via === "onChangeText" ? `Typed ${JSON.stringify(m.value)} into "${label}"${id}` : `Tapped "${label}"${id}${m.via === "onLongPress" ? " (via onLongPress)" : ""}`;
+          return text10(`${verb}${scrolledNote}.`);
+        }
+        let msg = res?.reason ?? "Tap failed.";
+        if (res?.candidates?.length) {
+          msg += "\n\nTappable candidates:\n" + res.candidates.map((c) => `- ${c.name}${c.text ? ` "${c.text}"` : ""}${c.testID ? ` [testID=${c.testID}]` : ""}${c.nativeTag != null ? ` #${c.nativeTag}` : ""}`).join("\n");
+        }
+        return fail12(msg);
+      } catch (e) {
+        return fail12(errMsg12(e));
+      }
+    }
+  );
+}
+
 // src/server.ts
 var SERVER_INSTRUCTIONS = `Buoy MCP \u2014 drive Buoy dev tools running in a React Native app from your editor.
 
 Buoy tools live inside the app and sync to a local broker; this server connects to that
 broker as a dashboard client. Start by calling \`list_devices\` to see which device(s) are
-connected and which tools (e.g. "perf-monitor", "network", "react-query") they expose, then:
+connected and which tools (e.g. "perf-monitor", "network", "react-query") they expose.
+
+To inspect what's HAPPENING at runtime \u2014 network requests, state changes (redux/zustand/jotai),
+react-query updates, storage writes, route changes, renders \u2014 use \`get_events\` with a \`sources\`
+filter (e.g. sources:["network"] to list HTTP requests). It's the universal, token-bounded
+activity reader across ALL tools and is compact by default \u2014 reach for it before reading source
+code, and prefer it over \`get_snapshot\` for any "what happened / show me the requests" question.
+
+Need to SEE a component (verify a UI change, check styling/layout)? Use \`screenshot_component\` with
+a testID/name \u2014 it locates the live component on-device and returns a cropped screenshot inline.
+iOS Simulator only, and only works when this MCP server runs on the same Mac as the booted Simulator.
+
+Need to DRIVE the UI (tap a button, follow a flow)? Use \`describe_screen\` to list the on-screen
+elements (accessibility-style tree with tap points + testIDs, no screenshot), then \`tap_element\`
+({ testID | query | nativeTag }) to tap one \u2014 it invokes the element's onPress directly in JS, so
+it's fast and works on physical devices too. Re-run \`describe_screen\` after the screen changes.
+
+For everything else:
 - \`list_tool_actions\` to see what a tool can do,
-- \`get_snapshot\` to read a tool's current state,
+- \`get_snapshot\` ONLY when you need a tool's full current state (returns raw, heavy payloads),
 - \`call_action\` to invoke any tool action generically.
 
 Higher-level tools (e.g. perf-monitor's \`run_benchmark_batch\`) wrap these for common workflows.
@@ -1165,18 +2167,109 @@ require the connected app to have an active Buoy Pro license. If they error with
 required", tell the user to upgrade to Buoy Pro in the app \u2014 don't try to work around it.`;
 function createMcpServer(sync) {
   const server = new import_mcp.McpServer(
-    { name: "buoy", version: "3.0.2" },
+    { name: "buoy", version: VERSION },
     { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
   );
   registerGenericTools(server, sync);
   registerPerfMonitorTools(server, sync);
+  registerEventsTools(server, sync);
+  registerReactQueryTools(server, sync);
+  registerZustandTools(server, sync);
+  registerJotaiTools(server, sync);
+  registerReduxTools(server, sync);
+  registerStorageTools(server, sync);
+  registerRoutesTools(server, sync);
+  registerConsoleTools(server, sync);
+  registerScreenshotTools(server, sync);
+  registerInteractTools(server, sync);
   return server;
 }
 var deviceIdField = {
-  deviceId: import_zod3.z.string().optional().describe(
+  deviceId: import_zod13.z.string().optional().describe(
     'Target device id (from list_devices). Omit to auto-select when exactly one device is connected. Use "All" to broadcast.'
   )
 };
+
+// src/init.ts
+var import_node_fs3 = __toESM(require("fs"));
+var import_node_path3 = __toESM(require("path"));
+function runInit(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const skillSrcDir = opts.skillSrcDir ?? import_node_path3.default.resolve(__dirname, "../skill");
+  const log = opts.log ?? ((m) => process.stdout.write(m + "\n"));
+  const entry = opts.cliPath ? { type: "stdio", command: "node", args: [opts.cliPath] } : { type: "stdio", command: "npx", args: ["-y", `${PACKAGE_NAME}@latest`] };
+  const done = [];
+  upsertMcpConfig(import_node_path3.default.join(cwd, ".mcp.json"), "mcpServers", entry, cwd, done);
+  if (import_node_fs3.default.existsSync(import_node_path3.default.join(cwd, ".cursor"))) {
+    upsertMcpConfig(import_node_path3.default.join(cwd, ".cursor", "mcp.json"), "mcpServers", entry, cwd, done);
+  }
+  if (import_node_fs3.default.existsSync(import_node_path3.default.join(cwd, ".vscode"))) {
+    upsertMcpConfig(import_node_path3.default.join(cwd, ".vscode", "mcp.json"), "servers", entry, cwd, done);
+  }
+  installSkills(skillSrcDir, cwd, done);
+  log("Buoy MCP installed:");
+  for (const line of done) log("  \u2022 " + line);
+  log("");
+  log("Next steps:");
+  log("  1. Restart your editor (or reconnect the MCP server) to load `buoy`.");
+  log("  2. Open your app with Buoy devtools running on a device or simulator.");
+  log('  3. Say "buoy optimize" to start a guided performance pass.');
+  if (!opts.cliPath) {
+    log("");
+    log(`This launches the server via \`npx -y ${PACKAGE_NAME}@latest\`, so it stays`);
+    log(`up to date automatically. To force-refresh, re-run \`npx -y ${PACKAGE_NAME}@latest init\`.`);
+  }
+}
+function upsertMcpConfig(file, key, entry, cwd, done) {
+  let json3 = {};
+  if (import_node_fs3.default.existsSync(file)) {
+    try {
+      json3 = JSON.parse(import_node_fs3.default.readFileSync(file, "utf8"));
+    } catch {
+      import_node_fs3.default.copyFileSync(file, file + ".bak");
+      done.push(`existing ${rel(file, cwd)} was invalid JSON \u2014 backed up to ${rel(file, cwd)}.bak`);
+      json3 = {};
+    }
+  } else {
+    import_node_fs3.default.mkdirSync(import_node_path3.default.dirname(file), { recursive: true });
+  }
+  const servers = json3[key] && typeof json3[key] === "object" ? json3[key] : {};
+  const existed = "buoy" in servers;
+  servers.buoy = entry;
+  json3[key] = servers;
+  import_node_fs3.default.writeFileSync(file, JSON.stringify(json3, null, 2) + "\n");
+  done.push(`${existed ? "updated" : "added"} \`buoy\` in ${rel(file, cwd)}`);
+}
+function installSkills(skillSrcDir, cwd, done) {
+  if (!import_node_fs3.default.existsSync(skillSrcDir)) {
+    done.push("\u26A0 no bundled skills found \u2014 skipped");
+    return;
+  }
+  const skills = import_node_fs3.default.readdirSync(skillSrcDir, { withFileTypes: true }).filter((e) => e.isDirectory() && import_node_fs3.default.existsSync(import_node_path3.default.join(skillSrcDir, e.name, "SKILL.md")));
+  if (skills.length === 0) {
+    done.push("\u26A0 no skills with a SKILL.md found \u2014 skipped");
+    return;
+  }
+  for (const skill of skills) {
+    const from = import_node_path3.default.join(skillSrcDir, skill.name);
+    const to = import_node_path3.default.join(cwd, ".claude", "skills", skill.name);
+    copyDir(from, to);
+    done.push(`installed the ${skill.name} skill \u2192 ${rel(import_node_path3.default.join(to, "SKILL.md"), cwd)}`);
+  }
+}
+function copyDir(from, to) {
+  import_node_fs3.default.mkdirSync(to, { recursive: true });
+  for (const entry of import_node_fs3.default.readdirSync(from, { withFileTypes: true })) {
+    const s = import_node_path3.default.join(from, entry.name);
+    const d = import_node_path3.default.join(to, entry.name);
+    if (entry.isDirectory()) copyDir(s, d);
+    else import_node_fs3.default.copyFileSync(s, d);
+  }
+}
+function rel(file, cwd) {
+  const r = import_node_path3.default.relative(cwd, file);
+  return r && !r.startsWith("..") ? r : file;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ALL_DEVICES,
@@ -1185,13 +2278,26 @@ var deviceIdField = {
   DASHBOARD_NAME,
   DEFAULT_ACTION_TIMEOUT_MS,
   DEFAULT_SNAPSHOT_TIMEOUT_MS,
+  PACKAGE_NAME,
   SyncClient,
+  VERSION,
   buildAutomationConfig,
   compareReportStats,
   createMcpServer,
   estimateBatchMs,
   formatRankingMarkdown,
+  getUpdateNotice,
   rankBatchFromIndex,
+  registerConsoleTools,
+  registerEventsTools,
   registerGenericTools,
-  registerPerfMonitorTools
+  registerJotaiTools,
+  registerPerfMonitorTools,
+  registerReactQueryTools,
+  registerReduxTools,
+  registerRoutesTools,
+  registerScreenshotTools,
+  registerStorageTools,
+  registerZustandTools,
+  runInit
 });