@mergesafe-io/connect 0.1.0 → 0.3.0

package/README.md

@@ -1,16 +1,31 @@
 # @mergesafe-io/connect
 
-One command to connect your AI client to the [MergeSafe](https://app.mergesafe.io) MCP server — no JSON editing.
+One command connects every AI client on your machine to the
+[MergeSafe](https://app.mergesafe.io) MCP server — globally, so it works in
+every project. No JSON editing.
 
 ```bash
-npx @mergesafe-io/connect claude-desktop --key msk_your_api_key
+npx @mergesafe-io/connect --key msk_your_api_key
 ```
 
-That's it. Restart the client and the `mergesafe` tools are available.
+That's it. The CLI detects which clients are installed (Claude Code, Claude
+Desktop, Cursor, Windsurf, VS Code, …), writes each one's **global** config,
+and backs up every file it touches. Restart your clients and the `mergesafe`
+tools are available everywhere.
+
+To uninstall from every detected client:
+
+```bash
+npx @mergesafe-io/connect --uninstall
+```
+
+That removes only the mergesafe entry — all other configs are preserved.
 
 ## What it does
 
-- Finds the right MCP config file for your client and OS
+- Detects the AI clients installed on your machine (or targets just one if
+  you name it: `npx @mergesafe-io/connect cursor --key msk_…`)
+- Finds the right **global** MCP config file for each client and OS
 - Backs up the existing file next to it (`*.bak-<timestamp>`)
 - Merges in the `mergesafe` server entry — every other setting and server is preserved
 - Refuses to touch a file it can't parse (broken JSON aborts with a clear message)
@@ -19,43 +34,43 @@ No dependencies, no telemetry, Node 18+.
 
 ## Supported clients
 
-| Client | Config written |
+| Client | Global config written |
 |---|---|
-| `claude-desktop` | `claude_desktop_config.json` (global, per-OS path) — bridges through `mcp-remote` |
-| `cursor` | `~/.cursor/mcp.json` (or `./.cursor/mcp.json` with `--project`) |
-| `cursor-local` | `./.cursor/mcp.json` — local stdio server (needs `mergesafe-mcp` on PATH) |
+| `claude-code` | `~/.claude.json` (user scope — every project and session) |
+| `claude-desktop` | `claude_desktop_config.json` (per-OS path) — bridges through `mcp-remote` |
+| `cursor` | `~/.cursor/mcp.json` (`--project` for `./.cursor/mcp.json`) |
 | `windsurf` | `~/.codeium/windsurf/mcp_config.json` |
-| `vscode` | `./.vscode/mcp.json` (current project) |
-| `opencode` | `./opencode.json` (current project) |
+| `vscode` | user-profile `mcp.json` (`--project` for `./.vscode/mcp.json`) |
+| `opencode` | `~/.config/opencode/config.json` |
 | `cline` | `cline_mcp_settings.json` (stock VS Code global storage, per-OS path) |
-| `roo-code` | `./.roo/mcp.json` (current project) |
-| `continue` | `./.continue/mcpServers/mergesafe.yaml` (dedicated file, whole-file write) |
+| `roo-code` | `mcp_settings.json` in VS Code global storage (`--project` for `./.roo/mcp.json`) |
+| `continue` | `~/.continue/mcpServers/mergesafe.yaml` (`--project` for the project copy) |
 
 Not covered: Zed (its `settings.json` is JSONC with comments — a rewrite would
-destroy them; configure manually). For Claude Code CLI and Gemini CLI, use their
-built-in commands instead:
-`claude mcp add --transport sse mergesafe https://mcp.mergesafe.io/sse --header "Authorization: Bearer msk_…"`
+destroy them; configure manually). Gemini CLI: use its built-in command:
+`gemini mcp add --transport http mergesafe https://mcp.mergesafe.io/mcp -H "Authorization: Bearer msk_…"`
 
 ## Options
 
 | Flag | Effect |
 |---|---|
 | `--key <msk_…>` | Your MergeSafe API key (from app.mergesafe.io → Settings). Prompted if omitted. |
-| `--project` | Write the project-local config instead of the global one (cursor) |
-| `--dry-run` | Print the target path and resulting file without writing |
+| `--project` | Write the project-local config instead of the global one (cursor, vscode, roo-code, continue — needs an explicit client) |
+| `--with-rules` | Also write agent rules files (`.cursor/rules/mergesafe.mdc`, `AGENTS.md` block) so the AI runs MergeSafe after coding |
+| `--dry-run` | Print the target paths and resulting files without writing |
+| `--uninstall` | Remove the `mergesafe` entry (no client = every detected client) |
 | `--help` | Usage |
 
 ## Development
 
 ```bash
 npm test           # node --test, zero deps
-node bin/mergesafe-connect.js cursor --key msk_x --dry-run
+node bin/mergesafe-connect.js --key msk_x --dry-run          # auto-detect
+node bin/mergesafe-connect.js cursor --key msk_x --dry-run   # single client
 ```
 
 ## Publishing
 
-The `@mergesafe` npm scope must exist (create the org on npmjs.com), then:
-
 ```bash
 npm publish --access public
 ```

package/lib/actions.js

@@ -0,0 +1,104 @@
+/** Install/uninstall actions for one client: back up, merge, write. */
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { SERVER_NAME } from "./clients.js";
+import { applyEntry, removeEntry } from "./config-file.js";
+import { writeRulesFiles } from "./rules.js";
+
+export async function handleInstall(client, key, configPath, dryRun, withRules, cwd) {
+  const existingText = await readIfExists(configPath);
+
+  const newText = client.buildFileContent
+    ? // Dedicated-file clients (Continue): whole-file write
+      client.buildFileContent(key)
+    : // Merge via applyEntry — only the mergesafe entry is touched
+      applyEntry(existingText ?? "", client.rootKey, SERVER_NAME, client.buildEntry(key));
+
+  if (dryRun) {
+    console.log(`Would write ${configPath}:\n\n${newText}`);
+    if (withRules) {
+      console.log("Would also write agent rules files (.cursor/rules/mergesafe.mdc, AGENTS.md).");
+    }
+    return;
+  }
+
+  await backupIfPresent(existingText, configPath);
+  await fs.mkdir(path.dirname(configPath), { recursive: true });
+  await fs.writeFile(configPath, newText, "utf8");
+
+  console.log(`✔ ${client.label} is connected to MergeSafe (${configPath})`);
+  console.log(`→ ${client.restartHint}`);
+
+  if (withRules) {
+    await reportRules(cwd);
+  }
+}
+
+export async function handleUninstall(client, configPath, dryRun) {
+  const existingText = await readIfExists(configPath);
+
+  if (existingText === null) {
+    console.log(`⚠ No config found at ${configPath} — nothing to remove.`);
+    return;
+  }
+
+  if (client.deleteFile) {
+    // Continue: delete the dedicated YAML file entirely
+    if (!dryRun) {
+      await fs.unlink(configPath);
+    }
+    console.log(`🗑 ${dryRun ? "Would remove" : "Removed"} ${configPath}`);
+    console.log(`→ ${client.restartHint}`);
+    return;
+  }
+
+  if (!client.deleteKey) {
+    throw new Error(`Client "${client.label}" does not support --uninstall`);
+  }
+
+  const newText = removeEntry(existingText, client.rootKey, SERVER_NAME);
+
+  if (newText === null) {
+    console.log(`⚠ No mergesafe entry found in ${configPath} — nothing to remove.`);
+    return;
+  }
+
+  if (dryRun) {
+    console.log(`Would write ${configPath}:\n\n${newText}`);
+    return;
+  }
+
+  await backupIfPresent(existingText, configPath);
+  await fs.writeFile(configPath, newText, "utf8");
+  console.log(`🗑 Removed mergesafe entry from ${configPath}`);
+  console.log(`→ ${client.restartHint}`);
+}
+
+export async function reportRules(cwd) {
+  const written = await writeRulesFiles({ cwd });
+  for (const file of written) {
+    console.log(`✔ Rules written: ${file}`);
+  }
+  console.log("→ Your AI agent will now run MergeSafe after each coding session.");
+}
+
+async function backupIfPresent(existingText, configPath) {
+  if (existingText === null) return;
+  const backupPath = `${configPath}.bak-${timestamp()}`;
+  await fs.copyFile(configPath, backupPath);
+  console.log(`• Backed up existing config to ${backupPath}`);
+}
+
+async function readIfExists(filePath) {
+  try {
+    return await fs.readFile(filePath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+}

package/lib/cli.js

@@ -1,35 +1,40 @@
-/** CLI flow: parse args, resolve client + key, back up, merge, write. */
-import fs from "node:fs/promises";
+/** CLI flow: parse args, detect or resolve clients, delegate to actions. */
 import os from "node:os";
-import path from "node:path";
 import readline from "node:readline/promises";
 import { parseArgs } from "node:util";
 
+import { handleInstall, handleUninstall, reportRules } from "./actions.js";
 import { SERVER_NAME, getClient, listClientIds } from "./clients.js";
-import { applyEntry } from "./config-file.js";
+import { detectClients } from "./detect.js";
 
-const USAGE = `Usage: npx @mergesafe-io/connect <client> [options]
+const USAGE = `Usage: npx @mergesafe-io/connect [client] [options]
 
-Writes the MergeSafe MCP server entry into the client's config file.
-The existing file is backed up first; only the "${SERVER_NAME}" entry is touched.
+Connects your AI clients to the MergeSafe MCP server — globally, so it works
+in every project. With no <client> argument, every installed client is
+detected and configured in one go. Existing files are backed up first; only
+the "${SERVER_NAME}" entry is touched.
 
-Clients:
-  claude-desktop   Claude Desktop (global config, via mcp-remote bridge)
-  cursor           Cursor — global ~/.cursor/mcp.json (--project for ./.cursor/mcp.json)
-  cursor-local     Cursor local stdio server — ./.cursor/mcp.json (needs mergesafe-mcp)
+Clients (all global unless noted):
+  claude-code      Claude Code — ~/.claude.json (user scope, every project)
+  claude-desktop   Claude Desktop — claude_desktop_config.json (via mcp-remote bridge)
+  cursor           Cursor — ~/.cursor/mcp.json (--project for ./.cursor/mcp.json)
   windsurf         Windsurf — ~/.codeium/windsurf/mcp_config.json
-  vscode           VS Code — .vscode/mcp.json in the current project
-  opencode         opencode — opencode.json in the current project
+  vscode           VS Code — user-profile mcp.json (--project for ./.vscode/mcp.json)
+  opencode         opencode — ~/.config/opencode/config.json
   cline            Cline — cline_mcp_settings.json (stock VS Code global storage)
-  roo-code         Roo Code — .roo/mcp.json in the current project
-  continue         Continue — .continue/mcpServers/mergesafe.yaml in the current project
+  roo-code         Roo Code — VS Code global storage (--project for ./.roo/mcp.json)
+  continue         Continue — ~/.continue/mcpServers/mergesafe.yaml (--project for ./.continue/…)
 
 Options:
   --key <msk_...>  MergeSafe API key (create one on app.mergesafe.io/dashboard/settings;
                    prompted interactively if omitted)
-  --project        Write the project-local config instead of the global one (cursor)
+  --project        Write the project-local config instead of the global one
+                   (cursor, vscode, roo-code, continue — needs an explicit client)
+  --with-rules     Also write agent rules files (.cursor/rules/mergesafe.mdc,
+                   AGENTS.md block) so the AI runs MergeSafe after coding
   --dry-run        Print the target path and resulting file without writing
-  --help           Show this help
+  --uninstall      Remove the mergesafe entry (no client = every detected client)
+  --help           Show usage
 `;
 
 export async function main(argv) {
@@ -39,21 +44,18 @@ export async function main(argv) {
     options: {
       key: { type: "string" },
       project: { type: "boolean", default: false },
+      "with-rules": { type: "boolean", default: false },
       "dry-run": { type: "boolean", default: false },
+      uninstall: { type: "boolean", default: false },
       help: { type: "boolean", default: false },
     },
   });
 
-  if (values.help || positionals.length === 0) {
+  if (values.help) {
     console.log(USAGE);
-    if (!values.help) {
-      throw new Error(`Missing <client> argument. Supported: ${listClientIds().join(", ")}`);
-    }
     return;
   }
 
-  const client = getClient(positionals[0]);
-  const key = await resolveKey(values.key);
   const ctx = {
     platform: process.platform,
     home: os.homedir(),
@@ -62,29 +64,74 @@ export async function main(argv) {
     project: values.project,
   };
 
-  const configPath = client.configPath(ctx);
-  const existingText = await readIfExists(configPath);
-  // Dedicated-file clients (Continue) get a whole-file write; the rest are
-  // merged into the shared JSON config without touching other entries.
-  const newText = client.buildFileContent
-    ? client.buildFileContent(key)
-    : applyEntry(existingText ?? "", client.rootKey, SERVER_NAME, client.buildEntry(key));
-
-  if (values["dry-run"]) {
-    console.log(`Would write ${configPath}:\n\n${newText}`);
+  // --uninstall can come before the client name: "uninstall cursor" or "cursor --uninstall"
+  const filtered = positionals.filter((p) => p !== "--uninstall");
+  if (filtered.length === 0) {
+    await runAllDetected(values, ctx);
     return;
   }
 
-  if (existingText !== null) {
-    const backupPath = `${configPath}.bak-${timestamp()}`;
-    await fs.copyFile(configPath, backupPath);
-    console.log(`• Backed up existing config to ${backupPath}`);
+  const client = getClient(filtered[0]);
+  const configPath = client.configPath(ctx);
+  if (values.uninstall) {
+    await handleUninstall(client, configPath, values["dry-run"]);
+  } else {
+    const key = await resolveKey(values.key);
+    await handleInstall(client, key, configPath, values["dry-run"], values["with-rules"], ctx.cwd);
+  }
+}
+
+/** No-client mode: detect every installed client and configure them globally. */
+async function runAllDetected(values, ctx) {
+  if (values.project) {
+    throw new Error(
+      "--project needs an explicit client (e.g. `npx @mergesafe-io/connect cursor --project`).",
+    );
+  }
+
+  const detected = detectClients(ctx);
+  if (detected.length === 0) {
+    console.log(USAGE);
+    throw new Error(
+      `No supported AI client detected on this machine. Specify one explicitly: ${listClientIds().join(", ")}`,
+    );
+  }
+  console.log(`Detected clients: ${detected.map((id) => getClient(id).label).join(", ")}\n`);
+
+  const key = values.uninstall ? null : await resolveKey(values.key);
+  const failures = [];
+  for (const id of detected) {
+    const client = getClient(id);
+    try {
+      if (values.uninstall) {
+        await handleUninstall(client, client.configPath(ctx), values["dry-run"]);
+      } else {
+        await handleInstall(client, key, client.configPath(ctx), values["dry-run"], false, ctx.cwd);
+      }
+    } catch (err) {
+      failures.push(`${client.label}: ${err.message}`);
+    }
+    console.log("");
   }
-  await fs.mkdir(path.dirname(configPath), { recursive: true });
-  await fs.writeFile(configPath, newText, "utf8");
 
-  console.log(`✔ ${client.label} is connected to MergeSafe (${configPath})`);
-  console.log(`→ ${client.restartHint}`);
+  if (values["with-rules"] && !values.uninstall && !values["dry-run"]) {
+    await reportRules(ctx.cwd);
+  }
+  reportOutcome(detected.length, failures, values.uninstall);
+}
+
+function reportOutcome(total, failures, uninstall) {
+  for (const failure of failures) {
+    console.error(`⚠ ${failure}`);
+  }
+  if (failures.length === total) {
+    throw new Error("Nothing was configured — every detected client failed (see above).");
+  }
+  if (!uninstall) {
+    console.log(
+      "✔ MergeSafe is connected globally — restart your clients and the tools work in every project.",
+    );
+  }
 }
 
 async function resolveKey(flagValue) {
@@ -102,16 +149,3 @@ async function resolveKey(flagValue) {
   }
   return key;
 }
-
-async function readIfExists(filePath) {
-  try {
-    return await fs.readFile(filePath, "utf8");
-  } catch (err) {
-    if (err.code === "ENOENT") return null;
-    throw err;
-  }
-}
-
-function timestamp() {
-  return new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
-}

package/lib/clients.js

@@ -1,24 +1,48 @@
 /** Per-client knowledge: where the MCP config lives and what to write in it. */
 import path from "node:path";
 
+import { claudeDesktopConfigPath, vscodeUserDir } from "./paths.js";
+
+export const MCP_HTTP_URL = "https://mcp.mergesafe.io/mcp";
+// Legacy endpoint, kept for clients without solid Streamable HTTP support
+// (opencode: SSE-only "remote" type; cline: open transport bugs; continue:
+// header auth unverified on streamable-http). Revisit as they catch up.
 export const MCP_SSE_URL = "https://mcp.mergesafe.io/sse";
 export const SERVER_NAME = "mergesafe";
 
 /**
  * ctx: { platform, home, cwd, env, project } — injected by the CLI so
  * every path decision stays testable without touching the real machine.
+ *
+ * Every client is global (user-wide) by default; `--project` opts the few
+ * clients that support it into a project-local config instead.
+ * `detectPaths` lists markers whose existence means the client is installed.
  */
 const CLIENTS = {
+  "claude-code": {
+    label: "Claude Code",
+    rootKey: "mcpServers",
+    configPath: (ctx) => path.join(ctx.home, ".claude.json"),
+    detectPaths: (ctx) => [path.join(ctx.home, ".claude.json"), path.join(ctx.home, ".claude")],
+    deleteKey: true,
+    // Same entry `claude mcp add --scope user --transport http` writes:
+    // user scope, so every project and session sees the server.
+    buildEntry: (key) => ({ type: "http", url: MCP_HTTP_URL, headers: bearer(key) }),
+    restartHint: "Restart any open Claude Code sessions — the server is user-wide, every project gets it.",
+  },
   "claude-desktop": {
     label: "Claude Desktop",
     rootKey: "mcpServers",
     configPath: (ctx) => claudeDesktopConfigPath(ctx),
-    // Claude Desktop has no native SSE + Bearer support; bridge via
-    // mcp-remote. No space after "Authorization:" and env-expanded token —
-    // both required by mcp-remote arg parsing.
+    detectPaths: (ctx) => [path.dirname(claudeDesktopConfigPath(ctx))],
+    deleteKey: true,
+    // Claude Desktop has no native remote + Bearer support; bridge via
+    // mcp-remote (http-first: tries Streamable HTTP, falls back to SSE).
+    // No space after "Authorization:" and env-expanded token — both
+    // required by mcp-remote arg parsing.
     buildEntry: (key) => ({
       command: "npx",
-      args: ["mcp-remote", MCP_SSE_URL, "--header", "Authorization:Bearer ${AUTH_TOKEN}"],
+      args: ["mcp-remote", MCP_HTTP_URL, "--header", "Authorization:Bearer ${AUTH_TOKEN}"],
       env: { AUTH_TOKEN: key },
     }),
     restartHint: "Fully quit and reopen Claude Desktop (needs Node.js 18+ for npx).",
@@ -30,67 +54,73 @@ const CLIENTS = {
       ctx.project
         ? path.join(ctx.cwd, ".cursor", "mcp.json")
         : path.join(ctx.home, ".cursor", "mcp.json"),
-    buildEntry: (key) => ({ url: MCP_SSE_URL, headers: bearer(key) }),
+    detectPaths: (ctx) => [path.join(ctx.home, ".cursor")],
+    deleteKey: true,
+    // Cursor auto-detects Streamable HTTP from the URL (SSE fallback built in).
+    buildEntry: (key) => ({ url: MCP_HTTP_URL, headers: bearer(key) }),
     restartHint: "Restart Cursor or reload the window.",
   },
   windsurf: {
     label: "Windsurf",
     rootKey: "mcpServers",
     configPath: (ctx) => path.join(ctx.home, ".codeium", "windsurf", "mcp_config.json"),
-    buildEntry: (key) => ({ serverUrl: MCP_SSE_URL, headers: bearer(key) }),
+    detectPaths: (ctx) => [path.join(ctx.home, ".codeium", "windsurf")],
+    deleteKey: true,
+    buildEntry: (key) => ({ serverUrl: MCP_HTTP_URL, headers: bearer(key) }),
     restartHint: "Fully quit and reopen Windsurf.",
   },
   vscode: {
-    label: "VS Code (project)",
+    label: "VS Code",
     rootKey: "servers",
-    configPath: (ctx) => path.join(ctx.cwd, ".vscode", "mcp.json"),
-    buildEntry: (key) => ({ type: "sse", url: MCP_SSE_URL, headers: bearer(key) }),
-    restartHint: "Open mcp.json in VS Code and press the “Start” CodeLens.",
+    configPath: (ctx) =>
+      ctx.project
+        ? path.join(ctx.cwd, ".vscode", "mcp.json")
+        : path.join(vscodeUserDir(ctx), "mcp.json"),
+    detectPaths: (ctx) => [vscodeUserDir(ctx)],
+    deleteKey: true,
+    buildEntry: (key) => ({ type: "http", url: MCP_HTTP_URL, headers: bearer(key) }),
+    restartHint: "Restart VS Code, then check MCP: List Servers in the command palette.",
   },
   opencode: {
-    label: "opencode (project)",
+    label: "opencode",
     rootKey: "mcp",
-    configPath: (ctx) => path.join(ctx.cwd, "opencode.json"),
+    configPath: (ctx) => path.join(ctx.home, ".config", "opencode", "config.json"),
+    detectPaths: (ctx) => [path.join(ctx.home, ".config", "opencode")],
+    deleteKey: true,
     buildEntry: (key) => ({ type: "remote", url: MCP_SSE_URL, enabled: true, headers: bearer(key) }),
     restartHint: "Restart opencode for changes to take effect.",
   },
-  "cursor-local": {
-    label: "Cursor (local server)",
-    rootKey: "mcpServers",
-    configPath: (ctx) => path.join(ctx.cwd, ".cursor", "mcp.json"),
-    // Local stdio server so Cursor can scan the local project — requires the
-    // mergesafe-mcp command (Python package) on PATH; Cursor starts it itself.
-    buildEntry: (key) => ({
-      command: "mergesafe-mcp",
-      env: {
-        MCP_TRANSPORT: "stdio",
-        MERGESAFE_API_URL: "https://api.mergesafe.io",
-        MERGESAFE_FRONTEND_URL: "https://app.mergesafe.io",
-        MERGESAFE_API_KEY: key,
-      },
-    }),
-    restartHint:
-      "Restart Cursor. Requires the mergesafe-mcp command installed (Python 3.11+).",
-  },
   cline: {
     label: "Cline",
     rootKey: "mcpServers",
     configPath: (ctx) =>
       path.join(vscodeUserDir(ctx), "globalStorage", "saoudrizwan.claude-dev", "settings", "cline_mcp_settings.json"),
+    detectPaths: (ctx) => [path.join(vscodeUserDir(ctx), "globalStorage", "saoudrizwan.claude-dev")],
+    deleteKey: true,
     buildEntry: (key) => ({ url: MCP_SSE_URL, headers: bearer(key) }),
     restartHint: "Reload the VS Code window (stock VS Code path — not Insiders/VSCodium).",
   },
   "roo-code": {
-    label: "Roo Code (project)",
+    label: "Roo Code",
     rootKey: "mcpServers",
-    configPath: (ctx) => path.join(ctx.cwd, ".roo", "mcp.json"),
+    configPath: (ctx) =>
+      ctx.project
+        ? path.join(ctx.cwd, ".roo", "mcp.json")
+        : path.join(vscodeUserDir(ctx), "globalStorage", "rooveterinaryinc.roo-cline", "settings", "mcp_settings.json"),
+    detectPaths: (ctx) => [path.join(vscodeUserDir(ctx), "globalStorage", "rooveterinaryinc.roo-cline")],
+    deleteKey: true,
     buildEntry: (key) => ({ type: "sse", url: MCP_SSE_URL, headers: bearer(key), disabled: false }),
-    restartHint: "Reload the VS Code window; project config overrides global settings.",
+    restartHint: "Reload the VS Code window.",
   },
   continue: {
-    label: "Continue (project)",
-    configPath: (ctx) => path.join(ctx.cwd, ".continue", "mcpServers", "mergesafe.yaml"),
+    label: "Continue",
+    configPath: (ctx) =>
+      ctx.project
+        ? path.join(ctx.cwd, ".continue", "mcpServers", "mergesafe.yaml")
+        : path.join(ctx.home, ".continue", "mcpServers", "mergesafe.yaml"),
+    detectPaths: (ctx) => [path.join(ctx.home, ".continue")],
     // Continue uses one YAML file per MCP server — whole-file write, no merge.
+    deleteFile: true,
     buildFileContent: (key) =>
       [
         "name: Mergesafe MCP",
@@ -113,32 +143,6 @@ function bearer(key) {
   return { Authorization: `Bearer ${key}` };
 }
 
-/** Stock VS Code user dir per OS (globalStorage lives under it). */
-function vscodeUserDir(ctx) {
-  if (ctx.platform === "darwin") {
-    return path.join(ctx.home, "Library", "Application Support", "Code", "User");
-  }
-  if (ctx.platform === "win32") {
-    const appData = ctx.env.APPDATA || path.join(ctx.home, "AppData", "Roaming");
-    return path.join(appData, "Code", "User");
-  }
-  const configHome = ctx.env.XDG_CONFIG_HOME || path.join(ctx.home, ".config");
-  return path.join(configHome, "Code", "User");
-}
-
-function claudeDesktopConfigPath(ctx) {
-  const file = "claude_desktop_config.json";
-  if (ctx.platform === "darwin") {
-    return path.join(ctx.home, "Library", "Application Support", "Claude", file);
-  }
-  if (ctx.platform === "win32") {
-    const appData = ctx.env.APPDATA || path.join(ctx.home, "AppData", "Roaming");
-    return path.join(appData, "Claude", file);
-  }
-  const configHome = ctx.env.XDG_CONFIG_HOME || path.join(ctx.home, ".config");
-  return path.join(configHome, "Claude", file);
-}
-
 export function getClient(id) {
   const client = CLIENTS[id];
   if (!client) {

package/lib/config-file.js

@@ -14,6 +14,40 @@ export function applyEntry(text, rootKey, serverName, entry) {
   return `${JSON.stringify(config, null, 2)}\n`;
 }
 
+/**
+ * Remove the `serverName` entry under `rootKey` from the JSON text.
+ * Preserves all other entries. If the section becomes empty, removes it too.
+ * Returns the new file text (2-space indent, trailing newline).
+ */
+export function removeEntry(text, rootKey, serverName) {
+  const config = parseConfig(text);
+  const section = config[rootKey];
+
+  if (!section || typeof section !== "object" || Array.isArray(section)) {
+    // Nothing to remove — the config has no such section
+    return null;
+  }
+
+  const copy = { ...section };
+  delete copy[serverName];
+
+  if (Object.keys(copy).length === 0) {
+    delete config[rootKey];
+  } else {
+    config[rootKey] = copy;
+  }
+
+  return `${JSON.stringify(config, null, 2)}\n`;
+}
+
+/**
+ * Remove the mergesafe server entry from a dedicated YAML file (Continue).
+ * Returns the new file text (overwrite), or null if the file doesn't exist.
+ */
+export function removeFileContent() {
+  return "";
+}
+
 function parseConfig(text) {
   if (!text || !text.trim()) {
     return {};

package/lib/detect.js

@@ -0,0 +1,14 @@
+/** Detect which supported AI clients are installed on this machine. */
+import fs from "node:fs";
+
+import { getClient, listClientIds } from "./clients.js";
+
+/**
+ * Return the ids of every client whose marker path exists.
+ * `exists` is injectable so detection stays testable without a real machine.
+ */
+export function detectClients(ctx, exists = fs.existsSync) {
+  return listClientIds().filter((id) =>
+    getClient(id).detectPaths(ctx).some((markerPath) => exists(markerPath)),
+  );
+}

package/lib/paths.js

@@ -0,0 +1,29 @@
+/** Per-OS filesystem locations shared by several clients. */
+import path from "node:path";
+
+/** Stock VS Code user dir per OS (globalStorage and user mcp.json live under it). */
+export function vscodeUserDir(ctx) {
+  if (ctx.platform === "darwin") {
+    return path.join(ctx.home, "Library", "Application Support", "Code", "User");
+  }
+  if (ctx.platform === "win32") {
+    const appData = ctx.env.APPDATA || path.join(ctx.home, "AppData", "Roaming");
+    return path.join(appData, "Code", "User");
+  }
+  const configHome = ctx.env.XDG_CONFIG_HOME || path.join(ctx.home, ".config");
+  return path.join(configHome, "Code", "User");
+}
+
+/** Claude Desktop's claude_desktop_config.json per OS. */
+export function claudeDesktopConfigPath(ctx) {
+  const file = "claude_desktop_config.json";
+  if (ctx.platform === "darwin") {
+    return path.join(ctx.home, "Library", "Application Support", "Claude", file);
+  }
+  if (ctx.platform === "win32") {
+    const appData = ctx.env.APPDATA || path.join(ctx.home, "AppData", "Roaming");
+    return path.join(appData, "Claude", file);
+  }
+  const configHome = ctx.env.XDG_CONFIG_HOME || path.join(ctx.home, ".config");
+  return path.join(configHome, "Claude", file);
+}

package/lib/rules.js

@@ -0,0 +1,80 @@
+/** Agent rules files: make the AI call MergeSafe after every coding session.
+ *
+ * MCP server instructions are honored unevenly across clients; project rules
+ * files are the reliable trigger. This module owns:
+ *   - .cursor/rules/mergesafe.mdc      (whole file, alwaysApply)
+ *   - AGENTS.md / CLAUDE.md            (one marked block, upserted in place)
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export const RULES_START = "<!-- mergesafe:start -->";
+export const RULES_END = "<!-- mergesafe:end -->";
+
+const RULE_TEXT = `After generating or modifying code in this project, run the MergeSafe MCP tool \`analyze_directory\` on the project root before you conclude, and report its verdict. If \`release_status\` is "blocked", fix the listed blockers (each finding ships a ready-to-use fix prompt) and re-run the check before declaring the work done.`;
+
+const CURSOR_RULE = `---
+description: MergeSafe post-generation check
+alwaysApply: true
+---
+
+${RULE_TEXT}
+`;
+
+const MARKDOWN_BLOCK = `${RULES_START}
+## MergeSafe check
+
+${RULE_TEXT}
+${RULES_END}`;
+
+/** Upsert the marked MergeSafe block into a markdown document (idempotent). */
+export function applyRulesBlock(existingText) {
+  const text = existingText ?? "";
+  const start = text.indexOf(RULES_START);
+  const end = text.indexOf(RULES_END);
+  if (start !== -1 && end !== -1 && end > start) {
+    return text.slice(0, start) + MARKDOWN_BLOCK + text.slice(end + RULES_END.length);
+  }
+  if (!text.trim()) return `${MARKDOWN_BLOCK}\n`;
+  return `${text.replace(/\n*$/, "")}\n\n${MARKDOWN_BLOCK}\n`;
+}
+
+async function readIfExists(filePath) {
+  try {
+    return await fs.readFile(filePath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+/**
+ * Write the rules files for a project.
+ *
+ * AGENTS.md is always upserted (created if missing — it is the cross-agent
+ * standard); CLAUDE.md is only updated when it already exists, so we never
+ * plant a client-specific file uninvited.
+ *
+ * @returns {Promise<string[]>} the paths written.
+ */
+export async function writeRulesFiles({ cwd }) {
+  const written = [];
+
+  const mdcPath = path.join(cwd, ".cursor", "rules", "mergesafe.mdc");
+  await fs.mkdir(path.dirname(mdcPath), { recursive: true });
+  await fs.writeFile(mdcPath, CURSOR_RULE, "utf8");
+  written.push(mdcPath);
+
+  const agentsPath = path.join(cwd, "AGENTS.md");
+  await fs.writeFile(agentsPath, applyRulesBlock(await readIfExists(agentsPath)), "utf8");
+  written.push(agentsPath);
+
+  const claudePath = path.join(cwd, "CLAUDE.md");
+  const claudeText = await readIfExists(claudePath);
+  if (claudeText !== null) {
+    await fs.writeFile(claudePath, applyRulesBlock(claudeText), "utf8");
+    written.push(claudePath);
+  }
+
+  return written;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mergesafe-io/connect",
-  "version": "0.1.0",
-  "description": "One-command MergeSafe MCP setup for Claude Desktop, Cursor, Windsurf, VS Code and opencode.",
+  "version": "0.3.0",
+  "description": "One command connects every AI client on your machine to MergeSafe MCP — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code and more, globally.",
   "keywords": ["mergesafe", "mcp", "model-context-protocol", "installer"],
   "homepage": "https://app.mergesafe.io",
   "license": "MIT",