mcpman 0.4.0 → 0.7.0

package/README.md

@@ -39,6 +39,12 @@ mcpman install @modelcontextprotocol/server-filesystem
 - **Config sync** — keep server configs consistent across all your AI clients; `--remove` cleans extras
 - **Security audit** — scan servers for vulnerabilities with trust scoring; `--fix` auto-updates vulnerable packages
 - **Auto-update** — get notified when server updates are available
+- **Plugin system** — extend mcpman with npm-based plugins for custom registries (e.g. Ollama, HuggingFace)
+- **Export/Import** — portable JSON bundles for full config migration across machines
+- **Server testing** — validate MCP servers respond to JSON-RPC initialize + tools/list
+- **Log streaming** — stream stdout/stderr from servers in real time
+- **Profiles** — save/restore named server configurations for quick switching
+- **Self-upgrade** — update mcpman itself with a single command
 - **Interactive prompts** — guided installation with env var configuration
 - **No extra daemon** — pure CLI, works anywhere Node ≥ 20 runs
 
@@ -153,6 +159,207 @@ mcpman update my-server  # update specific server
 mcpman update --check    # check only, don't apply
 ```
 
+### `config <set|get|list|reset>`
+
+Manage persistent CLI configuration at `~/.mcpman/config.json`.
+
+```sh
+mcpman config set defaultClient cursor
+mcpman config get defaultClient
+mcpman config list
+mcpman config reset
+```
+
+Keys: `defaultClient`, `updateCheckInterval`, `preferredRegistry`, `vaultTimeout`, `plugins`.
+
+### `search <query>`
+
+Search for MCP servers on npm or Smithery registry.
+
+```sh
+mcpman search filesystem
+mcpman search brave --registry smithery
+mcpman search tools --all        # include plugin registries
+mcpman search tools --limit 10
+```
+
+**Options:**
+- `--registry <npm|smithery>` — registry to search (default: npm)
+- `--limit <n>` — max results (default: 20, max: 100)
+- `--all` — include plugin registries in results
+
+### `info <server>`
+
+Show detailed information about an MCP server package.
+
+```sh
+mcpman info @modelcontextprotocol/server-filesystem
+mcpman info my-server --json
+```
+
+### `run <server>`
+
+Launch an MCP server with vault secrets auto-injected into the process environment.
+
+```sh
+mcpman run my-server
+mcpman run my-server --env API_KEY=sk-...
+```
+
+### `upgrade`
+
+Upgrade mcpman itself to the latest version from npm.
+
+```sh
+mcpman upgrade           # check and install latest
+mcpman upgrade --check   # only check, don't install
+```
+
+### `test [server]`
+
+Validate MCP server connectivity by sending JSON-RPC `initialize` + `tools/list`.
+
+```sh
+mcpman test my-server    # test a specific server
+mcpman test --all        # test all installed servers
+```
+
+Reports pass/fail, response time, and discovered tools for each server.
+
+### `logs <server>`
+
+Stream stdout/stderr from an MCP server process in real time.
+
+```sh
+mcpman logs my-server    # stream logs (Ctrl+C to stop)
+```
+
+Vault secrets are auto-injected into the server environment.
+
+### `profiles <create|switch|list|delete>`
+
+Manage named server configuration profiles for quick switching.
+
+```sh
+mcpman profiles create dev           # snapshot current servers as "dev"
+mcpman profiles create prod -d "Production config"
+mcpman profiles list                 # show all profiles
+mcpman profiles switch dev           # apply "dev" profile to lockfile
+mcpman profiles delete old           # remove a profile
+```
+
+After switching, run `mcpman sync` to apply the profile to all clients.
+
+### `plugin <add|remove|list>`
+
+Manage mcpman plugins for custom registries.
+
+```sh
+mcpman plugin add mcpman-plugin-ollama    # install plugin
+mcpman plugin remove mcpman-plugin-ollama # uninstall plugin
+mcpman plugin list                        # show installed plugins
+```
+
+Plugins are npm packages that export a `McpmanPlugin` interface with `name`, `prefix`, and `resolve()`. Once installed, their prefix (e.g. `ollama:`) works with `mcpman install ollama:my-model`.
+
+### `export [output-file]`
+
+Export mcpman config, lockfile, vault, and plugins to a portable JSON file.
+
+```sh
+mcpman export                    # default: mcpman-export.json
+mcpman export backup.json
+mcpman export --no-vault         # exclude encrypted vault
+mcpman export --no-plugins       # exclude plugin list
+```
+
+### `import <file>`
+
+Restore mcpman config, lockfile, vault, and plugins from an export bundle.
+
+```sh
+mcpman import mcpman-export.json
+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`.
+
 ---
 
 ## Comparison
@@ -168,8 +375,20 @@ mcpman update --check    # check only, don't apply
 | CI/CD | GitHub Actions | None | None |
 | Auto-update | Version check + notify | None | None |
 | Registry sources | npm + Smithery + GitHub | Smithery only | npm only |
+| Plugin system | npm-based custom registries | None | None |
+| Export/Import | Full config portability | None | None |
+| Server testing | JSON-RPC validation | None | None |
+| Log streaming | Real-time stdout/stderr | None | None |
+| Profiles | Named config switching | None | None |
+| 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 |
 
 ---
 

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

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

package/dist/chunk-YZNTMR6O.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+// src/core/lockfile.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+var LOCKFILE_NAME = "mcpman.lock";
+function findLockfile() {
+  let dir = process.cwd();
+  while (true) {
+    const candidate = path.join(dir, LOCKFILE_NAME);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function getGlobalLockfilePath() {
+  return path.join(os.homedir(), ".mcpman", LOCKFILE_NAME);
+}
+function resolveLockfilePath() {
+  return findLockfile() ?? getGlobalLockfilePath();
+}
+function readLockfile(filePath) {
+  const target = filePath ?? resolveLockfilePath();
+  if (!fs.existsSync(target)) {
+    return { lockfileVersion: 1, servers: {} };
+  }
+  try {
+    const raw = fs.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 = path.dirname(target);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const tmp = `${target}.tmp`;
+  fs.writeFileSync(tmp, serialize(data), "utf-8");
+  fs.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 {
+  LOCKFILE_NAME,
+  findLockfile,
+  getGlobalLockfilePath,
+  resolveLockfilePath,
+  readLockfile,
+  writeLockfile,
+  addEntry,
+  removeEntry,
+  getLockedVersion,
+  createEmptyLockfile
+};

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

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