@buoy-gg/mcp 7.0.2 → 7.0.4

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;