@buoy-gg/mcp 7.0.3 → 7.0.4

package/README.md

@@ -18,6 +18,20 @@ One command, non-destructive:
 
 The config it writes launches the server via `npx -y @buoy-gg/mcp@latest`, so every editor restart re-resolves the newest published version — you never get pinned to a stale copy. Restart your editor, open your app with Buoy running, and start with `list_devices`.
 
+### Corporate / private npm registries
+
+If your machine's `.npmrc` points npm at a private registry that isn't reachable (a common setup on work laptops, e.g. off-VPN), `npx @latest` would hang trying to download the package on every editor launch — so `init` probes that registry first and, when it's unreachable, automatically installs a **pinned local copy** (from public npm) and writes a `node <path>` config instead. That takes the network off the startup path entirely.
+
+You can also force it:
+
+```bash
+npx -y @buoy-gg/mcp@latest init --local                 # always install locally, no network on startup
+npx -y @buoy-gg/mcp@latest init --npx                    # always use the auto-updating npx entry
+npx -y @buoy-gg/mcp@latest init --registry <url>         # registry the local install pulls from
+```
+
+To update a local install later, just re-run `init`.
+
 ## What your agent can do
 
 **Read the runtime**

package/dist/{chunk-MGZN6MJE.mjs → chunk-EC6YNLYA.mjs}

@@ -296,7 +296,7 @@ async function waitForBroker(url, attempts = 20) {
 var delay = (ms) => new Promise((r) => setTimeout(r, ms));
 
 // src/version.ts
-var VERSION = "7.0.3" ? "7.0.3" : "0.0.0-dev";
+var VERSION = "7.0.4" ? "7.0.4" : "0.0.0-dev";
 var PACKAGE_NAME = "@buoy-gg/mcp";
 
 // src/update/checkForUpdate.ts
@@ -2615,13 +2615,17 @@ var deviceIdField = {
 };
 
 // src/init.ts
+import { spawnSync } from "child_process";
 import fs3 from "fs";
+import os3 from "os";
 import path3 from "path";
+var PUBLIC_REGISTRY = "https://registry.npmjs.org";
+var PROBE_TIMEOUT_MS = 3e3;
 function runInit(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const skillSrcDir = opts.skillSrcDir ?? path3.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 entry = resolveEntry(opts, log);
   const done = [];
   upsertMcpConfig(path3.join(cwd, ".mcp.json"), "mcpServers", entry, cwd, done);
   if (fs3.existsSync(path3.join(cwd, ".cursor"))) {
@@ -2638,12 +2642,125 @@ function runInit(opts = {}) {
   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) {
+  if (entry.command === "npx") {
     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\`.`);
+  } else if (!opts.cliPath) {
+    log("");
+    log(`This uses a pinned local install (no network on startup). To update it later,`);
+    log(`re-run init (\`node ${entry.args[0]?.replace(/dist[/\\]cli\.js$/, "") ?? ""}...\` \u2014 or reinstall).`);
+  }
+}
+function resolveEntry(opts, log) {
+  if (opts.cliPath) {
+    return { type: "stdio", command: "node", args: [opts.cliPath] };
+  }
+  const mode = opts.mode ?? "auto";
+  if (mode === "npx") {
+    return npxEntry();
+  }
+  if (mode === "local") {
+    return localEntry(opts, log);
+  }
+  const probe = probeRegistry();
+  if (probe.reachable) {
+    return npxEntry();
+  }
+  log(
+    `\u26A0 npm registry ${probe.registry ? `(${probe.registry}) ` : ""}looks unreachable \u2014 \`npx @latest\` would hang your editor at startup. Falling back to a pinned local install.`
+  );
+  return localEntry(opts, log);
+}
+function npxEntry() {
+  return { type: "stdio", command: "npx", args: ["-y", `${PACKAGE_NAME}@latest`] };
+}
+function localEntry(opts, log) {
+  const installDir = opts.installDir ?? process.env.BUOY_MCP_HOME ?? path3.join(os3.homedir(), ".buoy-mcp");
+  const registry = opts.registry ?? PUBLIC_REGISTRY;
+  const cliPath = installLocalCopy(installDir, registry, log);
+  if (cliPath) {
+    return { type: "stdio", command: "node", args: [cliPath] };
   }
+  log("\u26A0 local install failed \u2014 writing the npx entry instead (see the error above).");
+  return npxEntry();
+}
+function installLocalCopy(installDir, registry, log) {
+  const spec = `${PACKAGE_NAME}@${VERSION === "0.0.0-dev" ? "latest" : VERSION}`;
+  fs3.mkdirSync(installDir, { recursive: true });
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  log(`Installing ${spec} into ${installDir} from ${registry} \u2026`);
+  const res = spawnSync(
+    npm,
+    [
+      "install",
+      spec,
+      "--prefix",
+      installDir,
+      "--registry",
+      registry,
+      `--@buoy-gg:registry=${registry}`,
+      "--no-audit",
+      "--no-fund",
+      "--loglevel=error"
+    ],
+    { stdio: ["ignore", "ignore", "inherit"], encoding: "utf8" }
+  );
+  if (res.status !== 0) {
+    log(`\u26A0 npm install exited with code ${res.status ?? "?"}${res.error ? ` (${res.error.message})` : ""}.`);
+    return null;
+  }
+  const cliPath = path3.join(installDir, "node_modules", PACKAGE_NAME, "dist", "cli.js");
+  if (!fs3.existsSync(cliPath)) {
+    log(`\u26A0 install finished but ${cliPath} is missing.`);
+    return null;
+  }
+  return cliPath;
 }
+function probeRegistry() {
+  const registry = effectiveRegistry();
+  if (!registry) return { reachable: false, registry: null };
+  if (/^https?:\/\/registry\.npmjs\.org\/?$/i.test(registry)) {
+    return { reachable: true, registry };
+  }
+  return { reachable: hostReachable(registry), registry };
+}
+function effectiveRegistry() {
+  const scoped = npmConfigGet("@buoy-gg:registry");
+  if (scoped) return scoped;
+  const global = npmConfigGet("registry");
+  return global ?? PUBLIC_REGISTRY;
+}
+function npmConfigGet(key) {
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  const res = spawnSync(npm, ["config", "get", key], { encoding: "utf8", timeout: PROBE_TIMEOUT_MS });
+  if (res.status !== 0 || typeof res.stdout !== "string") return null;
+  const val = res.stdout.trim();
+  if (!val || val === "undefined" || val === "null") return null;
+  return val;
+}
+function hostReachable(registry) {
+  const done = spawnSync(
+    process.execPath,
+    ["-e", REACHABILITY_PROBE, registry, String(PROBE_TIMEOUT_MS)],
+    { encoding: "utf8", timeout: PROBE_TIMEOUT_MS + 2e3 }
+  );
+  return done.status === 0;
+}
+var REACHABILITY_PROBE = `
+const url = process.argv[1];
+const ms = Number(process.argv[2]) || 3000;
+const c = new AbortController();
+const t = setTimeout(() => c.abort(), ms);
+fetch(url, { method: 'HEAD', signal: c.signal })
+  .then(() => { clearTimeout(t); process.exit(0); })
+  .catch(() => {
+    // A HEAD may be rejected while the host is up; a bare TCP-level failure is
+    // what we care about. fetch throwing a TypeError = network unreachable.
+    clearTimeout(t);
+    process.exit(1);
+  });
+`;
 function upsertMcpConfig(file, key, entry, cwd, done) {
   let json3 = {};
   if (fs3.existsSync(file)) {

package/dist/cli.js

@@ -336,7 +336,7 @@ var import_node_os = __toESM(require("os"));
 var import_node_path = __toESM(require("path"));
 
 // src/version.ts
-var VERSION = "7.0.3" ? "7.0.3" : "0.0.0-dev";
+var VERSION = "7.0.4" ? "7.0.4" : "0.0.0-dev";
 var PACKAGE_NAME = "@buoy-gg/mcp";
 
 // src/update/checkForUpdate.ts
@@ -2647,13 +2647,17 @@ var deviceIdField = {
 };
 
 // src/init.ts
+var import_node_child_process2 = require("child_process");
 var import_node_fs3 = __toESM(require("fs"));
+var import_node_os3 = __toESM(require("os"));
 var import_node_path3 = __toESM(require("path"));
+var PUBLIC_REGISTRY = "https://registry.npmjs.org";
+var PROBE_TIMEOUT_MS = 3e3;
 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 entry = resolveEntry(opts, log);
   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"))) {
@@ -2670,12 +2674,125 @@ function runInit(opts = {}) {
   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) {
+  if (entry.command === "npx") {
     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\`.`);
+  } else if (!opts.cliPath) {
+    log("");
+    log(`This uses a pinned local install (no network on startup). To update it later,`);
+    log(`re-run init (\`node ${entry.args[0]?.replace(/dist[/\\]cli\.js$/, "") ?? ""}...\` \u2014 or reinstall).`);
+  }
+}
+function resolveEntry(opts, log) {
+  if (opts.cliPath) {
+    return { type: "stdio", command: "node", args: [opts.cliPath] };
+  }
+  const mode = opts.mode ?? "auto";
+  if (mode === "npx") {
+    return npxEntry();
+  }
+  if (mode === "local") {
+    return localEntry(opts, log);
   }
+  const probe = probeRegistry();
+  if (probe.reachable) {
+    return npxEntry();
+  }
+  log(
+    `\u26A0 npm registry ${probe.registry ? `(${probe.registry}) ` : ""}looks unreachable \u2014 \`npx @latest\` would hang your editor at startup. Falling back to a pinned local install.`
+  );
+  return localEntry(opts, log);
+}
+function npxEntry() {
+  return { type: "stdio", command: "npx", args: ["-y", `${PACKAGE_NAME}@latest`] };
 }
+function localEntry(opts, log) {
+  const installDir = opts.installDir ?? process.env.BUOY_MCP_HOME ?? import_node_path3.default.join(import_node_os3.default.homedir(), ".buoy-mcp");
+  const registry = opts.registry ?? PUBLIC_REGISTRY;
+  const cliPath = installLocalCopy(installDir, registry, log);
+  if (cliPath) {
+    return { type: "stdio", command: "node", args: [cliPath] };
+  }
+  log("\u26A0 local install failed \u2014 writing the npx entry instead (see the error above).");
+  return npxEntry();
+}
+function installLocalCopy(installDir, registry, log) {
+  const spec = `${PACKAGE_NAME}@${VERSION === "0.0.0-dev" ? "latest" : VERSION}`;
+  import_node_fs3.default.mkdirSync(installDir, { recursive: true });
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  log(`Installing ${spec} into ${installDir} from ${registry} \u2026`);
+  const res = (0, import_node_child_process2.spawnSync)(
+    npm,
+    [
+      "install",
+      spec,
+      "--prefix",
+      installDir,
+      "--registry",
+      registry,
+      `--@buoy-gg:registry=${registry}`,
+      "--no-audit",
+      "--no-fund",
+      "--loglevel=error"
+    ],
+    { stdio: ["ignore", "ignore", "inherit"], encoding: "utf8" }
+  );
+  if (res.status !== 0) {
+    log(`\u26A0 npm install exited with code ${res.status ?? "?"}${res.error ? ` (${res.error.message})` : ""}.`);
+    return null;
+  }
+  const cliPath = import_node_path3.default.join(installDir, "node_modules", PACKAGE_NAME, "dist", "cli.js");
+  if (!import_node_fs3.default.existsSync(cliPath)) {
+    log(`\u26A0 install finished but ${cliPath} is missing.`);
+    return null;
+  }
+  return cliPath;
+}
+function probeRegistry() {
+  const registry = effectiveRegistry();
+  if (!registry) return { reachable: false, registry: null };
+  if (/^https?:\/\/registry\.npmjs\.org\/?$/i.test(registry)) {
+    return { reachable: true, registry };
+  }
+  return { reachable: hostReachable(registry), registry };
+}
+function effectiveRegistry() {
+  const scoped = npmConfigGet("@buoy-gg:registry");
+  if (scoped) return scoped;
+  const global = npmConfigGet("registry");
+  return global ?? PUBLIC_REGISTRY;
+}
+function npmConfigGet(key) {
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  const res = (0, import_node_child_process2.spawnSync)(npm, ["config", "get", key], { encoding: "utf8", timeout: PROBE_TIMEOUT_MS });
+  if (res.status !== 0 || typeof res.stdout !== "string") return null;
+  const val = res.stdout.trim();
+  if (!val || val === "undefined" || val === "null") return null;
+  return val;
+}
+function hostReachable(registry) {
+  const done = (0, import_node_child_process2.spawnSync)(
+    process.execPath,
+    ["-e", REACHABILITY_PROBE, registry, String(PROBE_TIMEOUT_MS)],
+    { encoding: "utf8", timeout: PROBE_TIMEOUT_MS + 2e3 }
+  );
+  return done.status === 0;
+}
+var REACHABILITY_PROBE = `
+const url = process.argv[1];
+const ms = Number(process.argv[2]) || 3000;
+const c = new AbortController();
+const t = setTimeout(() => c.abort(), ms);
+fetch(url, { method: 'HEAD', signal: c.signal })
+  .then(() => { clearTimeout(t); process.exit(0); })
+  .catch(() => {
+    // A HEAD may be rejected while the host is up; a bare TCP-level failure is
+    // what we care about. fetch throwing a TypeError = network unreachable.
+    clearTimeout(t);
+    process.exit(1);
+  });
+`;
 function upsertMcpConfig(file, key, entry, cwd, done) {
   let json3 = {};
   if (import_node_fs3.default.existsSync(file)) {
@@ -2762,7 +2879,13 @@ async function main() {
 }
 if (process.argv[2] === "init") {
   try {
-    runInit();
+    const args = process.argv.slice(3);
+    let mode = "auto";
+    if (args.includes("--local")) mode = "local";
+    else if (args.includes("--npx")) mode = "npx";
+    const ri = args.indexOf("--registry");
+    const registry = ri !== -1 ? args[ri + 1] : void 0;
+    runInit({ mode, registry });
     process.exit(0);
   } catch (err) {
     process.stderr.write(`[buoy-mcp] init failed: ${err?.message ?? err}

package/dist/cli.mjs

@@ -3,7 +3,7 @@ import {
   SyncClient,
   createMcpServer,
   runInit
-} from "./chunk-MGZN6MJE.mjs";
+} from "./chunk-EC6YNLYA.mjs";
 
 // src/cli.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -41,7 +41,13 @@ async function main() {
 }
 if (process.argv[2] === "init") {
   try {
-    runInit();
+    const args = process.argv.slice(3);
+    let mode = "auto";
+    if (args.includes("--local")) mode = "local";
+    else if (args.includes("--npx")) mode = "npx";
+    const ri = args.indexOf("--registry");
+    const registry = ri !== -1 ? args[ri + 1] : void 0;
+    runInit({ mode, registry });
     process.exit(0);
   } catch (err) {
     process.stderr.write(`[buoy-mcp] init failed: ${err?.message ?? err}

package/dist/index.d.mts

@@ -132,20 +132,61 @@ declare function createMcpServer(sync: SyncClient): McpServer;
  * Idempotent + non-destructive: merges into existing configs (never clobbers
  * other servers), and re-running just refreshes the buoy entry + skill.
  *
+ * ## How the server gets launched (and why corporate registries broke it)
+ *
  * By default the written config launches the server via
  * `npx -y @buoy-gg/mcp@latest`, so every editor restart re-resolves the newest
- * published version — users can't get pinned to a stale local copy. (Passing an
- * explicit `cliPath` writes a `node <path>` entry instead, for local dev/testing
- * against a working build.)
+ * published version — users can't get pinned to a stale local copy.
+ *
+ * That default fails hard on machines whose `.npmrc` routes npm at an
+ * unreachable private registry (e.g. a corporate `@buoy-gg:registry=` or a
+ * global `registry=` pointing at an internal host that doesn't resolve off-VPN).
+ * There, `npx @latest` blocks trying to download the package from a host that
+ * never answers, the editor's MCP startup times out (~30s), and the server
+ * silently never comes up — invisible to the user.
+ *
+ * So `init` now:
+ *   1. Probes the npm registry that WOULD serve `@buoy-gg/mcp`. If it's
+ *      unreachable, it falls back to a **local install** automatically.
+ *   2. Local mode installs a pinned copy into a stable dir (`~/.buoy-mcp`) from
+ *      the public npm registry (bypassing the broken `.npmrc`) and writes a
+ *      `node <path>` config — taking the network off the editor-startup path
+ *      entirely.
+ *   3. `--local` / `--npx` force a mode; `--registry <url>` overrides which
+ *      registry the local install pulls from.
+ *   4. A `cliPath` (local-dev escape hatch) still writes a `node <path>` entry
+ *      pointed at a working build, no publish needed.
  */
+type InitMode = "auto" | "npx" | "local";
 interface InitOptions {
     /** Project root to install into. @default process.cwd() */
     cwd?: string;
     /**
      * Absolute path to a built cli.js. When set, the config launches that file
-     * via `node` instead of `npx @latest` — for local development only.
+     * via `node` instead of `npx @latest` — for local development only. Takes
+     * precedence over `mode`.
      */
     cliPath?: string;
+    /**
+     * Launch strategy for the written config:
+     *   - `"auto"` (default): npx `@latest`, but fall back to a local install if
+     *     the npm registry for `@buoy-gg/mcp` is unreachable.
+     *   - `"npx"`: always write the `npx -y @latest` entry (skip the probe).
+     *   - `"local"`: always install a pinned copy to a stable dir and point the
+     *     config at it (no network on editor startup).
+     * @default "auto"
+     */
+    mode?: InitMode;
+    /**
+     * Registry to pull the local install from. @default the public npm registry.
+     * Only used for `local` (or auto-fallback-to-local) installs.
+     */
+    registry?: string;
+    /**
+     * Stable dir the local install lives in.
+     * @default `$BUOY_MCP_HOME` or `~/.buoy-mcp`.
+     */
+    installDir?: string;
     /** Where the skill source lives. @default resolved from __dirname (../skill). */
     skillSrcDir?: string;
     log?: (msg: string) => void;

package/dist/index.d.ts

@@ -132,20 +132,61 @@ declare function createMcpServer(sync: SyncClient): McpServer;
  * Idempotent + non-destructive: merges into existing configs (never clobbers
  * other servers), and re-running just refreshes the buoy entry + skill.
  *
+ * ## How the server gets launched (and why corporate registries broke it)
+ *
  * By default the written config launches the server via
  * `npx -y @buoy-gg/mcp@latest`, so every editor restart re-resolves the newest
- * published version — users can't get pinned to a stale local copy. (Passing an
- * explicit `cliPath` writes a `node <path>` entry instead, for local dev/testing
- * against a working build.)
+ * published version — users can't get pinned to a stale local copy.
+ *
+ * That default fails hard on machines whose `.npmrc` routes npm at an
+ * unreachable private registry (e.g. a corporate `@buoy-gg:registry=` or a
+ * global `registry=` pointing at an internal host that doesn't resolve off-VPN).
+ * There, `npx @latest` blocks trying to download the package from a host that
+ * never answers, the editor's MCP startup times out (~30s), and the server
+ * silently never comes up — invisible to the user.
+ *
+ * So `init` now:
+ *   1. Probes the npm registry that WOULD serve `@buoy-gg/mcp`. If it's
+ *      unreachable, it falls back to a **local install** automatically.
+ *   2. Local mode installs a pinned copy into a stable dir (`~/.buoy-mcp`) from
+ *      the public npm registry (bypassing the broken `.npmrc`) and writes a
+ *      `node <path>` config — taking the network off the editor-startup path
+ *      entirely.
+ *   3. `--local` / `--npx` force a mode; `--registry <url>` overrides which
+ *      registry the local install pulls from.
+ *   4. A `cliPath` (local-dev escape hatch) still writes a `node <path>` entry
+ *      pointed at a working build, no publish needed.
  */
+type InitMode = "auto" | "npx" | "local";
 interface InitOptions {
     /** Project root to install into. @default process.cwd() */
     cwd?: string;
     /**
      * Absolute path to a built cli.js. When set, the config launches that file
-     * via `node` instead of `npx @latest` — for local development only.
+     * via `node` instead of `npx @latest` — for local development only. Takes
+     * precedence over `mode`.
      */
     cliPath?: string;
+    /**
+     * Launch strategy for the written config:
+     *   - `"auto"` (default): npx `@latest`, but fall back to a local install if
+     *     the npm registry for `@buoy-gg/mcp` is unreachable.
+     *   - `"npx"`: always write the `npx -y @latest` entry (skip the probe).
+     *   - `"local"`: always install a pinned copy to a stable dir and point the
+     *     config at it (no network on editor startup).
+     * @default "auto"
+     */
+    mode?: InitMode;
+    /**
+     * Registry to pull the local install from. @default the public npm registry.
+     * Only used for `local` (or auto-fallback-to-local) installs.
+     */
+    registry?: string;
+    /**
+     * Stable dir the local install lives in.
+     * @default `$BUOY_MCP_HOME` or `~/.buoy-mcp`.
+     */
+    installDir?: string;
     /** Where the skill source lives. @default resolved from __dirname (../skill). */
     skillSrcDir?: string;
     log?: (msg: string) => void;

package/dist/index.js

@@ -371,7 +371,7 @@ var import_node_os = __toESM(require("os"));
 var import_node_path = __toESM(require("path"));
 
 // src/version.ts
-var VERSION = "7.0.3" ? "7.0.3" : "0.0.0-dev";
+var VERSION = "7.0.4" ? "7.0.4" : "0.0.0-dev";
 var PACKAGE_NAME = "@buoy-gg/mcp";
 
 // src/update/checkForUpdate.ts
@@ -2682,13 +2682,17 @@ var deviceIdField = {
 };
 
 // src/init.ts
+var import_node_child_process2 = require("child_process");
 var import_node_fs3 = __toESM(require("fs"));
+var import_node_os3 = __toESM(require("os"));
 var import_node_path3 = __toESM(require("path"));
+var PUBLIC_REGISTRY = "https://registry.npmjs.org";
+var PROBE_TIMEOUT_MS = 3e3;
 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 entry = resolveEntry(opts, log);
   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"))) {
@@ -2705,12 +2709,125 @@ function runInit(opts = {}) {
   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) {
+  if (entry.command === "npx") {
     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\`.`);
+  } else if (!opts.cliPath) {
+    log("");
+    log(`This uses a pinned local install (no network on startup). To update it later,`);
+    log(`re-run init (\`node ${entry.args[0]?.replace(/dist[/\\]cli\.js$/, "") ?? ""}...\` \u2014 or reinstall).`);
+  }
+}
+function resolveEntry(opts, log) {
+  if (opts.cliPath) {
+    return { type: "stdio", command: "node", args: [opts.cliPath] };
+  }
+  const mode = opts.mode ?? "auto";
+  if (mode === "npx") {
+    return npxEntry();
+  }
+  if (mode === "local") {
+    return localEntry(opts, log);
+  }
+  const probe = probeRegistry();
+  if (probe.reachable) {
+    return npxEntry();
+  }
+  log(
+    `\u26A0 npm registry ${probe.registry ? `(${probe.registry}) ` : ""}looks unreachable \u2014 \`npx @latest\` would hang your editor at startup. Falling back to a pinned local install.`
+  );
+  return localEntry(opts, log);
+}
+function npxEntry() {
+  return { type: "stdio", command: "npx", args: ["-y", `${PACKAGE_NAME}@latest`] };
+}
+function localEntry(opts, log) {
+  const installDir = opts.installDir ?? process.env.BUOY_MCP_HOME ?? import_node_path3.default.join(import_node_os3.default.homedir(), ".buoy-mcp");
+  const registry = opts.registry ?? PUBLIC_REGISTRY;
+  const cliPath = installLocalCopy(installDir, registry, log);
+  if (cliPath) {
+    return { type: "stdio", command: "node", args: [cliPath] };
   }
+  log("\u26A0 local install failed \u2014 writing the npx entry instead (see the error above).");
+  return npxEntry();
+}
+function installLocalCopy(installDir, registry, log) {
+  const spec = `${PACKAGE_NAME}@${VERSION === "0.0.0-dev" ? "latest" : VERSION}`;
+  import_node_fs3.default.mkdirSync(installDir, { recursive: true });
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  log(`Installing ${spec} into ${installDir} from ${registry} \u2026`);
+  const res = (0, import_node_child_process2.spawnSync)(
+    npm,
+    [
+      "install",
+      spec,
+      "--prefix",
+      installDir,
+      "--registry",
+      registry,
+      `--@buoy-gg:registry=${registry}`,
+      "--no-audit",
+      "--no-fund",
+      "--loglevel=error"
+    ],
+    { stdio: ["ignore", "ignore", "inherit"], encoding: "utf8" }
+  );
+  if (res.status !== 0) {
+    log(`\u26A0 npm install exited with code ${res.status ?? "?"}${res.error ? ` (${res.error.message})` : ""}.`);
+    return null;
+  }
+  const cliPath = import_node_path3.default.join(installDir, "node_modules", PACKAGE_NAME, "dist", "cli.js");
+  if (!import_node_fs3.default.existsSync(cliPath)) {
+    log(`\u26A0 install finished but ${cliPath} is missing.`);
+    return null;
+  }
+  return cliPath;
 }
+function probeRegistry() {
+  const registry = effectiveRegistry();
+  if (!registry) return { reachable: false, registry: null };
+  if (/^https?:\/\/registry\.npmjs\.org\/?$/i.test(registry)) {
+    return { reachable: true, registry };
+  }
+  return { reachable: hostReachable(registry), registry };
+}
+function effectiveRegistry() {
+  const scoped = npmConfigGet("@buoy-gg:registry");
+  if (scoped) return scoped;
+  const global = npmConfigGet("registry");
+  return global ?? PUBLIC_REGISTRY;
+}
+function npmConfigGet(key) {
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  const res = (0, import_node_child_process2.spawnSync)(npm, ["config", "get", key], { encoding: "utf8", timeout: PROBE_TIMEOUT_MS });
+  if (res.status !== 0 || typeof res.stdout !== "string") return null;
+  const val = res.stdout.trim();
+  if (!val || val === "undefined" || val === "null") return null;
+  return val;
+}
+function hostReachable(registry) {
+  const done = (0, import_node_child_process2.spawnSync)(
+    process.execPath,
+    ["-e", REACHABILITY_PROBE, registry, String(PROBE_TIMEOUT_MS)],
+    { encoding: "utf8", timeout: PROBE_TIMEOUT_MS + 2e3 }
+  );
+  return done.status === 0;
+}
+var REACHABILITY_PROBE = `
+const url = process.argv[1];
+const ms = Number(process.argv[2]) || 3000;
+const c = new AbortController();
+const t = setTimeout(() => c.abort(), ms);
+fetch(url, { method: 'HEAD', signal: c.signal })
+  .then(() => { clearTimeout(t); process.exit(0); })
+  .catch(() => {
+    // A HEAD may be rejected while the host is up; a bare TCP-level failure is
+    // what we care about. fetch throwing a TypeError = network unreachable.
+    clearTimeout(t);
+    process.exit(1);
+  });
+`;
 function upsertMcpConfig(file, key, entry, cwd, done) {
   let json3 = {};
   if (import_node_fs3.default.existsSync(file)) {

package/dist/index.mjs

@@ -27,7 +27,7 @@ import {
   registerStorageTools,
   registerZustandTools,
   runInit
-} from "./chunk-MGZN6MJE.mjs";
+} from "./chunk-EC6YNLYA.mjs";
 export {
   ALL_DEVICES,
   BROKER_PORT,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@buoy-gg/mcp",
   "mcpName": "io.github.buoy-gg/mcp",
-  "version": "7.0.3",
+  "version": "7.0.4",
   "description": "MCP server for Buoy devtools — lets any LLM copilot drive Buoy tools (perf-monitor benchmarks, etc.) over the devtool sync protocol",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -31,7 +31,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "socket.io-client": "^4.8.1",
     "zod": "^3.25.0",
-    "@buoy-gg/sync-broker": "7.0.3"
+    "@buoy-gg/sync-broker": "7.0.4"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",