@yawlabs/mcph 0.46.1 → 0.46.3

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `@yawlabs/mcph` are documented here. This project uses [semantic versioning](https://semver.org) and a CI-gated release flow: pushing a `vX.Y.Z` tag triggers `.github/workflows/release.yml`, which publishes to npm.
 
+## 0.46.3 — 2026-04-18
+
+- **`mcph --help` rewritten: quickstart, grouped subcommands, env vars, config precedence** — The old help listed ten subcommands in a flat table and spent most of its real estate on install flag details (already available via `mcph install --help`) and a three-line token-resolution note. Subcommands are now grouped by purpose (Setup, Inspection, Maintenance, Other), each with a multi-line description that explains what the command actually does — not just its name. A numbered Quickstart at the top points users at the token URL and shows the two commands needed to finish onboarding. An Environment variables section documents the eight `MCPH_*` overrides (`MCPH_URL`, `MCPH_POLL_INTERVAL`, `MCPH_SERVER_CAP`, `MCPH_MIN_COMPLIANCE`, `MCPH_AUTO_LOAD`, `MCPH_PRUNE_RESPONSES`, `MCPH_DISABLE_PERSISTENCE`) that were previously only discoverable by reading the doctor source. Config resolution is expanded from three lines to a proper four-tier precedence list (env → project.local → project → user-global). Trailing pointer to `mcph <subcommand> --help` for flag-level detail so the top-level stays scannable. `INSTALL_USAGE` import removed from `index.ts` since the install flag block no longer inlines into top-level help.
+
+## 0.46.2 — 2026-04-18
+
+- **Doctor's UPGRADE AVAILABLE section points at `mcph upgrade`** — Previously it inlined `npm install -g @yawlabs/mcph@latest` with a long prose aside about npx-vs-global. Now it tells the user to run `mcph upgrade` (prints the exact command for their install method) or `mcph upgrade --run` (executes for global-npm). Shorter, single source of truth for "how do I actually update?" since doctor already detects staleness and the upgrade subcommand already understands how the install was done.
+
 ## 0.46.1 — 2026-04-18
 
 - **Fix `mcph upgrade` reporting `Current: dev` in shipped bundles** — The v0.46.0 `readCurrentVersion()` used `(globalThis as ...).__VERSION__`, but tsup's `define` only substitutes bare identifier references, not property accesses — so the compiled bundle fell through to the "dev" fallback regardless of what version was installed. Switched to the same `declare const __VERSION__ / typeof __VERSION__ !== "undefined"` pattern used in `index.ts`, `doctor-cmd.ts`, `server.ts`, and `upstream.ts`. Smoke-tested via `npx @yawlabs/mcph@latest upgrade`: now reports the actual installed version.

package/dist/index.js

@@ -1458,7 +1458,7 @@ function selectFlakyNamespaces(entries, limit) {
 }
 
 // src/doctor-cmd.ts
-var VERSION = true ? "0.46.1" : "dev";
+var VERSION = true ? "0.46.3" : "dev";
 async function runDoctor(opts = {}) {
   if (opts.json) return runDoctorJson(opts);
   const lines = [];
@@ -1528,9 +1528,8 @@ async function runDoctor(opts = {}) {
   if (staleHint) {
     print("UPGRADE AVAILABLE");
     print(`  Running ${VERSION}; npm latest is ${staleHint}.`);
-    print("  If `mcph` is globally installed it shadows `npx` \u2014 upgrade with:");
-    print("    npm install -g @yawlabs/mcph@latest");
-    print("  Otherwise restart your MCP client; `npx -y @yawlabs/mcph` will fetch the new version.");
+    print("  Run `mcph upgrade` to see the exact command for your install, or");
+    print("  `mcph upgrade --run` to execute it (global-npm installs only).");
     print("");
   }
   let exitCode = 0;
@@ -2543,7 +2542,6 @@ async function runInstallAll(opts, log2, err) {
     exitCode: 1
   };
 }
-var INSTALL_USAGE = USAGE;
 
 // src/reset-learning-cmd.ts
 import { unlink } from "fs/promises";
@@ -4746,7 +4744,7 @@ function categorizeSpawnError(err) {
 }
 async function connectToUpstream(config, onDisconnect, onListChanged) {
   const client = new Client(
-    { name: "mcph", version: true ? "0.46.1" : "dev" },
+    { name: "mcph", version: true ? "0.46.3" : "dev" },
     { capabilities: {} }
   );
   let transport;
@@ -5227,7 +5225,7 @@ var ConnectServer = class _ConnectServer {
     this.apiUrl = apiUrl6;
     this.token = token6;
     this.server = new Server(
-      { name: "mcph", version: true ? "0.46.1" : "dev" },
+      { name: "mcph", version: true ? "0.46.3" : "dev" },
       {
         capabilities: {
           tools: { listChanged: true },
@@ -7572,7 +7570,7 @@ async function runUpgrade(opts = {}) {
   return { exitCode: 3, lines };
 }
 function readCurrentVersion() {
-  return true ? "0.46.1" : "dev";
+  return true ? "0.46.3" : "dev";
 }
 
 // src/index.ts
@@ -7653,42 +7651,76 @@ if (subcommand === "compliance") {
   }
   runUpgrade(parsed.options).then((r) => process.exit(r.exitCode));
 } else if (subcommand === "--help" || subcommand === "-h" || subcommand === "help") {
-  const installBlock = `    ${INSTALL_USAGE.replace(/^Usage: /, "").replace(/\n/g, "\n    ")}`;
-  process.stdout.write(
-    `
-  mcph \u2014 MCP server orchestrator for mcp.hosting
+  process.stdout.write(`
+  mcph \u2014 one install, every MCP server, managed from the cloud.
 
-  Usage:
-    mcph                              Run as MCP server (requires a token)
-    mcph install <client> [flags]     Auto-edit an MCP client's config to launch mcph
-    mcph doctor [--json]              Print loaded config + detected clients (support diagnostic)
-    mcph servers [--json]             List servers configured in your mcp.hosting dashboard
-    mcph bundles [list|match]         Browse curated multi-server bundles
-    mcph compliance <target> [flags]  Run the compliance suite against an MCP server
-    mcph reset-learning               Clear cross-session learning history (~/.mcph/state.json)
-    mcph completion <shell>           Print a shell completion script (bash|zsh|fish|powershell)
-    mcph upgrade [--run] [--json]     Show (or run) the upgrade command for @yawlabs/mcph
-    mcph --version                    Print version
+  Quickstart:
+    1. Get a token      https://mcp.hosting/dashboard/settings/tokens
+    2. Install mcph     mcph install claude-code --token mcp_pat_...
+    3. Verify setup     mcph doctor
 
-  Install:
-${installBlock}
+  Setup:
+    install <client>         Auto-edit an MCP client's config to launch mcph.
+                             Clients: claude-code | claude-desktop | cursor | vscode.
+    install --list           Detect MCP clients on this machine (read-only).
+    install --all            Install into every detected client in one shot.
 
-  Compliance flags:
-    --publish   Publish the report to mcp.hosting and print the URL
+  Inspection:
+    doctor                   Diagnose setup: config, token, clients, learning,
+                             upgrade, flaky-namespace reliability rollup.
+    servers [<filter>]       List servers in your mcp.hosting dashboard; the
+                             positional arg substring-filters by namespace.
+    bundles [list|match]     Browse curated multi-server bundles. \`list\` shows
+                             all; \`match\` partitions against your enabled
+                             servers (ready vs. partially installed).
 
-  Token resolution (highest first):
-    1. MCPH_TOKEN env var
-    2. <project>/.mcph/config.local.json  (machine-local override; gitignore)
-    3. ~/.mcph/config.json                (user-global default)
+  Maintenance:
+    upgrade                  Show (or --run) the command that bumps
+                             @yawlabs/mcph to the latest version.
+    reset-learning           Clear cross-session learning history
+                             (~/.mcph/state.json).
+    completion <shell>       Print a shell completion script for bash, zsh,
+                             fish, or powershell. Redirect to your
+                             completions directory to install.
 
-  Token rotation: mcph reads its config at startup. Restart the MCP
-  client (or kill mcph; the client will respawn it) after editing.
+  Other:
+    compliance <target>      Run the 88-test compliance suite against an MCP
+                             server. --publish posts the report to
+                             mcp.hosting and prints the public URL.
+    help, --help, -h         Show this help.
+    --version, -V            Print mcph version.
 
-`
-  );
+  Running \`mcph\` with no subcommand starts the MCP server (requires a
+  resolved token). Most read-only subcommands accept \`--json\` for
+  machine-readable output. Run \`mcph <subcommand> --help\` for per-
+  subcommand flag details.
+
+  Environment variables:
+    MCPH_TOKEN                 API token (overrides every config file).
+    MCPH_URL                   API base URL (default https://mcp.hosting).
+    MCPH_POLL_INTERVAL         Dashboard polling interval, seconds (default 60).
+    MCPH_SERVER_CAP            Max concurrently active servers (default 6).
+    MCPH_MIN_COMPLIANCE        Minimum grade to auto-activate (A|B|C|D|F).
+    MCPH_AUTO_LOAD             Load all servers at startup, ignoring SERVER_CAP.
+    MCPH_PRUNE_RESPONSES       Set to \`0\` to disable response pruning.
+    MCPH_DISABLE_PERSISTENCE   Disable cross-session learning state.
+
+  Config resolution (highest precedence first):
+    1. MCPH_TOKEN / MCPH_URL env vars
+    2. <project>/.mcph/config.local.json   machine-local overrides (gitignore)
+    3. <project>/.mcph/config.json         project-shared (checked in)
+    4. ~/.mcph/config.json                 user-global default
+
+  Token rotation: mcph reads config at startup. Restart the MCP client
+  (or kill mcph; the client will respawn it) after editing any config.
+
+  Docs:   https://mcp.hosting
+  Source: https://github.com/YawLabs/mcph
+
+`);
   process.exit(0);
 } else if (subcommand === "--version" || subcommand === "-V") {
-  process.stdout.write(`mcph ${true ? "0.46.1" : "dev"}
+  process.stdout.write(`mcph ${true ? "0.46.3" : "dev"}
 `);
   process.exit(0);
 } else if (subcommand && !subcommand.startsWith("-")) {

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@yawlabs/mcph",
-  "version": "0.46.1",
+  "version": "0.46.3",
   "description": "mcp.hosting — one install, all your MCP servers, managed from the cloud",
   "license": "UNLICENSED",
-  "author": "Yaw Labs <contact@yaw.sh> (https://yaw.sh)",
+  "author": "Yaw Labs <support@mcp.hosting> (https://mcp.hosting)",
   "type": "module",
   "bin": {
     "mcph": "./dist/index.js"