mcpman 0.6.0 → 0.7.0

package/README.md

@@ -283,6 +283,83 @@ 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
@@ -306,6 +383,12 @@ 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 |
 
 ---
 

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
+};