mcpman 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# mcpman
+
+![npm version](https://img.shields.io/npm/v/mcpman)
+![license](https://img.shields.io/npm/l/mcpman)
+![node](https://img.shields.io/node/v/mcpman)
+
+**The package manager for MCP servers.**
+
+Install, manage, and inspect Model Context Protocol servers across all your AI clients — Claude Desktop, Cursor, VS Code, and Windsurf — from a single CLI.
+
+---
+
+## Quick Start
+
+```sh
+# Install an MCP server globally (no install required)
+npx mcpman install @modelcontextprotocol/server-filesystem
+
+# Or install mcpman globally
+npm install -g mcpman
+mcpman install @modelcontextprotocol/server-filesystem
+```
+
+---
+
+## Features
+
+- **Universal** — manages servers for Claude Desktop, Cursor, VS Code, and Windsurf from one tool
+- **Registry-aware** — resolves packages from npm, Smithery, or GitHub URLs
+- **Lockfile** — tracks installed servers in `mcpman.lock` for reproducible setups
+- **Health checks** — verifies runtimes, env vars, and server connectivity with `doctor`
+- **Interactive prompts** — guided installation with env var configuration
+- **No extra daemon** — pure CLI, works anywhere Node ≥ 20 runs
+
+---
+
+## Commands
+
+### `install <server>`
+
+Install an MCP server and register it with your AI clients.
+
+```sh
+mcpman install @modelcontextprotocol/server-filesystem
+mcpman install my-smithery-server
+mcpman install https://github.com/owner/repo
+```
+
+**Options:**
+- `--client <type>` — target a specific client (`claude-desktop`, `cursor`, `vscode`, `windsurf`)
+- `--json` — output machine-readable JSON
+
+### `list`
+
+List all installed MCP servers.
+
+```sh
+mcpman list
+mcpman list --json
+```
+
+Shows server name, version, runtime, source, and which clients have it registered.
+
+### `remove <server>`
+
+Uninstall a server and deregister it from all clients.
+
+```sh
+mcpman remove @modelcontextprotocol/server-filesystem
+```
+
+### `doctor [server]`
+
+Run health diagnostics on all installed servers or a specific one.
+
+```sh
+mcpman doctor
+mcpman doctor my-server
+```
+
+Checks: runtime availability, required env vars, process spawn, and MCP handshake.
+
+### `init`
+
+Scaffold an `mcpman.lock` file in the current directory for project-scoped server management.
+
+```sh
+mcpman init
+```
+
+---
+
+## Comparison
+
+| Feature | mcpman | Smithery CLI | mcpm.sh |
+|---|---|---|---|
+| Multi-client support | All 4 clients | Claude only | Limited |
+| Lockfile | `mcpman.lock` | None | None |
+| Health checks | Runtime + env + process | None | None |
+| Registry sources | npm + Smithery + GitHub | Smithery only | npm only |
+| Interactive setup | Yes | Partial | No |
+| Project-scoped | Yes (`init`) | No | No |
+
+---
+
+## Contributing
+
+1. Fork the repo and create a feature branch
+2. `npm install` to install dependencies
+3. `npm test` to run the test suite
+4. Submit a pull request with a clear description
+
+Please follow the existing code style (TypeScript strict, ES modules).
+
+---
+
+## License
+
+MIT

package/dist/chunk-QY22QTBR.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+
+// src/clients/base-client-handler.ts
+import fs from "fs";
+import path from "path";
+
+// src/clients/types.ts
+var ConfigParseError = class extends Error {
+  constructor(configPath, cause) {
+    super(`Failed to parse config: ${configPath} \u2014 ${String(cause)}`);
+    this.configPath = configPath;
+    this.name = "ConfigParseError";
+  }
+};
+var ConfigWriteError = class extends Error {
+  constructor(configPath, cause) {
+    super(`Failed to write config: ${configPath} \u2014 ${String(cause)}`);
+    this.configPath = configPath;
+    this.name = "ConfigWriteError";
+  }
+};
+
+// src/clients/base-client-handler.ts
+async function atomicWrite(filePath, content) {
+  const tmpPath = `${filePath}.tmp`;
+  try {
+    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) {
+    try {
+      await fs.promises.unlink(tmpPath);
+    } catch {
+    }
+    throw err;
+  }
+}
+async function pathExists(p) {
+  try {
+    await fs.promises.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var BaseClientHandler = class {
+  async isInstalled() {
+    const dir = path.dirname(this.getConfigPath());
+    return pathExists(dir);
+  }
+  /** Read raw JSON from disk, return empty object if file missing */
+  async readRaw() {
+    const configPath = this.getConfigPath();
+    try {
+      const raw = await fs.promises.readFile(configPath, "utf-8");
+      return JSON.parse(raw);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return {};
+      }
+      throw new ConfigParseError(configPath, err);
+    }
+  }
+  /** Serialize raw object to disk atomically */
+  async writeRaw(data) {
+    const configPath = this.getConfigPath();
+    try {
+      await atomicWrite(configPath, JSON.stringify(data, null, 2));
+    } catch (err) {
+      throw new ConfigWriteError(configPath, err);
+    }
+  }
+  /** Convert raw JSON to ClientConfig — override for non-standard formats */
+  toClientConfig(raw) {
+    const mcpServers = raw.mcpServers ?? {};
+    return { servers: mcpServers };
+  }
+  /** Merge ClientConfig back into raw JSON — override for non-standard formats */
+  fromClientConfig(raw, config) {
+    return { ...raw, mcpServers: config.servers };
+  }
+  async readConfig() {
+    const raw = await this.readRaw();
+    return this.toClientConfig(raw);
+  }
+  async writeConfig(config) {
+    const raw = await this.readRaw();
+    await this.writeRaw(this.fromClientConfig(raw, config));
+  }
+  async addServer(name, entry) {
+    const config = await this.readConfig();
+    config.servers[name] = entry;
+    await this.writeConfig(config);
+  }
+  async removeServer(name) {
+    const config = await this.readConfig();
+    delete config.servers[name];
+    await this.writeConfig(config);
+  }
+};
+
+// src/utils/paths.ts
+import os from "os";
+import path2 from "path";
+function getHomedir() {
+  return os.homedir();
+}
+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";
+  displayName = "Claude Desktop";
+  getConfigPath() {
+    return resolveConfigPath("claude-desktop");
+  }
+};
+
+// src/clients/cursor.ts
+var CursorHandler = class extends BaseClientHandler {
+  type = "cursor";
+  displayName = "Cursor";
+  getConfigPath() {
+    return resolveConfigPath("cursor");
+  }
+};
+
+// src/clients/vscode.ts
+var VSCodeHandler = class extends BaseClientHandler {
+  type = "vscode";
+  displayName = "VS Code";
+  getConfigPath() {
+    return resolveConfigPath("vscode");
+  }
+  toClientConfig(raw) {
+    const mcp = raw.mcp ?? {};
+    const servers = mcp.servers ?? {};
+    return { servers };
+  }
+  fromClientConfig(raw, config) {
+    const existingMcp = raw.mcp ?? {};
+    return {
+      ...raw,
+      mcp: { ...existingMcp, servers: config.servers }
+    };
+  }
+};
+
+// src/clients/windsurf.ts
+var WindsurfHandler = class extends BaseClientHandler {
+  type = "windsurf";
+  displayName = "Windsurf";
+  getConfigPath() {
+    return resolveConfigPath("windsurf");
+  }
+};
+
+// src/clients/client-detector.ts
+function getAllClientTypes() {
+  return ["claude-desktop", "cursor", "vscode", "windsurf"];
+}
+function getClient(type) {
+  switch (type) {
+    case "claude-desktop":
+      return new ClaudeDesktopHandler();
+    case "cursor":
+      return new CursorHandler();
+    case "vscode":
+      return new VSCodeHandler();
+    case "windsurf":
+      return new WindsurfHandler();
+  }
+}
+async function getInstalledClients() {
+  const all = getAllClientTypes().map(getClient);
+  const results = await Promise.all(
+    all.map(async (handler) => ({ handler, installed: await handler.isInstalled() }))
+  );
+  return results.filter((r) => r.installed).map((r) => r.handler);
+}
+
+export {
+  getAllClientTypes,
+  getClient,
+  getInstalledClients
+};

package/dist/client-detector-SUIJSIYM.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import {
+  getAllClientTypes,
+  getClient,
+  getInstalledClients
+} from "./chunk-QY22QTBR.js";
+export {
+  getAllClientTypes,
+  getClient,
+  getInstalledClients
+};