@buoy-gg/mcp 7.0.26 → 7.0.28

package/dist/cli.js

@@ -46,6 +46,33 @@ var DEVICE_RETENTION_MS = 15 * 6e4;
 var DASHBOARD_NAME = "Dashboard";
 var ALL_DEVICES = "All";
 
+// src/sync/actionTimeout.ts
+function isRecoveryAction(toolId, action) {
+  return toolId === "app" && (action === "ping" || action === "reloadApp");
+}
+function isUnresponsive(consecutiveTimeouts) {
+  return consecutiveTimeouts >= 2;
+}
+function actionTimeoutMs(input) {
+  if (isRecoveryAction(input.toolId, input.action)) {
+    return { timeoutMs: input.fullMs, usedFullBudget: false };
+  }
+  if (!isUnresponsive(input.consecutiveTimeouts)) {
+    return { timeoutMs: input.fullMs, usedFullBudget: false };
+  }
+  if (input.now - input.lastFullBudgetAt > input.recoveryProbeMs) {
+    return { timeoutMs: input.fullMs, usedFullBudget: true };
+  }
+  return { timeoutMs: input.shortMs, usedFullBudget: false };
+}
+function diagnoseCrashed(opts) {
+  if (opts.consecutiveTimeouts >= 2) return true;
+  if (opts.lastOkAt > 0 && opts.now - opts.lastOkAt > opts.unresponsiveAfterMs) {
+    return true;
+  }
+  return false;
+}
+
 // src/sync/SyncClient.ts
 var SyncClient = class {
   constructor(opts = {}) {
@@ -314,27 +341,34 @@ var SyncClient = class {
   noteTimeout(deviceId) {
     this.healthOf(deviceId).consecutiveTimeouts += 1;
   }
-  /** True once a device has missed a call and hasn't answered since. */
+  /** True once a device has missed TWO calls and hasn't answered since. */
   isUnresponsive(deviceId) {
-    return this.healthOf(deviceId).consecutiveTimeouts > 0;
+    return isUnresponsive(this.healthOf(deviceId).consecutiveTimeouts);
   }
   /**
    * Full timeout normally; a short one for a device already not answering.
    *
-   * With one escape hatch: every RECOVERY_PROBE_MS a flagged device gets the
-   * full budget again. Without it the flag is self-sustaining — a device whose
-   * work legitimately takes longer than the short budget (a big snapshot, a
-   * slow simulator) can never answer, so it can never clear the flag, and every
-   * later reply is a confident "most likely CRASHED" about a healthy app.
+   * A single missed call does not trigger the short budget — one slow
+   * `describeScreen` is not a crash. `app.ping` / `app.reloadApp` always get
+   * the full budget (they are the recovery path).
+   *
+   * Escape hatch: every RECOVERY_PROBE_MS a flagged device gets the full
+   * budget again so the short timeout cannot become self-sustaining.
    */
-  timeoutFor(deviceId) {
-    if (!this.isUnresponsive(deviceId)) return this.actionTimeoutMs;
+  timeoutFor(deviceId, toolId, action) {
     const h = this.healthOf(deviceId);
-    if (Date.now() - h.lastFullBudgetAt > RECOVERY_PROBE_MS) {
-      h.lastFullBudgetAt = Date.now();
-      return this.actionTimeoutMs;
-    }
-    return UNRESPONSIVE_ACTION_TIMEOUT_MS;
+    const { timeoutMs, usedFullBudget } = actionTimeoutMs({
+      consecutiveTimeouts: h.consecutiveTimeouts,
+      lastFullBudgetAt: h.lastFullBudgetAt,
+      now: Date.now(),
+      fullMs: this.actionTimeoutMs,
+      shortMs: UNRESPONSIVE_ACTION_TIMEOUT_MS,
+      recoveryProbeMs: RECOVERY_PROBE_MS,
+      toolId,
+      action
+    });
+    if (usedFullBudget) h.lastFullBudgetAt = Date.now();
+    return timeoutMs;
   }
   /**
    * Plain-language diagnosis for a device that isn't answering, including the
@@ -347,7 +381,12 @@ var SyncClient = class {
   unresponsiveNote(deviceId) {
     const h = this.healthOf(deviceId);
     const since = h.lastOkAt ? Math.round((Date.now() - h.lastOkAt) / 1e3) : null;
-    const crashed = h.consecutiveTimeouts >= 2 || h.lastOkAt === 0 || Date.now() - h.lastOkAt > UNRESPONSIVE_AFTER_MS;
+    const crashed = diagnoseCrashed({
+      consecutiveTimeouts: h.consecutiveTimeouts,
+      lastOkAt: h.lastOkAt,
+      now: Date.now(),
+      unresponsiveAfterMs: UNRESPONSIVE_AFTER_MS
+    });
     const lines = [
       `The app on "${deviceId}" is not responding (${h.consecutiveTimeouts} call${h.consecutiveTimeouts === 1 ? "" : "s"} unanswered${since != null ? `, last answered ${since}s ago` : ""}).`,
       crashed ? "It is most likely CRASHED \u2014 a fatal render error unmounts the React tree, and the dev tools live in that tree, so nothing on-device can answer until the app is reloaded." : "It may be busy, mid-reload, or crashing."
@@ -549,7 +588,7 @@ var SyncClient = class {
     const target = deviceId === ALL_DEVICES ? ALL_DEVICES : this.resolveDevice(deviceId);
     if (!this.socket) throw new Error("SyncClient is not connected");
     const requestId = (0, import_node_crypto.randomUUID)();
-    const timeoutMs = opts.timeoutMs ?? this.timeoutFor(target);
+    const timeoutMs = opts.timeoutMs ?? this.timeoutFor(target, toolId, action);
     const result = await new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pendingActions.delete(requestId);
@@ -612,7 +651,7 @@ var import_node_os = __toESM(require("os"));
 var import_node_path = __toESM(require("path"));
 
 // src/version.ts
-var VERSION = "7.0.26" ? "7.0.26" : "0.0.0-dev";
+var VERSION = "7.0.28" ? "7.0.28" : "0.0.0-dev";
 var PACKAGE_NAME = "@buoy-gg/mcp";
 
 // src/update/checkForUpdate.ts
@@ -1638,7 +1677,14 @@ function statusIcon(e) {
   return "\u2705";
 }
 function statusLabel(e) {
-  if (e.error) return `ERR ${e.error}`;
+  if (e.status !== void 0 && e.status > 0) return String(e.status);
+  if (e.error) {
+    const cleaned = e.error.replace(/^HTTP\s+\d+:\s*/i, "").trim();
+    if (!cleaned || cleaned === "undefined" || cleaned === "no error") {
+      return "ERR";
+    }
+    return `ERR ${e.error}`;
+  }
   if (e.status === void 0) return "pending";
   return String(e.status);
 }
@@ -2098,10 +2144,20 @@ A rule that never fires is usually one of: the master switch is off, the interce
 
 // src/tools/packs/reactQuery.ts
 var import_zod5 = require("zod");
-var RQ_TOOL_ID = "react-query";
+var RQ_TOOL_ID = "query";
+var RQ_TOOL_ID_LEGACY = "react-query";
 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);
+async function callQueryAction(sync, action, params, target) {
+  try {
+    return await sync.callAction(RQ_TOOL_ID, action, params, target);
+  } catch (e) {
+    const msg = errMsg5(e);
+    if (!/unknown tool/i.test(msg)) throw e;
+    return await sync.callAction(RQ_TOOL_ID_LEGACY, action, params, target);
+  }
+}
 var STATUS_ICON = {
   fresh: "\u{1F7E2}",
   stale: "\u{1F7E1}",
@@ -2134,8 +2190,8 @@ function registerReactQueryTools(server, sync) {
     async (args) => {
       try {
         const target = sync.requireProDevice(args.deviceId);
-        const res = await sync.callAction(
-          RQ_TOOL_ID,
+        const res = await callQueryAction(
+          sync,
           "listQueries",
           { includeData: args.includeData ?? false, staleOnly: args.staleOnly ?? false, limit: args.limit ?? 25 },
           target
@@ -2181,13 +2237,13 @@ ${lines.join("\n")}${note}`);
       try {
         const target = sync.requireProDevice(args.deviceId);
         if (args.action === "clear") {
-          await sync.callAction(RQ_TOOL_ID, "clearQueryCache", {}, target);
+          await callQueryAction(sync, "clearQueryCache", {}, target);
           return text4("Cleared the entire React Query cache.");
         }
         if (!args.queryHash) {
           return fail5(`'${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);
+        await callQueryAction(sync, args.action, { queryHash: args.queryHash }, target);
         return text4(`Ran ${args.action} on query \`${args.queryHash}\`.`);
       } catch (e) {
         return fail5(errMsg5(e));
@@ -2614,17 +2670,23 @@ ${shown.map((r) => `- \`${r}\``).join("\n")}`
   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.",
+      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. Pushes by default (back still works); pass replace:true to leave the current screen instead of stacking on top of it (e.g. resetting to '/').",
       inputSchema: {
         path: import_zod10.z.string().describe("The concrete path to navigate to, e.g. '/pokemon/25'."),
+        replace: import_zod10.z.boolean().optional().describe("Replace the current screen instead of pushing (use when resetting, e.g. to '/')."),
         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);
-        await sync.callAction(ROUTES_TOOL_ID, "navigate", { path: args.path }, target);
-        return text9(`Navigated to \`${args.path}\`.`);
+        await sync.callAction(
+          ROUTES_TOOL_ID,
+          "navigate",
+          { path: args.path, replace: args.replace === true },
+          target
+        );
+        return text9(`Navigated to \`${args.path}\`${args.replace ? " (replaced current screen)" : ""}.`);
       } catch (e) {
         return fail10(errMsg10(e));
       }
@@ -2924,6 +2986,40 @@ async function cropToBuffer(srcPath, full, region) {
   }
 }
 
+// src/tools/packs/screenshotLocate.ts
+function pickDescribeScreenMatch(elements, query, nativeTag) {
+  if (nativeTag != null) {
+    const exact = elements.find((e) => e.nativeTag === nativeTag);
+    if (exact) return exact;
+  }
+  const q = (query ?? "").trim().toLowerCase();
+  if (!q) return void 0;
+  let best;
+  for (const el of elements) {
+    const fields = [el.testID, el.label, el.text, el.name].filter(Boolean).map((s) => s.toLowerCase());
+    let score = 0;
+    for (const f of fields) {
+      if (f === q) score = Math.max(score, 100);
+      else if (f.startsWith(q)) score = Math.max(score, 50);
+      else if (f.includes(q)) score = Math.max(score, 25);
+    }
+    const tap = el.tap;
+    if (tap && tap.x >= 0 && tap.x <= 1 && tap.y >= 0 && tap.y <= 1) score += 20;
+    else if (tap) score -= 40;
+    if (score <= 0) continue;
+    if (!best || score > best.score) best = { el, score };
+  }
+  return best?.el;
+}
+function frameToRect(frame, screen) {
+  return {
+    x: frame.x * screen.width,
+    y: frame.y * screen.height,
+    width: frame.width * screen.width,
+    height: frame.height * screen.height
+  };
+}
+
 // src/tools/packs/screenshot.ts
 var TOOL_ID = "highlight-updates";
 var MARGIN_PT = 12;
@@ -2933,7 +3029,7 @@ var errMsg13 = (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.";
+      return "No components matched via highlight tracking or the live fiber walk. Pass a testID / name from describe_screen, 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":
@@ -2957,7 +3053,7 @@ 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.",
+      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. If highlight tracking hasn't seen a render yet, it falls back to a live fiber walk (same as describe_screen). iOS Simulator only, and the MCP server must run on the same Mac as the booted Simulator. Requires Buoy Pro.",
       inputSchema: {
         query: import_zod13.z.string().optional().describe('Fuzzy match against testID, nativeID, accessibilityLabel, component name, or view type \u2014 e.g. "submit-button".'),
         nativeTag: import_zod13.z.number().optional().describe("An exact nativeTag (from a previous call's candidates) to skip fuzzy matching."),
@@ -2981,15 +3077,37 @@ function registerScreenshotTools(server, sync) {
           },
           target
         );
-        if (!res.matched || !res.rect || !res.screen) {
-          return fail13(reasonMessage(res, args.query) + candidatesText(res.candidates));
+        let located = res;
+        if (!located.matched && (located.reason === "no-renders" || located.reason === "no-match")) {
+          const screen = await sync.callAction(TOOL_ID, "describeScreen", {}, target).catch(() => null);
+          const match = screen?.elements ? pickDescribeScreenMatch(screen.elements, args.query, args.nativeTag) : void 0;
+          if (match?.frame && screen?.screen) {
+            located = {
+              matched: true,
+              live: true,
+              rect: frameToRect(match.frame, screen.screen),
+              screen: screen.screen,
+              nativeTag: match.nativeTag ?? void 0,
+              componentName: match.name,
+              testID: match.testID
+            };
+          } else if (located.reason === "no-renders") {
+            located = {
+              matched: false,
+              reason: "no-match",
+              candidates: located.candidates
+            };
+          }
+        }
+        if (!located.matched || !located.rect || !located.screen) {
+          return fail13(reasonMessage(located, args.query) + candidatesText(located.candidates));
         }
         const shot = await captureIosFramebuffer();
         if (!shot.ok || !shot.srcPath || !shot.width || !shot.height) {
           return fail13(shot.error ?? "Screenshot capture failed.");
         }
-        const pxScale = shot.width / res.screen.width;
-        const r = res.rect;
+        const pxScale = shot.width / located.screen.width;
+        const r = located.rect;
         const pad = CAPTURE_PADDING_PT;
         const crop = await cropToBuffer(
           shot.srcPath,
@@ -3004,9 +3122,9 @@ function registerScreenshotTools(server, sync) {
         if (!crop.ok || !crop.buffer) {
           return fail13(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 label = located.componentName || "component";
+        const idPart = located.testID ? ` (testID: "${located.testID}")` : "";
+        const warn = located.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: [
@@ -3570,6 +3688,19 @@ ${JSON.stringify(slim)}
 
 // src/tools/packs/assets.ts
 var import_zod17 = require("zod");
+
+// src/tools/packs/assetsGraphNote.ts
+function graphUnavailableNote(ss) {
+  if (ss.graphSupported && ss.graphCount != null) return null;
+  const err = (ss.graphError ?? "").trim();
+  const looksLikeDev = ss.dev === true || !!err;
+  if (looksLikeDev) {
+    return err ? `\u26A0 Metro bundle graph unavailable (${err}) \u2014 showing runtime-registered assets only; never-loaded detection unavailable.` : "\u26A0 Metro bundle graph unavailable \u2014 showing runtime-registered assets only; never-loaded detection unavailable.";
+  }
+  return "\u26A0 No Metro bundle graph (release build, or graph fetch failed) \u2014 showing runtime-registered assets only; never-loaded detection unavailable.";
+}
+
+// src/tools/packs/assets.ts
 var ASSETS_TOOL_ID = "assets";
 var text15 = (s) => ({ content: [{ type: "text", text: s }] });
 var fail17 = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
@@ -3612,11 +3743,8 @@ function formatListMarkdown2(list, limit) {
   if (ss.fontFamilies.length > 0) {
     lines.push(`Loaded font families: ${ss.fontFamilies.join(", ")}`);
   }
-  if (!ss.graphSupported || ss.graphCount == null) {
-    lines.push(
-      "\u26A0 No Metro bundle graph (release build or graph fetch failed) \u2014 showing runtime-registered assets only; never-loaded detection unavailable." + (ss.graphError ? ` (${ss.graphError})` : "")
-    );
-  }
+  const graphNote = graphUnavailableNote(ss);
+  if (graphNote) lines.push(graphNote);
   if (ss.measuring) lines.push("\u26A0 Size measurement in progress \u2014 byte totals are partial; re-run get_assets shortly.");
   const ins = list.insights;
   const chips = [];
@@ -3905,16 +4033,14 @@ function registerReloadTools(server, sync) {
         const previousRealm = args.wait === false ? null : await ping(sync, target, PROBE_TIMEOUT_MS);
         let ack = null;
         let recovered = false;
-        try {
-          ack = await sync.callAction(
-            APP_TOOL_ID,
-            RELOAD_ACTION,
-            { strategy: args.strategy ?? "auto" },
-            target
-          );
-        } catch (inAppError) {
+        const tryDevServer = async (inAppError) => {
           const origin = sync.devServerOrigin(target);
-          if (!origin) throw inAppError;
+          if (!origin) {
+            if (inAppError) throw inAppError;
+            throw new Error(
+              "The app is not answering and no dev-server origin is known (it was never learned from a successful ping). Reload the app by hand."
+            );
+          }
           const res = await reloadViaDevServer(origin);
           if (!res.ok) {
             throw new Error(
@@ -3922,6 +4048,20 @@ function registerReloadTools(server, sync) {
             );
           }
           recovered = true;
+        };
+        if (sync.isUnresponsive(target) && sync.devServerOrigin(target)) {
+          await tryDevServer();
+        } else {
+          try {
+            ack = await sync.callAction(
+              APP_TOOL_ID,
+              RELOAD_ACTION,
+              { strategy: args.strategy ?? "auto" },
+              target
+            );
+          } catch (inAppError) {
+            await tryDevServer(inAppError);
+          }
         }
         const via = recovered ? ` via the dev server (the app was unresponsive \u2014 its own reload could not be reached)` : ack?.strategy ? ` via ${ack.strategy}` : "";
         if (args.wait === false) {
@@ -4931,9 +5071,8 @@ function runInit(opts = {}) {
   const entry = resolveEntry(opts, log);
   const done = [];
   upsertMcpConfig(import_node_path4.default.join(cwd, ".mcp.json"), "mcpServers", entry, cwd, done);
-  if (import_node_fs4.default.existsSync(import_node_path4.default.join(cwd, ".cursor"))) {
-    upsertMcpConfig(import_node_path4.default.join(cwd, ".cursor", "mcp.json"), "mcpServers", entry, cwd, done);
-  }
+  import_node_fs4.default.mkdirSync(import_node_path4.default.join(cwd, ".cursor"), { recursive: true });
+  upsertMcpConfig(import_node_path4.default.join(cwd, ".cursor", "mcp.json"), "mcpServers", entry, cwd, done);
   if (import_node_fs4.default.existsSync(import_node_path4.default.join(cwd, ".vscode"))) {
     upsertMcpConfig(import_node_path4.default.join(cwd, ".vscode", "mcp.json"), "servers", entry, cwd, done);
   }

package/dist/cli.mjs

@@ -3,7 +3,7 @@ import {
   SyncClient,
   createMcpServer,
   runInit
-} from "./chunk-NPMUQLCZ.mjs";
+} from "./chunk-SFG6ZYH6.mjs";
 
 // src/cli.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/index.d.mts

@@ -127,16 +127,17 @@ declare class SyncClient {
      * first miss we stop paying the full timeout on every subsequent call.
      */
     private noteTimeout;
-    /** True once a device has missed a call and hasn't answered since. */
+    /** True once a device has missed TWO calls and hasn't answered since. */
     isUnresponsive(deviceId: string): boolean;
     /**
      * Full timeout normally; a short one for a device already not answering.
      *
-     * With one escape hatch: every RECOVERY_PROBE_MS a flagged device gets the
-     * full budget again. Without it the flag is self-sustaining — a device whose
-     * work legitimately takes longer than the short budget (a big snapshot, a
-     * slow simulator) can never answer, so it can never clear the flag, and every
-     * later reply is a confident "most likely CRASHED" about a healthy app.
+     * A single missed call does not trigger the short budget — one slow
+     * `describeScreen` is not a crash. `app.ping` / `app.reloadApp` always get
+     * the full budget (they are the recovery path).
+     *
+     * Escape hatch: every RECOVERY_PROBE_MS a flagged device gets the full
+     * budget again so the short timeout cannot become self-sustaining.
      */
     private timeoutFor;
     /**
@@ -244,8 +245,9 @@ declare function createMcpServer(sync: SyncClient): McpServer;
  * project, so a user doesn't have to hand-edit any config.
  *
  * - Registers the `buoy` server in the editor MCP config(s): `.mcp.json`
- *   (Claude Code, always), and `.cursor/mcp.json` / `.vscode/mcp.json` when
- *   those editor folders already exist.
+ *   (Claude Code, always), `.cursor/mcp.json` (always — Cursor is a first-class
+ *   client; we create `.cursor/` if needed), and `.vscode/mcp.json` when
+ *   `.vscode/` already exists.
  * - Copies the `buoy-optimize` skill into `.claude/skills/`.
  *
  * Idempotent + non-destructive: merges into existing configs (never clobbers

package/dist/index.d.ts

@@ -127,16 +127,17 @@ declare class SyncClient {
      * first miss we stop paying the full timeout on every subsequent call.
      */
     private noteTimeout;
-    /** True once a device has missed a call and hasn't answered since. */
+    /** True once a device has missed TWO calls and hasn't answered since. */
     isUnresponsive(deviceId: string): boolean;
     /**
      * Full timeout normally; a short one for a device already not answering.
      *
-     * With one escape hatch: every RECOVERY_PROBE_MS a flagged device gets the
-     * full budget again. Without it the flag is self-sustaining — a device whose
-     * work legitimately takes longer than the short budget (a big snapshot, a
-     * slow simulator) can never answer, so it can never clear the flag, and every
-     * later reply is a confident "most likely CRASHED" about a healthy app.
+     * A single missed call does not trigger the short budget — one slow
+     * `describeScreen` is not a crash. `app.ping` / `app.reloadApp` always get
+     * the full budget (they are the recovery path).
+     *
+     * Escape hatch: every RECOVERY_PROBE_MS a flagged device gets the full
+     * budget again so the short timeout cannot become self-sustaining.
      */
     private timeoutFor;
     /**
@@ -244,8 +245,9 @@ declare function createMcpServer(sync: SyncClient): McpServer;
  * project, so a user doesn't have to hand-edit any config.
  *
  * - Registers the `buoy` server in the editor MCP config(s): `.mcp.json`
- *   (Claude Code, always), and `.cursor/mcp.json` / `.vscode/mcp.json` when
- *   those editor folders already exist.
+ *   (Claude Code, always), `.cursor/mcp.json` (always — Cursor is a first-class
+ *   client; we create `.cursor/` if needed), and `.vscode/mcp.json` when
+ *   `.vscode/` already exists.
  * - Copies the `buoy-optimize` skill into `.claude/skills/`.
  *
  * Idempotent + non-destructive: merges into existing configs (never clobbers