@muhaven/mcp 0.1.3 → 0.1.5

package/CHANGELOG.md

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

package/bin/muhaven-mcp.cjs

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