@yawlabs/mcph 0.43.0 → 0.45.0

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.45.0 — 2026-04-18
+
+- **Clearer 401/403 errors with token fingerprint + actionable fix link** — When the backend rejects a token (`HTTP 401` revoked/malformed, `HTTP 403` accepted but scope-denied), `fetchConfig` now throws an error that names the offending token by its fingerprint (e.g., `mcp_pat_…abcd`), explains what state the token is in, and points directly at the tokens page with a concrete re-install command. Prior wording was "Invalid MCPH_TOKEN — check your token at mcp.hosting" and "Access denied — your token may have expired" — both too vague to action without pinging support. New wording is structured as three lines: cause, fix URL, and the `mcph install … --token mcp_pat_...` re-install command. Messages surface verbatim through `mcph servers`, the top-level `mcph` runtime, and anywhere else `fetchConfig` is awaited, so every user-facing rejection reads the same way.
+
+## 0.44.0 — 2026-04-18
+
+- **`mcph install --list` + `mcph install --all`** — Two new modes on the install subcommand. `--list` is read-only: it enumerates every client/scope combo for the current OS and shows whether an `mcp.hosting` entry is already wired up, plus a path-per-row and a one-line summary (`N/M client scopes have mcp.hosting configured on linux`). No token, no network, no writes — just a diagnostic view that mirrors the `doctor` CLIENTS section but without the rest of doctor's noise. `--all` walks `INSTALL_TARGETS`, picks the default scope per client (user where supported, else the first non-project-dir scope, else skipped unless `--project-dir` is passed), and calls `runInstall` in a loop — so `--dry-run`, `--force`, `--skip`, and `--token` all propagate as expected. Status is aggregated into a single summary line, and the process exit code is non-zero if any sub-install failed so CI can still gate on one-shot onboarding. Works around the main drop-off during setup ("which client am I supposed to pick?") by offering both the answer (`--list`) and the sledgehammer (`--all`) from the same subcommand.
+
 ## 0.43.0 — 2026-04-18
 
 - **`mcph servers <namespace-filter>` — positional filter** — Passing a bare positional argument now filters the listing to servers whose namespace contains that substring (case-insensitive): `mcph servers git` matches both `github` and `gitlab`. Applies to both the text table and the `--json` output so the two surfaces agree. Summary line reflects the filtered count, and a filter that matches nothing prints an explanatory "No servers match …" instead of an empty table (which previously looked like an empty account).

package/README.md

@@ -65,6 +65,15 @@ Helpful flags:
 - `--force` / `--skip` — overwrite or leave an existing `mcp.hosting` entry. Without either, mcph prompts (TTY) or refuses (non-TTY).
 - `--no-mcph-config` — write only the client config; leave `~/.mcph/config.json` untouched.
 
+Or install into every detected client at once:
+
+```bash
+mcph install --list                       # read-only: detect clients + show install state per scope
+mcph install --all --token mcp_pat_…     # one-shot: install into every user-scope client on this machine
+```
+
+`--list` never writes (no token needed). `--all` installs into every client whose user-scope target is resolvable on this OS — Claude Desktop is skipped on Linux, VS Code is skipped unless `--project-dir` is given (it's workspace-only). Aggregate exit code is non-zero if any sub-install fails.
+
 Or [edit the JSON by hand](#manual-install) if you'd rather.
 
 ### Diagnose problems — `mcph doctor`

package/dist/index.js

@@ -464,12 +464,22 @@ async function fetchConfig(apiUrl6, token6, currentVersion) {
   if (res.statusCode === 401) {
     await res.body.text().catch(() => {
     });
-    throw new ConfigError("Invalid MCPH_TOKEN \u2014 check your token at mcp.hosting", true);
+    throw new ConfigError(
+      `Token rejected (HTTP 401) \u2014 the token ${tokenFingerprint(token6)} is invalid or revoked.
+  Generate a new token at https://mcp.hosting/dashboard/settings/tokens,
+  then re-run \`mcph install <client> --token mcp_pat_...\` or set MCPH_TOKEN.`,
+      true
+    );
   }
   if (res.statusCode === 403) {
     await res.body.text().catch(() => {
     });
-    throw new ConfigError("Access denied \u2014 your token may have expired", true);
+    throw new ConfigError(
+      `Access denied (HTTP 403) \u2014 the token ${tokenFingerprint(token6)} was accepted but lacks permission to read this account's servers.
+  The account may be suspended or the token scope reduced \u2014 check
+  https://mcp.hosting/dashboard/settings/tokens, or reach support@mcp.hosting.`,
+      true
+    );
   }
   if (res.statusCode !== 200) {
     const body = await res.body.text().catch(() => "");
@@ -663,7 +673,18 @@ var SUBCOMMAND_SPEC = [
   {
     name: "install",
     positional: [...INSTALL_CLIENTS],
-    flags: ["--scope", "--token", "--project-dir", "--os", "--force", "--skip", "--dry-run", "--no-mcph-config"]
+    flags: [
+      "--scope",
+      "--token",
+      "--project-dir",
+      "--os",
+      "--force",
+      "--skip",
+      "--dry-run",
+      "--no-mcph-config",
+      "--list",
+      "--all"
+    ]
   },
   { name: "doctor", flags: ["--json", "--help"] },
   { name: "servers", flags: ["--json", "--help"] },
@@ -1435,7 +1456,7 @@ function selectFlakyNamespaces(entries, limit) {
 }
 
 // src/doctor-cmd.ts
-var VERSION = true ? "0.43.0" : "dev";
+var VERSION = true ? "0.45.0" : "dev";
 async function runDoctor(opts = {}) {
   if (opts.json) return runDoctorJson(opts);
   const lines = [];
@@ -1769,6 +1790,62 @@ function walkContainer(root, path4) {
   if (typeof cur !== "object" || cur === null || Array.isArray(cur)) return null;
   return cur;
 }
+async function probeClientsAsync(opts) {
+  const result = [];
+  for (const target of INSTALL_TARGETS) {
+    const unavailable = !target.availableOn.includes(opts.os);
+    if (unavailable) {
+      result.push({
+        clientId: target.clientId,
+        scope: target.scopes[0].scope,
+        path: "(n/a)",
+        exists: false,
+        hasMcphEntry: false,
+        malformed: false,
+        unavailable: true
+      });
+      continue;
+    }
+    for (const scope of target.scopes) {
+      const resolved = resolveInstallPath({
+        clientId: target.clientId,
+        scope: scope.scope,
+        os: opts.os,
+        home: opts.home,
+        projectDir: scope.requiresProjectDir ? opts.cwd : void 0
+      });
+      const exists3 = existsSync(resolved.absolute);
+      let hasMcphEntry = false;
+      let malformed = false;
+      if (exists3) {
+        try {
+          const raw = await readFile3(resolved.absolute, "utf8");
+          if (raw.trim().length > 0) {
+            const parsed = parseJsonc(raw);
+            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+              const container = walkContainer(parsed, resolved.containerPath);
+              if (container) hasMcphEntry = ENTRY_NAME in container;
+            } else {
+              malformed = true;
+            }
+          }
+        } catch {
+          malformed = true;
+        }
+      }
+      result.push({
+        clientId: target.clientId,
+        scope: scope.scope,
+        path: resolved.absolute,
+        exists: exists3,
+        hasMcphEntry,
+        malformed,
+        unavailable: false
+      });
+    }
+  }
+  return result;
+}
 async function fetchLatestVersion(override) {
   if (override) {
     try {
@@ -1950,7 +2027,7 @@ import { homedir as homedir5 } from "os";
 import { dirname as dirname2 } from "path";
 import { join as join5, resolve as resolve2 } from "path";
 import { createInterface } from "readline/promises";
-var USAGE = "Usage: mcph install <claude-code|claude-desktop|cursor|vscode> [--scope user|project|local]\n                       [--token <mcp_pat_\u2026>] [--project-dir <path>] [--os macos|linux|windows]\n                       [--force | --skip] [--dry-run] [--no-mcph-config]";
+var USAGE = "Usage: mcph install <claude-code|claude-desktop|cursor|vscode> [--scope user|project|local]\n                       [--token <mcp_pat_\u2026>] [--project-dir <path>] [--os macos|linux|windows]\n                       [--force | --skip] [--dry-run] [--no-mcph-config]\n       mcph install --list                       (detect clients; no writes)\n       mcph install --all  [--token <mcp_pat_\u2026>] (install into every detected client)";
 async function runInstall(opts) {
   const stdout = opts.io?.stdout ?? process.stdout;
   const stderr = opts.io?.stderr ?? process.stderr;
@@ -1965,10 +2042,21 @@ async function runInstall(opts) {
     stderr.write(`${s}
 `);
   };
+  if (opts.listOnly && opts.all) {
+    err("mcph install: --list and --all are mutually exclusive");
+    return { written: [], wouldWrite: [], messages, exitCode: 2 };
+  }
+  if (opts.listOnly) return runInstallList(opts, log2);
+  if (opts.all) return runInstallAll(opts, log2, err);
   if (opts.force && opts.skip) {
     err("mcph install: --force and --skip are mutually exclusive");
     return { written: [], wouldWrite: [], messages, exitCode: 2 };
   }
+  if (!opts.clientId) {
+    err(`mcph install: client argument required
+${USAGE}`);
+    return { written: [], wouldWrite: [], messages, exitCode: 2 };
+  }
   const target = INSTALL_TARGETS.find((t) => t.clientId === opts.clientId);
   if (!target) {
     err(`mcph install: unknown client ${opts.clientId}
@@ -2294,6 +2382,12 @@ function parseInstallArgs(argv) {
       case "--no-mcph-config":
         opts.skipMcphConfig = true;
         break;
+      case "--list":
+        opts.listOnly = true;
+        break;
+      case "--all":
+        opts.all = true;
+        break;
       case "-h":
       case "--help":
         return { ok: false, error: USAGE };
@@ -2303,6 +2397,16 @@ ${USAGE}` };
         positional.push(a);
     }
   }
+  if (opts.listOnly || opts.all) {
+    if (positional.length > 0) {
+      return {
+        ok: false,
+        error: `mcph install: ${opts.listOnly ? "--list" : "--all"} does not take a client argument.
+${USAGE}`
+      };
+    }
+    return { ok: true, options: opts };
+  }
   if (positional.length !== 1)
     return { ok: false, error: `Expected exactly one client argument, got ${positional.length}.
 ${USAGE}` };
@@ -2316,6 +2420,127 @@ ${USAGE}` };
   opts.clientId = clientId;
   return { ok: true, options: opts };
 }
+async function runInstallList(opts, log2) {
+  const home = opts.home ?? homedir5();
+  const cwd = opts.cwd ?? process.cwd();
+  const os = opts.os ?? CURRENT_OS;
+  const probes = await probeClientsAsync({ home, os, cwd });
+  const rows = probes.map((p) => ({
+    client: INSTALL_TARGETS.find((t) => t.clientId === p.clientId)?.label ?? p.clientId,
+    scope: p.scope,
+    path: displayPath(p.path, home),
+    status: statusFor(p)
+  }));
+  const installed = probes.filter((p) => p.hasMcphEntry).length;
+  const available = probes.filter((p) => !p.unavailable).length;
+  log2(`${installed}/${available} client scopes have mcp.hosting configured on ${os}.`);
+  log2("");
+  const widths = {
+    client: Math.max("CLIENT".length, ...rows.map((r) => r.client.length)),
+    scope: Math.max("SCOPE".length, ...rows.map((r) => r.scope.length)),
+    path: Math.max("PATH".length, ...rows.map((r) => r.path.length)),
+    status: Math.max("STATUS".length, ...rows.map((r) => r.status.length))
+  };
+  const header = `  ${"CLIENT".padEnd(widths.client)}  ${"SCOPE".padEnd(widths.scope)}  ${"PATH".padEnd(widths.path)}  ${"STATUS".padEnd(widths.status)}`;
+  log2(header);
+  for (const r of rows) {
+    log2(
+      `  ${r.client.padEnd(widths.client)}  ${r.scope.padEnd(widths.scope)}  ${r.path.padEnd(widths.path)}  ${r.status.padEnd(widths.status)}`
+    );
+  }
+  log2("");
+  log2("Install into a specific client: `mcph install <client> [--scope user|project|local]`");
+  log2("Install into every available user-scope client: `mcph install --all`");
+  return { written: [], wouldWrite: [], messages: [], exitCode: 0 };
+}
+function statusFor(p) {
+  if (p.unavailable) return "unavailable";
+  if (p.malformed) return "malformed";
+  if (p.hasMcphEntry) return "installed";
+  if (p.exists) return "other-entries";
+  return "not installed";
+}
+function displayPath(abs, home) {
+  if (abs === "(n/a)") return abs;
+  if (home && abs.startsWith(home)) {
+    const tail = abs.slice(home.length).replace(/^[\\/]/, "");
+    return `~${process.platform === "win32" ? "\\" : "/"}${tail}`;
+  }
+  return abs;
+}
+async function runInstallAll(opts, log2, err) {
+  const os = opts.os ?? CURRENT_OS;
+  const targets = INSTALL_TARGETS.filter((t) => t.availableOn.includes(os));
+  if (targets.length === 0) {
+    err(`mcph install --all: no installable clients on ${os}.`);
+    return { written: [], wouldWrite: [], messages: [], exitCode: 1 };
+  }
+  const plans = [];
+  const skipped = [];
+  for (const t of targets) {
+    const userScope = t.scopes.find((s) => s.scope === "user");
+    if (userScope) {
+      plans.push({ clientId: t.clientId, scope: "user" });
+      continue;
+    }
+    const firstNoProj = t.scopes.find((s) => !s.requiresProjectDir);
+    if (firstNoProj) {
+      plans.push({ clientId: t.clientId, scope: firstNoProj.scope });
+      continue;
+    }
+    if (opts.projectDir) {
+      plans.push({ clientId: t.clientId, scope: t.scopes[0].scope });
+      continue;
+    }
+    skipped.push({
+      clientId: t.clientId,
+      reason: `requires --project-dir (scopes: ${t.scopes.map((s) => s.scope).join(", ")})`
+    });
+  }
+  log2(`Installing into ${plans.length} client${plans.length === 1 ? "" : "s"}\u2026`);
+  if (skipped.length > 0) {
+    for (const s of skipped) log2(`  skip ${s.clientId}: ${s.reason}`);
+  }
+  log2("");
+  const aggregateWritten = [];
+  const aggregateWouldWrite = [];
+  const aggregateMessages = [];
+  let failed = 0;
+  let succeeded = 0;
+  for (const plan of plans) {
+    log2(`\u2500\u2500 ${plan.clientId} (${plan.scope}) \u2500\u2500`);
+    const result = await runInstall({
+      ...opts,
+      listOnly: false,
+      all: false,
+      clientId: plan.clientId,
+      scope: plan.scope
+    });
+    aggregateWritten.push(...result.written);
+    aggregateWouldWrite.push(...result.wouldWrite);
+    aggregateMessages.push(...result.messages);
+    if (result.exitCode === 0) succeeded += 1;
+    else failed += 1;
+    log2("");
+  }
+  const totalPlanned = plans.length;
+  if (failed === 0) {
+    log2(`\u2713 ${succeeded}/${totalPlanned} clients installed successfully.`);
+    return {
+      written: aggregateWritten,
+      wouldWrite: aggregateWouldWrite,
+      messages: aggregateMessages,
+      exitCode: 0
+    };
+  }
+  err(`${failed}/${totalPlanned} client install${failed === 1 ? "" : "s"} failed. ${succeeded} succeeded.`);
+  return {
+    written: aggregateWritten,
+    wouldWrite: aggregateWouldWrite,
+    messages: aggregateMessages,
+    exitCode: 1
+  };
+}
 var INSTALL_USAGE = USAGE;
 
 // src/reset-learning-cmd.ts
@@ -4519,7 +4744,7 @@ function categorizeSpawnError(err) {
 }
 async function connectToUpstream(config, onDisconnect, onListChanged) {
   const client = new Client(
-    { name: "mcph", version: true ? "0.43.0" : "dev" },
+    { name: "mcph", version: true ? "0.45.0" : "dev" },
     { capabilities: {} }
   );
   let transport;
@@ -5000,7 +5225,7 @@ var ConnectServer = class _ConnectServer {
     this.apiUrl = apiUrl6;
     this.token = token6;
     this.server = new Server(
-      { name: "mcph", version: true ? "0.43.0" : "dev" },
+      { name: "mcph", version: true ? "0.45.0" : "dev" },
       {
         capabilities: {
           tools: { listChanged: true },
@@ -7276,7 +7501,7 @@ ${installBlock}
   );
   process.exit(0);
 } else if (subcommand === "--version" || subcommand === "-V") {
-  process.stdout.write(`mcph ${true ? "0.43.0" : "dev"}
+  process.stdout.write(`mcph ${true ? "0.45.0" : "dev"}
 `);
   process.exit(0);
 } else if (subcommand && !subcommand.startsWith("-")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/mcph",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "description": "mcp.hosting — one install, all your MCP servers, managed from the cloud",
   "license": "UNLICENSED",
   "author": "Yaw Labs <contact@yaw.sh> (https://yaw.sh)",