@muhaven/mcp 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -7,6 +7,161 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.7] — 2026-05-18
+
+`position.*` tools can now drive real on-chain action via @muhaven/mcp
+— Path C of MCP Option A (dashboard URL elicitation → existing passkey
+ceremony). Pre-0.1.7, position tools returned a placeholder UserOp
+envelope + broker signature that no host could submit; the path was
+attestation-only despite implying buy/sell/claim. 0.1.7 swaps the
+envelope for a pre-filled dashboard deep-link URL the user opens to
+review + tap their passkey through the existing dashboard flow.
+
+### Added
+
+- **`muhaven.cash.wrap`** — new tool. Returns a `/cash?amount=` deep-
+  link for USDC → mhUSDC conversion. Common LLM chain: `read.portfolio`
+  → notice 0 mhUSDC → `cash.wrap` → then `position.buy` (each is its
+  own user-confirmed deep-link). Input is human-readable USDC ("100" =
+  $100). 23 tools total now (was 22).
+
+- **Token identifier accepts symbols OR addresses.** Every `position.*`
+  tool's `token` field used to require a 0x-address. Now accepts either
+  a symbol ("TBILL1") or a 0x-address. The dashboard pages resolve the
+  symbol via the marketplace store; unknown identifiers leave the form
+  blank for the user to fill in. Saves the LLM a round-trip through
+  `read.tokens` for the common "buy 5 of TBILL1" flow.
+
+- **Exported pure helpers** (`buildPositionDeeplink`,
+  `formatUsdc6ToDecimal`) so third-party MCP servers + tests can reason
+  about the URL shape without spawning anything.
+
+### Changed
+
+- **`position.buy/sell/claim` return shape** is now `{ dashboardUrl,
+  action, instructions, echo }` instead of `{ intentHash,
+  unsignedUserOp, brokerSignature, signerAddress }`. The `instructions`
+  field is a pre-formatted two-line string the LLM can show the user
+  verbatim ("Open this link to review and authorize..."). The `echo`
+  field mirrors input for LLM self-verification. **Breaking** for any
+  consumer that pinned the 0.1.6 response shape — the prior shape was
+  itself never end-to-end usable (placeholder envelope), so the
+  practical impact is "MCP buy now actually works" rather than
+  regression.
+
+- **`position.rebalance`** returns `not_implemented` with a clear
+  next-step hint pointing at single-leg `position.buy` / `position.sell`
+  or the dashboard. Multi-leg `execute_plan` (one URL, one passkey,
+  one batched UserOp) lands in Wave 5 with composite preview UI.
+
+- **Broker dep no longer required for position tools.** Previously, a
+  `position.buy` call without a running `muhaven-broker` daemon
+  returned `broker.unavailable`. Now position tools talk only to the
+  dashboard URL — the broker is still needed for `read.*` / governance
+  / issuer / policy tools (those use the JWT-authed path).
+
+### Removed
+
+- `signEnvelope` + `PositionEnvelopeData` + the per-process
+  `hasSessionKey` probe cache + `__resetSessionKeyProbeCacheForTests`'s
+  cache (the function is retained as a no-op for back-compat with any
+  test harness importing it). The whole broker-attestation path for
+  position tools is gone — they don't need a signing key at all.
+
+### Internal
+
+- 21 new vitest cases in `__tests__/position-deeplink.test.ts`,
+  replacing `session-key-required.test.ts` (deleted — covered a
+  removed code path). Total `@muhaven/mcp` suite: **262/262 passing**
+  (was 241). Tool-hash count: **23** (was 22).
+
+### Operator notes
+
+- Once installed, the fresh-install ritual is unchanged: `muhaven-broker
+  setup --register claude-code` still wires the MCP server into Claude
+  Code via `claude mcp add-json`.
+- Existing 0.1.6 installs: `npm install -g @muhaven/mcp@latest` picks up
+  the new bin; no setup re-run needed.
+- `MUHAVEN_DASHBOARD_URL` env var (defaults to `https://muhaven.app`)
+  now drives the deep-link URL prefix; staging operators set it to
+  `https://muhaven-staging.example` and the URLs flow through.
+
+## [0.1.6] — 2026-05-17
+
+Adds `muhaven-broker setup --register HOST` so a fresh install no longer
+requires hand-writing a `.mcp.json` (or equivalent host-config file).
+This closes the last manual step of the install ritual — operators run
+one command end-to-end from `npm install -g @muhaven/mcp` to a working
+MCP server registered with their host.
+
+Initial host coverage: **Claude Code** (via `claude mcp add-json`).
+`claude-desktop` and `cursor` are reserved as known host names — they
+parse cleanly today but the registrar declines to act and points the
+operator at the per-host JSON snippet in `docs.muhaven.app/mcp/install`.
+Both ship in a Wave 5 follow-up (file-edit registrars need merge-then-
+write semantics + dedicated tests).
+
+### Added
+
+- **`muhaven-broker setup --register HOST[,HOST...]` flag** — auto-wire
+  the MCP server into one or more host configs after the login step:
+  - **claude-code** (live): probes `claude --version`, removes any
+    existing `muhaven` entry (idempotent), then runs
+    `claude mcp add-json muhaven '{"type":"stdio","command":"muhaven-mcp","env":{...}}' --scope <scope>`.
+    `env` carries `MUHAVEN_BACKEND_URL`, `MUHAVEN_DASHBOARD_URL`, and
+    `MUHAVEN_KEYRING` when set (the broker session key + endpoint stay
+    daemon-only — never baked into the host config).
+  - **claude-desktop / cursor**: reserved names. Parse cleanly; registrar
+    short-circuits with a "not implemented yet" hint pointing at the
+    docs snippet. Adding a host is a focused diff: implement the
+    registrar + extend `KNOWN_REGISTER_HOSTS`.
+  - Accepts comma-separated values (`--register claude-code,cursor`) and
+    repeated flags (`--register claude-code --register cursor`). Dedupes
+    across both forms.
+  - Unknown host names fail fast with exit code 2 + the allowlist in the
+    error message.
+
+- **`--register-scope user|project|local` flag** — scope for the
+  `claude mcp add-json` call. Default `user` (every project on this
+  machine sees the server — matches the per-user broker model);
+  `project` writes `.mcp.json` at CWD (git-shared if you commit it);
+  `local` writes `~/.claude.json` as a per-project user-only entry
+  (Claude Code's `claude mcp add` default).
+
+- **Pure helpers exported from `src/broker/setup.ts`** for testing +
+  third-party reuse: `buildRegisterEnv`, `buildClaudeMcpRegisterJson`,
+  `buildClaudeMcpAddJsonArgv`, `buildClaudeMcpRemoveArgv`,
+  `registerWithHost`. Plus type exports for `RegisterHost`,
+  `RegisterScope`, `RegisterHostOutcome`, `ShellResult`, and the
+  `KNOWN_REGISTER_HOSTS` + `KNOWN_REGISTER_SCOPES` constants.
+
+- **`SetupDeps.shellOut`** seam — abstracts child-process execution so
+  tests can script the host-CLI responses without spawning real
+  binaries. Default implementation in `cli.ts` uses `node:child_process`
+  `spawn` (argv-safe — no shell interpolation of the JSON payload).
+
+### Operator UX
+
+- Setup's exit code is **0 on register failure**. The broker daemon and
+  JWT (the load-bearing artifacts) are already in place; an opt-in
+  registration failure surfaces as a warning on stderr with the exact
+  re-run hint and a fallback link to the per-host JSON snippet. This
+  matches the existing pattern for `--skip-login` (operator can complete
+  the missing step in isolation later).
+
+- A `cli_missing` outcome (claude binary not on PATH) is distinct from
+  a `failed` outcome (claude ran but errored). The error copy reflects
+  which: operators on a machine without Claude Code get an "install
+  Claude Code" prompt; operators with Claude Code installed get the
+  CLI's actual error message.
+
+### Tests
+
+- **35 new vitest cases** covering `parseSetupFlags --register / 
+  --register-scope` (11), pure helpers (12), and the `registerWithHost`
+  + `runSetup` integration (12). Total `__tests__/setup.test.ts` now
+  93 cases. Full `@muhaven/mcp` suite: 241 cases passing.
+
 ## [0.1.5] — 2026-05-17
 
 Adds the `muhaven-broker stop` subcommand so operators can cleanly tear

package/dist/broker.cjs

@@ -1047,6 +1047,12 @@ async function waitForBroker(options) {
     `muhaven-broker daemon did not become reachable within ${timeoutMs}ms: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`
   );
 }
+var KNOWN_REGISTER_HOSTS = [
+  "claude-code",
+  "claude-desktop",
+  "cursor"
+];
+var KNOWN_REGISTER_SCOPES = ["user", "project", "local"];
 function parseSetupFlags(argv) {
   let foreground = false;
   let noLaunchBrowser = false;
@@ -1054,6 +1060,8 @@ function parseSetupFlags(argv) {
   let backendBaseUrl;
   let dashboardBaseUrl;
   let skipLogin = false;
+  const register = [];
+  let registerScope = "user";
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--foreground" || a === "-f") foreground = true;
@@ -1062,7 +1070,29 @@ function parseSetupFlags(argv) {
     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}`);
+    else if (a === "--register" && i + 1 < argv.length) {
+      const value = argv[++i];
+      for (const raw of value.split(",")) {
+        const host = raw.trim().toLowerCase();
+        if (host === "") continue;
+        if (!KNOWN_REGISTER_HOSTS.includes(host)) {
+          throw new Error(
+            `unknown --register host: ${JSON.stringify(host)} (expected one of ${KNOWN_REGISTER_HOSTS.join(", ")})`
+          );
+        }
+        if (!register.includes(host)) {
+          register.push(host);
+        }
+      }
+    } else if (a === "--register-scope" && i + 1 < argv.length) {
+      const value = argv[++i];
+      if (!KNOWN_REGISTER_SCOPES.includes(value)) {
+        throw new Error(
+          `unknown --register-scope: ${JSON.stringify(value)} (expected one of ${KNOWN_REGISTER_SCOPES.join(", ")})`
+        );
+      }
+      registerScope = value;
+    } else throw new Error(`unknown flag: ${a}`);
   }
   return {
     foreground,
@@ -1070,9 +1100,77 @@ function parseSetupFlags(argv) {
     brokerEndpoint,
     backendBaseUrl,
     dashboardBaseUrl,
-    skipLogin
+    skipLogin,
+    register,
+    registerScope
   };
 }
+function buildRegisterEnv(effectiveEnv) {
+  const env = {};
+  if (effectiveEnv.MUHAVEN_BACKEND_URL) env.MUHAVEN_BACKEND_URL = effectiveEnv.MUHAVEN_BACKEND_URL;
+  if (effectiveEnv.MUHAVEN_DASHBOARD_URL) env.MUHAVEN_DASHBOARD_URL = effectiveEnv.MUHAVEN_DASHBOARD_URL;
+  if (effectiveEnv.MUHAVEN_KEYRING) env.MUHAVEN_KEYRING = effectiveEnv.MUHAVEN_KEYRING;
+  return env;
+}
+function buildClaudeMcpRegisterJson(registerEnv) {
+  const payload = {
+    type: "stdio",
+    command: "muhaven-mcp"
+  };
+  if (Object.keys(registerEnv).length > 0) {
+    payload.env = registerEnv;
+  }
+  return JSON.stringify(payload);
+}
+function buildClaudeMcpAddJsonArgv(serverName, json, scope) {
+  return ["mcp", "add-json", serverName, json, "--scope", scope];
+}
+function buildClaudeMcpRemoveArgv(serverName, scope) {
+  return ["mcp", "remove", serverName, "--scope", scope];
+}
+async function registerWithHost(deps, options) {
+  if (options.host === "claude-code") {
+    return registerWithClaudeCode(deps, options);
+  }
+  return { status: "not_implemented", host: options.host };
+}
+async function registerWithClaudeCode(deps, options) {
+  let probe;
+  try {
+    probe = await deps.shellOut("claude", ["--version"]);
+  } catch (err) {
+    return {
+      status: "cli_missing",
+      host: options.host,
+      cmd: `claude --version (${err.message})`
+    };
+  }
+  if (probe.exitCode !== 0) {
+    return {
+      status: "cli_missing",
+      host: options.host,
+      cmd: "claude --version"
+    };
+  }
+  await deps.shellOut("claude", buildClaudeMcpRemoveArgv(options.serverName, options.scope));
+  const json = buildClaudeMcpRegisterJson(options.registerEnv);
+  const addArgv = buildClaudeMcpAddJsonArgv(options.serverName, json, options.scope);
+  let add;
+  try {
+    add = await deps.shellOut("claude", addArgv);
+  } catch (err) {
+    return {
+      status: "failed",
+      host: options.host,
+      reason: `spawn claude failed: ${err.message}`
+    };
+  }
+  if (add.exitCode !== 0) {
+    const reason = [add.stderr, add.stdout].map((s) => s.trim()).filter((s) => s.length > 0).join(" | ") || `exit ${add.exitCode}`;
+    return { status: "failed", host: options.host, reason };
+  }
+  return { status: "registered", host: options.host, scope: options.scope };
+}
 async function runSetup(argv, deps) {
   let flags;
   try {
@@ -1080,7 +1178,7 @@ async function runSetup(argv, deps) {
   } 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]"
+      "usage: muhaven-broker setup [--foreground|-f] [--no-launch-browser] [--skip-login]\n                            [--broker-endpoint PATH] [--backend-base-url URL]\n                            [--dashboard-base-url URL]\n                            [--register HOST[,HOST...]] [--register-scope user|project|local]"
     );
     return 2;
   }
@@ -1243,6 +1341,39 @@ async function runSetup(argv, deps) {
       return code;
     }
   }
+  if (flags.register.length > 0) {
+    const registerEnv = buildRegisterEnv(effectiveEnv);
+    for (const host of flags.register) {
+      const outcome = await registerWithHost(deps, {
+        host,
+        scope: flags.registerScope,
+        serverName: "muhaven",
+        registerEnv
+      });
+      switch (outcome.status) {
+        case "registered":
+          deps.print(
+            `Host register: ${outcome.host} wired (scope: ${outcome.scope}). Restart the host to pick up the new MCP server.`
+          );
+          break;
+        case "cli_missing":
+          deps.printErr(
+            `Host register: ${outcome.host} CLI not found on PATH (${outcome.cmd}). Install Claude Code and re-run \`muhaven-broker setup --register ${outcome.host}\`, or copy the JSON snippet from https://docs.muhaven.app/mcp/install#step-3-wire-your-host`
+          );
+          break;
+        case "not_implemented":
+          deps.printErr(
+            `Host register: ${outcome.host} registrar not implemented yet (Wave 5). Use the JSON snippet from https://docs.muhaven.app/mcp/install#step-3-wire-your-host for now.`
+          );
+          break;
+        case "failed":
+          deps.printErr(
+            `Host register: ${outcome.host} failed \u2014 ${outcome.reason}. Setup continues; re-run \`muhaven-broker setup --register ${outcome.host}\` after fixing.`
+          );
+          break;
+      }
+    }
+  }
   deps.print("");
   deps.print("================================");
   deps.print("Setup complete.");
@@ -1604,6 +1735,10 @@ function printUsage() {
   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("                       [--register HOST[,HOST...]] auto-wire the MCP server into the named host");
+  print("                         (claude-code today; claude-desktop / cursor reserved for Wave 5)");
+  print("                       [--register-scope user|project|local] scope for the host-config write");
+  print("                         (default: user \u2014 every project sees the server)");
   print("  stop               Cleanly stop a running daemon (SIGTERM with SIGKILL fallback");
   print("                       after 5s). Also clears the keystore JWT as a best effort.");
   print("  login              Acquire a JWT via the device-code flow + store in keystore");
@@ -1615,7 +1750,7 @@ function printUsage() {
 }
 function getBrokerPackageVersion() {
   {
-    return "0.1.5";
+    return "0.1.7";
   }
 }
 function printVersion() {
@@ -1624,6 +1759,33 @@ function printVersion() {
 function resolveBrokerBinPath() {
   return path.resolve(__dirname, "..", "bin", "muhaven-broker.cjs");
 }
+function defaultShellOut(cmd, argv) {
+  return new Promise((resolve, reject) => {
+    const child = child_process.spawn(cmd, argv, {
+      // Inherit env so PATH + npm-shim resolution work; explicitly NOT
+      // forwarding stdio so the parent's transcript stays clean.
+      stdio: ["ignore", "pipe", "pipe"],
+      // Windows: .cmd / .ps1 shims under %APPDATA%\npm need cmd.exe
+      // to interpret them. Node 18+ auto-routes through cmd.exe when
+      // it sees a non-.exe extension, but explicitly setting
+      // `shell: true` on Windows is safer for npm-global PATH entries.
+      // On POSIX, `shell: false` (the default) is correct + safer.
+      shell: process.platform === "win32"
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString("utf-8");
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString("utf-8");
+    });
+    child.on("error", (err) => reject(err));
+    child.on("close", (code) => {
+      resolve({ exitCode: code ?? 0, stdout, stderr });
+    });
+  });
+}
 async function runSetup2(argv) {
   const deps = {
     print,
@@ -1637,7 +1799,8 @@ async function runSetup2(argv) {
     resolveBinPath: resolveBrokerBinPath,
     env: process.env,
     platformId: process.platform,
-    osRelease: os.release()
+    osRelease: os.release(),
+    shellOut: defaultShellOut
   };
   return runSetup(argv, deps);
 }

package/dist/broker.js

@@ -1049,6 +1049,12 @@ async function waitForBroker(options) {
     `muhaven-broker daemon did not become reachable within ${timeoutMs}ms: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`
   );
 }
+var KNOWN_REGISTER_HOSTS = [
+  "claude-code",
+  "claude-desktop",
+  "cursor"
+];
+var KNOWN_REGISTER_SCOPES = ["user", "project", "local"];
 function parseSetupFlags(argv) {
   let foreground = false;
   let noLaunchBrowser = false;
@@ -1056,6 +1062,8 @@ function parseSetupFlags(argv) {
   let backendBaseUrl;
   let dashboardBaseUrl;
   let skipLogin = false;
+  const register = [];
+  let registerScope = "user";
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--foreground" || a === "-f") foreground = true;
@@ -1064,7 +1072,29 @@ function parseSetupFlags(argv) {
     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}`);
+    else if (a === "--register" && i + 1 < argv.length) {
+      const value = argv[++i];
+      for (const raw of value.split(",")) {
+        const host = raw.trim().toLowerCase();
+        if (host === "") continue;
+        if (!KNOWN_REGISTER_HOSTS.includes(host)) {
+          throw new Error(
+            `unknown --register host: ${JSON.stringify(host)} (expected one of ${KNOWN_REGISTER_HOSTS.join(", ")})`
+          );
+        }
+        if (!register.includes(host)) {
+          register.push(host);
+        }
+      }
+    } else if (a === "--register-scope" && i + 1 < argv.length) {
+      const value = argv[++i];
+      if (!KNOWN_REGISTER_SCOPES.includes(value)) {
+        throw new Error(
+          `unknown --register-scope: ${JSON.stringify(value)} (expected one of ${KNOWN_REGISTER_SCOPES.join(", ")})`
+        );
+      }
+      registerScope = value;
+    } else throw new Error(`unknown flag: ${a}`);
   }
   return {
     foreground,
@@ -1072,9 +1102,77 @@ function parseSetupFlags(argv) {
     brokerEndpoint,
     backendBaseUrl,
     dashboardBaseUrl,
-    skipLogin
+    skipLogin,
+    register,
+    registerScope
   };
 }
+function buildRegisterEnv(effectiveEnv) {
+  const env = {};
+  if (effectiveEnv.MUHAVEN_BACKEND_URL) env.MUHAVEN_BACKEND_URL = effectiveEnv.MUHAVEN_BACKEND_URL;
+  if (effectiveEnv.MUHAVEN_DASHBOARD_URL) env.MUHAVEN_DASHBOARD_URL = effectiveEnv.MUHAVEN_DASHBOARD_URL;
+  if (effectiveEnv.MUHAVEN_KEYRING) env.MUHAVEN_KEYRING = effectiveEnv.MUHAVEN_KEYRING;
+  return env;
+}
+function buildClaudeMcpRegisterJson(registerEnv) {
+  const payload = {
+    type: "stdio",
+    command: "muhaven-mcp"
+  };
+  if (Object.keys(registerEnv).length > 0) {
+    payload.env = registerEnv;
+  }
+  return JSON.stringify(payload);
+}
+function buildClaudeMcpAddJsonArgv(serverName, json, scope) {
+  return ["mcp", "add-json", serverName, json, "--scope", scope];
+}
+function buildClaudeMcpRemoveArgv(serverName, scope) {
+  return ["mcp", "remove", serverName, "--scope", scope];
+}
+async function registerWithHost(deps, options) {
+  if (options.host === "claude-code") {
+    return registerWithClaudeCode(deps, options);
+  }
+  return { status: "not_implemented", host: options.host };
+}
+async function registerWithClaudeCode(deps, options) {
+  let probe;
+  try {
+    probe = await deps.shellOut("claude", ["--version"]);
+  } catch (err) {
+    return {
+      status: "cli_missing",
+      host: options.host,
+      cmd: `claude --version (${err.message})`
+    };
+  }
+  if (probe.exitCode !== 0) {
+    return {
+      status: "cli_missing",
+      host: options.host,
+      cmd: "claude --version"
+    };
+  }
+  await deps.shellOut("claude", buildClaudeMcpRemoveArgv(options.serverName, options.scope));
+  const json = buildClaudeMcpRegisterJson(options.registerEnv);
+  const addArgv = buildClaudeMcpAddJsonArgv(options.serverName, json, options.scope);
+  let add;
+  try {
+    add = await deps.shellOut("claude", addArgv);
+  } catch (err) {
+    return {
+      status: "failed",
+      host: options.host,
+      reason: `spawn claude failed: ${err.message}`
+    };
+  }
+  if (add.exitCode !== 0) {
+    const reason = [add.stderr, add.stdout].map((s) => s.trim()).filter((s) => s.length > 0).join(" | ") || `exit ${add.exitCode}`;
+    return { status: "failed", host: options.host, reason };
+  }
+  return { status: "registered", host: options.host, scope: options.scope };
+}
 async function runSetup(argv, deps) {
   let flags;
   try {
@@ -1082,7 +1180,7 @@ async function runSetup(argv, deps) {
   } 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]"
+      "usage: muhaven-broker setup [--foreground|-f] [--no-launch-browser] [--skip-login]\n                            [--broker-endpoint PATH] [--backend-base-url URL]\n                            [--dashboard-base-url URL]\n                            [--register HOST[,HOST...]] [--register-scope user|project|local]"
     );
     return 2;
   }
@@ -1245,6 +1343,39 @@ async function runSetup(argv, deps) {
       return code;
     }
   }
+  if (flags.register.length > 0) {
+    const registerEnv = buildRegisterEnv(effectiveEnv);
+    for (const host of flags.register) {
+      const outcome = await registerWithHost(deps, {
+        host,
+        scope: flags.registerScope,
+        serverName: "muhaven",
+        registerEnv
+      });
+      switch (outcome.status) {
+        case "registered":
+          deps.print(
+            `Host register: ${outcome.host} wired (scope: ${outcome.scope}). Restart the host to pick up the new MCP server.`
+          );
+          break;
+        case "cli_missing":
+          deps.printErr(
+            `Host register: ${outcome.host} CLI not found on PATH (${outcome.cmd}). Install Claude Code and re-run \`muhaven-broker setup --register ${outcome.host}\`, or copy the JSON snippet from https://docs.muhaven.app/mcp/install#step-3-wire-your-host`
+          );
+          break;
+        case "not_implemented":
+          deps.printErr(
+            `Host register: ${outcome.host} registrar not implemented yet (Wave 5). Use the JSON snippet from https://docs.muhaven.app/mcp/install#step-3-wire-your-host for now.`
+          );
+          break;
+        case "failed":
+          deps.printErr(
+            `Host register: ${outcome.host} failed \u2014 ${outcome.reason}. Setup continues; re-run \`muhaven-broker setup --register ${outcome.host}\` after fixing.`
+          );
+          break;
+      }
+    }
+  }
   deps.print("");
   deps.print("================================");
   deps.print("Setup complete.");
@@ -1606,6 +1737,10 @@ function printUsage() {
   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("                       [--register HOST[,HOST...]] auto-wire the MCP server into the named host");
+  print("                         (claude-code today; claude-desktop / cursor reserved for Wave 5)");
+  print("                       [--register-scope user|project|local] scope for the host-config write");
+  print("                         (default: user \u2014 every project sees the server)");
   print("  stop               Cleanly stop a running daemon (SIGTERM with SIGKILL fallback");
   print("                       after 5s). Also clears the keystore JWT as a best effort.");
   print("  login              Acquire a JWT via the device-code flow + store in keystore");
@@ -1617,7 +1752,7 @@ function printUsage() {
 }
 function getBrokerPackageVersion() {
   {
-    return "0.1.5";
+    return "0.1.7";
   }
 }
 function printVersion() {
@@ -1626,6 +1761,33 @@ function printVersion() {
 function resolveBrokerBinPath() {
   return resolve(__dirname$1, "..", "bin", "muhaven-broker.cjs");
 }
+function defaultShellOut(cmd, argv) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, argv, {
+      // Inherit env so PATH + npm-shim resolution work; explicitly NOT
+      // forwarding stdio so the parent's transcript stays clean.
+      stdio: ["ignore", "pipe", "pipe"],
+      // Windows: .cmd / .ps1 shims under %APPDATA%\npm need cmd.exe
+      // to interpret them. Node 18+ auto-routes through cmd.exe when
+      // it sees a non-.exe extension, but explicitly setting
+      // `shell: true` on Windows is safer for npm-global PATH entries.
+      // On POSIX, `shell: false` (the default) is correct + safer.
+      shell: process.platform === "win32"
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString("utf-8");
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString("utf-8");
+    });
+    child.on("error", (err) => reject(err));
+    child.on("close", (code) => {
+      resolve({ exitCode: code ?? 0, stdout, stderr });
+    });
+  });
+}
 async function runSetup2(argv) {
   const deps = {
     print,
@@ -1639,7 +1801,8 @@ async function runSetup2(argv) {
     resolveBinPath: resolveBrokerBinPath,
     env: process.env,
     platformId: process.platform,
-    osRelease: release()
+    osRelease: release(),
+    shellOut: defaultShellOut
   };
   return runSetup(argv, deps);
 }