@muhaven/mcp 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -7,6 +7,129 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+down a detached daemon spawned by `muhaven-broker setup` without
+hunting for PIDs in `ps` output or hand-rolling `taskkill` recipes.
+Surfaced after `muhaven-broker setup` lands in 0.1.4 — operators
+naturally asked "how do I stop this?" and the answer (`muhaven-broker
+logout` + manual `kill`) was non-obvious.
+
+### Added
+
+- **`muhaven-broker stop` subcommand** — clean shutdown:
+  - Probes the broker via `hello()`. Unreachable → "not running,
+    nothing to stop." exit 0.
+  - Best-effort `clearJwt()` so the OS keychain doesn't keep a stale
+    JWT after shutdown. Warning + continue on failure (don't abort
+    the kill).
+  - Reads `hello.pid` (new optional field — see below). On pre-0.1.5
+    daemons that omit the field, prints a manual-kill hint with
+    cross-platform commands and exits 1.
+  - `process.kill(pid, 'SIGTERM')` → polls `hello()` until it fails
+    (clean exit) or 5s elapses, then `process.kill(pid, 'SIGKILL')`.
+  - Pure orchestrator (`runStop` in `src/broker/stop.ts`) with
+    injectable IO so every branch is unit-testable without spawning
+    real processes.
+
+### Changed
+
+- **`hello` response gains optional `pid?: number`** field (broker
+  protocol stays at 0.3.0 — additive optional field, back-compat with
+  pre-0.1.5 daemons). Populated from `process.pid` at request-handle
+  time; consumers MUST handle `undefined` for older daemons.
+
+### Tests
+
+- 206 vitest pass (up from 197 in 0.1.4). Net +9 cases in new
+  `__tests__/stop.test.ts`:
+  - `runStop` not-running short-circuit
+  - happy path (hello → clearJwt → SIGTERM → exit-detected → 0)
+  - pre-0.1.5 daemon (no `pid` in hello) returns 1 with manual hint
+  - SIGKILL fallback after gracefulShutdownMs timeout
+  - SIGTERM permission error returns 1
+  - SIGKILL permission error returns 1 with "may be orphaned" hint
+  - `clearJwt` failure does NOT abort the kill (warning + continue)
+  - `defaultKillProcess` returns false on ESRCH (process gone)
+  - `defaultKillProcess` rethrows non-ESRCH errors (POSIX-only test)
+
 ## [0.1.4] — 2026-05-17
 
 Adds the one-shot `muhaven-broker setup` subcommand so a fresh install

package/dist/broker.cjs

@@ -658,7 +658,8 @@ async function handleBrokerRequest(req, signer, keystore, nowSec = () => Math.fl
         sessionKeyAddress: signer.address,
         hasJwt,
         hasSessionKey,
-        ...options.effectiveConfig ? { effectiveConfig: options.effectiveConfig } : {}
+        ...options.effectiveConfig ? { effectiveConfig: options.effectiveConfig } : {},
+        ...options.pid !== void 0 ? { pid: options.pid } : {}
       };
     }
     case "sign_hash": {
@@ -889,7 +890,8 @@ var BrokerDaemon = class {
           effectiveConfig: {
             backendBaseUrl: this.config.backendBaseUrl,
             dashboardBaseUrl: this.config.dashboardBaseUrl
-          }
+          },
+          pid: process.pid
         }
       );
       socket.end(serializeResponse(res));
@@ -1045,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;
@@ -1052,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;
@@ -1060,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,
@@ -1068,8 +1100,76 @@ 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;
@@ -1078,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;
   }
@@ -1241,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.");
@@ -1260,6 +1393,82 @@ async function runSetup(argv, deps) {
   return 0;
 }
 
+// src/broker/stop.ts
+async function runStop(deps) {
+  const gracefulShutdownMs = deps.gracefulShutdownMs ?? 5e3;
+  const pollIntervalMs = deps.pollIntervalMs ?? 200;
+  const broker = deps.newBrokerClient(deps.endpoint, deps.brokerTimeoutMs);
+  let hello;
+  try {
+    hello = await broker.hello();
+  } catch {
+    deps.print("Broker daemon: not running, nothing to stop.");
+    return 0;
+  }
+  try {
+    await broker.clearJwt();
+    deps.print("JWT cleared from keystore.");
+  } catch (err) {
+    deps.print(
+      `Warning: clearJwt failed (${err instanceof Error ? err.message : String(err)}); continuing with daemon shutdown.`
+    );
+  }
+  const pid = hello.pid;
+  if (pid === void 0) {
+    deps.printErr(
+      "Broker daemon did not advertise its PID (older than @muhaven/mcp@0.1.5)."
+    );
+    deps.printErr("Stop manually with:");
+    deps.printErr("  POSIX:   pkill -f muhaven-broker");
+    deps.printErr("  Windows: Stop-Process -Name node -Force  (filter to muhaven-broker)");
+    return 1;
+  }
+  try {
+    deps.killProcess(pid, "SIGTERM");
+    deps.print(`Sent SIGTERM to broker daemon (PID ${pid}). Waiting up to ${gracefulShutdownMs}ms for clean exit...`);
+  } catch (err) {
+    deps.printErr(
+      `Failed to send SIGTERM to PID ${pid}: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return 1;
+  }
+  const maxAttempts = Math.ceil(gracefulShutdownMs / pollIntervalMs);
+  for (let i = 0; i < maxAttempts; i++) {
+    await deps.sleep(pollIntervalMs);
+    try {
+      await broker.hello();
+    } catch {
+      deps.print("Broker daemon stopped cleanly.");
+      return 0;
+    }
+  }
+  deps.print(`Daemon did not exit after ${gracefulShutdownMs}ms \u2014 sending SIGKILL.`);
+  try {
+    deps.killProcess(pid, "SIGKILL");
+    deps.print(`Broker daemon force-killed (PID ${pid}).`);
+    return 0;
+  } catch (err) {
+    deps.printErr(
+      `Failed to SIGKILL PID ${pid}: ${err instanceof Error ? err.message : String(err)}`
+    );
+    deps.printErr(
+      "  Daemon process may be orphaned. Inspect with `ps aux | grep muhaven-broker` and kill manually."
+    );
+    return 1;
+  }
+}
+function defaultKillProcess(pid, signal) {
+  try {
+    process.kill(pid, signal);
+    return true;
+  } catch (err) {
+    if (err.code === "ESRCH") {
+      return false;
+    }
+    throw err;
+  }
+}
+
 // src/broker/cli.ts
 function print(line) {
   process.stdout.write(line + "\n");
@@ -1526,16 +1735,22 @@ 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");
   print("                       [--from-daemon] resolves backend/dashboard URLs from the running daemon");
-  print("  logout             Clear the JWT from the keystore");
+  print("  logout             Clear the JWT from the keystore (does NOT stop the daemon)");
   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";
+    return "0.1.6";
   }
 }
 function printVersion() {
@@ -1544,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,
@@ -1557,10 +1799,24 @@ async function runSetup2(argv) {
     resolveBinPath: resolveBrokerBinPath,
     env: process.env,
     platformId: process.platform,
-    osRelease: os.release()
+    osRelease: os.release(),
+    shellOut: defaultShellOut
   };
   return runSetup(argv, deps);
 }
+async function runStop2() {
+  const config = loadMcpConfig();
+  const deps = {
+    print,
+    printErr,
+    newBrokerClient: (endpoint, timeoutMs) => new BrokerClient({ endpoint, timeoutMs }),
+    killProcess: defaultKillProcess,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    endpoint: config.brokerEndpoint,
+    brokerTimeoutMs: config.brokerTimeoutMs
+  };
+  return runStop(deps);
+}
 async function runCli(argv) {
   const [sub, ...rest] = argv;
   switch (sub) {
@@ -1569,6 +1825,8 @@ async function runCli(argv) {
       return 0;
     case "setup":
       return runSetup2(rest);
+    case "stop":
+      return runStop2();
     case "login":
       return runLogin(rest);
     case "logout":
@@ -1597,3 +1855,4 @@ exports.runDoctor = runDoctor;
 exports.runLogin = runLogin;
 exports.runLogout = runLogout;
 exports.runSetup = runSetup2;
+exports.runStop = runStop2;

package/dist/broker.d.cts

@@ -39,6 +39,10 @@ declare function getBrokerPackageVersion(): string;
  * surface unnecessarily).
  */
 declare function runSetup(argv: readonly string[]): Promise<number>;
+/**
+ * Wire `runStop` against the real BrokerClient + Node's process.kill.
+ */
+declare function runStop(): Promise<number>;
 declare function runCli(argv: readonly string[]): Promise<number>;
 
-export { getBrokerPackageVersion, parseLoginFlags, runCli, runDoctor, runLogin, runLogout, runSetup };
+export { getBrokerPackageVersion, parseLoginFlags, runCli, runDoctor, runLogin, runLogout, runSetup, runStop };

package/dist/broker.d.ts

@@ -39,6 +39,10 @@ declare function getBrokerPackageVersion(): string;
  * surface unnecessarily).
  */
 declare function runSetup(argv: readonly string[]): Promise<number>;
+/**
+ * Wire `runStop` against the real BrokerClient + Node's process.kill.
+ */
+declare function runStop(): Promise<number>;
 declare function runCli(argv: readonly string[]): Promise<number>;
 
-export { getBrokerPackageVersion, parseLoginFlags, runCli, runDoctor, runLogin, runLogout, runSetup };
+export { getBrokerPackageVersion, parseLoginFlags, runCli, runDoctor, runLogin, runLogout, runSetup, runStop };

package/dist/broker.js

@@ -660,7 +660,8 @@ async function handleBrokerRequest(req, signer, keystore, nowSec = () => Math.fl
         sessionKeyAddress: signer.address,
         hasJwt,
         hasSessionKey,
-        ...options.effectiveConfig ? { effectiveConfig: options.effectiveConfig } : {}
+        ...options.effectiveConfig ? { effectiveConfig: options.effectiveConfig } : {},
+        ...options.pid !== void 0 ? { pid: options.pid } : {}
       };
     }
     case "sign_hash": {
@@ -891,7 +892,8 @@ var BrokerDaemon = class {
           effectiveConfig: {
             backendBaseUrl: this.config.backendBaseUrl,
             dashboardBaseUrl: this.config.dashboardBaseUrl
-          }
+          },
+          pid: process.pid
         }
       );
       socket.end(serializeResponse(res));
@@ -1047,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;
@@ -1054,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;
@@ -1062,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,
@@ -1070,8 +1102,76 @@ 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;
@@ -1080,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;
   }
@@ -1243,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.");
@@ -1262,6 +1395,82 @@ async function runSetup(argv, deps) {
   return 0;
 }
 
+// src/broker/stop.ts
+async function runStop(deps) {
+  const gracefulShutdownMs = deps.gracefulShutdownMs ?? 5e3;
+  const pollIntervalMs = deps.pollIntervalMs ?? 200;
+  const broker = deps.newBrokerClient(deps.endpoint, deps.brokerTimeoutMs);
+  let hello;
+  try {
+    hello = await broker.hello();
+  } catch {
+    deps.print("Broker daemon: not running, nothing to stop.");
+    return 0;
+  }
+  try {
+    await broker.clearJwt();
+    deps.print("JWT cleared from keystore.");
+  } catch (err) {
+    deps.print(
+      `Warning: clearJwt failed (${err instanceof Error ? err.message : String(err)}); continuing with daemon shutdown.`
+    );
+  }
+  const pid = hello.pid;
+  if (pid === void 0) {
+    deps.printErr(
+      "Broker daemon did not advertise its PID (older than @muhaven/mcp@0.1.5)."
+    );
+    deps.printErr("Stop manually with:");
+    deps.printErr("  POSIX:   pkill -f muhaven-broker");
+    deps.printErr("  Windows: Stop-Process -Name node -Force  (filter to muhaven-broker)");
+    return 1;
+  }
+  try {
+    deps.killProcess(pid, "SIGTERM");
+    deps.print(`Sent SIGTERM to broker daemon (PID ${pid}). Waiting up to ${gracefulShutdownMs}ms for clean exit...`);
+  } catch (err) {
+    deps.printErr(
+      `Failed to send SIGTERM to PID ${pid}: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return 1;
+  }
+  const maxAttempts = Math.ceil(gracefulShutdownMs / pollIntervalMs);
+  for (let i = 0; i < maxAttempts; i++) {
+    await deps.sleep(pollIntervalMs);
+    try {
+      await broker.hello();
+    } catch {
+      deps.print("Broker daemon stopped cleanly.");
+      return 0;
+    }
+  }
+  deps.print(`Daemon did not exit after ${gracefulShutdownMs}ms \u2014 sending SIGKILL.`);
+  try {
+    deps.killProcess(pid, "SIGKILL");
+    deps.print(`Broker daemon force-killed (PID ${pid}).`);
+    return 0;
+  } catch (err) {
+    deps.printErr(
+      `Failed to SIGKILL PID ${pid}: ${err instanceof Error ? err.message : String(err)}`
+    );
+    deps.printErr(
+      "  Daemon process may be orphaned. Inspect with `ps aux | grep muhaven-broker` and kill manually."
+    );
+    return 1;
+  }
+}
+function defaultKillProcess(pid, signal) {
+  try {
+    process.kill(pid, signal);
+    return true;
+  } catch (err) {
+    if (err.code === "ESRCH") {
+      return false;
+    }
+    throw err;
+  }
+}
+
 // src/broker/cli.ts
 function print(line) {
   process.stdout.write(line + "\n");
@@ -1528,16 +1737,22 @@ 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");
   print("                       [--from-daemon] resolves backend/dashboard URLs from the running daemon");
-  print("  logout             Clear the JWT from the keystore");
+  print("  logout             Clear the JWT from the keystore (does NOT stop the daemon)");
   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";
+    return "0.1.6";
   }
 }
 function printVersion() {
@@ -1546,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,
@@ -1559,10 +1801,24 @@ async function runSetup2(argv) {
     resolveBinPath: resolveBrokerBinPath,
     env: process.env,
     platformId: process.platform,
-    osRelease: release()
+    osRelease: release(),
+    shellOut: defaultShellOut
   };
   return runSetup(argv, deps);
 }
+async function runStop2() {
+  const config = loadMcpConfig();
+  const deps = {
+    print,
+    printErr,
+    newBrokerClient: (endpoint, timeoutMs) => new BrokerClient({ endpoint, timeoutMs }),
+    killProcess: defaultKillProcess,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    endpoint: config.brokerEndpoint,
+    brokerTimeoutMs: config.brokerTimeoutMs
+  };
+  return runStop(deps);
+}
 async function runCli(argv) {
   const [sub, ...rest] = argv;
   switch (sub) {
@@ -1571,6 +1827,8 @@ async function runCli(argv) {
       return 0;
     case "setup":
       return runSetup2(rest);
+    case "stop":
+      return runStop2();
     case "login":
       return runLogin(rest);
     case "logout":
@@ -1592,4 +1850,4 @@ async function runCli(argv) {
   }
 }
 
-export { getBrokerPackageVersion, parseLoginFlags, runCli, runDoctor, runLogin, runLogout, runSetup2 as runSetup };
+export { getBrokerPackageVersion, parseLoginFlags, runCli, runDoctor, runLogin, runLogout, runSetup2 as runSetup, runStop2 as runStop };

package/dist/index.cjs

@@ -1210,7 +1210,7 @@ var SERVER_NAME = "@muhaven/mcp";
 var SERVER_VERSION = resolveServerVersion();
 function resolveServerVersion() {
   {
-    return "0.1.4";
+    return "0.1.6";
   }
 }
 function toJsonInputSchema(schema) {
@@ -1794,7 +1794,8 @@ async function handleBrokerRequest(req, signer, keystore, nowSec = () => Math.fl
         sessionKeyAddress: signer.address,
         hasJwt,
         hasSessionKey,
-        ...options.effectiveConfig ? { effectiveConfig: options.effectiveConfig } : {}
+        ...options.effectiveConfig ? { effectiveConfig: options.effectiveConfig } : {},
+        ...options.pid !== void 0 ? { pid: options.pid } : {}
       };
     }
     case "sign_hash": {
@@ -2025,7 +2026,8 @@ var BrokerDaemon = class {
           effectiveConfig: {
             backendBaseUrl: this.config.backendBaseUrl,
             dashboardBaseUrl: this.config.dashboardBaseUrl
-          }
+          },
+          pid: process.pid
         }
       );
       socket.end(serializeResponse(res));

package/dist/index.d.cts

@@ -18,6 +18,12 @@ import { z } from 'zod';
  * keeper of the device-flow JWT (per ADR-3 D1 "polling, not loopback
  * callback") in addition to the session-key private half.
  *
+ * @muhaven/mcp@0.1.5 added `hello.pid` (still protocol 0.3.0 — additive
+ * optional field) so `muhaven-broker stop` can reach into the daemon
+ * process by PID without forcing operators to grep `ps` output. Older
+ * 0.1.4 daemons omit the field; `runStop` falls back to a structured
+ * error message in that case.
+ *
  * Threat-model invariants:
  *  - The broker NEVER reaches out to the network. It only:
  *      (a) signs hashes that the MCP server received from the backend,
@@ -94,6 +100,13 @@ interface BrokerHelloResponse {
         readonly backendBaseUrl: string;
         readonly dashboardBaseUrl: string;
     };
+    /**
+     * OS process id of the daemon. Surfaced so `muhaven-broker stop` can
+     * `process.kill(pid, 'SIGTERM')` without grepping `ps` output. Added in
+     * @muhaven/mcp@0.1.5 (no protocol-version bump — additive optional
+     * field). Older daemons omit; consumers MUST handle `undefined`.
+     */
+    readonly pid?: number;
 }
 interface BrokerSignHashResponse {
     readonly type: 'sign_hash';
@@ -804,6 +817,13 @@ interface HandleBrokerRequestOptions {
         readonly backendBaseUrl: string;
         readonly dashboardBaseUrl: string;
     };
+    /**
+     * The daemon's own OS PID. Injectable so unit tests can pin a value;
+     * production callers pass `process.pid` from the daemon process at
+     * handler-construction time. Surfaced via `hello.pid` so
+     * `muhaven-broker stop` can SIGTERM by PID. Added in @muhaven/mcp@0.1.5.
+     */
+    pid?: number;
 }
 declare function handleBrokerRequest(req: BrokerRequest, signer: ISigner, keystore: IKeystore, nowSec?: () => number, options?: HandleBrokerRequestOptions): Promise<BrokerResponse>;
 declare class BrokerDaemon {

package/dist/index.d.ts

@@ -18,6 +18,12 @@ import { z } from 'zod';
  * keeper of the device-flow JWT (per ADR-3 D1 "polling, not loopback
  * callback") in addition to the session-key private half.
  *
+ * @muhaven/mcp@0.1.5 added `hello.pid` (still protocol 0.3.0 — additive
+ * optional field) so `muhaven-broker stop` can reach into the daemon
+ * process by PID without forcing operators to grep `ps` output. Older
+ * 0.1.4 daemons omit the field; `runStop` falls back to a structured
+ * error message in that case.
+ *
  * Threat-model invariants:
  *  - The broker NEVER reaches out to the network. It only:
  *      (a) signs hashes that the MCP server received from the backend,
@@ -94,6 +100,13 @@ interface BrokerHelloResponse {
         readonly backendBaseUrl: string;
         readonly dashboardBaseUrl: string;
     };
+    /**
+     * OS process id of the daemon. Surfaced so `muhaven-broker stop` can
+     * `process.kill(pid, 'SIGTERM')` without grepping `ps` output. Added in
+     * @muhaven/mcp@0.1.5 (no protocol-version bump — additive optional
+     * field). Older daemons omit; consumers MUST handle `undefined`.
+     */
+    readonly pid?: number;
 }
 interface BrokerSignHashResponse {
     readonly type: 'sign_hash';
@@ -804,6 +817,13 @@ interface HandleBrokerRequestOptions {
         readonly backendBaseUrl: string;
         readonly dashboardBaseUrl: string;
     };
+    /**
+     * The daemon's own OS PID. Injectable so unit tests can pin a value;
+     * production callers pass `process.pid` from the daemon process at
+     * handler-construction time. Surfaced via `hello.pid` so
+     * `muhaven-broker stop` can SIGTERM by PID. Added in @muhaven/mcp@0.1.5.
+     */
+    pid?: number;
 }
 declare function handleBrokerRequest(req: BrokerRequest, signer: ISigner, keystore: IKeystore, nowSec?: () => number, options?: HandleBrokerRequestOptions): Promise<BrokerResponse>;
 declare class BrokerDaemon {

package/dist/index.js

@@ -1206,7 +1206,7 @@ var SERVER_NAME = "@muhaven/mcp";
 var SERVER_VERSION = resolveServerVersion();
 function resolveServerVersion() {
   {
-    return "0.1.4";
+    return "0.1.6";
   }
 }
 function toJsonInputSchema(schema) {
@@ -1790,7 +1790,8 @@ async function handleBrokerRequest(req, signer, keystore, nowSec = () => Math.fl
         sessionKeyAddress: signer.address,
         hasJwt,
         hasSessionKey,
-        ...options.effectiveConfig ? { effectiveConfig: options.effectiveConfig } : {}
+        ...options.effectiveConfig ? { effectiveConfig: options.effectiveConfig } : {},
+        ...options.pid !== void 0 ? { pid: options.pid } : {}
       };
     }
     case "sign_hash": {
@@ -2021,7 +2022,8 @@ var BrokerDaemon = class {
           effectiveConfig: {
             backendBaseUrl: this.config.backendBaseUrl,
             dashboardBaseUrl: this.config.dashboardBaseUrl
-          }
+          },
+          pid: process.pid
         }
       );
       socket.end(serializeResponse(res));

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.2",
   "name": "muhaven-mcp",
   "display_name": "MuHaven (RWA portfolio)",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muhaven/mcp",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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": {