@yawlabs/mcph 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+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.29.0 — 2026-04-18
+
+- **Compliance-aware routing (`MCPH_MIN_COMPLIANCE`)** — Phase 3 item. Set the env var to `A`, `B`, `C`, `D`, or `F` and `mcp_connect_activate` refuses to load any installed server whose reported `complianceGrade` is below the floor, with an error that names the grade and the env var to unset. `mcp_connect_discover` annotates below-grade servers in place (so the model knows they exist and why they won't auto-activate) and emits a "Compliance filter active" header. Forward-compatible schema: the optional `complianceGrade` field on `UpstreamServerConfig` rides the existing `/api/connect/config` response — the feature kicks in automatically once the backend starts populating grades. Ungraded servers always pass (don't punish unknown).
+
+## 0.28.1 — 2026-04-18
+
+Docs-only release.
+
+- First-ever `CHANGELOG.md`, covering 0.5.0 → 0.28.0. Linked from `README.md`.
+- README catches up with the meta-tools shipped in the 0.20 – 0.28 arc: `mcp_connect_read_tool`, `mcp_connect_exec`, `mcp_connect_bundles` are now documented in the top-level list. Corrected "session-local" phrasing on the Learning ranker signal (cross-session since v0.23.0).
+- New "Multi-device sync" section under "Config sync" — same token, same servers across every machine; no dotfile repos for secrets.
+- Phase 2 "Multi-device config sync" marked shipped in `ROADMAP.md` (docs-only; backing behavior already worked).
+- `package.json` `files` array now includes `CHANGELOG.md` so release notes ship with the npm tarball.
+
+## 0.28.0 — 2026-04-18
+
+Phase 3 opener. Two client-only intelligence features.
+
+- **Tool deduplication** — `mcp_connect_discover` now surfaces an "Overlapping tools" block when two or more currently-connected servers expose the same bare tool name. Top 5 overlaps, sorted by namespace count descending, with a dispatch-to-disambiguate hint.
+- **Curated bundles (`mcp_connect_bundles`)** — New meta-tool returning hand-picked multi-server presets: `devops-incident`, `pr-review`, `growth-stack`, `data-ops`, `product-release`, `support-ops`. `action: "list"` (default) returns all bundles; `action: "match"` partitions them into "ready to activate now" vs. "partially installed" against the user's current config.
+
+## 0.27.0 — 2026-04-18
+
+Four Phase 2 items shipped together.
+
+- **Automatic load (`MCPH_AUTO_LOAD`)** — Opt-in env flag. On startup, after persistence hydration, activates every namespace in the top recurring pack (by frequency, tie-break recency) from pack history, provided every namespace is installed. Silent no-op otherwise.
+- **Per-tool filter on `mcp_connect_activate`** — Pass `tools: [...]` to expose only the named tools via `tools/list`. Hidden tools stay reachable through `mcp_connect_dispatch` (routes are unfiltered). Re-activate without `tools` to clear the filter. `discover()` shows a `(filtered: K of N)` indicator on filtered connections.
+- **Orchestration pipeline (`mcp_connect_exec`)** — Declarative multi-step tool-call pipeline. Each step names a namespaced tool plus args; `{"$ref": "<stepId>[.path]"}` markers in args splice a prior step's output into the next step's input. No eval / no expression language — only sequential dispatch and dot/bracket path resolution. Capped at 16 steps; any step failure fails the pipeline and returns completed outputs as `partial`.
+- **Marketplace pointer** — `discover()` appends `https://mcp.hosting/explore` for users with fewer than 5 installed servers. URL hint only; a full marketplace meta-tool is parked until the backend ships a catalog API.
+
+## 0.26.0 — 2026-04-18
+
+- **Recurring packs block in `discover()`** — When pack history and installed config overlap, `discover()` now surfaces an "Recurring packs" block at the top of its output with a ready-to-run `mcp_connect_activate` call. Saves the second `mcp_connect_suggest` round-trip when the signal is already there.
+
+## 0.25.1 — 2026-04-18
+
+- Truthed up "this session" phrasing across user-facing strings and tool descriptions. With cross-session persistence (v0.23.0) shipping, counts and pack history are no longer session-scoped; the copy now matches.
+
+## 0.25.0 — 2026-04-18
+
+- `mcp_connect_suggest` now emits a ready-to-run `mcp_connect_activate` call with a verbatim `namespaces=[...]` JSON array, rather than pointing at `mcp_connect_dispatch` (the wrong primitive for loading a pack).
+
+## 0.24.0 — 2026-04-18
+
+- **`mcph doctor` STATE section** — Prints `~/.mcph/state.json` path, last-saved age, learning count, pack history count; shows "disabled" when persistence is opted out.
+- **`MCPH_DISABLE_PERSISTENCE` opt-out** — Env flag skips both load and save. Useful for CI, sandboxed containers, or users who don't want a state file.
+
+## 0.23.0 — 2026-04-18
+
+- **Cross-session persistence** — Learning counts (`succeeded`/`dispatched`/`lastUsedAt` per namespace) and pack history (co-activation chains) now round-trip through `~/.mcph/state.json`. Schema-versioned, atomic write-rename.
+
+## 0.22.0 — 2026-04-17
+
+- **Inline usage hints in `discover()`** — `used Nx` success counts and "often loaded with X, Y" co-activation peers are surfaced per-server in discover output.
+
+## 0.21.0 — 2026-04-17
+
+- **Concurrent server cap** — Default max 6 simultaneously-active servers; `MCPH_SERVER_CAP` env override. Hard cap both as context protection and a business lever.
+
+## 0.20.0 — 2026-04-17
+
+- **`mcp_connect_read_tool`** — Schema-on-demand: return a single tool's schema + docs without activating its server. For servers with large tool catalogs where the model only needs 1–2 tools, reads 1–2 schemas instead of loading the entire catalog.
+
+## 0.19.x and earlier
+
+- v0.19.0 — internal refactor around config reconciliation.
+- v0.18.0 — analytics uploads for tool-call patterns, load/unload events, error rates.
+- v0.17.0 — resource + prompt proxying (beyond tools).
+- v0.16.0 — error tracking surfaced in `discover()`.
+- v0.15.x — `install` command gates success on config refresh; misc fixes.
+- v0.14.0 — auto-allow mcph tools in Claude Code settings + discover dedup.
+- v0.13.0 — deferred tools: advertise inactive-but-cached servers in `tools/list`.
+- v0.12.x — legacy-config migrator + `doctor` freshness checks.
+- v0.11.x — stability patches.
+- v0.10.x — 7-feature bundle, adaptive routing, policy profiles.
+- v0.9.0 — `mcph compliance` subcommand.
+- v0.8.0 — runtime detection + test runner + error deep-links.
+- v0.7.0 — two-stage retrieval: BM25 + semantic rerank.
+- v0.6.0 — BM25 dispatch + auto-warm discover + stderr capture.
+- v0.5.0 — `MCPH_POLL_INTERVAL` env var.
+- v0.1.x – v0.4.x — initial public release, core meta-tools, namespace routing, config polling.

package/README.md

@@ -27,16 +27,19 @@ Your MCP client (Claude Code, Cursor, etc.)
    - **`mcp_connect_install`** — install a new MCP server on your mcp.hosting account.
    - **`mcp_connect_import`** — bulk-import servers from an existing client config (`claude_desktop_config.json`, `mcp.json`, etc.).
    - **`mcp_connect_health`** — show call counts, error rates, and latency per loaded server.
-   - **`mcp_connect_suggest`** — surface recurring multi-server workflows mcph has watched in this session. When you repeatedly use `gh` → `linear` → `slack` for the same kind of task, `suggest` lists the pattern so you can dispatch it as one intent next time.
+   - **`mcp_connect_suggest`** — surface recurring multi-server workflows mcph has learned from persisted pack history. When you repeatedly use `gh` → `linear` → `slack` for the same kind of task, `suggest` lists the pattern with a ready-to-run `activate` call so you can load the whole pack at once.
+   - **`mcp_connect_read_tool`** — return a single tool's schema + docs without activating its server. Reads 1–2 schemas instead of loading a whole catalog when the model only needs a couple of tools from a big server.
+   - **`mcp_connect_exec`** — run a short declarative pipeline of tool calls in one round-trip. Steps name namespaced tools + args; `{"$ref": "<stepId>[.path]"}` markers splice prior outputs into later inputs. No eval — only dot/bracket path resolution. Capped at 16 steps.
+   - **`mcp_connect_bundles`** — list curated multi-server presets (DevOps incident, PR review, growth stack, data ops, etc.) and/or match them against your current config. Pair it with `mcp_connect_activate` to load a whole bundle at once.
 
 Installing a server puts it on your account; loading it brings its tools into the current session's context. mcph loads servers lazily so your context window stays clean.
 
 Ranking is two-stage when the backend has a Voyage embeddings key configured: a local BM25 pass narrows to a shortlist, then a `/api/connect/rerank` call semantically reorders. With no key on the backend it gracefully degrades to BM25-only — `dispatch` and `discover(context)` keep working, just with slightly weaker ranking on ambiguous queries.
 
-On top of the ranker, mcph applies three session-local signals to dispatch scores:
+On top of the ranker, mcph applies three client-side signals to dispatch scores:
 
 - **Health-aware**: servers that have recently failed to load or have high error rates get down-ranked. Never boosts above raw — "all else equal, prefer the one that works".
-- **Learning**: servers that have succeeded this session get a small (+10% max) nudge, so the router remembers what's been useful.
+- **Learning**: servers that have succeeded before get a small (+10% max) nudge, so the router remembers what's been useful. Success counts persist across restarts via `~/.mcph/state.json` (opt out with `MCPH_DISABLE_PERSISTENCE=1`).
 - **Sampling tiebreak**: when the top two candidates are within 10% of each other and your client supports [MCP sampling](https://modelcontextprotocol.io/specification/server/sampling), mcph asks your client's LLM to pick. Uses the model you're already running — no extra provider key, no extra cost to mcph.
 
 ## Install
@@ -264,6 +267,12 @@ When a load fails (missing token, runtime not on PATH, server crashes on init),
 
 mcph polls [mcp.hosting](https://mcp.hosting) every 60 seconds for config changes. When you add, remove, or modify a server on the dashboard, mcph picks it up automatically — no restart needed.
 
+### Multi-device sync
+
+Because every mcph install reads the same account's server list, the same token gives you the same servers across every machine. Install mcph on a second laptop with the same `mcp_pat_...`, and within 60 seconds it sees the same GitHub/Slack/Stripe/etc. servers you configured from the first. Tokens, environment variables, and credentials stay in the dashboard — you don't have to sync a JSON file across machines, copy secrets into a dotfile repo, or re-paste an API key per device.
+
+Rotate a credential in one place (the dashboard), every machine picks up the new value on the next poll. Revoke a token in Settings → API Tokens, every install stops working immediately (the token is the only thing authenticating the config pull). This is why `~/.mcph/config.json` holds a token, not a server list — the server list is the cloud's concern.
+
 ## Environment variables
 
 | Variable | Required | Description |
@@ -277,6 +286,7 @@ mcph polls [mcp.hosting](https://mcp.hosting) every 60 seconds for config change
 | `MCPH_PRUNE_RESPONSES` | No | Conservative response pruning (redact large file blobs etc. before returning to the client). Set to `0` or `false` to disable. Default: enabled. |
 | `MCPH_DISABLE_PERSISTENCE` | No | Set to `1` or `true` to keep learning + pack-history scoped to the current process — nothing loaded at start, nothing written on shutdown. Intended for ephemeral / shared environments (CI, containers). Default: cross-session persistence enabled at `~/.mcph/state.json`. |
 | `MCPH_AUTO_LOAD` | No | Set to `1` or `true` to pre-activate the top recurring pack (from persisted pack-history) on startup — no LLM round-trip required. Skips silently when history is empty or no pack's namespaces are all installed. Default: off. Requires persistence to be enabled. |
+| `MCPH_MIN_COMPLIANCE` | No | Minimum compliance grade (`A`, `B`, `C`, `D`, or `F`, case-insensitive) an installed server must report before `mcp_connect_activate` will load it. Ungraded servers always pass (don't punish unknown). `discover()` annotates below-grade servers in place and shows a "Compliance filter active" header when set. Invalid values log a warning and disable the filter. Default: unset (no filter). |
 | `MCP_CONNECT_TIMEOUT` | No | Connection timeout in ms for upstream servers (default: `15000`) |
 | `MCP_CONNECT_IDLE_THRESHOLD` | No | Baseline for idle auto-unload (default: `10`). The per-namespace adaptive cap is `[5, 50]` — bursty namespaces extend past the baseline, long-idle ones unload at it. |
 
@@ -301,4 +311,5 @@ The popular Python-based MCP servers (`fetch`, `sqlite`, `time`, `sentry`, etc.)
 
 - [mcp.hosting](https://mcp.hosting) — Dashboard and server management
 - [@yawlabs/mcp-compliance](https://www.npmjs.com/package/@yawlabs/mcp-compliance) — Test your MCP servers for spec compliance
+- [CHANGELOG](./CHANGELOG.md) — Release notes
 - [GitHub](https://github.com/YawLabs/mcph) — Source code and issues

package/dist/index.js

@@ -946,7 +946,7 @@ function errorMessage(err) {
 }
 
 // src/doctor-cmd.ts
-var VERSION = true ? "0.28.0" : "dev";
+var VERSION = true ? "0.29.0" : "dev";
 async function runDoctor(opts = {}) {
   const lines = [];
   const write = opts.out ?? ((s) => process.stdout.write(s));
@@ -1825,6 +1825,42 @@ function bundleActivateHint(bundle) {
   return `mcp_connect_activate({ namespaces: ${JSON.stringify(bundle.namespaces)} })`;
 }
 
+// src/compliance.ts
+var GRADE_ORDER = {
+  A: 4,
+  B: 3,
+  C: 2,
+  D: 1,
+  F: 0
+};
+function gradeRank(grade) {
+  if (!grade) return -1;
+  const up = grade.toUpperCase();
+  if (up in GRADE_ORDER) return GRADE_ORDER[up];
+  return -1;
+}
+var invalidWarned = false;
+function parseMinCompliance(raw) {
+  if (raw === void 0) return null;
+  const trimmed = raw.trim();
+  if (trimmed === "") return null;
+  const up = trimmed.toUpperCase();
+  if (up === "A" || up === "B" || up === "C" || up === "D" || up === "F") {
+    return up;
+  }
+  if (!invalidWarned) {
+    invalidWarned = true;
+    log("warn", "Invalid MCPH_MIN_COMPLIANCE; filter disabled", { value: raw });
+  }
+  return null;
+}
+function passesMinCompliance(serverGrade, min) {
+  if (min === null) return true;
+  const serverRank = gradeRank(serverGrade);
+  if (serverRank < 0) return true;
+  return serverRank >= gradeRank(min);
+}
+
 // src/cost-estimate.ts
 var BYTES_PER_TOKEN = 4;
 var CACHED_TOOL_SCHEMA_PAD_BYTES = 200;
@@ -2319,7 +2355,7 @@ var META_TOOLS = {
   },
   activate: {
     name: "mcp_connect_activate",
-    description: 'Load one or more installed MCP servers\' tools into the current session by namespace. Each server adds its tools to your context, so load only what the current task needs. When you move on, unload servers you\'re done with via `mcp_connect_deactivate` before loading new ones. Tools are prefixed by namespace (e.g., "gh_create_issue"). Pass "server" for one or "servers" for multiple. Optionally pass `tools: [...]` to expose only those tools by name \u2014 the rest stay proxyable via mcp_connect_dispatch.',
+    description: 'Load one or more installed MCP servers\' tools into the current session by namespace. Each server adds its tools to your context, so load only what the current task needs. When you move on, unload servers you\'re done with via `mcp_connect_deactivate` before loading new ones. Tools are prefixed by namespace (e.g., "gh_create_issue"). Pass "server" for one or "servers" for multiple. Optionally pass `tools: [...]` to expose only those tools by name \u2014 the rest stay proxyable via mcp_connect_dispatch. If `MCPH_MIN_COMPLIANCE` is set, activation refuses servers whose reported grade is below the floor (ungraded servers always pass); the refusal message names the grade and the env var to unset.',
     inputSchema: {
       type: "object",
       properties: {
@@ -3791,7 +3827,7 @@ function categorizeSpawnError(err) {
 }
 async function connectToUpstream(config, onDisconnect, onListChanged) {
   const client = new Client(
-    { name: "mcph", version: true ? "0.28.0" : "dev" },
+    { name: "mcph", version: true ? "0.29.0" : "dev" },
     { capabilities: {} }
   );
   let transport;
@@ -4242,6 +4278,9 @@ function isPersistenceDisabled() {
   if (raw === void 0 || raw === "") return false;
   return raw === "1" || raw.toLowerCase() === "true";
 }
+function resolveMinCompliance() {
+  return parseMinCompliance(process.env.MCPH_MIN_COMPLIANCE);
+}
 function isAutoLoadEnabled() {
   const raw = process.env.MCPH_AUTO_LOAD;
   if (raw === void 0 || raw === "") return false;
@@ -4305,7 +4344,7 @@ var ConnectServer = class _ConnectServer {
     this.apiUrl = apiUrl6;
     this.token = token6;
     this.server = new Server(
-      { name: "mcph", version: true ? "0.28.0" : "dev" },
+      { name: "mcph", version: true ? "0.29.0" : "dev" },
       {
         capabilities: {
           tools: { listChanged: true },
@@ -5100,6 +5139,11 @@ var ConnectServer = class _ConnectServer {
     const lines = [context ? "Servers ranked by relevance:\n" : "Installed MCP servers:\n"];
     if (autoWarmed && sorted.length > 0) {
       lines.push(`Auto-loaded "${sorted[0].namespace}" \u2014 top match for your query.
+`);
+    }
+    const minCompliance = resolveMinCompliance();
+    if (minCompliance !== null) {
+      lines.push(`Compliance filter active: MCPH_MIN_COMPLIANCE=${minCompliance}
 `);
     }
     if (context) {
@@ -5160,7 +5204,17 @@ var ConnectServer = class _ConnectServer {
           costLabel = ` \u2014 ${formatCostLabel(estimateFromToolCache(cached))}`;
         }
       }
-      lines.push(`  ${server.namespace} \u2014 ${server.name} [${status}] (${server.type})${relevance}${costLabel}`);
+      let complianceLabel = "";
+      if (minCompliance !== null && server.complianceGrade) {
+        if (passesMinCompliance(server.complianceGrade, minCompliance)) {
+          complianceLabel = ` [${server.complianceGrade}]`;
+        } else {
+          complianceLabel = ` (grade ${server.complianceGrade} \u2014 below MCPH_MIN_COMPLIANCE=${minCompliance}, won't auto-activate)`;
+        }
+      }
+      lines.push(
+        `  ${server.namespace} \u2014 ${server.name} [${status}] (${server.type})${relevance}${costLabel}${complianceLabel}`
+      );
       const shadow = formatShadowLine(server);
       if (shadow) lines.push(`    ${shadow}`);
       const warning = formatHealthWarning(connection?.health, this.activationFailures.get(server.namespace));
@@ -5418,10 +5472,21 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
     const results = [];
     let anyChanged = false;
     let anyError = false;
+    const minCompliance = resolveMinCompliance();
     const total = namespaces.length;
     let i = 0;
     for (const namespace of namespaces) {
       i += 1;
+      if (minCompliance !== null) {
+        const cfg = this.config?.servers.find((s) => s.namespace === namespace);
+        if (cfg && !passesMinCompliance(cfg.complianceGrade, minCompliance)) {
+          const grade = cfg.complianceGrade ?? "unknown";
+          const message = `Refused to load "${namespace}": compliance grade ${grade} is below MCPH_MIN_COMPLIANCE=${minCompliance}. Unset MCPH_MIN_COMPLIANCE (or lower it) to override.`;
+          results.push(message);
+          anyError = true;
+          continue;
+        }
+      }
       progress?.(`Loading ${namespace} (${i}/${total})`, i - 1, total);
       const r = await this.activateOne(namespace, progress);
       results.push(r.message);
@@ -6340,7 +6405,7 @@ ${installBlock}
   );
   process.exit(0);
 } else if (subcommand === "--version" || subcommand === "-V") {
-  process.stdout.write(`mcph ${true ? "0.28.0" : "dev"}
+  process.stdout.write(`mcph ${true ? "0.29.0" : "dev"}
 `);
   process.exit(0);
 } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/mcph",
-  "version": "0.28.0",
+  "version": "0.29.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)",
@@ -11,7 +11,8 @@
   "files": [
     "dist",
     "!dist/**/*.test.*",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsup",