@muhaven/mcp 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -7,6 +7,136 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.4] — 2026-05-17
+
+Adds the one-shot `muhaven-broker setup` subcommand so a fresh install
+goes from `npm install -g @muhaven/mcp` straight to a working MCP host
+in two commands. Surfaced during the Wave 4 demo-recording prep — the
+prior five-line manual ritual (env exports + session-key mint +
+background daemon + login) was the longest opaque block in the demo
+script. Also adds `--version` / `--help` to both `muhaven-broker` and
+`muhaven-mcp` bins.
+
+### Added
+
+- **`muhaven-broker setup` subcommand** — orchestrates env defaulting +
+  session-key minting + detached daemon spawn + login in a single
+  invocation. Flags:
+  - `--foreground` / `-f`: keep the daemon attached to the current
+    shell (useful when systemd/launchd will supervise instead of the
+    backgrounded child).
+  - `--skip-login`: spawn the daemon but defer the device-code flow.
+  - `--no-launch-browser`: pass-through to the embedded `login` step.
+  - `--broker-endpoint`, `--backend-base-url`, `--dashboard-base-url`:
+    same overrides as `login`.
+
+  Env defaults applied (only when the var is unset):
+  - `MUHAVEN_BACKEND_URL=https://api.muhaven.app`
+  - `MUHAVEN_DASHBOARD_URL=https://muhaven.app`
+  - `MUHAVEN_KEYRING=file` (auto-applied on Windows / WSL2 /
+    devcontainer / GitHub Codespace / SSH — same heuristic as
+    `muhaven-broker doctor`'s environment detector). Native macOS +
+    Linux desktop leave the value unset so the OS keychain remains
+    the default.
+
+  Idempotent: re-running `setup` against an already-up daemon detects
+  the existing JWT and short-circuits to `Login: skipped — JWT already
+  in keystore.`. Against a daemon that's up but unauthenticated, it
+  skips the spawn and only runs the login step.
+
+  Closing summary always surfaces the broker endpoint and a
+  platform-specific "Stop daemon" command (`kill <pid>` on POSIX,
+  `Stop-Process -Id <pid>` on Windows). Sign-out is explicitly
+  documented as separate from daemon shutdown — `muhaven-broker logout`
+  clears the JWT but leaves the daemon running.
+
+- **`muhaven-broker --version` / `-v`** — prints `muhaven-broker
+  @muhaven/mcp@<version>` and exits 0. Wired into the dispatcher
+  alongside the existing `--help` / `-h`. Reads the package version
+  from the tsup-injected `__SERVER_VERSION__` constant.
+
+- **`muhaven-mcp --version` / `-v` and `--help` / `-h`** — bin shim
+  short-circuits before requiring `dist/index.cjs`, so the flags exit
+  cleanly without spinning up the broker IPC + tool registry. Reads
+  the version from the sibling `package.json` directly.
+
+### Security
+
+- **Session key never lands in `process.env`** — the orchestrator
+  builds a local `effectiveEnv` snapshot and passes the minted
+  session key only to the spawned daemon's env. Prior version
+  mutated `process.env.MUHAVEN_BROKER_SESSION_KEY` so any subsequent
+  child of the operator's shell would inherit the key. Foreground
+  mode brackets its required `process.env` mutation in a try/finally
+  that restores the original values on exit.
+
+- **Spawned daemon strips `NODE_OPTIONS` / `NODE_TLS_REJECT_UNAUTHORIZED`
+  / `NODE_EXTRA_CA_CERTS` / `NODE_PATH`** from inherited env so a
+  same-user attacker who set those in the operator's shell can't
+  hijack the daemon's execution to exfiltrate the session key.
+
+- **URL flag validation** — `--backend-base-url` / `--dashboard-base-url`
+  must be `https://` (with `http://localhost` / `127.0.0.1` /
+  `[::1]` dev carve-out). Rejects `javascript:`, `file:`, `data:`,
+  and plain `http:` to non-loopback BEFORE the spawn — defense
+  against the OAuth-device-flow phishing vector where a malicious
+  `--backend-base-url` would ship the JWT to an attacker host.
+
+- **`--broker-endpoint` path validation** — must be a `\\.\pipe\…`
+  path on Windows or an absolute path on POSIX. Rejects relative
+  paths + flag-injection (e.g. `--broker-endpoint --from-daemon` is
+  parsed but rejected at validation, preventing the spawned daemon
+  from being bound to an attacker-controlled location).
+
+- **Preserved env values not echoed** — `Env preserved: NAME (set in
+  your shell)` only — values stay opaque. Prior version printed
+  `Env preserved: NAME=value` which would leak operator-supplied
+  values to shell history / CI logs.
+
+- **Session key minted via viem's `generatePrivateKey`** — guarantees
+  the result is in the valid secp256k1 scalar range. Prior version
+  used raw `crypto.randomBytes(32)`, which had a (negligible but
+  nonzero) probability of returning an out-of-range value that the
+  signer would reject as invalid much later in the flow.
+
+- **Bin path resolved via `__dirname`** — `resolveBrokerBinPath` walks
+  from the bundled `dist/broker.cjs` to the sibling
+  `bin/muhaven-broker.cjs` deterministically, so Windows global-npm
+  shim wrappers (`.cmd` / `.ps1` in `process.argv[1]`) don't end up
+  as the spawn target.
+
+- **`detectMcpHost` no longer falls through to `npm_lifecycle_event`**
+  — that var is the npm script name, not an MCP-host identity. The
+  device-flow `/link` page's "requesting client" panel would have
+  displayed "setup" for operators running via `npm run setup`,
+  misleading the passkey ceremony.
+
+### Tests
+
+- 197 vitest pass (up from 134 in 0.1.3). Net +58 cases in
+  `__tests__/setup.test.ts` (+22 over the initial +36 after the
+  parallel agent security review) + 5 in `__tests__/cli-version-flag.test.ts`:
+  - **+10** `applyEnvDefaults` — defaults applied on empty env;
+    backend/dashboard preserved when set; KEYRING auto-applied on
+    win32/WSL2/SSH/devcontainer/Codespaces; left unset on native
+    macOS/Linux desktop; explicit `MUHAVEN_KEYRING=os` preserved on
+    Windows; empty-string vars treated as unset.
+  - **+2** `mintSessionKey` — 0x-prefixed 32-byte hex shape;
+    non-deterministic across calls.
+  - **+3** `decideSetupAction` — spawn-and-login / login-only /
+    already-ready decision tree.
+  - **+6** `parseSetupFlags` — defaults; `--foreground` and `-f`
+    aliases; `--skip-login`; `--no-launch-browser` pass-through; value
+    flag parsing; unknown-flag rejection.
+  - **+3** `waitForBroker` — first-call success; retry-until-success
+    with virtual clock; timeout throws with last error in message.
+  - **+12** `runSetup` orchestrator — flag-error path returns 2;
+    foreground mode short-circuits; spawn_and_login happy path;
+    login_only path; already_ready path; `--skip-login`; login-failure
+    bubbles exit code + leaves daemon running; wait timeout returns 1;
+    `--no-launch-browser` pass-through; value-flag pass-through;
+    session key minted vs preserved.
+
 ## [0.1.3] — 2026-05-16
 
 Q2 fix bundle from the post-§4 queue closing four findings from §3e⁶

package/bin/muhaven-mcp.cjs

@@ -1,5 +1,50 @@
 #!/usr/bin/env node
 /* eslint-disable */
+//
+// `muhaven-mcp` bin entrypoint.
+//
+// Production: MCPB hosts (Claude Desktop / Cursor / Claude Code) spawn this
+// binary over STDIO and immediately start a JSON-RPC handshake. The host
+// never passes argv flags — but operators occasionally run `muhaven-mcp
+// --version` / `--help` from the shell to sanity-check the install. Those
+// flags short-circuit BEFORE we wire up the STDIO transport so they exit
+// cleanly without spinning up the broker IPC + tool registry.
+//
+// Keep this shim tiny — the production path is `runMcpStdioCli()` from the
+// bundled dist. Anything richer goes in src/ where it's testable.
+//
+
+const args = process.argv.slice(2);
+
+if (args.includes('--version') || args.includes('-v')) {
+  const pkg = require('../package.json');
+  process.stdout.write(`muhaven-mcp ${pkg.version}\n`);
+  process.exit(0);
+}
+
+if (args.includes('--help') || args.includes('-h')) {
+  const pkg = require('../package.json');
+  process.stdout.write(
+    [
+      `muhaven-mcp ${pkg.version} — MuHaven MCP STDIO server`,
+      ``,
+      `Usage:`,
+      `  muhaven-mcp                        Run the MCP server over STDIO`,
+      `                                     (called by Claude Desktop / Cursor /`,
+      `                                     Claude Code — not directly by humans)`,
+      `  muhaven-mcp --version | -v         Print the @muhaven/mcp package version`,
+      `  muhaven-mcp --help    | -h         Show this help`,
+      ``,
+      `For first-time setup, run:   muhaven-broker setup`,
+      `For troubleshooting, run:    muhaven-broker doctor`,
+      ``,
+      `Docs: https://github.com/hasToDev/muhaven/blob/master/packages/mcp/README.md`,
+      ``,
+    ].join('\n'),
+  );
+  process.exit(0);
+}
+
 const { runMcpStdioCli } = require('../dist/index.cjs');
 
 runMcpStdioCli().then(

package/dist/broker.cjs

@@ -7,7 +7,6 @@ var net = require('net');
 var promises = require('fs/promises');
 var accounts = require('viem/accounts');
 
-// src/broker/cli.ts
 var DEFAULT_BACKEND_URL = "https://api.muhaven.app";
 var DEFAULT_DASHBOARD_URL = "https://muhaven.app";
 var DEFAULT_REQUEST_TIMEOUT_MS = 15e3;
@@ -934,6 +933,332 @@ async function runBrokerDaemonCli() {
   await new Promise(() => {
   });
 }
+var DANGEROUS_NODE_ENV_VARS = [
+  "NODE_OPTIONS",
+  "NODE_TLS_REJECT_UNAUTHORIZED",
+  "NODE_EXTRA_CA_CERTS",
+  "NODE_PATH"
+];
+function applyEnvDefaults(input) {
+  const { env } = input;
+  const platformId = input.platformId ?? process.platform;
+  const osRelease = input.osRelease ?? os.release();
+  const toSet = {};
+  const preserved = [];
+  const defaultIfUnset = (name, value) => {
+    if (env[name] && env[name].length > 0) {
+      preserved.push(name);
+    } else {
+      toSet[name] = value;
+    }
+  };
+  defaultIfUnset("MUHAVEN_BACKEND_URL", "https://api.muhaven.app");
+  defaultIfUnset("MUHAVEN_DASHBOARD_URL", "https://muhaven.app");
+  const wantFileKeyring = platformId === "win32" || platformId === "linux" && (env.WSL_DISTRO_NAME !== void 0 || /microsoft/i.test(osRelease)) || env.REMOTE_CONTAINERS === "true" || env.CODESPACES === "true" || env.SSH_CONNECTION !== void 0;
+  if (wantFileKeyring) {
+    defaultIfUnset("MUHAVEN_KEYRING", "file");
+  } else if (env.MUHAVEN_KEYRING) {
+    preserved.push("MUHAVEN_KEYRING");
+  }
+  return { toSet, preserved };
+}
+function mintSessionKey() {
+  return accounts.generatePrivateKey();
+}
+function decideSetupAction(input) {
+  if (input.hello === null) return "spawn_and_login";
+  if (!input.hello.hasJwt) return "login_only";
+  return "already_ready";
+}
+function spawnDaemon(options) {
+  const sanitized = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (!DANGEROUS_NODE_ENV_VARS.includes(k)) {
+      sanitized[k] = v;
+    }
+  }
+  const merged = { ...sanitized, ...options.env };
+  const child = child_process.spawn(process.execPath, [options.binPath], {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+    env: merged
+  });
+  child.unref();
+  if (child.pid === void 0) {
+    throw new Error("failed to spawn muhaven-broker daemon \u2014 child pid is undefined");
+  }
+  return child.pid;
+}
+function validateHttpUrlFlag(name, value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return `${name} is not a valid URL: ${value}`;
+  }
+  if (parsed.protocol === "https:") return null;
+  if (parsed.protocol === "http:") {
+    const host = parsed.hostname;
+    if (host === "localhost" || host === "127.0.0.1" || host === "[::1]") return null;
+    return `${name} must use https:// (got http:// to ${host} \u2014 refusing to ship JWT cleartext)`;
+  }
+  return `${name} must use https:// (got ${parsed.protocol})`;
+}
+function validateBrokerEndpointFlag(value, platformId) {
+  if (!value || value.length === 0) {
+    return "--broker-endpoint cannot be empty";
+  }
+  if (platformId === "win32") {
+    if (value.startsWith("\\\\.\\pipe\\") || value.startsWith("//./pipe/")) {
+      return null;
+    }
+    return "--broker-endpoint on Windows must be a named pipe path (\\\\.\\pipe\\...)";
+  }
+  if (!value.startsWith("/")) {
+    return "--broker-endpoint on POSIX must be an absolute path (e.g. /run/muhaven/broker.sock)";
+  }
+  return null;
+}
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function waitForBroker(options) {
+  const timeoutMs = options.timeoutMs ?? 8e3;
+  const intervalMs = options.intervalMs ?? 200;
+  const sleep = options.sleep ?? defaultSleep;
+  const now = options.now ?? Date.now;
+  const deadline = now() + timeoutMs;
+  let lastErr = null;
+  while (now() < deadline) {
+    try {
+      const hello = await options.broker.hello();
+      return { hasJwt: hello.hasJwt };
+    } catch (err) {
+      lastErr = err;
+      if (now() + intervalMs < deadline) {
+        await sleep(intervalMs);
+      } else {
+        break;
+      }
+    }
+  }
+  throw new Error(
+    `muhaven-broker daemon did not become reachable within ${timeoutMs}ms: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`
+  );
+}
+function parseSetupFlags(argv) {
+  let foreground = false;
+  let noLaunchBrowser = false;
+  let brokerEndpoint;
+  let backendBaseUrl;
+  let dashboardBaseUrl;
+  let skipLogin = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--foreground" || a === "-f") foreground = true;
+    else if (a === "--no-launch-browser") noLaunchBrowser = true;
+    else if (a === "--skip-login") skipLogin = true;
+    else if (a === "--broker-endpoint" && i + 1 < argv.length) brokerEndpoint = argv[++i];
+    else if (a === "--backend-base-url" && i + 1 < argv.length) backendBaseUrl = argv[++i];
+    else if (a === "--dashboard-base-url" && i + 1 < argv.length) dashboardBaseUrl = argv[++i];
+    else throw new Error(`unknown flag: ${a}`);
+  }
+  return {
+    foreground,
+    noLaunchBrowser,
+    brokerEndpoint,
+    backendBaseUrl,
+    dashboardBaseUrl,
+    skipLogin
+  };
+}
+async function runSetup(argv, deps) {
+  let flags;
+  try {
+    flags = parseSetupFlags(argv);
+  } catch (err) {
+    deps.printErr(`error: ${err.message}`);
+    deps.printErr(
+      "usage: muhaven-broker setup [--foreground|-f] [--no-launch-browser] [--skip-login]\n                            [--broker-endpoint PATH] [--backend-base-url URL]\n                            [--dashboard-base-url URL]"
+    );
+    return 2;
+  }
+  if (flags.backendBaseUrl) {
+    const err = validateHttpUrlFlag("--backend-base-url", flags.backendBaseUrl);
+    if (err) {
+      deps.printErr(`error: ${err}`);
+      return 2;
+    }
+  }
+  if (flags.dashboardBaseUrl) {
+    const err = validateHttpUrlFlag("--dashboard-base-url", flags.dashboardBaseUrl);
+    if (err) {
+      deps.printErr(`error: ${err}`);
+      return 2;
+    }
+  }
+  if (flags.brokerEndpoint) {
+    const err = validateBrokerEndpointFlag(flags.brokerEndpoint, deps.platformId);
+    if (err) {
+      deps.printErr(`error: ${err}`);
+      return 2;
+    }
+  }
+  const overrides = applyEnvDefaults({
+    env: deps.env,
+    platformId: deps.platformId,
+    osRelease: deps.osRelease
+  });
+  const effectiveEnv = {};
+  for (const [k, v] of Object.entries(deps.env)) {
+    if (typeof v === "string") effectiveEnv[k] = v;
+  }
+  for (const [k, v] of Object.entries(overrides.toSet)) {
+    effectiveEnv[k] = v;
+  }
+  if (flags.brokerEndpoint) effectiveEnv.MUHAVEN_BROKER_ENDPOINT = flags.brokerEndpoint;
+  if (flags.backendBaseUrl) effectiveEnv.MUHAVEN_BACKEND_URL = flags.backendBaseUrl;
+  if (flags.dashboardBaseUrl) effectiveEnv.MUHAVEN_DASHBOARD_URL = flags.dashboardBaseUrl;
+  for (const name of overrides.preserved) {
+    deps.print(`Env preserved: ${name} (set in your shell)`);
+  }
+  for (const [k, v] of Object.entries(overrides.toSet)) {
+    deps.print(`Env defaulted: ${k}=${v}`);
+  }
+  let sessionKey = effectiveEnv.MUHAVEN_BROKER_SESSION_KEY;
+  let mintedKey = false;
+  if (!sessionKey || sessionKey === "") {
+    sessionKey = deps.mintSessionKey();
+    mintedKey = true;
+    deps.print("Session key: minted fresh (secp256k1, ephemeral to this daemon).");
+  } else {
+    deps.print("Session key: using MUHAVEN_BROKER_SESSION_KEY from env.");
+  }
+  effectiveEnv.MUHAVEN_BROKER_SESSION_KEY = sessionKey;
+  if (flags.foreground) {
+    deps.print("Foreground mode \u2014 running daemon attached to this shell. Ctrl-C to stop.");
+    const restorationKeys = [
+      ...Object.keys(overrides.toSet),
+      "MUHAVEN_BROKER_SESSION_KEY",
+      ...flags.brokerEndpoint ? ["MUHAVEN_BROKER_ENDPOINT"] : [],
+      ...flags.backendBaseUrl ? ["MUHAVEN_BACKEND_URL"] : [],
+      ...flags.dashboardBaseUrl ? ["MUHAVEN_DASHBOARD_URL"] : []
+    ];
+    const originalValues = {};
+    for (const k of restorationKeys) {
+      originalValues[k] = process.env[k];
+      process.env[k] = effectiveEnv[k];
+    }
+    try {
+      await deps.runForegroundDaemon();
+    } finally {
+      for (const k of restorationKeys) {
+        if (originalValues[k] === void 0) delete process.env[k];
+        else process.env[k] = originalValues[k];
+      }
+    }
+    return 0;
+  }
+  const config = loadMcpConfig(effectiveEnv);
+  const broker = deps.newBrokerClient(config.brokerEndpoint, config.brokerTimeoutMs);
+  let helloProbe = null;
+  try {
+    helloProbe = await broker.hello();
+  } catch {
+  }
+  const action = decideSetupAction({ hello: helloProbe });
+  let daemonPid = null;
+  if (action === "spawn_and_login") {
+    deps.print("Broker daemon: not running, starting one (detached) ...");
+    daemonPid = deps.spawnDaemon({
+      binPath: deps.resolveBinPath(),
+      env: {
+        // Explicit env for the spawned daemon. Includes every var that the
+        // daemon's loadBrokerConfig will read, sourced from our resolved
+        // effectiveEnv (NOT from process.env). spawnDaemon will sanitize
+        // process.env-inherited values further (strips NODE_OPTIONS etc.).
+        ...overrides.toSet,
+        MUHAVEN_BROKER_ENDPOINT: config.brokerEndpoint,
+        MUHAVEN_BACKEND_URL: effectiveEnv.MUHAVEN_BACKEND_URL,
+        MUHAVEN_DASHBOARD_URL: effectiveEnv.MUHAVEN_DASHBOARD_URL,
+        MUHAVEN_BROKER_SESSION_KEY: sessionKey
+      }
+    });
+    try {
+      const readyHello = await deps.waitForBroker({ broker });
+      helloProbe = readyHello;
+      deps.print(`Broker daemon: ready (PID ${daemonPid}, endpoint ${config.brokerEndpoint}).`);
+    } catch (err) {
+      deps.printErr(err.message);
+      deps.printErr(
+        "  hint: re-run `muhaven-broker setup` after checking that no other broker is bound to the same endpoint."
+      );
+      return 1;
+    }
+  } else {
+    deps.print(`Broker daemon: already reachable at ${config.brokerEndpoint}.`);
+  }
+  const needsLogin = !flags.skipLogin && !(helloProbe && helloProbe.hasJwt);
+  if (flags.skipLogin) {
+    deps.print("Login: skipped per --skip-login.");
+  } else if (helloProbe && helloProbe.hasJwt) {
+    deps.print("Login: skipped \u2014 JWT already in keystore.");
+  }
+  if (needsLogin) {
+    const loginArgv = [];
+    if (flags.noLaunchBrowser) loginArgv.push("--no-launch-browser");
+    if (flags.brokerEndpoint) {
+      loginArgv.push("--broker-endpoint", flags.brokerEndpoint);
+    }
+    if (flags.backendBaseUrl) {
+      loginArgv.push("--backend-base-url", flags.backendBaseUrl);
+    }
+    if (flags.dashboardBaseUrl) {
+      loginArgv.push("--dashboard-base-url", flags.dashboardBaseUrl);
+    }
+    const restorationKeys = ["MUHAVEN_BACKEND_URL", "MUHAVEN_DASHBOARD_URL", "MUHAVEN_BROKER_ENDPOINT"];
+    const originalValues = {};
+    for (const k of restorationKeys) {
+      originalValues[k] = process.env[k];
+      if (effectiveEnv[k]) process.env[k] = effectiveEnv[k];
+    }
+    let code;
+    try {
+      code = await deps.runLogin(loginArgv);
+    } finally {
+      for (const k of restorationKeys) {
+        if (originalValues[k] === void 0) delete process.env[k];
+        else process.env[k] = originalValues[k];
+      }
+    }
+    if (code !== 0) {
+      deps.printErr(
+        "Setup: login step failed \u2014 daemon is still running, re-run `muhaven-broker login` to retry."
+      );
+      if (daemonPid !== null) {
+        const killCmd = deps.platformId === "win32" ? `Stop-Process -Id ${daemonPid}` : `kill ${daemonPid}`;
+        deps.printErr(`  (daemon PID ${daemonPid}; stop with: ${killCmd})`);
+      }
+      return code;
+    }
+  }
+  deps.print("");
+  deps.print("================================");
+  deps.print("Setup complete.");
+  if (daemonPid !== null) {
+    deps.print(`  Daemon PID : ${daemonPid}`);
+    const killCmd = deps.platformId === "win32" ? `Stop-Process -Id ${daemonPid}` : `kill ${daemonPid}`;
+    deps.print(`  Stop daemon: ${killCmd}`);
+  } else {
+    deps.print("  Daemon     : already running");
+  }
+  deps.print(`  Endpoint   : ${config.brokerEndpoint}`);
+  deps.print("  Sign out   : muhaven-broker logout   (clears JWT, leaves daemon running)");
+  if (mintedKey) {
+    deps.print("  Session key: ephemeral \u2014 minted by setup, lives only in the daemon process.");
+  }
+  deps.print("================================");
+  return 0;
+}
 
 // src/broker/cli.ts
 function print(line) {
@@ -943,7 +1268,7 @@ function printErr(line) {
   process.stderr.write(line + "\n");
 }
 function detectMcpHost() {
-  return process.env.MCP_HOST_NAME ?? process.env.CLAUDE_CODE_HOST ?? process.env.npm_lifecycle_event ?? "muhaven-broker-cli";
+  return process.env.MCP_HOST_NAME ?? process.env.CLAUDE_CODE_HOST ?? "muhaven-broker-cli";
 }
 function detectEnvironment() {
   const warnings = [];
@@ -1197,11 +1522,44 @@ function printUsage() {
   print("usage: muhaven-broker [<subcommand>] [options]");
   print("");
   print("  (no subcommand)    Run the daemon (production mode)");
+  print("  setup              One-shot install: env defaults + session key + detached daemon + login");
+  print("                       [--foreground|-f] keeps the daemon attached (skip background spawn)");
+  print("                       [--skip-login] starts the daemon but lets you run login later");
+  print("                       [--no-launch-browser] pass-through to login");
   print("  login              Acquire a JWT via the device-code flow + store in keystore");
   print("                       [--from-daemon] resolves backend/dashboard URLs from the running daemon");
   print("  logout             Clear the JWT from the keystore");
   print("  doctor             Print environment + keystore + reachability report");
   print("  -h, --help         Show this help");
+  print("  -v, --version      Print the @muhaven/mcp package version");
+}
+function getBrokerPackageVersion() {
+  {
+    return "0.1.4";
+  }
+}
+function printVersion() {
+  print(`muhaven-broker @muhaven/mcp@${getBrokerPackageVersion()}`);
+}
+function resolveBrokerBinPath() {
+  return path.resolve(__dirname, "..", "bin", "muhaven-broker.cjs");
+}
+async function runSetup2(argv) {
+  const deps = {
+    print,
+    printErr,
+    mintSessionKey,
+    newBrokerClient: (endpoint, timeoutMs) => new BrokerClient({ endpoint, timeoutMs }),
+    spawnDaemon,
+    waitForBroker,
+    runLogin,
+    runForegroundDaemon: runBrokerDaemonCli,
+    resolveBinPath: resolveBrokerBinPath,
+    env: process.env,
+    platformId: process.platform,
+    osRelease: os.release()
+  };
+  return runSetup(argv, deps);
 }
 async function runCli(argv) {
   const [sub, ...rest] = argv;
@@ -1209,6 +1567,8 @@ async function runCli(argv) {
     case void 0:
       await runBrokerDaemonCli();
       return 0;
+    case "setup":
+      return runSetup2(rest);
     case "login":
       return runLogin(rest);
     case "logout":
@@ -1219,6 +1579,10 @@ async function runCli(argv) {
     case "--help":
       printUsage();
       return 0;
+    case "-v":
+    case "--version":
+      printVersion();
+      return 0;
     default:
       printErr(`unknown subcommand: ${sub}`);
       printUsage();
@@ -1226,8 +1590,10 @@ async function runCli(argv) {
   }
 }
 
+exports.getBrokerPackageVersion = getBrokerPackageVersion;
 exports.parseLoginFlags = parseLoginFlags;
 exports.runCli = runCli;
 exports.runDoctor = runDoctor;
 exports.runLogin = runLogin;
 exports.runLogout = runLogout;
+exports.runSetup = runSetup2;

package/dist/broker.d.cts

@@ -31,6 +31,14 @@ declare function parseLoginFlags(argv: readonly string[]): LoginFlags;
 declare function runLogin(argv: readonly string[]): Promise<number>;
 declare function runLogout(): Promise<number>;
 declare function runDoctor(): Promise<number>;
+declare function getBrokerPackageVersion(): string;
+/**
+ * Wire `runSetup` against the real cli helpers + IO. Kept here (not in
+ * `setup.ts`) so the pure orchestrator stays free of the cli-only
+ * `runLogin` import (which would pull device-flow + viem into the test
+ * surface unnecessarily).
+ */
+declare function runSetup(argv: readonly string[]): Promise<number>;
 declare function runCli(argv: readonly string[]): Promise<number>;
 
-export { parseLoginFlags, runCli, runDoctor, runLogin, runLogout };
+export { getBrokerPackageVersion, parseLoginFlags, runCli, runDoctor, runLogin, runLogout, runSetup };

package/dist/broker.d.ts

@@ -31,6 +31,14 @@ declare function parseLoginFlags(argv: readonly string[]): LoginFlags;
 declare function runLogin(argv: readonly string[]): Promise<number>;
 declare function runLogout(): Promise<number>;
 declare function runDoctor(): Promise<number>;
+declare function getBrokerPackageVersion(): string;
+/**
+ * Wire `runSetup` against the real cli helpers + IO. Kept here (not in
+ * `setup.ts`) so the pure orchestrator stays free of the cli-only
+ * `runLogin` import (which would pull device-flow + viem into the test
+ * surface unnecessarily).
+ */
+declare function runSetup(argv: readonly string[]): Promise<number>;
 declare function runCli(argv: readonly string[]): Promise<number>;
 
-export { parseLoginFlags, runCli, runDoctor, runLogin, runLogout };
+export { getBrokerPackageVersion, parseLoginFlags, runCli, runDoctor, runLogin, runLogout, runSetup };

package/dist/broker.js

@@ -1,11 +1,14 @@
+import path, { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
 import { platform, release, hostname, homedir } from 'os';
-import { exec } from 'child_process';
-import { join, dirname } from 'path';
+import { exec, spawn } from 'child_process';
 import { connect, createServer } from 'net';
 import { mkdir, chmod, writeFile, readFile, unlink, stat } from 'fs/promises';
-import { privateKeyToAccount } from 'viem/accounts';
+import { privateKeyToAccount, generatePrivateKey } from 'viem/accounts';
 
-// src/broker/cli.ts
+var getFilename = () => fileURLToPath(import.meta.url);
+var getDirname = () => path.dirname(getFilename());
+var __dirname$1 = /* @__PURE__ */ getDirname();
 var DEFAULT_BACKEND_URL = "https://api.muhaven.app";
 var DEFAULT_DASHBOARD_URL = "https://muhaven.app";
 var DEFAULT_REQUEST_TIMEOUT_MS = 15e3;
@@ -418,8 +421,8 @@ var OsKeystore = class {
   }
 };
 var FileKeystore = class {
-  constructor(path) {
-    this.path = path;
+  constructor(path2) {
+    this.path = path2;
   }
   path;
   backend = "file";
@@ -932,6 +935,332 @@ async function runBrokerDaemonCli() {
   await new Promise(() => {
   });
 }
+var DANGEROUS_NODE_ENV_VARS = [
+  "NODE_OPTIONS",
+  "NODE_TLS_REJECT_UNAUTHORIZED",
+  "NODE_EXTRA_CA_CERTS",
+  "NODE_PATH"
+];
+function applyEnvDefaults(input) {
+  const { env } = input;
+  const platformId = input.platformId ?? process.platform;
+  const osRelease = input.osRelease ?? release();
+  const toSet = {};
+  const preserved = [];
+  const defaultIfUnset = (name, value) => {
+    if (env[name] && env[name].length > 0) {
+      preserved.push(name);
+    } else {
+      toSet[name] = value;
+    }
+  };
+  defaultIfUnset("MUHAVEN_BACKEND_URL", "https://api.muhaven.app");
+  defaultIfUnset("MUHAVEN_DASHBOARD_URL", "https://muhaven.app");
+  const wantFileKeyring = platformId === "win32" || platformId === "linux" && (env.WSL_DISTRO_NAME !== void 0 || /microsoft/i.test(osRelease)) || env.REMOTE_CONTAINERS === "true" || env.CODESPACES === "true" || env.SSH_CONNECTION !== void 0;
+  if (wantFileKeyring) {
+    defaultIfUnset("MUHAVEN_KEYRING", "file");
+  } else if (env.MUHAVEN_KEYRING) {
+    preserved.push("MUHAVEN_KEYRING");
+  }
+  return { toSet, preserved };
+}
+function mintSessionKey() {
+  return generatePrivateKey();
+}
+function decideSetupAction(input) {
+  if (input.hello === null) return "spawn_and_login";
+  if (!input.hello.hasJwt) return "login_only";
+  return "already_ready";
+}
+function spawnDaemon(options) {
+  const sanitized = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (!DANGEROUS_NODE_ENV_VARS.includes(k)) {
+      sanitized[k] = v;
+    }
+  }
+  const merged = { ...sanitized, ...options.env };
+  const child = spawn(process.execPath, [options.binPath], {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+    env: merged
+  });
+  child.unref();
+  if (child.pid === void 0) {
+    throw new Error("failed to spawn muhaven-broker daemon \u2014 child pid is undefined");
+  }
+  return child.pid;
+}
+function validateHttpUrlFlag(name, value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return `${name} is not a valid URL: ${value}`;
+  }
+  if (parsed.protocol === "https:") return null;
+  if (parsed.protocol === "http:") {
+    const host = parsed.hostname;
+    if (host === "localhost" || host === "127.0.0.1" || host === "[::1]") return null;
+    return `${name} must use https:// (got http:// to ${host} \u2014 refusing to ship JWT cleartext)`;
+  }
+  return `${name} must use https:// (got ${parsed.protocol})`;
+}
+function validateBrokerEndpointFlag(value, platformId) {
+  if (!value || value.length === 0) {
+    return "--broker-endpoint cannot be empty";
+  }
+  if (platformId === "win32") {
+    if (value.startsWith("\\\\.\\pipe\\") || value.startsWith("//./pipe/")) {
+      return null;
+    }
+    return "--broker-endpoint on Windows must be a named pipe path (\\\\.\\pipe\\...)";
+  }
+  if (!value.startsWith("/")) {
+    return "--broker-endpoint on POSIX must be an absolute path (e.g. /run/muhaven/broker.sock)";
+  }
+  return null;
+}
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function waitForBroker(options) {
+  const timeoutMs = options.timeoutMs ?? 8e3;
+  const intervalMs = options.intervalMs ?? 200;
+  const sleep = options.sleep ?? defaultSleep;
+  const now = options.now ?? Date.now;
+  const deadline = now() + timeoutMs;
+  let lastErr = null;
+  while (now() < deadline) {
+    try {
+      const hello = await options.broker.hello();
+      return { hasJwt: hello.hasJwt };
+    } catch (err) {
+      lastErr = err;
+      if (now() + intervalMs < deadline) {
+        await sleep(intervalMs);
+      } else {
+        break;
+      }
+    }
+  }
+  throw new Error(
+    `muhaven-broker daemon did not become reachable within ${timeoutMs}ms: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`
+  );
+}
+function parseSetupFlags(argv) {
+  let foreground = false;
+  let noLaunchBrowser = false;
+  let brokerEndpoint;
+  let backendBaseUrl;
+  let dashboardBaseUrl;
+  let skipLogin = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--foreground" || a === "-f") foreground = true;
+    else if (a === "--no-launch-browser") noLaunchBrowser = true;
+    else if (a === "--skip-login") skipLogin = true;
+    else if (a === "--broker-endpoint" && i + 1 < argv.length) brokerEndpoint = argv[++i];
+    else if (a === "--backend-base-url" && i + 1 < argv.length) backendBaseUrl = argv[++i];
+    else if (a === "--dashboard-base-url" && i + 1 < argv.length) dashboardBaseUrl = argv[++i];
+    else throw new Error(`unknown flag: ${a}`);
+  }
+  return {
+    foreground,
+    noLaunchBrowser,
+    brokerEndpoint,
+    backendBaseUrl,
+    dashboardBaseUrl,
+    skipLogin
+  };
+}
+async function runSetup(argv, deps) {
+  let flags;
+  try {
+    flags = parseSetupFlags(argv);
+  } catch (err) {
+    deps.printErr(`error: ${err.message}`);
+    deps.printErr(
+      "usage: muhaven-broker setup [--foreground|-f] [--no-launch-browser] [--skip-login]\n                            [--broker-endpoint PATH] [--backend-base-url URL]\n                            [--dashboard-base-url URL]"
+    );
+    return 2;
+  }
+  if (flags.backendBaseUrl) {
+    const err = validateHttpUrlFlag("--backend-base-url", flags.backendBaseUrl);
+    if (err) {
+      deps.printErr(`error: ${err}`);
+      return 2;
+    }
+  }
+  if (flags.dashboardBaseUrl) {
+    const err = validateHttpUrlFlag("--dashboard-base-url", flags.dashboardBaseUrl);
+    if (err) {
+      deps.printErr(`error: ${err}`);
+      return 2;
+    }
+  }
+  if (flags.brokerEndpoint) {
+    const err = validateBrokerEndpointFlag(flags.brokerEndpoint, deps.platformId);
+    if (err) {
+      deps.printErr(`error: ${err}`);
+      return 2;
+    }
+  }
+  const overrides = applyEnvDefaults({
+    env: deps.env,
+    platformId: deps.platformId,
+    osRelease: deps.osRelease
+  });
+  const effectiveEnv = {};
+  for (const [k, v] of Object.entries(deps.env)) {
+    if (typeof v === "string") effectiveEnv[k] = v;
+  }
+  for (const [k, v] of Object.entries(overrides.toSet)) {
+    effectiveEnv[k] = v;
+  }
+  if (flags.brokerEndpoint) effectiveEnv.MUHAVEN_BROKER_ENDPOINT = flags.brokerEndpoint;
+  if (flags.backendBaseUrl) effectiveEnv.MUHAVEN_BACKEND_URL = flags.backendBaseUrl;
+  if (flags.dashboardBaseUrl) effectiveEnv.MUHAVEN_DASHBOARD_URL = flags.dashboardBaseUrl;
+  for (const name of overrides.preserved) {
+    deps.print(`Env preserved: ${name} (set in your shell)`);
+  }
+  for (const [k, v] of Object.entries(overrides.toSet)) {
+    deps.print(`Env defaulted: ${k}=${v}`);
+  }
+  let sessionKey = effectiveEnv.MUHAVEN_BROKER_SESSION_KEY;
+  let mintedKey = false;
+  if (!sessionKey || sessionKey === "") {
+    sessionKey = deps.mintSessionKey();
+    mintedKey = true;
+    deps.print("Session key: minted fresh (secp256k1, ephemeral to this daemon).");
+  } else {
+    deps.print("Session key: using MUHAVEN_BROKER_SESSION_KEY from env.");
+  }
+  effectiveEnv.MUHAVEN_BROKER_SESSION_KEY = sessionKey;
+  if (flags.foreground) {
+    deps.print("Foreground mode \u2014 running daemon attached to this shell. Ctrl-C to stop.");
+    const restorationKeys = [
+      ...Object.keys(overrides.toSet),
+      "MUHAVEN_BROKER_SESSION_KEY",
+      ...flags.brokerEndpoint ? ["MUHAVEN_BROKER_ENDPOINT"] : [],
+      ...flags.backendBaseUrl ? ["MUHAVEN_BACKEND_URL"] : [],
+      ...flags.dashboardBaseUrl ? ["MUHAVEN_DASHBOARD_URL"] : []
+    ];
+    const originalValues = {};
+    for (const k of restorationKeys) {
+      originalValues[k] = process.env[k];
+      process.env[k] = effectiveEnv[k];
+    }
+    try {
+      await deps.runForegroundDaemon();
+    } finally {
+      for (const k of restorationKeys) {
+        if (originalValues[k] === void 0) delete process.env[k];
+        else process.env[k] = originalValues[k];
+      }
+    }
+    return 0;
+  }
+  const config = loadMcpConfig(effectiveEnv);
+  const broker = deps.newBrokerClient(config.brokerEndpoint, config.brokerTimeoutMs);
+  let helloProbe = null;
+  try {
+    helloProbe = await broker.hello();
+  } catch {
+  }
+  const action = decideSetupAction({ hello: helloProbe });
+  let daemonPid = null;
+  if (action === "spawn_and_login") {
+    deps.print("Broker daemon: not running, starting one (detached) ...");
+    daemonPid = deps.spawnDaemon({
+      binPath: deps.resolveBinPath(),
+      env: {
+        // Explicit env for the spawned daemon. Includes every var that the
+        // daemon's loadBrokerConfig will read, sourced from our resolved
+        // effectiveEnv (NOT from process.env). spawnDaemon will sanitize
+        // process.env-inherited values further (strips NODE_OPTIONS etc.).
+        ...overrides.toSet,
+        MUHAVEN_BROKER_ENDPOINT: config.brokerEndpoint,
+        MUHAVEN_BACKEND_URL: effectiveEnv.MUHAVEN_BACKEND_URL,
+        MUHAVEN_DASHBOARD_URL: effectiveEnv.MUHAVEN_DASHBOARD_URL,
+        MUHAVEN_BROKER_SESSION_KEY: sessionKey
+      }
+    });
+    try {
+      const readyHello = await deps.waitForBroker({ broker });
+      helloProbe = readyHello;
+      deps.print(`Broker daemon: ready (PID ${daemonPid}, endpoint ${config.brokerEndpoint}).`);
+    } catch (err) {
+      deps.printErr(err.message);
+      deps.printErr(
+        "  hint: re-run `muhaven-broker setup` after checking that no other broker is bound to the same endpoint."
+      );
+      return 1;
+    }
+  } else {
+    deps.print(`Broker daemon: already reachable at ${config.brokerEndpoint}.`);
+  }
+  const needsLogin = !flags.skipLogin && !(helloProbe && helloProbe.hasJwt);
+  if (flags.skipLogin) {
+    deps.print("Login: skipped per --skip-login.");
+  } else if (helloProbe && helloProbe.hasJwt) {
+    deps.print("Login: skipped \u2014 JWT already in keystore.");
+  }
+  if (needsLogin) {
+    const loginArgv = [];
+    if (flags.noLaunchBrowser) loginArgv.push("--no-launch-browser");
+    if (flags.brokerEndpoint) {
+      loginArgv.push("--broker-endpoint", flags.brokerEndpoint);
+    }
+    if (flags.backendBaseUrl) {
+      loginArgv.push("--backend-base-url", flags.backendBaseUrl);
+    }
+    if (flags.dashboardBaseUrl) {
+      loginArgv.push("--dashboard-base-url", flags.dashboardBaseUrl);
+    }
+    const restorationKeys = ["MUHAVEN_BACKEND_URL", "MUHAVEN_DASHBOARD_URL", "MUHAVEN_BROKER_ENDPOINT"];
+    const originalValues = {};
+    for (const k of restorationKeys) {
+      originalValues[k] = process.env[k];
+      if (effectiveEnv[k]) process.env[k] = effectiveEnv[k];
+    }
+    let code;
+    try {
+      code = await deps.runLogin(loginArgv);
+    } finally {
+      for (const k of restorationKeys) {
+        if (originalValues[k] === void 0) delete process.env[k];
+        else process.env[k] = originalValues[k];
+      }
+    }
+    if (code !== 0) {
+      deps.printErr(
+        "Setup: login step failed \u2014 daemon is still running, re-run `muhaven-broker login` to retry."
+      );
+      if (daemonPid !== null) {
+        const killCmd = deps.platformId === "win32" ? `Stop-Process -Id ${daemonPid}` : `kill ${daemonPid}`;
+        deps.printErr(`  (daemon PID ${daemonPid}; stop with: ${killCmd})`);
+      }
+      return code;
+    }
+  }
+  deps.print("");
+  deps.print("================================");
+  deps.print("Setup complete.");
+  if (daemonPid !== null) {
+    deps.print(`  Daemon PID : ${daemonPid}`);
+    const killCmd = deps.platformId === "win32" ? `Stop-Process -Id ${daemonPid}` : `kill ${daemonPid}`;
+    deps.print(`  Stop daemon: ${killCmd}`);
+  } else {
+    deps.print("  Daemon     : already running");
+  }
+  deps.print(`  Endpoint   : ${config.brokerEndpoint}`);
+  deps.print("  Sign out   : muhaven-broker logout   (clears JWT, leaves daemon running)");
+  if (mintedKey) {
+    deps.print("  Session key: ephemeral \u2014 minted by setup, lives only in the daemon process.");
+  }
+  deps.print("================================");
+  return 0;
+}
 
 // src/broker/cli.ts
 function print(line) {
@@ -941,7 +1270,7 @@ function printErr(line) {
   process.stderr.write(line + "\n");
 }
 function detectMcpHost() {
-  return process.env.MCP_HOST_NAME ?? process.env.CLAUDE_CODE_HOST ?? process.env.npm_lifecycle_event ?? "muhaven-broker-cli";
+  return process.env.MCP_HOST_NAME ?? process.env.CLAUDE_CODE_HOST ?? "muhaven-broker-cli";
 }
 function detectEnvironment() {
   const warnings = [];
@@ -1195,11 +1524,44 @@ function printUsage() {
   print("usage: muhaven-broker [<subcommand>] [options]");
   print("");
   print("  (no subcommand)    Run the daemon (production mode)");
+  print("  setup              One-shot install: env defaults + session key + detached daemon + login");
+  print("                       [--foreground|-f] keeps the daemon attached (skip background spawn)");
+  print("                       [--skip-login] starts the daemon but lets you run login later");
+  print("                       [--no-launch-browser] pass-through to login");
   print("  login              Acquire a JWT via the device-code flow + store in keystore");
   print("                       [--from-daemon] resolves backend/dashboard URLs from the running daemon");
   print("  logout             Clear the JWT from the keystore");
   print("  doctor             Print environment + keystore + reachability report");
   print("  -h, --help         Show this help");
+  print("  -v, --version      Print the @muhaven/mcp package version");
+}
+function getBrokerPackageVersion() {
+  {
+    return "0.1.4";
+  }
+}
+function printVersion() {
+  print(`muhaven-broker @muhaven/mcp@${getBrokerPackageVersion()}`);
+}
+function resolveBrokerBinPath() {
+  return resolve(__dirname$1, "..", "bin", "muhaven-broker.cjs");
+}
+async function runSetup2(argv) {
+  const deps = {
+    print,
+    printErr,
+    mintSessionKey,
+    newBrokerClient: (endpoint, timeoutMs) => new BrokerClient({ endpoint, timeoutMs }),
+    spawnDaemon,
+    waitForBroker,
+    runLogin,
+    runForegroundDaemon: runBrokerDaemonCli,
+    resolveBinPath: resolveBrokerBinPath,
+    env: process.env,
+    platformId: process.platform,
+    osRelease: release()
+  };
+  return runSetup(argv, deps);
 }
 async function runCli(argv) {
   const [sub, ...rest] = argv;
@@ -1207,6 +1569,8 @@ async function runCli(argv) {
     case void 0:
       await runBrokerDaemonCli();
       return 0;
+    case "setup":
+      return runSetup2(rest);
     case "login":
       return runLogin(rest);
     case "logout":
@@ -1217,6 +1581,10 @@ async function runCli(argv) {
     case "--help":
       printUsage();
       return 0;
+    case "-v":
+    case "--version":
+      printVersion();
+      return 0;
     default:
       printErr(`unknown subcommand: ${sub}`);
       printUsage();
@@ -1224,4 +1592,4 @@ async function runCli(argv) {
   }
 }
 
-export { parseLoginFlags, runCli, runDoctor, runLogin, runLogout };
+export { getBrokerPackageVersion, parseLoginFlags, runCli, runDoctor, runLogin, runLogout, runSetup2 as runSetup };

package/dist/index.cjs

@@ -1210,7 +1210,7 @@ var SERVER_NAME = "@muhaven/mcp";
 var SERVER_VERSION = resolveServerVersion();
 function resolveServerVersion() {
   {
-    return "0.1.3";
+    return "0.1.4";
   }
 }
 function toJsonInputSchema(schema) {

package/dist/index.js

@@ -1206,7 +1206,7 @@ var SERVER_NAME = "@muhaven/mcp";
 var SERVER_VERSION = resolveServerVersion();
 function resolveServerVersion() {
   {
-    return "0.1.3";
+    return "0.1.4";
   }
 }
 function toJsonInputSchema(schema) {

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.2",
   "name": "muhaven-mcp",
   "display_name": "MuHaven (RWA portfolio)",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Confidential RWA portfolio management on Fhenix CoFHE. Read your encrypted balances, propose yield claims and policy changes — all signing happens in a sibling broker daemon, the LLM never sees your private key.",
   "long_description": "MuHaven MCP exposes 22 tools across read.* / position.* / policy.* / issuer.* / governance.* groups for managing real-world asset (RWA) tokens with FHE-encrypted balances. Authentication uses a one-time device-code ceremony (run `muhaven-broker login`); subsequent tool calls fetch the JWT from the broker over a Unix socket. Position / governance tools return unsigned UserOps + broker signatures — they NEVER auto-submit to a bundler. The companion `muhaven-broker` daemon must be running before tools can be invoked. See README for setup.",
   "author": {
@@ -94,5 +94,5 @@
       "sensitive": false
     }
   ],
-  "$comment_setup": "First-run instructions: (1) install this package via your MCPB host (Claude Desktop / Cursor / Claude Code). (2) Start the broker daemon: `muhaven-broker` (running in the background; see README for systemd / launchd / Windows-Service recipes). (3) Authenticate: `muhaven-broker login` — opens browser to https://muhaven.app/link?code=XXXX-XXXX, complete passkey ceremony. (4) Use any tool in this MCP package."
+  "$comment_setup": "First-run instructions: (1) install this package via your MCPB host (Claude Desktop / Cursor / Claude Code) or globally via `npm install -g @muhaven/mcp`. (2) Run `muhaven-broker setup` — one-shot: applies env defaults, mints an ephemeral session key, spawns the broker daemon detached, then walks you through the passkey-bound device-code login (opens browser to https://muhaven.app/link?code=XXXX-XXXX). The daemon stays running after `setup` returns. Use `muhaven-broker setup --foreground` if systemd / launchd / a Windows service will own the daemon's lifecycle instead. (3) Use any tool in this MCP package."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muhaven/mcp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "MuHaven MCP server — read/position/policy toolsets bridging Claude Desktop / Cursor / Claude Code to the MuHaven backend, with a sibling muhaven-broker daemon holding the session-key private half over a local IPC socket",
   "type": "module",
   "repository": {