mcpman 0.7.0 → 0.9.0

package/README.md

@@ -360,6 +360,162 @@ mcpman why my-server --json          # JSON output for scripting
 
 Displays: source (npm/smithery/github/local), resolved URL, version, installed timestamp, which clients have it registered, which named profiles include it, and required env var names. Detects orphaned servers (in client config but not in lockfile) and suggests `mcpman sync --remove`.
 
+### `env <set|get|list|del|clear>`
+
+Manage per-server environment variables (non-sensitive defaults).
+
+```sh
+mcpman env set my-server API_URL=https://api.example.com
+mcpman env get my-server API_URL
+mcpman env list my-server
+mcpman env del my-server API_URL
+mcpman env clear my-server
+```
+
+Stored in `~/.mcpman/env/<server>.json`. For sensitive values, use `mcpman secrets` instead. At runtime, vault secrets take priority over env defaults.
+
+### `bench <server>`
+
+Benchmark MCP server latency with JSON-RPC initialize calls.
+
+```sh
+mcpman bench my-server               # 5 runs (default)
+mcpman bench my-server --runs 10     # custom run count
+mcpman bench my-server --json        # machine-readable output
+mcpman bench my-server --timeout 5000 # exit 1 if p95 > 5s
+```
+
+Reports min, max, avg, p50, p95 response times in milliseconds.
+
+### `diff <client-a> <client-b>`
+
+Show visual diff of MCP server configs between two AI clients.
+
+```sh
+mcpman diff claude-desktop cursor     # color-coded diff
+mcpman diff vscode windsurf --json    # JSON output
+```
+
+Displays added (green), removed (red), and changed (yellow) servers between two client configurations. Useful before running `mcpman sync`.
+
+### `group <add|rm|list|delete|install|run>`
+
+Organize servers into named groups for batch operations.
+
+```sh
+mcpman group add work server-a server-b   # tag servers
+mcpman group rm work server-b             # untag server
+mcpman group list                         # show all groups
+mcpman group list work                    # show group members
+mcpman group install work                 # install all in group
+mcpman group run work                     # run all concurrently
+mcpman group delete work                  # remove entire group
+```
+
+Groups are lightweight labels stored in `~/.mcpman/groups.json`. Unlike profiles (full snapshots), groups are just server name lists for convenience.
+
+### `pin <server> [version]`
+
+Pin a server to a specific version to prevent auto-updates.
+
+```sh
+mcpman pin my-server 1.2.3           # pin to exact version
+mcpman pin my-server                 # pin to current version
+mcpman pin --unpin my-server         # remove pin
+mcpman pin --list                    # show all pinned servers
+```
+
+Pinned servers are skipped by `mcpman update` and version check notifications. Pins stored in `~/.mcpman/pins.json`.
+
+### `rollback [index]`
+
+Restore a previous lockfile state from automatic snapshots.
+
+```sh
+mcpman rollback --list               # show snapshot history
+mcpman rollback 0                    # restore most recent snapshot
+mcpman rollback 2                    # restore specific snapshot
+```
+
+Snapshots are created automatically before every lockfile write. Keeps the last 5 snapshots in `~/.mcpman/rollback/`. After rollback, run `mcpman sync` to apply to all clients.
+
+### `validate [--client <name>]`
+
+Validate lockfile schema and client config JSON for correctness.
+
+```sh
+mcpman validate                      # validate lockfile + all clients
+mcpman validate --client cursor      # validate specific client only
+mcpman validate --json               # machine-readable output
+```
+
+Checks: required fields (name, version, source, command, args), valid JSON structure, mcpServers entries have command+args. Exits 1 if any errors found. Distinct from `doctor` (which checks runtime health).
+
+### `status [--server <name>]`
+
+Show live process status of all installed MCP servers.
+
+```sh
+mcpman status                        # check all servers
+mcpman status --server my-server     # check specific server
+mcpman status --json                 # JSON output
+```
+
+Probes each server with a JSON-RPC `initialize` call (3s timeout). Reports: alive/dead status, response time, and error details.
+
+### `replay [index]`
+
+Re-run previous CLI commands from history.
+
+```sh
+mcpman replay --list                 # show last 20 commands
+mcpman replay 0                     # re-run most recent command
+mcpman replay 5                     # re-run 5th command
+```
+
+Maintains a ring buffer of the last 50 commands at `~/.mcpman/history.json`. Each entry includes the command, arguments, and timestamp.
+
+### `alias <add|remove|list>`
+
+Create short aliases for frequently used commands.
+
+```sh
+mcpman alias add dev "group run dev-servers"
+mcpman alias add fs "install @modelcontextprotocol/server-filesystem"
+mcpman alias remove dev
+mcpman alias list
+```
+
+Aliases stored in `~/.mcpman/aliases.json`. Unlike groups (server batches), aliases are command-line shorthands.
+
+### `template <save|apply|list|delete>`
+
+Save and share install templates for team onboarding.
+
+```sh
+mcpman template save myteam          # snapshot current servers
+mcpman template save myteam -d "Team setup"
+mcpman template apply myteam         # print install commands
+mcpman template list                 # show all templates
+mcpman template delete myteam        # remove template
+```
+
+Templates stored in `~/.mcpman/templates/`. Unlike `export` (full migration bundle with vault+plugins), templates are lightweight server presets for sharing.
+
+### `notify <add|remove|list|test>`
+
+Configure webhook and shell hooks for server lifecycle events.
+
+```sh
+mcpman notify add --event install --webhook https://hooks.example.com/mcp
+mcpman notify add --event health-fail --shell "echo alert | mail admin"
+mcpman notify list                   # show all hooks
+mcpman notify remove 0              # remove hook by index
+mcpman notify test install           # fire test event
+```
+
+Events: `install`, `remove`, `update`, `health-fail`. Webhooks use native `fetch()`, shell hooks use `execSync`. Hooks stored in `~/.mcpman/notify.json`.
+
 ---
 
 ## Comparison
@@ -389,6 +545,18 @@ Displays: source (npm/smithery/github/local), resolved URL, version, installed t
 | Custom registries | `registry` CRUD | None | None |
 | Shell completions | bash + zsh + fish | None | None |
 | Provenance query | `why` (clients + profiles) | None | None |
+| Env management | Per-server env var CRUD | None | None |
+| Benchmarking | Latency p50/p95 stats | None | None |
+| Config diff | Visual client diff | None | None |
+| Server groups | Batch install/run tags | None | None |
+| Version pinning | `pin`/`unpin` CLI | None | None |
+| Rollback | Auto-snapshot + restore | None | None |
+| Config validation | Schema + JSON checks | None | None |
+| Live status | Process probe + response time | None | None |
+| Command replay | History ring buffer | None | None |
+| Command aliases | Shorthand definitions | None | None |
+| Install templates | Sharable server presets | None | None |
+| Event notifications | Webhook + shell hooks | None | None |
 
 ---
 

package/dist/chunk-6GGMDJQE.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+import {
+  getRollbackDir
+} from "./chunk-DSCBWQ3W.js";
+
+// src/core/lockfile.ts
+import fs2 from "fs";
+import os from "os";
+import path2 from "path";
+
+// src/core/rollback-service.ts
+import fs from "fs";
+import path from "path";
+var MAX_SNAPSHOTS = 5;
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+function listSnapshotFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith(".json")).sort();
+}
+function snapshotBeforeWrite(content, rollbackDir) {
+  const dir = rollbackDir ?? getRollbackDir();
+  ensureDir(dir);
+  const existing = listSnapshotFiles(dir);
+  if (existing.length > 0) {
+    const latest = existing[existing.length - 1];
+    try {
+      const prev = fs.readFileSync(path.join(dir, latest), "utf-8");
+      if (prev === content) return;
+    } catch {
+    }
+  }
+  const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const filename = `${ts}.json`;
+  fs.writeFileSync(path.join(dir, filename), content, "utf-8");
+  evictOldSnapshots(dir);
+}
+function evictOldSnapshots(rollbackDir) {
+  const dir = rollbackDir ?? getRollbackDir();
+  const files = listSnapshotFiles(dir);
+  const excess = files.length - MAX_SNAPSHOTS;
+  for (let i = 0; i < excess; i++) {
+    try {
+      fs.unlinkSync(path.join(dir, files[i]));
+    } catch {
+    }
+  }
+}
+function listSnapshots(rollbackDir) {
+  const dir = rollbackDir ?? getRollbackDir();
+  const files = listSnapshotFiles(dir).reverse();
+  return files.map((filename, index) => {
+    const filepath = path.join(dir, filename);
+    let sizeBytes = 0;
+    let createdAt = "";
+    try {
+      const stat = fs.statSync(filepath);
+      sizeBytes = stat.size;
+      createdAt = stat.mtime.toISOString();
+    } catch {
+    }
+    return { index, filename, createdAt, sizeBytes };
+  });
+}
+function readSnapshot(index, rollbackDir) {
+  const dir = rollbackDir ?? getRollbackDir();
+  const files = listSnapshotFiles(dir).reverse();
+  const filename = files[index];
+  if (!filename) return null;
+  try {
+    return fs.readFileSync(path.join(dir, filename), "utf-8");
+  } catch {
+    return null;
+  }
+}
+function restoreSnapshot(index, targetPath, rollbackDir) {
+  const content = readSnapshot(index, rollbackDir);
+  if (content === null) return null;
+  const dir = path.dirname(targetPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${targetPath}.tmp`;
+  fs.writeFileSync(tmp, content, "utf-8");
+  fs.renameSync(tmp, targetPath);
+  return content;
+}
+
+// src/core/lockfile.ts
+var LOCKFILE_NAME = "mcpman.lock";
+function findLockfile() {
+  let dir = process.cwd();
+  while (true) {
+    const candidate = path2.join(dir, LOCKFILE_NAME);
+    if (fs2.existsSync(candidate)) return candidate;
+    const parent = path2.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function getGlobalLockfilePath() {
+  return path2.join(os.homedir(), ".mcpman", LOCKFILE_NAME);
+}
+function resolveLockfilePath() {
+  return findLockfile() ?? getGlobalLockfilePath();
+}
+function readLockfile(filePath) {
+  const target = filePath ?? resolveLockfilePath();
+  if (!fs2.existsSync(target)) {
+    return { lockfileVersion: 1, servers: {} };
+  }
+  try {
+    const raw = fs2.readFileSync(target, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return { lockfileVersion: 1, servers: {} };
+  }
+}
+function serialize(data) {
+  const sorted = {
+    lockfileVersion: data.lockfileVersion,
+    servers: Object.fromEntries(
+      Object.entries(data.servers).sort(([a], [b]) => a.localeCompare(b))
+    )
+  };
+  return `${JSON.stringify(sorted, null, 2)}
+`;
+}
+function writeLockfile(data, filePath) {
+  const target = filePath ?? resolveLockfilePath();
+  const dir = path2.dirname(target);
+  if (!fs2.existsSync(dir)) {
+    fs2.mkdirSync(dir, { recursive: true });
+  }
+  const serialized = serialize(data);
+  if (fs2.existsSync(target)) {
+    try {
+      const current = fs2.readFileSync(target, "utf-8");
+      snapshotBeforeWrite(current);
+    } catch {
+    }
+  }
+  const tmp = `${target}.tmp`;
+  fs2.writeFileSync(tmp, serialized, "utf-8");
+  fs2.renameSync(tmp, target);
+}
+function addEntry(name, entry, filePath) {
+  const data = readLockfile(filePath);
+  data.servers[name] = entry;
+  writeLockfile(data, filePath);
+}
+function removeEntry(name, filePath) {
+  const data = readLockfile(filePath);
+  if (name in data.servers) {
+    delete data.servers[name];
+    writeLockfile(data, filePath);
+  }
+}
+function getLockedVersion(name, filePath) {
+  const data = readLockfile(filePath);
+  return data.servers[name]?.version;
+}
+function createEmptyLockfile(filePath) {
+  writeLockfile({ lockfileVersion: 1, servers: {} }, filePath);
+}
+
+export {
+  listSnapshots,
+  readSnapshot,
+  restoreSnapshot,
+  LOCKFILE_NAME,
+  findLockfile,
+  getGlobalLockfilePath,
+  resolveLockfilePath,
+  readLockfile,
+  writeLockfile,
+  addEntry,
+  removeEntry,
+  getLockedVersion,
+  createEmptyLockfile
+};

package/dist/{chunk-NS6HV723.js → chunk-CC7ICP7U.js}

@@ -1,64 +1,11 @@
 #!/usr/bin/env node
-
-// src/utils/paths.ts
-import os from "os";
-import path from "path";
-function getHomedir() {
-  return os.homedir();
-}
-function getMcpmanDir() {
-  return path.join(os.homedir(), ".mcpman");
-}
-function getConfigPath() {
-  return path.join(getMcpmanDir(), "config.json");
-}
-function getPluginDir() {
-  return path.join(getMcpmanDir(), "plugins");
-}
-function getProfilesDir() {
-  return path.join(getMcpmanDir(), "profiles");
-}
-function getAppDataDir() {
-  const home = getHomedir();
-  if (process.platform === "darwin") {
-    return path.join(home, "Library", "Application Support");
-  }
-  if (process.platform === "win32") {
-    return process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
-  }
-  return process.env.XDG_CONFIG_HOME ?? path.join(home, ".config");
-}
-function resolveConfigPath(client) {
-  const appData = getAppDataDir();
-  const home = getHomedir();
-  switch (client) {
-    case "claude-desktop":
-      return path.join(appData, "Claude", "claude_desktop_config.json");
-    case "cursor":
-      return path.join(appData, "Cursor", "User", "globalStorage", "cursor.mcp", "mcp.json");
-    case "windsurf":
-      return path.join(
-        appData,
-        "Windsurf",
-        "User",
-        "globalStorage",
-        "windsurf.mcpConfigJson",
-        "mcp.json"
-      );
-    case "vscode":
-      if (process.platform === "darwin") {
-        return path.join(appData, "Code", "User", "settings.json");
-      }
-      if (process.platform === "win32") {
-        return path.join(appData, "Code", "User", "settings.json");
-      }
-      return path.join(home, ".config", "Code", "User", "settings.json");
-  }
-}
+import {
+  resolveConfigPath
+} from "./chunk-DSCBWQ3W.js";
 
 // src/clients/base-client-handler.ts
 import fs from "fs";
-import path2 from "path";
+import path from "path";
 
 // src/clients/types.ts
 var ConfigParseError = class extends Error {
@@ -80,7 +27,7 @@ var ConfigWriteError = class extends Error {
 async function atomicWrite(filePath, content) {
   const tmpPath = `${filePath}.tmp`;
   try {
-    await fs.promises.mkdir(path2.dirname(filePath), { recursive: true });
+    await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
     await fs.promises.writeFile(tmpPath, content, { encoding: "utf-8", mode: 384 });
     await fs.promises.rename(tmpPath, filePath);
   } catch (err) {
@@ -101,7 +48,7 @@ async function pathExists(p) {
 }
 var BaseClientHandler = class {
   async isInstalled() {
-    const dir = path2.dirname(this.getConfigPath());
+    const dir = path.dirname(this.getConfigPath());
     return pathExists(dir);
   }
   /** Read raw JSON from disk, return empty object if file missing */
@@ -228,9 +175,6 @@ async function getInstalledClients() {
 }
 
 export {
-  getConfigPath,
-  getPluginDir,
-  getProfilesDir,
   getAllClientTypes,
   getClient,
   getInstalledClients

package/dist/chunk-DSCBWQ3W.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+// src/utils/paths.ts
+import os from "os";
+import path from "path";
+function getHomedir() {
+  return os.homedir();
+}
+function getMcpmanDir() {
+  return path.join(os.homedir(), ".mcpman");
+}
+function getConfigPath() {
+  return path.join(getMcpmanDir(), "config.json");
+}
+function getPluginDir() {
+  return path.join(getMcpmanDir(), "plugins");
+}
+function getProfilesDir() {
+  return path.join(getMcpmanDir(), "profiles");
+}
+function getEnvDir() {
+  return path.join(getMcpmanDir(), "env");
+}
+function getGroupsFile() {
+  return path.join(getMcpmanDir(), "groups.json");
+}
+function getPinsFile() {
+  return path.join(getMcpmanDir(), "pins.json");
+}
+function getRollbackDir() {
+  return path.join(getMcpmanDir(), "rollback");
+}
+function getHistoryFile() {
+  return path.join(getMcpmanDir(), "history.json");
+}
+function getAliasesFile() {
+  return path.join(getMcpmanDir(), "aliases.json");
+}
+function getTemplatesDir() {
+  return path.join(getMcpmanDir(), "templates");
+}
+function getNotifyFile() {
+  return path.join(getMcpmanDir(), "notify.json");
+}
+function getAppDataDir() {
+  const home = getHomedir();
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Application Support");
+  }
+  if (process.platform === "win32") {
+    return process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
+  }
+  return process.env.XDG_CONFIG_HOME ?? path.join(home, ".config");
+}
+function resolveConfigPath(client) {
+  const appData = getAppDataDir();
+  const home = getHomedir();
+  switch (client) {
+    case "claude-desktop":
+      return path.join(appData, "Claude", "claude_desktop_config.json");
+    case "cursor":
+      return path.join(appData, "Cursor", "User", "globalStorage", "cursor.mcp", "mcp.json");
+    case "windsurf":
+      return path.join(
+        appData,
+        "Windsurf",
+        "User",
+        "globalStorage",
+        "windsurf.mcpConfigJson",
+        "mcp.json"
+      );
+    case "vscode":
+      if (process.platform === "darwin") {
+        return path.join(appData, "Code", "User", "settings.json");
+      }
+      if (process.platform === "win32") {
+        return path.join(appData, "Code", "User", "settings.json");
+      }
+      return path.join(home, ".config", "Code", "User", "settings.json");
+  }
+}
+
+export {
+  getConfigPath,
+  getPluginDir,
+  getProfilesDir,
+  getEnvDir,
+  getGroupsFile,
+  getPinsFile,
+  getRollbackDir,
+  getHistoryFile,
+  getAliasesFile,
+  getTemplatesDir,
+  getNotifyFile,
+  resolveConfigPath
+};

package/dist/{client-detector-CY7WPF3K.js → client-detector-O2HN4MUB.js}

@@ -3,7 +3,8 @@ import {
   getAllClientTypes,
   getClient,
   getInstalledClients
-} from "./chunk-NS6HV723.js";
+} from "./chunk-CC7ICP7U.js";
+import "./chunk-DSCBWQ3W.js";
 export {
   getAllClientTypes,
   getClient,