@mergesafe-io/connect 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @mergesafe-io/connect
+
+One command to connect your AI client to the [MergeSafe](https://app.mergesafe.io) MCP server — no JSON editing.
+
+```bash
+npx @mergesafe-io/connect claude-desktop --key msk_your_api_key
+```
+
+That's it. Restart the client and the `mergesafe` tools are available.
+
+## What it does
+
+- Finds the right MCP config file for your 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)
+
+No dependencies, no telemetry, Node 18+.
+
+## Supported clients
+
+| Client | 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) |
+| `windsurf` | `~/.codeium/windsurf/mcp_config.json` |
+| `vscode` | `./.vscode/mcp.json` (current project) |
+| `opencode` | `./opencode.json` (current project) |
+| `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) |
+
+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_…"`
+
+## 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 |
+| `--help` | Usage |
+
+## Development
+
+```bash
+npm test           # node --test, zero deps
+node bin/mergesafe-connect.js cursor --key msk_x --dry-run
+```
+
+## Publishing
+
+The `@mergesafe` npm scope must exist (create the org on npmjs.com), then:
+
+```bash
+npm publish --access public
+```

package/bin/mergesafe-connect.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../lib/cli.js";
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(`\n✖ ${err.message}`);
+  process.exit(1);
+});

package/lib/cli.js

@@ -0,0 +1,117 @@
+/** CLI flow: parse args, resolve client + key, back up, merge, write. */
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { parseArgs } from "node:util";
+
+import { SERVER_NAME, getClient, listClientIds } from "./clients.js";
+import { applyEntry } from "./config-file.js";
+
+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.
+
+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)
+  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
+  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
+
+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)
+  --dry-run        Print the target path and resulting file without writing
+  --help           Show this help
+`;
+
+export async function main(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      key: { type: "string" },
+      project: { type: "boolean", default: false },
+      "dry-run": { type: "boolean", default: false },
+      help: { type: "boolean", default: false },
+    },
+  });
+
+  if (values.help || positionals.length === 0) {
+    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(),
+    cwd: process.cwd(),
+    env: process.env,
+    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}`);
+    return;
+  }
+
+  if (existingText !== null) {
+    const backupPath = `${configPath}.bak-${timestamp()}`;
+    await fs.copyFile(configPath, backupPath);
+    console.log(`• Backed up existing config to ${backupPath}`);
+  }
+  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}`);
+}
+
+async function resolveKey(flagValue) {
+  let key = flagValue;
+  if (!key) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    key = (await rl.question("Paste your MergeSafe API key (msk_…): ")).trim();
+    rl.close();
+  }
+  if (!key) {
+    throw new Error("An API key is required. Create one on app.mergesafe.io/dashboard/settings.");
+  }
+  if (!key.startsWith("msk_")) {
+    console.error("⚠ Key does not start with msk_ — double-check it, continuing anyway.");
+  }
+  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

@@ -0,0 +1,152 @@
+/** Per-client knowledge: where the MCP config lives and what to write in it. */
+import path from "node:path";
+
+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.
+ */
+const CLIENTS = {
+  "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.
+    buildEntry: (key) => ({
+      command: "npx",
+      args: ["mcp-remote", MCP_SSE_URL, "--header", "Authorization:Bearer ${AUTH_TOKEN}"],
+      env: { AUTH_TOKEN: key },
+    }),
+    restartHint: "Fully quit and reopen Claude Desktop (needs Node.js 18+ for npx).",
+  },
+  cursor: {
+    label: "Cursor",
+    rootKey: "mcpServers",
+    configPath: (ctx) =>
+      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) }),
+    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) }),
+    restartHint: "Fully quit and reopen Windsurf.",
+  },
+  vscode: {
+    label: "VS Code (project)",
+    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.",
+  },
+  opencode: {
+    label: "opencode (project)",
+    rootKey: "mcp",
+    configPath: (ctx) => path.join(ctx.cwd, "opencode.json"),
+    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"),
+    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)",
+    rootKey: "mcpServers",
+    configPath: (ctx) => path.join(ctx.cwd, ".roo", "mcp.json"),
+    buildEntry: (key) => ({ type: "sse", url: MCP_SSE_URL, headers: bearer(key), disabled: false }),
+    restartHint: "Reload the VS Code window; project config overrides global settings.",
+  },
+  continue: {
+    label: "Continue (project)",
+    configPath: (ctx) => path.join(ctx.cwd, ".continue", "mcpServers", "mergesafe.yaml"),
+    // Continue uses one YAML file per MCP server — whole-file write, no merge.
+    buildFileContent: (key) =>
+      [
+        "name: Mergesafe MCP",
+        "version: 0.0.1",
+        "schema: v1",
+        "mcpServers:",
+        "  - name: mergesafe",
+        "    type: sse",
+        `    url: ${MCP_SSE_URL}`,
+        "    requestOptions:",
+        "      headers:",
+        `        Authorization: Bearer ${key}`,
+        "",
+      ].join("\n"),
+    restartHint: "Use Continue in agent mode, then check the mergesafe tools appear.",
+  },
+};
+
+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) {
+    throw new Error(`Unknown client "${id}". Supported: ${listClientIds().join(", ")}`);
+  }
+  return client;
+}
+
+export function listClientIds() {
+  return Object.keys(CLIENTS);
+}

package/lib/config-file.js

@@ -0,0 +1,35 @@
+/** Non-destructive JSON config merging: only our entry is touched. */
+
+/**
+ * Merge `entry` under `rootKey`.`serverName` into the JSON text of an MCP
+ * config file. Everything else in the file is preserved as parsed.
+ * Returns the new file text (2-space indent, trailing newline).
+ */
+export function applyEntry(text, rootKey, serverName, entry) {
+  const config = parseConfig(text);
+  const section = config[rootKey];
+  const existing =
+    section && typeof section === "object" && !Array.isArray(section) ? section : {};
+  config[rootKey] = { ...existing, [serverName]: entry };
+  return `${JSON.stringify(config, null, 2)}\n`;
+}
+
+function parseConfig(text) {
+  if (!text || !text.trim()) {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new Error(
+      `Existing config is not valid JSON (${err.message}). Nothing was changed — fix or move the file, then re-run.`,
+    );
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(
+      "Existing config's top level is not a JSON object. Nothing was changed — fix or move the file, then re-run.",
+    );
+  }
+  return parsed;
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@mergesafe-io/connect",
+  "version": "0.1.0",
+  "description": "One-command MergeSafe MCP setup for Claude Desktop, Cursor, Windsurf, VS Code and opencode.",
+  "keywords": ["mergesafe", "mcp", "model-context-protocol", "installer"],
+  "homepage": "https://app.mergesafe.io",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "mergesafe-connect": "bin/mergesafe-connect.js"
+  },
+  "files": ["bin", "lib", "README.md"],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}