@yawlabs/mcph 0.27.0 → 0.28.1

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# 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.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 |
@@ -301,4 +310,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.27.0" : "dev";
+var VERSION = true ? "0.28.1" : "dev";
 async function runDoctor(opts = {}) {
   const lines = [];
   const write = opts.out ?? ((s) => process.stdout.write(s));
@@ -1761,6 +1761,70 @@ async function shutdownAnalytics() {
   dispatchBuffer.length = 0;
 }
 
+// src/bundles.ts
+var CURATED_BUNDLES = [
+  {
+    id: "devops-incident",
+    name: "DevOps Incident Triage",
+    description: "GitHub + PagerDuty + Slack for on-call triage",
+    namespaces: ["github", "pagerduty", "slack"],
+    category: "ops"
+  },
+  {
+    id: "pr-review",
+    name: "PR Review",
+    description: "GitHub + Linear for issue-to-PR traceability",
+    namespaces: ["github", "linear"],
+    category: "dev"
+  },
+  {
+    id: "growth-stack",
+    name: "Growth Stack",
+    description: "HubSpot + Slack + GA for lifecycle + funnel signals",
+    namespaces: ["hubspot", "slack", "ga"],
+    category: "growth"
+  },
+  {
+    id: "data-ops",
+    name: "Data Ops",
+    description: "Postgres + S3 + Snowflake for pipeline debugging",
+    namespaces: ["postgres", "s3", "snowflake"],
+    category: "data"
+  },
+  {
+    id: "product-release",
+    name: "Product Release",
+    description: "GitHub + Linear + Slack for ship-day coordination",
+    namespaces: ["github", "linear", "slack"],
+    category: "dev"
+  },
+  {
+    id: "support-ops",
+    name: "Support Ops",
+    description: "Zendesk + Slack + HubSpot for escalation handoffs",
+    namespaces: ["zendesk", "slack", "hubspot"],
+    category: "ops"
+  }
+];
+function matchBundles(installedNamespaces) {
+  const installed = new Set(installedNamespaces);
+  const ready = [];
+  const partial = [];
+  for (const bundle of CURATED_BUNDLES) {
+    const have = bundle.namespaces.filter((ns) => installed.has(ns));
+    const missing = bundle.namespaces.filter((ns) => !installed.has(ns));
+    if (missing.length === 0) {
+      ready.push(bundle);
+    } else if (have.length > 0) {
+      partial.push({ bundle, have, missing });
+    }
+  }
+  return { ready, partial };
+}
+function bundleActivateHint(bundle) {
+  return `mcp_connect_activate({ namespaces: ${JSON.stringify(bundle.namespaces)} })`;
+}
+
 // src/cost-estimate.ts
 var BYTES_PER_TOKEN = 4;
 var CACHED_TOOL_SCHEMA_PAD_BYTES = 200;
@@ -2461,6 +2525,27 @@ var META_TOOLS = {
       openWorldHint: false
     }
   },
+  bundles: {
+    name: "mcp_connect_bundles",
+    description: "List curated multi-server 'bundles' \u2014 presets like `pr-review` (github + linear) or `devops-incident` (github + pagerduty + slack) that commonly ship together. Use this BEFORE mcp_connect_discover when the user's intent maps to a known workflow (on-call triage, PR review, data pipeline debugging) \u2014 it returns a ready-to-run `mcp_connect_activate namespaces=[...]` call per bundle. With `action=\"match\"` (recommended after the user's installed list is known) the response partitions bundles into READY (every namespace already installed \u2014 activate now) and PARTIAL (some installed, some missing \u2014 shows the missing names and the mcp.hosting/explore install URL). With `action=\"list\"` (default) it returns the full curated catalog. Bundles are static client-side data, not a network call.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["list", "match"],
+          description: 'Either "list" (return the full curated catalog; default) or "match" (partition bundles against installed servers into ready-to-activate vs partially-installed).'
+        }
+      }
+    },
+    annotations: {
+      title: "Curated Server Bundles",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  },
   exec: {
     name: "mcp_connect_exec",
     description: "Run a short DECLARATIVE pipeline of upstream tool calls in a single round-trip. Use this when you already know the exact 2-4 tool calls to make and one call's output feeds another's args \u2014 e.g. `a = gh_list_prs(); b = gh_get_pr(a[0].number); return b`. NOT a code sandbox: there is no expression language, no loops, no branching, no arithmetic. The only control flow is sequential step execution; the only data-flow primitive is `{\"$ref\": \"<stepId>[.path.to.value]\"}` which substitutes a prior step's output (or a nested field of it) into the next step's args. Paths support dot keys and `[N]` / `.N` array indexing. Each step's `tool` must be a namespaced, already-loaded tool name (the exec does not auto-activate \u2014 call `mcp_connect_activate` first). Max 16 steps per exec. If any step fails, the whole pipeline fails and returns `{ ok: false, failedStep, error, partial: { ...completed outputs } }`. On success returns `{ ok: true, result: <return-step output>, steps: { ...all outputs } }`. Prefer this over back-to-back tool calls when the chain is deterministic \u2014 it saves prompt-token replay and client round-trips.",
@@ -2581,7 +2666,8 @@ var META_TOOL_NAMES = /* @__PURE__ */ new Set([
   META_TOOLS.install.name,
   META_TOOLS.read_tool.name,
   META_TOOLS.suggest.name,
-  META_TOOLS.exec.name
+  META_TOOLS.exec.name,
+  META_TOOLS.bundles.name
 ]);
 
 // src/pack-detect.ts
@@ -3705,7 +3791,7 @@ function categorizeSpawnError(err) {
 }
 async function connectToUpstream(config, onDisconnect, onListChanged) {
   const client = new Client(
-    { name: "mcph", version: true ? "0.27.0" : "dev" },
+    { name: "mcph", version: true ? "0.28.1" : "dev" },
     { capabilities: {} }
   );
   let transport;
@@ -4189,12 +4275,37 @@ function tokenizeForSummary(text) {
     text.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length >= 2)
   );
 }
+function computeToolOverlaps(connections) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const conn of connections) {
+    if (conn.status !== "connected") continue;
+    const ns = conn.config.namespace;
+    for (const tool of conn.tools) {
+      let set = byName.get(tool.name);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        byName.set(tool.name, set);
+      }
+      set.add(ns);
+    }
+  }
+  const overlaps = [];
+  for (const [bareName, nsSet] of byName) {
+    if (nsSet.size < 2) continue;
+    overlaps.push({ bareName, namespaces: [...nsSet].sort() });
+  }
+  overlaps.sort((a, b) => {
+    if (b.namespaces.length !== a.namespaces.length) return b.namespaces.length - a.namespaces.length;
+    return a.bareName.localeCompare(b.bareName);
+  });
+  return overlaps;
+}
 var ConnectServer = class _ConnectServer {
   constructor(apiUrl6, token6) {
     this.apiUrl = apiUrl6;
     this.token = token6;
     this.server = new Server(
-      { name: "mcph", version: true ? "0.27.0" : "dev" },
+      { name: "mcph", version: true ? "0.28.1" : "dev" },
       {
         capabilities: {
           tools: { listChanged: true },
@@ -4661,6 +4772,11 @@ var ConnectServer = class _ConnectServer {
       });
       return this.attachGuideNudge(result2);
     }
+    if (name === META_TOOLS.bundles.name) {
+      const action = args.action === "match" ? "match" : "list";
+      recordConnectEvent({ namespace: null, toolName: null, action: "bundles", latencyMs: null, success: true });
+      return this.attachGuideNudge(this.handleBundles(action));
+    }
     let routes = this.toolRoutes;
     let route = routes.get(name);
     if (route?.deferred) {
@@ -5059,6 +5175,16 @@ var ConnectServer = class _ConnectServer {
         }
       }
     }
+    const overlaps = computeToolOverlaps(this.connections.values());
+    if (overlaps.length > 0) {
+      lines.push("\nOverlapping tools (same bare name in multiple servers):");
+      const top = overlaps.slice(0, 5);
+      for (let i = 0; i < top.length; i++) {
+        const o = top[i];
+        const suffix = i === 0 ? " (use mcp_connect_dispatch to disambiguate)" : "";
+        lines.push(`  ${o.bareName} \u2014 available in: ${o.namespaces.join(", ")}${suffix}`);
+      }
+    }
     const inactive = this.config.servers.filter((s) => !s.isActive);
     if (inactive.length > 0) {
       lines.push("\nDisabled servers:");
@@ -5928,6 +6054,60 @@ Use mcp_connect_discover to see imported servers.`
 To load the top pack in one step, call \`mcp_connect_activate\` with namespaces=${nsJson}.`);
     return { content: [{ type: "text", text: lines.join("\n") }] };
   }
+  // Curated multi-server bundles. Static client-side data (see bundles.ts)
+  // — no network call. `action=list` prints every bundle with a ready-to-
+  // run `mcp_connect_activate` snippet; `action=match` cross-references
+  // the installed server list and partitions into fully-ready vs
+  // partially-installed so the caller only sees bundles that are actually
+  // actionable on this account.
+  handleBundles(action) {
+    if (action === "list") {
+      const lines2 = [`Curated server bundles (${CURATED_BUNDLES.length}):
+`];
+      for (const bundle of CURATED_BUNDLES) {
+        lines2.push(`  ${bundle.id} \u2014 ${bundle.description}`);
+        lines2.push(`    namespaces: ${JSON.stringify(bundle.namespaces)}`);
+        lines2.push(`    activate: ${bundleActivateHint(bundle)}`);
+      }
+      lines2.push("");
+      lines2.push(
+        'Call mcp_connect_bundles with action="match" to filter these against servers already installed on this account.'
+      );
+      return { content: [{ type: "text", text: lines2.join("\n") }] };
+    }
+    const installedNamespaces = this.getProfiledActiveServers().map((s) => s.namespace);
+    const { ready, partial } = matchBundles(installedNamespaces);
+    if (ready.length === 0 && partial.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "No curated bundles match your currently installed servers. Browse https://mcp.hosting/explore to add the servers a bundle needs, then re-run mcp_connect_bundles."
+          }
+        ]
+      };
+    }
+    const lines = [];
+    if (ready.length > 0) {
+      lines.push("Bundles ready to activate now:");
+      for (const bundle of ready) {
+        lines.push(`  ${bundle.id} \u2014 ${bundle.description}`);
+        lines.push(`    namespaces: ${JSON.stringify(bundle.namespaces)}`);
+        lines.push(`    activate: ${bundleActivateHint(bundle)}`);
+      }
+    }
+    if (partial.length > 0) {
+      if (ready.length > 0) lines.push("");
+      lines.push("Bundles partially installed:");
+      for (const entry of partial) {
+        const { bundle, have, missing } = entry;
+        lines.push(`  ${bundle.id} \u2014 ${bundle.description}`);
+        lines.push(`    have: ${have.join(", ")}`);
+        lines.push(`    missing: ${missing.join(", ")} (install from https://mcp.hosting/explore)`);
+      }
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
   // Declarative pipeline executor. Runs N tool calls in order, binding
   // each output under the step's id (or positional index), and lets
   // later steps splice those outputs into their args via
@@ -6160,7 +6340,7 @@ ${installBlock}
   );
   process.exit(0);
 } else if (subcommand === "--version" || subcommand === "-V") {
-  process.stdout.write(`mcph ${true ? "0.27.0" : "dev"}
+  process.stdout.write(`mcph ${true ? "0.28.1" : "dev"}
 `);
   process.exit(0);
 } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/mcph",
-  "version": "0.27.0",
+  "version": "0.28.1",
   "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",