@yawlabs/mcph 0.46.2 → 0.46.4

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 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.4 — 2026-04-18
+
+- **`mcph --help` Setup block rewritten for clarity** — The v0.46.3 rewrite used jargony wording ("Auto-edit an MCP client's config") and split the client list onto an ambiguous continuation line. Rewrote the three install rows to action-first prose: `install <client>` says "Configure one MCP client to launch mcph" and spells out the exact slugs (`claude-code, claude-desktop, cursor, vscode`) inline; `--list` says "List which MCP clients are installed on this machine"; `--all` says "Configure every installed MCP client in one go". Same three commands, but it now reads as plain English.
+- **Help + doctor now list `MCPH_AUTO_ACTIVATE`** — The env var has controlled the discover auto-activate gate since the confidence-scoring work landed, but neither the help page nor `mcph doctor`'s ENVIRONMENT section mentioned it, so the only way to discover the toggle was to grep `server.ts`. Added to both: help describes what flipping to `0` does, doctor surfaces the current value with `default on` hint. Also tightens the config resolution table in help — tier 3 (`<project>/.mcph/config.json`, the project-shared file) now notes "never put a token here — apiBase only" so nobody accidentally commits a token to a shared repo.
+
+## 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.

package/dist/index.js

@@ -1458,7 +1458,7 @@ function selectFlakyNamespaces(entries, limit) {
 }
 
 // src/doctor-cmd.ts
-var VERSION = true ? "0.46.2" : "dev";
+var VERSION = true ? "0.46.4" : "dev";
 async function runDoctor(opts = {}) {
   if (opts.json) return runDoctorJson(opts);
   const lines = [];
@@ -1563,6 +1563,7 @@ async function runDoctorJson(opts) {
     "MCPH_SERVER_CAP",
     "MCPH_MIN_COMPLIANCE",
     "MCPH_AUTO_LOAD",
+    "MCPH_AUTO_ACTIVATE",
     "MCPH_PRUNE_RESPONSES"
   ];
   const envOverrides = {};
@@ -1650,6 +1651,7 @@ function renderEnvSection(opts) {
     { name: "MCPH_SERVER_CAP", defaultHint: "default 6" },
     { name: "MCPH_MIN_COMPLIANCE", defaultHint: "filter inactive" },
     { name: "MCPH_AUTO_LOAD", defaultHint: "auto-load inactive" },
+    { name: "MCPH_AUTO_ACTIVATE", defaultHint: "default on" },
     { name: "MCPH_PRUNE_RESPONSES", defaultHint: "pruning active" }
   ];
   const widest = vars.reduce((m, v) => Math.max(m, v.name.length), 0);
@@ -2542,7 +2544,6 @@ async function runInstallAll(opts, log2, err) {
     exitCode: 1
   };
 }
-var INSTALL_USAGE = USAGE;
 
 // src/reset-learning-cmd.ts
 import { unlink } from "fs/promises";
@@ -4745,7 +4746,7 @@ function categorizeSpawnError(err) {
 }
 async function connectToUpstream(config, onDisconnect, onListChanged) {
   const client = new Client(
-    { name: "mcph", version: true ? "0.46.2" : "dev" },
+    { name: "mcph", version: true ? "0.46.4" : "dev" },
     { capabilities: {} }
   );
   let transport;
@@ -5226,7 +5227,7 @@ var ConnectServer = class _ConnectServer {
     this.apiUrl = apiUrl6;
     this.token = token6;
     this.server = new Server(
-      { name: "mcph", version: true ? "0.46.2" : "dev" },
+      { name: "mcph", version: true ? "0.46.4" : "dev" },
       {
         capabilities: {
           tools: { listChanged: true },
@@ -7571,7 +7572,7 @@ async function runUpgrade(opts = {}) {
   return { exitCode: 3, lines };
 }
 function readCurrentVersion() {
-  return true ? "0.46.2" : "dev";
+  return true ? "0.46.4" : "dev";
 }
 
 // src/index.ts
@@ -7652,42 +7653,82 @@ 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>         Configure one MCP client to launch mcph.
+                             <client> is one of: claude-code, claude-desktop,
+                             cursor, vscode.
+    install --list           List which MCP clients are installed on this
+                             machine (read-only; no writes).
+    install --all            Configure every installed MCP client in one go.
 
-  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_AUTO_ACTIVATE         Set to \`0\` to disable discover's auto-activate
+                               gate (default: a clearly-winning server is
+                               activated in the same call).
+    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; never
+                                           put a token here \u2014 apiBase only)
+    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.2" : "dev"}
+  process.stdout.write(`mcph ${true ? "0.46.4" : "dev"}
 `);
   process.exit(0);
 } else if (subcommand && !subcommand.startsWith("-")) {

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@yawlabs/mcph",
-  "version": "0.46.2",
+  "version": "0.46.4",
   "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"