@yawlabs/mcph 0.40.0 → 0.42.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.42.0 — 2026-04-18
+
+- **`mcph completion <shell>` — shell completion scripts** — Prints a completion script for `bash`, `zsh`, `fish`, or `powershell` to stdout so users can one-line it into their completions directory. Each script covers every known subcommand (install, doctor, servers, bundles, compliance, reset-learning, completion) with positional choices (install clients, bundles actions, completion shells) and per-subcommand flags (`--json`, `--scope`, `--token`, `--force`, etc.). Every template derives from a single `SUBCOMMAND_SPEC` table so adding a new subcommand elsewhere updates all four shells at once — no drift between what the CLI accepts and what it completes. Install hints are inlined as comments at the top of each generated script: the bash file drops into `~/.local/share/bash-completion/completions/mcph`, zsh into any `$fpath` dir as `_mcph`, fish into `~/.config/fish/completions/mcph.fish`, pwsh appended to `$PROFILE`.
+
+## 0.41.0 — 2026-04-18
+
+- **`mcph doctor --json` — machine-readable diagnostic output** — Doctor already tracks a lot of state (config files, token source, env overrides, persisted learning, installed clients, shell-history shadow hits, upgrade availability, diagnosis summary) and the text output optimises for pasting into a support ticket. `--json` emits the same data as a single structured blob so dashboards, CI scripts, and support tooling can pick fields with `jq` instead of parsing the text layout. Token is fingerprinted the same way in both modes (never raw). Section data is 1:1 with the text renderer: config (token/apiBase/loadedFiles/warnings), env overrides (null when unset), state (path/savedAt/entries; `disabled: true` when `MCPH_DISABLE_PERSISTENCE` is set), reliability (same `selectFlakyNamespaces` rollup that `mcp_connect_health` and the text RELIABILITY section use), clients probe results, shell shadow hits, upgrade info, and the exit-code diagnosis. Completes the `--json` pattern across `servers`, `bundles`, and now `doctor` — every CLI that reads state has a pipeline mode.
+
 ## 0.40.0 — 2026-04-18
 
 - **`mcph bundles` CLI subcommand** — CLI counterpart to the `mcp_connect_bundles` meta-tool (v0.28.0). Two actions mirror the meta-tool's `action` parameter: `list` prints every curated bundle grouped by category with activate hints (static, no network, no token needed — good for browsing or sharing in onboarding docs), and `match` partitions the curated set against the user's enabled servers from the backend into ready-to-activate vs partially-installed, so a human can see in the terminal what the LLM-facing tool would suggest. The LLM tool has always been primary surface, but "what bundles exist?" is a frequent enough support question that surfacing them in the CLI earns its keep. Match only counts `isActive: true` servers — disabled ones don't auto-activate, so they shouldn't count toward "ready" — matching the LLM tool's filter so both surfaces agree. Partial bundles sort fewest-missing first to match the discover inline hint ranking. `--json` emits machine-readable output (`{bundles}` for list, `{installed, ready, partial}` for match). Exit codes: 0 success, 1 match needs a token and none resolved, 2 match couldn't reach the backend.

package/dist/index.js

@@ -648,6 +648,222 @@ function renderMatch(match, installed, print) {
   }
 }
 
+// src/completion-cmd.ts
+var COMPLETION_USAGE = `Usage: mcph completion <bash|zsh|fish|powershell>
+
+  Print a shell completion script to stdout. Redirect it to the right
+  location for your shell:
+
+    bash        mcph completion bash       > ~/.local/share/bash-completion/completions/mcph
+    zsh         mcph completion zsh        > "\${fpath[1]}/_mcph"    (must be on $fpath)
+    fish        mcph completion fish       > ~/.config/fish/completions/mcph.fish
+    powershell  mcph completion powershell >> $PROFILE`;
+var INSTALL_CLIENTS = ["claude-code", "claude-desktop", "cursor", "vscode"];
+var SUBCOMMAND_SPEC = [
+  {
+    name: "install",
+    positional: [...INSTALL_CLIENTS],
+    flags: ["--scope", "--token", "--project-dir", "--os", "--force", "--skip", "--dry-run", "--no-mcph-config"]
+  },
+  { name: "doctor", flags: ["--json", "--help"] },
+  { name: "servers", flags: ["--json", "--help"] },
+  { name: "bundles", positional: ["list", "match"], flags: ["--json", "--help"] },
+  { name: "compliance", flags: ["--publish", "--help"] },
+  { name: "reset-learning", flags: ["--help"] },
+  { name: "completion", positional: ["bash", "zsh", "fish", "powershell"], flags: ["--help"] },
+  { name: "help", flags: [] }
+];
+function parseCompletionArgs(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    return { ok: false, error: COMPLETION_USAGE };
+  }
+  const positional = argv.filter((a) => !a.startsWith("-"));
+  if (positional.length === 0) {
+    return { ok: false, error: `mcph completion: missing shell argument
+
+${COMPLETION_USAGE}` };
+  }
+  if (positional.length > 1) {
+    return { ok: false, error: `mcph completion: too many arguments
+
+${COMPLETION_USAGE}` };
+  }
+  const shell = positional[0];
+  if (shell !== "bash" && shell !== "zsh" && shell !== "fish" && shell !== "powershell") {
+    return { ok: false, error: `mcph completion: unknown shell "${shell}"
+
+${COMPLETION_USAGE}` };
+  }
+  return { ok: true, options: { shell } };
+}
+async function runCompletion(opts = {}) {
+  const write = opts.out ?? ((s) => process.stdout.write(s));
+  const writeErr = opts.err ?? ((s) => process.stderr.write(s));
+  const lines = [];
+  const print = (s) => {
+    lines.push(s);
+    write(`${s}
+`);
+  };
+  if (!opts.shell) {
+    writeErr(`mcph completion: missing shell argument
+${COMPLETION_USAGE}
+`);
+    return { exitCode: 2, lines };
+  }
+  const script = renderScript(opts.shell);
+  print(script);
+  return { exitCode: 0, lines };
+}
+function renderScript(shell) {
+  switch (shell) {
+    case "bash":
+      return renderBash();
+    case "zsh":
+      return renderZsh();
+    case "fish":
+      return renderFish();
+    case "powershell":
+      return renderPowershell();
+  }
+}
+function renderBash() {
+  const subcommandList = SUBCOMMAND_SPEC.map((s) => s.name).join(" ");
+  const topLevelFlags = "--help -h --version -V";
+  const cases = SUBCOMMAND_SPEC.map((spec) => {
+    const posClause = spec.positional ? `    if [[ $cword -eq 2 ]]; then
+      COMPREPLY=( $(compgen -W "${spec.positional.join(" ")} ${spec.flags.join(" ")}" -- "$cur") )
+      return 0
+    fi` : "";
+    return `  ${spec.name})
+${posClause}
+    COMPREPLY=( $(compgen -W "${spec.flags.join(" ")}" -- "$cur") )
+    return 0
+    ;;`;
+  }).join("\n");
+  return `# bash completion for mcph \u2014 generated by \`mcph completion bash\`
+# Install: save this to ~/.local/share/bash-completion/completions/mcph
+#          or source it from your .bashrc.
+_mcph() {
+  local cur prev words cword
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  cword=$COMP_CWORD
+
+  if [[ $cword -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "${subcommandList} ${topLevelFlags}" -- "$cur") )
+    return 0
+  fi
+
+  case "\${COMP_WORDS[1]}" in
+${cases}
+  esac
+}
+complete -F _mcph mcph
+`;
+}
+function renderZsh() {
+  const subcommandDescriptions = {
+    install: "Auto-edit an MCP client's config",
+    doctor: "Print diagnostic of mcph setup",
+    servers: "List servers in your mcp.hosting dashboard",
+    bundles: "Browse curated multi-server bundles",
+    compliance: "Run the compliance suite against a server",
+    "reset-learning": "Clear cross-session learning history",
+    completion: "Print a shell completion script",
+    help: "Show usage"
+  };
+  const subcommandList = SUBCOMMAND_SPEC.map((s) => `    '${s.name}:${subcommandDescriptions[s.name] ?? ""}'`).join(
+    "\n"
+  );
+  const argsCases = SUBCOMMAND_SPEC.map((spec) => {
+    const lines = [`      ${spec.name})`];
+    if (spec.positional) {
+      lines.push(`        _arguments '1: :(${spec.positional.join(" ")})' '*: :(${spec.flags.join(" ")})'`);
+    } else {
+      lines.push(`        _arguments '*: :(${spec.flags.join(" ")})'`);
+    }
+    lines.push("        ;;");
+    return lines.join("\n");
+  }).join("\n");
+  return `#compdef mcph
+# zsh completion for mcph \u2014 generated by \`mcph completion zsh\`
+# Install: save this to a file on your $fpath named _mcph
+#          (e.g., ~/.zsh/completions/_mcph), then rebuild completions:
+#            autoload -U compinit && compinit
+_mcph() {
+  local context state line
+  _arguments -C \\
+    '1: :->cmd' \\
+    '*::arg:->args'
+
+  case $state in
+    cmd)
+      _values 'mcph subcommand' \\
+${subcommandList}
+      ;;
+    args)
+      case $line[1] in
+${argsCases}
+      esac
+      ;;
+  esac
+}
+_mcph "$@"
+`;
+}
+function renderFish() {
+  const header = `# fish completion for mcph \u2014 generated by \`mcph completion fish\`
+# Install: save this to ~/.config/fish/completions/mcph.fish
+complete -c mcph -f`;
+  const subcommandLines = SUBCOMMAND_SPEC.map((spec) => {
+    return `complete -c mcph -n __fish_use_subcommand -a ${spec.name}`;
+  });
+  const positionalLines = [];
+  const flagLines = [];
+  for (const spec of SUBCOMMAND_SPEC) {
+    if (spec.positional) {
+      for (const p of spec.positional) {
+        positionalLines.push(`complete -c mcph -n "__fish_seen_subcommand_from ${spec.name}" -a ${p}`);
+      }
+    }
+    for (const f of spec.flags) {
+      const long = f.replace(/^--/, "");
+      flagLines.push(`complete -c mcph -n "__fish_seen_subcommand_from ${spec.name}" -l ${long}`);
+    }
+  }
+  return [header, "", ...subcommandLines, "", ...positionalLines, "", ...flagLines, ""].join("\n");
+}
+function renderPowershell() {
+  const subcommandNames = SUBCOMMAND_SPEC.map((s) => `'${s.name}'`).join(", ");
+  const caseBranches = SUBCOMMAND_SPEC.map((spec) => {
+    const positional = spec.positional ? spec.positional.map((p) => `'${p}'`).join(", ") : "";
+    const flags = spec.flags.map((f) => `'${f}'`).join(", ");
+    const positionalLine = positional ? `      $completions += @(${positional})
+` : "";
+    return `    '${spec.name}' {
+${positionalLine}      $completions += @(${flags})
+    }`;
+  }).join("\n");
+  return `# PowerShell completion for mcph \u2014 generated by \`mcph completion powershell\`
+# Install: append this script to your profile ($PROFILE) and reload.
+Register-ArgumentCompleter -CommandName mcph -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $tokens = $commandAst.CommandElements | ForEach-Object { $_.ToString() }
+  $completions = @()
+  if ($tokens.Count -le 2) {
+    $completions = @(${subcommandNames}, '--help', '-h', '--version', '-V')
+  } else {
+    switch ($tokens[1]) {
+${caseBranches}
+    }
+  }
+  $completions | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+  }
+}
+`;
+}
+
 // src/compliance-cmd.ts
 import { spawn } from "child_process";
 import { request as request2 } from "undici";
@@ -1219,8 +1435,9 @@ function selectFlakyNamespaces(entries, limit) {
 }
 
 // src/doctor-cmd.ts
-var VERSION = true ? "0.40.0" : "dev";
+var VERSION = true ? "0.42.0" : "dev";
 async function runDoctor(opts = {}) {
+  if (opts.json) return runDoctorJson(opts);
   const lines = [];
   const write = opts.out ?? ((s) => process.stdout.write(s));
   const print = (s = "") => {
@@ -1309,6 +1526,101 @@ async function runDoctor(opts = {}) {
   }
   return { exitCode, lines, snapshot: { version: VERSION, config, clients } };
 }
+async function runDoctorJson(opts) {
+  const lines = [];
+  const write = opts.out ?? ((s) => process.stdout.write(s));
+  const cwd = opts.cwd ?? process.cwd();
+  const home = opts.home ?? homedir4();
+  const os = opts.os ?? CURRENT_OS;
+  const env = opts.env ?? process.env;
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const config = await loadMcphConfig({ cwd, home, env });
+  const clients = probeClients({ home, os, cwd });
+  const envVarNames = [
+    "MCPH_POLL_INTERVAL",
+    "MCPH_SERVER_CAP",
+    "MCPH_MIN_COMPLIANCE",
+    "MCPH_AUTO_LOAD",
+    "MCPH_PRUNE_RESPONSES"
+  ];
+  const envOverrides = {};
+  for (const name of envVarNames) {
+    const raw = env[name];
+    envOverrides[name] = raw === void 0 || raw === "" ? null : raw;
+  }
+  const persistRaw = env.MCPH_DISABLE_PERSISTENCE;
+  const persistDisabled = persistRaw !== void 0 && persistRaw !== "" && (persistRaw === "1" || persistRaw.toLowerCase() === "true");
+  const state = persistDisabled ? { disabled: true, path: null, savedAt: null, learningEntries: null, packHistoryEntries: null } : await (async () => {
+    const filePath = join4(userConfigDir(home), STATE_FILENAME);
+    const persisted = await loadState(filePath);
+    const fresh = persisted.savedAt === 0;
+    return {
+      disabled: false,
+      path: filePath,
+      savedAt: fresh ? null : new Date(persisted.savedAt).toISOString(),
+      learningEntries: fresh ? 0 : Object.keys(persisted.learning).length,
+      packHistoryEntries: fresh ? 0 : persisted.packHistory.length
+    };
+  })();
+  const reliability = [];
+  if (!persistDisabled) {
+    const filePath = join4(userConfigDir(home), STATE_FILENAME);
+    const persisted = await loadState(filePath);
+    if (persisted.savedAt !== 0) {
+      const entries = Object.entries(persisted.learning).map(([namespace, usage]) => ({ namespace, usage }));
+      for (const { namespace, usage } of selectFlakyNamespaces(entries, 5)) {
+        reliability.push({
+          namespace,
+          dispatched: usage.dispatched,
+          succeeded: usage.succeeded,
+          successRate: usage.succeeded / usage.dispatched,
+          lastUsedAt: new Date(usage.lastUsedAt).toISOString()
+        });
+      }
+    }
+  }
+  const shellShadows = scanShellHistoryForShadows({ home, env });
+  const skipCheck = opts.skipRegistryCheck === true || Boolean(process.env.VITEST);
+  const latest = skipCheck ? null : await fetchLatestVersion(opts.registryFetch);
+  const stale = latest !== null && VERSION !== "dev" && compareSemver(VERSION, latest) < 0;
+  let exitCode = 0;
+  let summary;
+  if (config.token === null) {
+    exitCode = 1;
+    summary = "No token resolved \u2014 mcph cannot start.";
+  } else if (config.warnings.length > 0) {
+    exitCode = 2;
+    summary = "Token present, but warnings need attention.";
+  } else {
+    summary = stale ? "Healthy, but an upgrade is available." : "All good. mcph should start cleanly.";
+  }
+  const snapshotJson = {
+    timestamp,
+    version: VERSION,
+    platform: os,
+    token: { fingerprint: tokenFingerprint(config.token), source: config.tokenSource },
+    apiBase: { value: config.apiBase, source: config.apiBaseSource },
+    loadedFiles: config.loadedFiles.map((f) => ({
+      scope: f.scope,
+      path: f.path,
+      ...f.version !== void 0 ? { schemaVersion: f.version } : {},
+      schemaAhead: f.version !== void 0 && f.version > CURRENT_SCHEMA_VERSION
+    })),
+    warnings: config.warnings,
+    env: envOverrides,
+    state,
+    reliability,
+    clients,
+    shellShadows,
+    upgrade: { current: VERSION, latest, stale },
+    diagnosis: { exitCode, summary }
+  };
+  const blob = JSON.stringify(snapshotJson, null, 2);
+  lines.push(blob);
+  write(`${blob}
+`);
+  return { exitCode, lines, snapshot: { version: VERSION, config, clients } };
+}
 function renderEnvSection(opts) {
   const { env, print } = opts;
   const vars = [
@@ -4207,7 +4519,7 @@ function categorizeSpawnError(err) {
 }
 async function connectToUpstream(config, onDisconnect, onListChanged) {
   const client = new Client(
-    { name: "mcph", version: true ? "0.40.0" : "dev" },
+    { name: "mcph", version: true ? "0.42.0" : "dev" },
     { capabilities: {} }
   );
   let transport;
@@ -4688,7 +5000,7 @@ var ConnectServer = class _ConnectServer {
     this.apiUrl = apiUrl6;
     this.token = token6;
     this.server = new Server(
-      { name: "mcph", version: true ? "0.40.0" : "dev" },
+      { name: "mcph", version: true ? "0.42.0" : "dev" },
       {
         capabilities: {
           tools: { listChanged: true },
@@ -6852,6 +7164,7 @@ var KNOWN_SUBCOMMANDS = [
   "reset-learning",
   "servers",
   "bundles",
+  "completion",
   "help",
   "--help",
   "-h",
@@ -6870,7 +7183,21 @@ if (subcommand === "compliance") {
   }
   runInstall(parsed.options).then((r) => process.exit(r.exitCode));
 } else if (subcommand === "doctor") {
-  runDoctor().then((r) => process.exit(r.exitCode));
+  const doctorArgs = process.argv.slice(3);
+  const doctorJson = doctorArgs.includes("--json");
+  const doctorUnknown = doctorArgs.find((a) => a !== "--json" && a !== "--help" && a !== "-h");
+  if (doctorArgs.includes("--help") || doctorArgs.includes("-h")) {
+    process.stdout.write(
+      "Usage: mcph doctor [--json]\n\n  Print a diagnostic of your mcph setup.\n\n  --json  Emit machine-readable JSON instead of text.\n"
+    );
+    process.exit(0);
+  }
+  if (doctorUnknown) {
+    process.stderr.write(`mcph doctor: unknown argument "${doctorUnknown}"
+`);
+    process.exit(2);
+  }
+  runDoctor({ json: doctorJson }).then((r) => process.exit(r.exitCode));
 } else if (subcommand === "reset-learning") {
   runResetLearning().then((r) => process.exit(r.exitCode));
 } else if (subcommand === "servers") {
@@ -6889,6 +7216,14 @@ if (subcommand === "compliance") {
     process.exit(2);
   }
   runBundlesCommand(parsed.options).then((r) => process.exit(r.exitCode));
+} else if (subcommand === "completion") {
+  const parsed = parseCompletionArgs(process.argv.slice(3));
+  if (!parsed.ok) {
+    process.stderr.write(`${parsed.error}
+`);
+    process.exit(2);
+  }
+  runCompletion(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(
@@ -6898,11 +7233,12 @@ if (subcommand === "compliance") {
   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                       Print loaded config + detected clients (support diagnostic)
+    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 --version                    Print version
 
   Install:
@@ -6923,7 +7259,7 @@ ${installBlock}
   );
   process.exit(0);
 } else if (subcommand === "--version" || subcommand === "-V") {
-  process.stdout.write(`mcph ${true ? "0.40.0" : "dev"}
+  process.stdout.write(`mcph ${true ? "0.42.0" : "dev"}
 `);
   process.exit(0);
 } else if (subcommand && !subcommand.startsWith("-")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/mcph",
-  "version": "0.40.0",
+  "version": "0.42.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)",