@muhaven/mcp 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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));
@@ -1260,6 +1262,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 +1604,18 @@ 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("  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.5";
   }
 }
 function printVersion() {
@@ -1561,6 +1641,19 @@ async function runSetup2(argv) {
   };
   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 +1662,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 +1692,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));
@@ -1262,6 +1264,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 +1606,18 @@ 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("  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.5";
   }
 }
 function printVersion() {
@@ -1563,6 +1643,19 @@ async function runSetup2(argv) {
   };
   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 +1664,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 +1687,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.5";
   }
 }
 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.5";
   }
 }
 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.5",
   "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.5",
   "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": {