mcpman 0.6.0 → 0.8.0

package/README.md

@@ -283,6 +283,162 @@ mcpman import backup.json --yes       # skip confirmation
 mcpman import backup.json --dry-run   # preview without applying
 ```
 
+### `create [name]`
+
+Scaffold a new MCP server project with working boilerplate.
+
+```sh
+mcpman create my-server              # interactive prompts
+mcpman create my-server --yes        # accept defaults
+mcpman create my-server --runtime python  # Python template
+```
+
+Generates `package.json` (with `mcp` field), `src/index.ts`, and `tsconfig.json` for Node; or `pyproject.toml` and `main.py` for Python. Both templates implement the MCP protocol with a sample `hello` tool ready to run.
+
+### `link [dir]`
+
+Register a local MCP server directory with AI clients — like `npm link` but for MCP.
+
+```sh
+mcpman link .                        # link current directory
+mcpman link ./path/to/server         # link specific directory
+mcpman link . --client cursor        # link to specific client only
+mcpman link . --name my-override     # override detected server name
+```
+
+Reads `package.json` or `pyproject.toml` to detect name, version, and entry point. Adds a lockfile entry with `source: "local"` and registers the absolute path in client configs. No file copying — edits are picked up immediately.
+
+### `watch <server>`
+
+Watch a local MCP server's source files and auto-restart on changes — like nodemon, built into mcpman.
+
+```sh
+mcpman watch my-server               # watch with defaults
+mcpman watch my-server --dir ./src   # override watch directory
+mcpman watch my-server --ext ts,js   # watch specific extensions
+mcpman watch my-server --delay 500   # set debounce delay (ms)
+mcpman watch my-server --clear       # clear terminal on restart
+```
+
+Uses Node.js built-in `fs.watch` (no chokidar). Debounces 300ms by default. Ignores `node_modules/`, `dist/`, `.git/`, `__pycache__/`. Vault secrets are injected same as `mcpman run`.
+
+### `registry <list|add|remove|set-default>`
+
+Manage custom registry URLs for MCP server resolution.
+
+```sh
+mcpman registry list                              # show all registries
+mcpman registry add corp https://mcp.corp.com/api # add custom registry
+mcpman registry remove corp                       # remove custom registry
+mcpman registry set-default smithery             # change default registry
+```
+
+Built-in registries (npm, smithery) are always present and cannot be removed. Custom registries are stored in `~/.mcpman/config.json`.
+
+### `completions <bash|zsh|fish|install>`
+
+Generate shell completion scripts for tab-completion of commands and server names.
+
+```sh
+mcpman completions bash              # output bash completion script
+mcpman completions zsh               # output zsh completion script
+mcpman completions fish              # output fish completion script
+mcpman completions install           # auto-detect shell and install
+source <(mcpman completions bash)    # enable completions in current session
+```
+
+Completes: subcommands, server names (from lockfile), client types (`--client`), and runtimes (`--runtime`). Server names are resolved dynamically at completion time so they stay fresh.
+
+### `why <server>`
+
+Show why a server is installed — source, clients, profiles, env vars.
+
+```sh
+mcpman why my-server                 # full provenance output
+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.
+
 ---
 
 ## Comparison
@@ -306,6 +462,18 @@ mcpman import backup.json --dry-run   # preview without applying
 | Self-upgrade | Built-in CLI updater | None | None |
 | Interactive setup | Yes | Partial | No |
 | Project-scoped | Yes (`init`) | No | No |
+| Server scaffolding | `create` (Node + Python) | None | None |
+| Local dev linking | `link` (like npm link) | None | None |
+| File watching | `watch` (auto-restart) | None | None |
+| 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 |
 
 ---
 

package/dist/chunk-AOCGFOA6.js

@@ -0,0 +1,80 @@
+#!/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 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,
+  resolveConfigPath
+};

package/dist/chunk-DZ3D5RZQ.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+import {
+  getRollbackDir
+} from "./chunk-AOCGFOA6.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-XPYCEHZZ.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-AOCGFOA6.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/{client-detector-CY7WPF3K.js → client-detector-NHXBDNMY.js}

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