@cg3/equip 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CG3 LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @cg3/equip
+
+Universal MCP server + behavioral rules installer for AI coding agents.
+
+Equip handles the hard part of distributing your MCP tool: detecting which AI coding platforms are installed, writing the correct config format for each one, and managing versioned behavioral rules — all with zero dependencies.
+
+## Supported Platforms
+
+| Platform | MCP Config | Rules |
+|---|---|---|
+| Claude Code | `~/.claude.json` (`mcpServers`) | `~/.claude/CLAUDE.md` (append) |
+| Cursor | `~/.cursor/mcp.json` (`mcpServers`) | Clipboard (no writable global path) |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` (`mcpServers`) | `global_rules.md` (append) |
+| VS Code | `Code/User/mcp.json` (`servers`, `type: "http"`) | Clipboard |
+| Cline | `globalStorage/.../cline_mcp_settings.json` (`mcpServers`) | `~/Documents/Cline/Rules/` (standalone file) |
+| Roo Code | `globalStorage/.../cline_mcp_settings.json` (`mcpServers`) | `~/.roo/rules/` (standalone file) |
+
+## Usage
+
+```js
+const { Equip } = require("@cg3/equip");
+
+const equip = new Equip({
+  name: "my-tool",
+  serverUrl: "https://mcp.example.com",
+  rules: {
+    content: `<!-- my-tool:v1.0.0 -->\n## My Tool\nAlways check My Tool first.\n<!-- /my-tool -->`,
+    version: "1.0.0",
+    marker: "my-tool",
+    fileName: "my-tool.md",  // For platforms with rules directories
+  },
+});
+
+// Detect installed platforms
+const platforms = equip.detect();
+
+// Install MCP + rules on all detected platforms
+for (const p of platforms) {
+  equip.installMcp(p, "api_key_here");
+  equip.installRules(p);
+}
+
+// Uninstall
+for (const p of platforms) {
+  equip.uninstallMcp(p);
+  equip.uninstallRules(p);
+}
+```
+
+## API
+
+### `new Equip(config)`
+
+- `config.name` — Server name in MCP configs (required)
+- `config.serverUrl` — Remote MCP server URL (required unless `stdio` provided)
+- `config.rules` — Behavioral rules config (optional)
+  - `content` — Markdown content with version markers
+  - `version` — Version string for idempotency tracking
+  - `marker` — Marker name used in `<!-- marker:vX.X -->` comments
+  - `fileName` — Standalone filename for directory-based platforms
+  - `clipboardPlatforms` — Platform IDs that use clipboard (default: `["cursor", "vscode"]`)
+- `config.stdio` — Stdio transport config (optional, alternative to HTTP)
+  - `command`, `args`, `envKey`
+
+### Instance Methods
+
+- `equip.detect()` — Returns array of detected platform objects
+- `equip.installMcp(platform, apiKey, options?)` — Install MCP config
+- `equip.uninstallMcp(platform, dryRun?)` — Remove MCP config
+- `equip.updateMcpKey(platform, apiKey, transport?)` — Update API key
+- `equip.installRules(platform, options?)` — Install behavioral rules
+- `equip.uninstallRules(platform, dryRun?)` — Remove behavioral rules
+- `equip.readMcp(platform)` — Check if MCP is configured
+- `equip.buildConfig(platformId, apiKey, transport?)` — Build MCP config object
+
+### Primitives
+
+All internal functions are also exported for advanced usage:
+
+```js
+const { detectPlatforms, installMcpJson, installRules, createManualPlatform, platformName, cli } = require("@cg3/equip");
+```
+
+## Key Features
+
+- **Zero dependencies** — Pure Node.js, works with Node 18+
+- **Platform-aware** — Handles each platform's config quirks (root keys, URL fields, type requirements)
+- **Non-destructive** — Merges into existing configs, creates backups, preserves other servers
+- **Versioned rules** — Marker-based blocks enable idempotent updates without clobbering user content
+- **Dry-run support** — Preview changes without writing files
+- **CLI helpers** — Colored output, prompts, clipboard utilities included
+
+## License
+
+MIT — CG3 LLC

package/index.js

@@ -0,0 +1,172 @@
+// @cg3/equip — Universal MCP + behavioral rules installer for AI coding agents.
+// Zero dependencies. Works with Claude Code, Cursor, Windsurf, VS Code, Cline, Roo Code.
+
+"use strict";
+
+const { detectPlatforms, whichSync, dirExists, fileExists } = require("./lib/detect");
+const { readMcpEntry, buildHttpConfig, buildHttpConfigWithAuth, buildStdioConfig, installMcp, installMcpJson, uninstallMcp, updateMcpKey } = require("./lib/mcp");
+const { parseRulesVersion, installRules, uninstallRules, markerPatterns } = require("./lib/rules");
+const { createManualPlatform, platformName, KNOWN_PLATFORMS } = require("./lib/platforms");
+const cli = require("./lib/cli");
+
+/**
+ * Equip — configure AI coding tools with your MCP server and behavioral rules.
+ *
+ * @example
+ * const equip = new Equip({
+ *   name: "prior",
+ *   serverUrl: "https://api.cg3.io/mcp",
+ *   rules: { content: "...", version: "0.5.3", marker: "prior" },
+ * });
+ * const platforms = equip.detect();
+ * await equip.install(platforms, { apiKey: "ask_xxx" });
+ */
+class Equip {
+  /**
+   * @param {object} config
+   * @param {string} config.name - Server name in MCP configs (e.g., "prior")
+   * @param {string} config.serverUrl - Remote MCP server URL
+   * @param {object} [config.rules] - Behavioral rules config
+   * @param {string} config.rules.content - Rules markdown content (with markers)
+   * @param {string} config.rules.version - Version string for marker tracking
+   * @param {string} config.rules.marker - Marker name (e.g., "prior")
+   * @param {string} [config.rules.fileName] - Standalone file name for file-based platforms (e.g., "prior.md")
+   * @param {string[]} [config.rules.clipboardPlatforms] - Platforms using clipboard (default: ["cursor", "vscode"])
+   * @param {object} [config.stdio] - Stdio transport config (alternative to HTTP)
+   * @param {string} config.stdio.command - Command to run
+   * @param {string[]} config.stdio.args - Command arguments
+   * @param {string} config.stdio.envKey - Env var name for API key
+   */
+  constructor(config) {
+    if (!config.name) throw new Error("Equip: name is required");
+    if (!config.serverUrl && !config.stdio) throw new Error("Equip: serverUrl or stdio is required");
+
+    this.name = config.name;
+    this.serverUrl = config.serverUrl;
+    this.rules = config.rules || null;
+    this.stdio = config.stdio || null;
+  }
+
+  /**
+   * Detect installed AI coding platforms.
+   * @returns {Array<object>} Platform objects
+   */
+  detect() {
+    return detectPlatforms(this.name);
+  }
+
+  /**
+   * Build MCP config for a platform.
+   * @param {string} platformId - Platform id
+   * @param {string} apiKey - API key
+   * @param {string} [transport="http"] - "http" or "stdio"
+   * @returns {object} MCP config object
+   */
+  buildConfig(platformId, apiKey, transport = "http") {
+    if (transport === "stdio" && this.stdio) {
+      const env = { [this.stdio.envKey]: apiKey };
+      return buildStdioConfig(this.stdio.command, this.stdio.args, env);
+    }
+    return buildHttpConfigWithAuth(this.serverUrl, apiKey, platformId);
+  }
+
+  /**
+   * Install MCP config on a platform.
+   * @param {object} platform - Platform object from detect()
+   * @param {string} apiKey - API key
+   * @param {object} [options] - { transport, dryRun }
+   * @returns {{ success: boolean, method: string }}
+   */
+  installMcp(platform, apiKey, options = {}) {
+    const { transport = "http", dryRun = false } = options;
+    const config = this.buildConfig(platform.platform, apiKey, transport);
+    return installMcp(platform, this.name, config, { dryRun, serverUrl: this.serverUrl });
+  }
+
+  /**
+   * Uninstall MCP config from a platform.
+   * @param {object} platform - Platform object
+   * @param {boolean} [dryRun=false]
+   * @returns {boolean}
+   */
+  uninstallMcp(platform, dryRun = false) {
+    return uninstallMcp(platform, this.name, dryRun);
+  }
+
+  /**
+   * Update API key in MCP config.
+   * @param {object} platform - Platform object
+   * @param {string} apiKey - New API key
+   * @param {string} [transport="http"]
+   * @returns {{ success: boolean, method: string }}
+   */
+  updateMcpKey(platform, apiKey, transport = "http") {
+    const config = this.buildConfig(platform.platform, apiKey, transport);
+    return updateMcpKey(platform, this.name, config);
+  }
+
+  /**
+   * Install behavioral rules on a platform.
+   * @param {object} platform - Platform object
+   * @param {object} [options] - { dryRun }
+   * @returns {{ action: string }}
+   */
+  installRules(platform, options = {}) {
+    if (!this.rules) return { action: "skipped" };
+    return installRules(platform, {
+      content: this.rules.content,
+      version: this.rules.version,
+      marker: this.rules.marker,
+      fileName: this.rules.fileName,
+      clipboardPlatforms: this.rules.clipboardPlatforms,
+      dryRun: options.dryRun || false,
+      copyToClipboard: cli.copyToClipboard,
+    });
+  }
+
+  /**
+   * Uninstall behavioral rules from a platform.
+   * @param {object} platform - Platform object
+   * @param {boolean} [dryRun=false]
+   * @returns {boolean}
+   */
+  uninstallRules(platform, dryRun = false) {
+    if (!this.rules) return false;
+    return uninstallRules(platform, {
+      marker: this.rules.marker,
+      fileName: this.rules.fileName,
+      dryRun,
+    });
+  }
+
+  /**
+   * Check if MCP is configured on a platform.
+   * @param {object} platform - Platform object
+   * @returns {object|null} Existing MCP config or null
+   */
+  readMcp(platform) {
+    return readMcpEntry(platform.configPath, platform.rootKey, this.name);
+  }
+}
+
+module.exports = {
+  Equip,
+  // Re-export primitives for advanced usage
+  detectPlatforms,
+  readMcpEntry,
+  buildHttpConfig,
+  buildHttpConfigWithAuth,
+  buildStdioConfig,
+  installMcp,
+  installMcpJson,
+  uninstallMcp,
+  updateMcpKey,
+  installRules,
+  uninstallRules,
+  parseRulesVersion,
+  markerPatterns,
+  createManualPlatform,
+  platformName,
+  KNOWN_PLATFORMS,
+  cli,
+};

package/lib/cli.js

@@ -0,0 +1,95 @@
+// CLI output helpers, prompts, and clipboard.
+// Zero dependencies.
+
+"use strict";
+
+const os = require("os");
+const readline = require("readline");
+
+// ─── Colors ──────────────────────────────────────────────────
+
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const YELLOW = "\x1b[33m";
+const CYAN = "\x1b[36m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+
+// ─── Output ──────────────────────────────────────────────────
+
+function log(msg = "") { process.stderr.write(msg + "\n"); }
+function ok(msg) { log(`  ${GREEN}✓${RESET} ${msg}`); }
+function fail(msg) { log(`  ${RED}✗${RESET} ${msg}`); }
+function warn(msg) { log(`  ${YELLOW}⚠${RESET} ${msg}`); }
+function info(msg) { log(`  ${CYAN}ⓘ${RESET} ${msg}`); }
+function step(n, total, title) { log(`\n${BOLD}[${n}/${total}] ${title}${RESET}`); }
+
+// ─── Prompts ─────────────────────────────────────────────────
+
+function prompt(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); });
+  });
+}
+
+/**
+ * Prompt that resolves on Enter (true) or Esc (false).
+ * Falls back to readline if stdin isn't a TTY.
+ */
+function promptEnterOrEsc(question) {
+  return new Promise((resolve) => {
+    process.stderr.write(question);
+    if (!process.stdin.isTTY) {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+      rl.question("", (answer) => { rl.close(); resolve(answer.toLowerCase() !== "n"); });
+      return;
+    }
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf-8");
+    const onData = (key) => {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdin.removeListener("data", onData);
+      if (key === "\x1b") { process.stderr.write("\n"); resolve(false); }
+      else if (key === "\r" || key === "\n") { process.stderr.write("\n"); resolve(true); }
+      else if (key === "\x03") { process.stderr.write("\n"); process.exit(0); }
+      else { process.stderr.write("\n"); resolve(true); }
+    };
+    process.stdin.on("data", onData);
+  });
+}
+
+// ─── Clipboard ───────────────────────────────────────────────
+
+function copyToClipboard(text) {
+  try {
+    const cp = require("child_process");
+    if (process.platform === "darwin") {
+      cp.execSync("pbcopy", { input: text, timeout: 3000 });
+    } else if (process.platform === "win32") {
+      cp.execSync("clip", { input: text, timeout: 3000 });
+    } else {
+      try { cp.execSync("xclip -selection clipboard", { input: text, timeout: 3000 }); }
+      catch { try { cp.execSync("xsel --clipboard --input", { input: text, timeout: 3000 }); }
+      catch { cp.execSync("wl-copy", { input: text, timeout: 3000 }); } }
+    }
+    return true;
+  } catch { return false; }
+}
+
+// ─── Utilities ───────────────────────────────────────────────
+
+function sanitizeError(msg) {
+  return msg.replace(os.homedir(), "~");
+}
+
+module.exports = {
+  GREEN, RED, YELLOW, CYAN, BOLD, DIM, RESET,
+  log, ok, fail, warn, info, step,
+  prompt, promptEnterOrEsc,
+  copyToClipboard,
+  sanitizeError,
+};

package/lib/detect.js

@@ -0,0 +1,156 @@
+// Platform detection — discovers installed AI coding tools.
+// Zero dependencies.
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execSync } = require("child_process");
+const { getVsCodeMcpPath, getVsCodeUserDir, getClineConfigPath, getRooConfigPath } = require("./platforms");
+const { readMcpEntry } = require("./mcp");
+
+// ─── Helpers ─────────────────────────────────────────────────
+
+function whichSync(cmd) {
+  try {
+    const r = execSync(process.platform === "win32" ? `where ${cmd} 2>nul` : `which ${cmd} 2>/dev/null`, { encoding: "utf-8", timeout: 5000 });
+    return r.trim().split(/\r?\n/)[0] || null;
+  } catch { return null; }
+}
+
+function dirExists(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+function fileExists(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+function cliVersion(cmd, regex) {
+  try {
+    const out = execSync(`${cmd} --version 2>&1`, { encoding: "utf-8", timeout: 5000 });
+    const m = out.match(regex || /(\d+\.\d+[\.\d]*)/);
+    return m ? m[1] : "unknown";
+  } catch { return null; }
+}
+
+function getClaudeCodeVersion() {
+  try {
+    const out = execSync("claude --version 2>&1", { encoding: "utf-8", timeout: 5000 });
+    const m = out.match(/(\d+\.\d+[\.\d]*)/);
+    return m ? m[1] : "unknown";
+  } catch { return null; }
+}
+
+// ─── Detection ──────────────────────────────────────────────
+
+/**
+ * Detect installed AI coding platforms.
+ * @param {string} [serverName] - MCP server name to check for existing config (default: null)
+ * @returns {Array<object>} Array of platform objects
+ */
+function detectPlatforms(serverName) {
+  const home = os.homedir();
+  const platforms = [];
+
+  // Claude Code
+  const claudeVersion = whichSync("claude") ? getClaudeCodeVersion() : null;
+  if (claudeVersion || dirExists(path.join(home, ".claude"))) {
+    const configPath = path.join(home, ".claude.json");
+    const rulesPath = path.join(home, ".claude", "CLAUDE.md");
+    platforms.push({
+      platform: "claude-code",
+      version: claudeVersion || "unknown",
+      configPath,
+      rulesPath,
+      existingMcp: serverName ? readMcpEntry(configPath, "mcpServers", serverName) : null,
+      hasCli: !!whichSync("claude"),
+      rootKey: "mcpServers",
+    });
+  }
+
+  // Cursor
+  const cursorDir = path.join(home, ".cursor");
+  if (whichSync("cursor") || dirExists(cursorDir)) {
+    const configPath = path.join(cursorDir, "mcp.json");
+    platforms.push({
+      platform: "cursor",
+      version: cliVersion("cursor") || "unknown",
+      configPath,
+      rulesPath: null, // Cursor: clipboard only
+      existingMcp: serverName ? readMcpEntry(configPath, "mcpServers", serverName) : null,
+      hasCli: !!whichSync("cursor"),
+      rootKey: "mcpServers",
+    });
+  }
+
+  // Windsurf
+  const windsurfDir = path.join(home, ".codeium", "windsurf");
+  if (dirExists(windsurfDir)) {
+    const configPath = path.join(windsurfDir, "mcp_config.json");
+    const rulesPath = path.join(windsurfDir, "memories", "global_rules.md");
+    platforms.push({
+      platform: "windsurf",
+      version: "unknown",
+      configPath,
+      rulesPath,
+      existingMcp: serverName ? readMcpEntry(configPath, "mcpServers", serverName) : null,
+      hasCli: false,
+      rootKey: "mcpServers",
+    });
+  }
+
+  // VS Code (Copilot)
+  const vscodeMcpPath = getVsCodeMcpPath();
+  if (whichSync("code") || fileExists(vscodeMcpPath) || dirExists(getVsCodeUserDir())) {
+    platforms.push({
+      platform: "vscode",
+      version: cliVersion("code") || "unknown",
+      configPath: vscodeMcpPath,
+      rulesPath: null, // VS Code: clipboard only
+      existingMcp: serverName ? readMcpEntry(vscodeMcpPath, "servers", serverName) : null,
+      hasCli: !!whichSync("code"),
+      rootKey: "servers",
+    });
+  }
+
+  // Cline (VS Code extension)
+  const clineConfigPath = getClineConfigPath();
+  if (fileExists(clineConfigPath) || dirExists(path.dirname(clineConfigPath))) {
+    const home_ = os.homedir();
+    platforms.push({
+      platform: "cline",
+      version: "unknown",
+      configPath: clineConfigPath,
+      rulesPath: path.join(home_, "Documents", "Cline", "Rules"),
+      existingMcp: serverName ? readMcpEntry(clineConfigPath, "mcpServers", serverName) : null,
+      hasCli: false,
+      rootKey: "mcpServers",
+    });
+  }
+
+  // Roo Code (VS Code extension)
+  const rooConfigPath = getRooConfigPath();
+  if (fileExists(rooConfigPath) || dirExists(path.dirname(rooConfigPath))) {
+    platforms.push({
+      platform: "roo-code",
+      version: "unknown",
+      configPath: rooConfigPath,
+      rulesPath: path.join(os.homedir(), ".roo", "rules"),
+      existingMcp: serverName ? readMcpEntry(rooConfigPath, "mcpServers", serverName) : null,
+      hasCli: false,
+      rootKey: "mcpServers",
+    });
+  }
+
+  return platforms;
+}
+
+module.exports = {
+  detectPlatforms,
+  whichSync,
+  dirExists,
+  fileExists,
+  cliVersion,
+};

package/lib/mcp.js

@@ -0,0 +1,233 @@
+// MCP config read/write/merge/uninstall.
+// Handles all platform-specific config format differences.
+// Zero dependencies.
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+// ─── Read ────────────────────────────────────────────────────
+
+/**
+ * Read an MCP server entry from a config file.
+ * @param {string} configPath - Path to config JSON file
+ * @param {string} rootKey - Root key ("mcpServers" or "servers")
+ * @param {string} serverName - Server name to read
+ * @returns {object|null} Server config or null
+ */
+function readMcpEntry(configPath, rootKey, serverName) {
+  try {
+    let raw = fs.readFileSync(configPath, "utf-8");
+    if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1); // Strip BOM
+    const data = JSON.parse(raw);
+    return data?.[rootKey]?.[serverName] || null;
+  } catch { return null; }
+}
+
+// ─── Config Builders ─────────────────────────────────────────
+
+/**
+ * Build HTTP MCP config for a platform.
+ * Handles platform-specific field names (url vs serverUrl, type field).
+ * @param {string} serverUrl - MCP server URL
+ * @param {string} platform - Platform id
+ * @returns {object} MCP config object
+ */
+function buildHttpConfig(serverUrl, platform) {
+  if (platform === "windsurf") return { serverUrl };
+  if (platform === "vscode") return { type: "http", url: serverUrl };
+  return { url: serverUrl };
+}
+
+/**
+ * Build HTTP MCP config with auth headers.
+ * @param {string} serverUrl - MCP server URL
+ * @param {string} apiKey - API key for auth
+ * @param {string} platform - Platform id
+ * @param {object} [extraHeaders] - Additional headers
+ * @returns {object} MCP config with headers
+ */
+function buildHttpConfigWithAuth(serverUrl, apiKey, platform, extraHeaders) {
+  return {
+    ...buildHttpConfig(serverUrl, platform),
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      ...extraHeaders,
+    },
+  };
+}
+
+/**
+ * Build stdio MCP config.
+ * @param {string} command - Command to run
+ * @param {string[]} args - Command arguments
+ * @param {object} env - Environment variables
+ * @returns {object} MCP stdio config
+ */
+function buildStdioConfig(command, args, env) {
+  if (process.platform === "win32") {
+    return { command: "cmd", args: ["/c", command, ...args], env };
+  }
+  return { command, args, env };
+}
+
+// ─── Install ─────────────────────────────────────────────────
+
+function fileExists(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+/**
+ * Install MCP config for a platform.
+ * Tries platform CLI first (if available), falls back to JSON write.
+ * @param {object} platform - Platform object from detect
+ * @param {string} serverName - Server name (e.g., "prior")
+ * @param {object} mcpEntry - MCP config object
+ * @param {object} [options] - { dryRun, serverUrl }
+ * @returns {{ success: boolean, method: string }}
+ */
+function installMcp(platform, serverName, mcpEntry, options = {}) {
+  const { dryRun = false, serverUrl } = options;
+
+  // Claude Code: try CLI first
+  if (platform.platform === "claude-code" && platform.hasCli && mcpEntry.url) {
+    try {
+      if (!dryRun) {
+        const headerArgs = mcpEntry.headers
+          ? Object.entries(mcpEntry.headers).map(([k, v]) => `--header "${k}: ${v}"`).join(" ")
+          : "";
+        execSync(`claude mcp add --transport http -s user ${headerArgs} ${serverName} ${mcpEntry.url}`, {
+          encoding: "utf-8", timeout: 15000, stdio: "pipe",
+        });
+        const check = readMcpEntry(platform.configPath, platform.rootKey, serverName);
+        if (check) return { success: true, method: "cli" };
+      } else {
+        return { success: true, method: "cli" };
+      }
+    } catch { /* fall through */ }
+  }
+
+  // Cursor: try CLI first
+  if (platform.platform === "cursor" && platform.hasCli) {
+    try {
+      const mcpJson = JSON.stringify({ name: serverName, ...mcpEntry });
+      if (!dryRun) {
+        execSync(`cursor --add-mcp '${mcpJson.replace(/'/g, "'\\''")}'`, {
+          encoding: "utf-8", timeout: 15000, stdio: "pipe",
+        });
+        const check = readMcpEntry(platform.configPath, platform.rootKey, serverName);
+        if (check) return { success: true, method: "cli" };
+      } else {
+        return { success: true, method: "cli" };
+      }
+    } catch { /* fall through */ }
+  }
+
+  // VS Code: try CLI first
+  if (platform.platform === "vscode" && platform.hasCli) {
+    try {
+      const mcpJson = JSON.stringify({ name: serverName, ...mcpEntry });
+      if (!dryRun) {
+        execSync(`code --add-mcp '${mcpJson.replace(/'/g, "'\\''")}'`, {
+          encoding: "utf-8", timeout: 15000, stdio: "pipe",
+        });
+        const check = readMcpEntry(platform.configPath, platform.rootKey, serverName);
+        if (check) return { success: true, method: "cli" };
+      } else {
+        return { success: true, method: "cli" };
+      }
+    } catch { /* fall through */ }
+  }
+
+  // JSON write (all platforms, fallback for CLI failures)
+  return installMcpJson(platform, serverName, mcpEntry, dryRun);
+}
+
+/**
+ * Write MCP config directly to JSON file.
+ * Merges with existing config, creates backup.
+ * @param {object} platform - Platform object
+ * @param {string} serverName - Server name
+ * @param {object} mcpEntry - MCP config
+ * @param {boolean} dryRun
+ * @returns {{ success: boolean, method: string }}
+ */
+function installMcpJson(platform, serverName, mcpEntry, dryRun) {
+  const { configPath, rootKey } = platform;
+
+  let existing = {};
+  try {
+    let raw = fs.readFileSync(configPath, "utf-8");
+    if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+    existing = JSON.parse(raw);
+    if (typeof existing !== "object" || existing === null) existing = {};
+  } catch { /* start fresh */ }
+
+  if (!existing[rootKey]) existing[rootKey] = {};
+  existing[rootKey][serverName] = mcpEntry;
+
+  if (!dryRun) {
+    const dir = path.dirname(configPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    if (fileExists(configPath)) {
+      try { fs.copyFileSync(configPath, configPath + ".bak"); } catch {}
+    }
+
+    fs.writeFileSync(configPath, JSON.stringify(existing, null, 2) + "\n");
+  }
+
+  return { success: true, method: "json" };
+}
+
+/**
+ * Remove an MCP server entry from a platform config.
+ * @param {object} platform - Platform object
+ * @param {string} serverName - Server name to remove
+ * @param {boolean} dryRun
+ * @returns {boolean} Whether anything was removed
+ */
+function uninstallMcp(platform, serverName, dryRun) {
+  const { configPath, rootKey } = platform;
+  if (!fileExists(configPath)) return false;
+
+  try {
+    const data = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    if (!data?.[rootKey]?.[serverName]) return false;
+    delete data[rootKey][serverName];
+    if (Object.keys(data[rootKey]).length === 0) delete data[rootKey];
+    if (!dryRun) {
+      fs.copyFileSync(configPath, configPath + ".bak");
+      if (Object.keys(data).length === 0) {
+        fs.unlinkSync(configPath);
+      } else {
+        fs.writeFileSync(configPath, JSON.stringify(data, null, 2) + "\n");
+      }
+    }
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * Update API key in existing MCP config.
+ * @param {object} platform - Platform object
+ * @param {string} serverName - Server name
+ * @param {object} mcpEntry - New MCP config
+ * @returns {{ success: boolean, method: string }}
+ */
+function updateMcpKey(platform, serverName, mcpEntry) {
+  return installMcpJson(platform, serverName, mcpEntry, false);
+}
+
+module.exports = {
+  readMcpEntry,
+  buildHttpConfig,
+  buildHttpConfigWithAuth,
+  buildStdioConfig,
+  installMcp,
+  installMcpJson,
+  uninstallMcp,
+  updateMcpKey,
+};

package/lib/platforms.js

@@ -0,0 +1,110 @@
+// Platform path resolution and metadata.
+// Zero dependencies.
+
+"use strict";
+
+const path = require("path");
+const os = require("os");
+
+// ─── Path Helpers ────────────────────────────────────────────
+
+function getVsCodeUserDir() {
+  const home = os.homedir();
+  if (process.platform === "win32") return path.join(process.env.APPDATA || path.join(home, "AppData", "Roaming"), "Code", "User");
+  if (process.platform === "darwin") return path.join(home, "Library", "Application Support", "Code", "User");
+  return path.join(home, ".config", "Code", "User");
+}
+
+function getVsCodeMcpPath() {
+  return path.join(getVsCodeUserDir(), "mcp.json");
+}
+
+function getClineConfigPath() {
+  const base = getVsCodeUserDir();
+  return path.join(base, "globalStorage", "saoudrizwan.claude-dev", "settings", "cline_mcp_settings.json");
+}
+
+function getRooConfigPath() {
+  const base = getVsCodeUserDir();
+  return path.join(base, "globalStorage", "rooveterinaryinc.roo-cline", "settings", "cline_mcp_settings.json");
+}
+
+// ─── Platform Registry ──────────────────────────────────────
+
+/**
+ * Returns platform definition for manual override.
+ * @param {string} platformId
+ * @returns {object} Platform object with configPath, rulesPath, rootKey, etc.
+ */
+function createManualPlatform(platformId) {
+  const home = os.homedir();
+  const configs = {
+    "claude-code": {
+      configPath: path.join(home, ".claude.json"),
+      rulesPath: path.join(home, ".claude", "CLAUDE.md"),
+      rootKey: "mcpServers",
+    },
+    cursor: {
+      configPath: path.join(home, ".cursor", "mcp.json"),
+      rulesPath: null,
+      rootKey: "mcpServers",
+    },
+    windsurf: {
+      configPath: path.join(home, ".codeium", "windsurf", "mcp_config.json"),
+      rulesPath: path.join(home, ".codeium", "windsurf", "memories", "global_rules.md"),
+      rootKey: "mcpServers",
+    },
+    vscode: {
+      configPath: getVsCodeMcpPath(),
+      rulesPath: null,
+      rootKey: "servers",
+    },
+    cline: {
+      configPath: getClineConfigPath(),
+      rulesPath: path.join(home, "Documents", "Cline", "Rules"),
+      rootKey: "mcpServers",
+    },
+    "roo-code": {
+      configPath: getRooConfigPath(),
+      rulesPath: path.join(home, ".roo", "rules"),
+      rootKey: "mcpServers",
+    },
+  };
+
+  const def = configs[platformId];
+  if (!def) {
+    throw new Error(`Unknown platform: ${platformId}. Supported: ${Object.keys(configs).join(", ")}`);
+  }
+
+  return { platform: platformId, version: "unknown", hasCli: false, existingMcp: null, ...def };
+}
+
+/**
+ * Display name for a platform id.
+ */
+function platformName(id) {
+  const names = {
+    "claude-code": "Claude Code",
+    cursor: "Cursor",
+    windsurf: "Windsurf",
+    vscode: "VS Code",
+    cline: "Cline",
+    "roo-code": "Roo Code",
+  };
+  return names[id] || id;
+}
+
+/**
+ * All known platform IDs.
+ */
+const KNOWN_PLATFORMS = ["claude-code", "cursor", "windsurf", "vscode", "cline", "roo-code"];
+
+module.exports = {
+  getVsCodeUserDir,
+  getVsCodeMcpPath,
+  getClineConfigPath,
+  getRooConfigPath,
+  createManualPlatform,
+  platformName,
+  KNOWN_PLATFORMS,
+};

package/lib/rules.js

@@ -0,0 +1,152 @@
+// Behavioral rules installation — marker-based versioned blocks.
+// Handles appending, updating, and removing rules from shared files.
+// Zero dependencies.
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+// ─── Constants ──────────────────────────────────────────────
+
+/**
+ * Create regex patterns for a given marker name.
+ * @param {string} marker - Marker name (e.g., "prior")
+ * @returns {{ MARKER_RE: RegExp, BLOCK_RE: RegExp }}
+ */
+function markerPatterns(marker) {
+  return {
+    MARKER_RE: new RegExp(`<!-- ${marker}:v[\\d.]+ -->`),
+    BLOCK_RE: new RegExp(`<!-- ${marker}:v[\\d.]+ -->[\\s\\S]*?<!-- \\/${marker} -->\\n?`),
+  };
+}
+
+/**
+ * Parse version from marker in content.
+ * @param {string} content
+ * @param {string} marker
+ * @returns {string|null}
+ */
+function parseRulesVersion(content, marker) {
+  const m = content.match(new RegExp(`<!-- ${marker}:v([\\d.]+) -->`));
+  return m ? m[1] : null;
+}
+
+// ─── Install ─────────────────────────────────────────────────
+
+/**
+ * Install behavioral rules to a platform's rules file.
+ * Supports: file-based (append/update), standalone file, or clipboard.
+ *
+ * @param {object} platform - Platform object with rulesPath
+ * @param {object} options
+ * @param {string} options.content - Rules content (with markers)
+ * @param {string} options.version - Current version string
+ * @param {string} options.marker - Marker name for tracking
+ * @param {string} [options.fileName] - For standalone file platforms (e.g., "prior.md")
+ * @param {string[]} [options.clipboardPlatforms] - Platform ids that use clipboard
+ * @param {boolean} [options.dryRun]
+ * @param {Function} [options.copyToClipboard] - Clipboard function
+ * @returns {{ action: string }} "created" | "updated" | "skipped" | "clipboard"
+ */
+function installRules(platform, options) {
+  const {
+    content,
+    version,
+    marker,
+    fileName,
+    clipboardPlatforms = ["cursor", "vscode"],
+    dryRun = false,
+    copyToClipboard,
+  } = options;
+
+  // Clipboard-only platforms
+  if (clipboardPlatforms.includes(platform.platform)) {
+    if (!dryRun && copyToClipboard) {
+      copyToClipboard(content);
+    }
+    return { action: "clipboard" };
+  }
+
+  if (!platform.rulesPath) return { action: "skipped" };
+
+  // Determine actual file path — standalone file vs append
+  const rulesPath = fileName
+    ? path.join(platform.rulesPath, fileName)
+    : platform.rulesPath;
+
+  const { MARKER_RE, BLOCK_RE } = markerPatterns(marker);
+
+  let existing = "";
+  try { existing = fs.readFileSync(rulesPath, "utf-8"); } catch {}
+
+  const existingVersion = parseRulesVersion(existing, marker);
+
+  if (existingVersion === version) {
+    return { action: "skipped" };
+  }
+
+  if (!dryRun) {
+    const dir = path.dirname(rulesPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    if (existingVersion) {
+      // Replace existing block
+      const updated = existing.replace(BLOCK_RE, content + "\n");
+      fs.writeFileSync(rulesPath, updated);
+      return { action: "updated" };
+    }
+
+    // Append
+    const sep = existing && !existing.endsWith("\n\n") ? (existing.endsWith("\n") ? "\n" : "\n\n") : "";
+    fs.writeFileSync(rulesPath, existing + sep + content + "\n");
+    return { action: "created" };
+  }
+
+  return { action: existingVersion ? "updated" : "created" };
+}
+
+/**
+ * Remove rules from a platform's rules file.
+ * @param {object} platform - Platform object
+ * @param {object} options
+ * @param {string} options.marker - Marker name
+ * @param {string} [options.fileName] - For standalone file platforms
+ * @param {boolean} [options.dryRun]
+ * @returns {boolean} Whether anything was removed
+ */
+function uninstallRules(platform, options) {
+  const { marker, fileName, dryRun = false } = options;
+
+  if (!platform.rulesPath) return false;
+
+  const rulesPath = fileName
+    ? path.join(platform.rulesPath, fileName)
+    : platform.rulesPath;
+
+  try {
+    if (!fs.statSync(rulesPath).isFile()) return false;
+  } catch { return false; }
+
+  try {
+    const content = fs.readFileSync(rulesPath, "utf-8");
+    const { MARKER_RE, BLOCK_RE } = markerPatterns(marker);
+    if (!MARKER_RE.test(content)) return false;
+    if (!dryRun) {
+      const cleaned = content.replace(BLOCK_RE, "").replace(/\n{3,}/g, "\n\n").trim();
+      if (cleaned) {
+        fs.writeFileSync(rulesPath, cleaned + "\n");
+      } else {
+        fs.unlinkSync(rulesPath);
+      }
+    }
+    return true;
+  } catch { return false; }
+}
+
+module.exports = {
+  markerPatterns,
+  parseRulesVersion,
+  installRules,
+  uninstallRules,
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@cg3/equip",
+  "version": "0.1.0",
+  "description": "Universal MCP + behavioral rules installer for AI coding agents",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./detect": "./lib/detect.js",
+    "./mcp": "./lib/mcp.js",
+    "./rules": "./lib/rules.js",
+    "./platforms": "./lib/platforms.js",
+    "./cli": "./lib/cli.js"
+  },
+  "files": [
+    "index.js",
+    "lib/"
+  ],
+  "keywords": [
+    "mcp",
+    "ai",
+    "agent",
+    "setup",
+    "claude",
+    "cursor",
+    "windsurf",
+    "vscode",
+    "cline",
+    "roo-code"
+  ],
+  "author": "CG3 LLC",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cg3-llc/equip"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}