@yawlabs/mcph 0.42.0 → 0.43.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 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.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).
+- **README catch-up — `CLI reference` block + `doctor --json` documented** — The README was missing the subcommands that landed in v0.38.0 onward (`servers`, `bundles`, `reset-learning`, `completion`) and hadn't been updated to mention doctor's `--json` mode. New compact "Other CLI subcommands" block lists every user-facing command with a one-line purpose, documents the `--json` pattern as the pipeline interface across doctor/servers/bundles, and includes copy-paste install snippets for bash/zsh/fish/powershell completions. The doctor paragraph now lists the actual section coverage (env overrides, persisted state, reliability rollup, shell-shadow hits, upgrade check) so first-time readers know what they get.
+
 ## 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`.

package/README.md

@@ -70,10 +70,40 @@ Or [edit the JSON by hand](#manual-install) if you'd rather.
 ### Diagnose problems — `mcph doctor`
 
 ```bash
-npx -y @yawlabs/mcph doctor
+npx -y @yawlabs/mcph doctor          # human-readable report
+npx -y @yawlabs/mcph doctor --json   # machine-readable snapshot for pipelines
 ```
 
-Prints the loaded config files, your token's source + fingerprint (last 4 chars), the API base URL, and which MCP clients on this machine have an `mcp.hosting` entry. Exits `0` healthy / `1` no token / `2` warnings (e.g. world-readable token file). Paste the full output into a support ticket and we can usually pinpoint the issue from that alone.
+Prints the loaded config files, your token's source + fingerprint (last 4 chars), the API base URL, installed clients, env overrides, persisted learning state, flaky-namespace reliability rollup, shell-history "shadow" hits (CLIs you run that an MCP server could replace), and an upgrade check against the npm registry. Exits `0` healthy / `1` no token / `2` warnings (e.g. world-readable token file). Paste the text output into a support ticket; the `--json` blob is the same data as a structured snapshot, so dashboards and CI scripts can `jq` instead of parsing the text layout.
+
+### Other CLI subcommands
+
+```bash
+mcph servers [<namespace-filter>] [--json]    # list servers; optional substring filter on namespace
+mcph bundles [list|match] [--json]    # browse curated multi-server bundles (PR review, DevOps incident, etc.)
+mcph reset-learning                   # clear cross-session learning history (~/.mcph/state.json)
+mcph completion <bash|zsh|fish|powershell>   # print shell completion script
+mcph compliance <target> [--publish]  # run the compliance suite against an MCP server
+mcph --version                        # print version
+```
+
+Every CLI that reads state has a `--json` mode for pipeline use. `mcph servers` hits the backend; `mcph bundles list` and `mcph completion` are fully static (no network, no token). `mcph bundles match` partitions the curated set against your enabled servers so you see the same ready-to-activate vs. partially-installed view the LLM-facing `mcp_connect_bundles` meta-tool produces.
+
+To wire up shell completion:
+
+```bash
+# bash
+mcph completion bash > ~/.local/share/bash-completion/completions/mcph
+
+# zsh (must be on $fpath, then rebuild compinit)
+mcph completion zsh > "${fpath[1]}/_mcph"
+
+# fish
+mcph completion fish > ~/.config/fish/completions/mcph.fish
+
+# powershell
+mcph completion powershell >> $PROFILE
+```
 
 ### Getting your token
 

package/dist/index.js

@@ -1435,7 +1435,7 @@ function selectFlakyNamespaces(entries, limit) {
 }
 
 // src/doctor-cmd.ts
-var VERSION = true ? "0.42.0" : "dev";
+var VERSION = true ? "0.43.0" : "dev";
 async function runDoctor(opts = {}) {
   if (opts.json) return runDoctorJson(opts);
   const lines = [];
@@ -4519,7 +4519,7 @@ function categorizeSpawnError(err) {
 }
 async function connectToUpstream(config, onDisconnect, onListChanged) {
   const client = new Client(
-    { name: "mcph", version: true ? "0.42.0" : "dev" },
+    { name: "mcph", version: true ? "0.43.0" : "dev" },
     { capabilities: {} }
   );
   let transport;
@@ -5000,7 +5000,7 @@ var ConnectServer = class _ConnectServer {
     this.apiUrl = apiUrl6;
     this.token = token6;
     this.server = new Server(
-      { name: "mcph", version: true ? "0.42.0" : "dev" },
+      { name: "mcph", version: true ? "0.43.0" : "dev" },
       {
         capabilities: {
           tools: { listChanged: true },
@@ -7055,24 +7055,33 @@ To load the top pack in one step, call \`mcp_connect_activate\` with namespaces=
 // src/servers-cmd.ts
 function parseServersArgs(argv) {
   let json = false;
+  let filter;
   for (const a of argv) {
     if (a === "--json") {
       json = true;
     } else if (a === "--help" || a === "-h") {
       return { ok: false, error: SERVERS_USAGE };
-    } else {
+    } else if (a.startsWith("-")) {
       return { ok: false, error: `mcph servers: unknown argument "${a}"
 
+${SERVERS_USAGE}` };
+    } else if (filter === void 0) {
+      filter = a;
+    } else {
+      return { ok: false, error: `mcph servers: unexpected extra argument "${a}"
+
 ${SERVERS_USAGE}` };
     }
   }
-  return { ok: true, options: { json } };
+  return { ok: true, options: { json, ...filter !== void 0 ? { filter } : {} } };
 }
-var SERVERS_USAGE = `Usage: mcph servers [--json]
+var SERVERS_USAGE = `Usage: mcph servers [<namespace-filter>] [--json]
 
   List the servers configured in your mcp.hosting dashboard.
 
-  --json   Emit machine-readable JSON instead of a table.`;
+  <namespace-filter>   Case-insensitive substring filter on namespace (e.g.,
+                       \`mcph servers git\` matches github + gitlab).
+  --json               Emit machine-readable JSON instead of a table.`;
 async function runServersCommand(opts = {}) {
   const write = opts.out ?? ((s) => process.stdout.write(s));
   const writeErr = opts.err ?? ((s) => process.stderr.write(s));
@@ -7109,11 +7118,19 @@ async function runServersCommand(opts = {}) {
     printErr("mcph servers: backend returned no data (unexpected 304).");
     return { exitCode: 2, lines };
   }
+  const filtered = opts.filter ? {
+    ...backend,
+    servers: backend.servers.filter((s) => s.namespace.toLowerCase().includes(opts.filter.toLowerCase()))
+  } : backend;
   if (opts.json) {
-    print(JSON.stringify(backend, null, 2));
+    print(JSON.stringify(filtered, null, 2));
+    return { exitCode: 0, lines };
+  }
+  if (opts.filter && filtered.servers.length === 0) {
+    print(`No servers match "${opts.filter}". Run \`mcph servers\` to see the full list.`);
     return { exitCode: 0, lines };
   }
-  renderTable(backend, print);
+  renderTable(filtered, print);
   return { exitCode: 0, lines };
 }
 function renderTable(cfg, print) {
@@ -7259,7 +7276,7 @@ ${installBlock}
   );
   process.exit(0);
 } else if (subcommand === "--version" || subcommand === "-V") {
-  process.stdout.write(`mcph ${true ? "0.42.0" : "dev"}
+  process.stdout.write(`mcph ${true ? "0.43.0" : "dev"}
 `);
   process.exit(0);
 } else if (subcommand && !subcommand.startsWith("-")) {

package/package.json

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