@mergesafe-io/connect 0.4.0 → 0.5.0

package/README.md

@@ -2,14 +2,14 @@
 
 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.
+every project. No config editing.
 
 ```bash
 npx @mergesafe-io/connect --key msk_your_api_key
 ```
 
 That's it. The CLI detects which clients are installed (Claude Code, Claude
-Desktop, Cursor, Windsurf, VS Code, …), writes each one's **global** config,
+Desktop, Codex, 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.
 
@@ -28,9 +28,9 @@ That removes only the mergesafe entry — all other configs are preserved.
 - 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)
+- Refuses to touch a file it can't parse (broken JSON or TOML aborts with a clear message)
 
-No dependencies, no telemetry, Node 18+.
+No telemetry, Node 18.17+. Codex TOML updates use `@decimalturn/toml-patch` to preserve comments and unrelated settings.
 
 ## Supported clients
 
@@ -38,6 +38,7 @@ No dependencies, no telemetry, Node 18+.
 |---|---|
 | `claude-code` | `~/.claude.json` (user scope — every project and session) |
 | `claude-desktop` | `claude_desktop_config.json` (per-OS path) — bridges through `mcp-remote` |
+| `codex` | `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`; `--project` for `./.codex/config.toml`) |
 | `cursor` | `~/.cursor/mcp.json` (`--project` for `./.cursor/mcp.json`) |
 | `windsurf` | `~/.codeium/windsurf/mcp_config.json` |
 | `vscode` | user-profile `mcp.json` (`--project` for `./.vscode/mcp.json`) |
@@ -50,12 +51,47 @@ Not covered: Zed (its `settings.json` is JSONC with comments — a rewrite would
 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_…"`
 
+## Codex
+
+```bash
+npx @mergesafe-io/connect@latest codex --key msk_your_api_key
+```
+
+The [official Codex MCP documentation](https://developers.openai.com/codex/mcp/)
+specifies `~/.codex/config.toml` for the shared user configuration and
+`.codex/config.toml` for trusted projects. If `CODEX_HOME` is set, the user
+configuration is written to `$CODEX_HOME/config.toml`, following the
+[Codex configuration documentation](https://learn.chatgpt.com/docs/config-file/config-advanced).
+The CLI, desktop app, and IDE extension share this configuration.
+
+The installer adds a Streamable HTTP connection with your API key:
+
+```toml
+[mcp_servers.mergesafe]
+url = "https://mcp.mergesafe.io/mcp"
+http_headers = { Authorization = "Bearer msk_your_api_key" }
+```
+
+Existing Codex settings, comments, and other MCP servers are preserved.
+Restart Codex or reload the IDE extension, then check `/mcp`.
+To install only in a trusted project:
+
+```bash
+npx @mergesafe-io/connect@latest codex --project --key msk_your_api_key
+```
+
+To remove only MergeSafe from the Codex user configuration:
+
+```bash
+npx @mergesafe-io/connect@latest codex --uninstall
+```
+
 ## 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, vscode, roo-code, continue — needs an explicit client) |
+| `--project` | Write the project-local config instead of the global one (codex, cursor, vscode, roo-code, continue — needs an explicit client) |
 | `--dry-run` | Print the target paths and resulting files without writing |
 | `--uninstall` | Remove the `mergesafe` entry (no client = every detected client) |
 | `--help` | Usage |
@@ -63,7 +99,8 @@ destroy them; configure manually). Gemini CLI: use its built-in command:
 ## Development
 
 ```bash
-npm test           # node --test, zero deps
+npm ci
+npm test           # node --test
 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
 ```

package/lib/actions.js

@@ -4,15 +4,17 @@ import path from "node:path";
 
 import { SERVER_NAME } from "./clients.js";
 import { applyEntry, removeEntry } from "./config-file.js";
+import { applyTomlEntry, removeTomlEntry } from "./toml-config.js";
 
 export async function handleInstall(client, key, configPath, dryRun) {
   const existingText = await readIfExists(configPath);
 
+  const mergeEntry = client.configFormat === "toml" ? applyTomlEntry : applyEntry;
   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));
+    : // Merge only the mergesafe entry in the client’s config format
+      mergeEntry(existingText ?? "", client.rootKey, SERVER_NAME, client.buildEntry(key));
 
   if (dryRun) {
     console.log(`Would write ${configPath}:\n\n${newText}`);
@@ -49,7 +51,8 @@ export async function handleUninstall(client, configPath, dryRun) {
     throw new Error(`Client "${client.label}" does not support --uninstall`);
   }
 
-  const newText = removeEntry(existingText, client.rootKey, SERVER_NAME);
+  const deleteEntry = client.configFormat === "toml" ? removeTomlEntry : removeEntry;
+  const newText = deleteEntry(existingText, client.rootKey, SERVER_NAME);
 
   if (newText === null) {
     console.log(`⚠ No mergesafe entry found in ${configPath} — nothing to remove.`);

package/lib/cli.js

@@ -17,6 +17,7 @@ the "${SERVER_NAME}" entry is touched.
 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)
+  codex            Codex — ~/.codex/config.toml (or $CODEX_HOME/config.toml; --project for ./.codex/config.toml)
   cursor           Cursor — ~/.cursor/mcp.json (--project for ./.cursor/mcp.json)
   windsurf         Windsurf — ~/.codeium/windsurf/mcp_config.json
   vscode           VS Code — user-profile mcp.json (--project for ./.vscode/mcp.json)
@@ -29,7 +30,7 @@ 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, vscode, roo-code, continue — needs an explicit client)
+                   (codex, cursor, vscode, roo-code, continue — needs an explicit client)
   --dry-run        Print the target path and resulting file without writing
   --uninstall      Remove the mergesafe entry (no client = every detected client)
   --help           Show usage

package/lib/clients.js

@@ -1,7 +1,7 @@
 /** 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";
+import { claudeDesktopConfigPath, codexUserDir, vscodeUserDir } from "./paths.js";
 
 export const MCP_HTTP_URL = "https://mcp.mergesafe.io/mcp";
 // Legacy endpoint, kept for clients without solid Streamable HTTP support
@@ -47,6 +47,20 @@ const CLIENTS = {
     }),
     restartHint: "Fully quit and reopen Claude Desktop (needs Node.js 18+ for npx).",
   },
+  codex: {
+    label: "Codex",
+    configFormat: "toml",
+    rootKey: "mcp_servers",
+    // Official configuration: https://developers.openai.com/codex/mcp/
+    configPath: (ctx) =>
+      ctx.project
+        ? path.join(ctx.cwd, ".codex", "config.toml")
+        : path.join(codexUserDir(ctx), "config.toml"),
+    detectPaths: (ctx) => [codexUserDir(ctx)],
+    deleteKey: true,
+    buildEntry: (key) => ({ url: MCP_HTTP_URL, http_headers: bearer(key) }),
+    restartHint: "Restart Codex or reload the IDE extension, then check /mcp. Project configs require a trusted project.",
+  },
   cursor: {
     label: "Cursor",
     rootKey: "mcpServers",

package/lib/paths.js

@@ -27,3 +27,10 @@ export function claudeDesktopConfigPath(ctx) {
   const configHome = ctx.env.XDG_CONFIG_HOME || path.join(ctx.home, ".config");
   return path.join(configHome, "Claude", file);
 }
+
+/** Codex's shared user configuration directory (CLI, app, and IDE extension).
+ * https://learn.chatgpt.com/docs/config-file/config-advanced
+ */
+export function codexUserDir(ctx) {
+  return ctx.env.CODEX_HOME || path.join(ctx.home, ".codex");
+}

package/lib/toml-config.js

@@ -0,0 +1,91 @@
+/** Edit only one MCP entry, preserving other TOML settings and comments. */
+import { parse, patch, TomlDocument } from "@decimalturn/toml-patch";
+
+export function applyTomlEntry(text, rootKey, serverName, entry) {
+  const config = parseConfig(text);
+  const section = config[rootKey];
+  if (section !== undefined && !isTable(section)) {
+    throw new Error(`Existing config's ${rootKey} is not a TOML table. Nothing was changed.`);
+  }
+  config[rootKey] = { ...section, [serverName]: entry };
+  return patchConfig(text, config, rootKey, serverName, !section || !Object.hasOwn(section, serverName));
+}
+
+export function removeTomlEntry(text, rootKey, serverName) {
+  const config = parseConfig(text);
+  const section = config[rootKey];
+  if (!isTable(section) || !Object.hasOwn(section, serverName)) return null;
+
+  delete section[serverName];
+  if (Object.keys(section).length === 0) delete config[rootKey];
+  return patchConfig(text, config, rootKey, serverName);
+}
+
+function isTable(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date);
+}
+
+function parseConfig(text) {
+  try {
+    return parse(text);
+  } catch {
+    // Parser errors can contain source lines with API keys; do not print them.
+    throw new Error("Existing config is not valid TOML. Nothing was changed — fix or move the file, then re-run.");
+  }
+}
+
+function patchConfig(text, config, rootKey, serverName, newEntry = false) {
+  try {
+    const bom = text.startsWith("\uFEFF") ? "\uFEFF" : "";
+    if (bom) text = text.slice(1);
+    // toml-patch attaches comments before a header to the preceding table.
+    // Keep other tables' leading comments out of the entry being replaced.
+    const comments = tableAnchors(text).filter(({ keys, commentStart, start }) =>
+      !(keys[0] === rootKey && (keys[1] === serverName || !Object.hasOwn(config, rootKey))) &&
+      commentStart < start,
+    ).map((anchor) => ({ ...anchor, text: text.slice(anchor.commentStart, anchor.start) }));
+    for (const comment of comments.slice().reverse()) {
+      text = text.slice(0, comment.commentStart) + text.slice(comment.start);
+    }
+    let updated = patch(text, config, newEntry ? { inlineTableStart: 2 } : undefined);
+    const anchors = new Map(tableAnchors(updated).map((anchor) => [anchor.id, anchor.start]));
+    for (const comment of comments.slice().reverse()) {
+      const start = anchors.get(comment.id);
+      if (start === undefined) throw new Error("An unrelated table was removed");
+      updated = updated.slice(0, start) + comment.text + updated.slice(start);
+    }
+    parse(updated);
+    return bom + (updated.endsWith("\n") ? updated : `${updated}\n`);
+  } catch {
+    throw new Error("Could not update the TOML config. Nothing was changed — fix or move the file, then re-run.");
+  }
+}
+
+/** Locate real TOML headers and their standalone leading comments via the CST. */
+function tableAnchors(text) {
+  const nodes = new TomlDocument(text).cst;
+  const lines = [0];
+  for (let i = 0; i < text.length; i++) if (text[i] === "\n") lines.push(i + 1);
+  const occurrences = new Map();
+  const anchors = [];
+  for (let i = 0; i < nodes.length; i++) {
+    const table = nodes[i];
+    if (table.type !== "Table" && table.type !== "TableArray") continue;
+    const keys = table.key.item.value;
+    const key = JSON.stringify([table.type, keys]);
+    const occurrence = occurrences.get(key) ?? 0;
+    occurrences.set(key, occurrence + 1);
+    const start = lines[table.loc.start.line - 1];
+    const preceding = nodes[i - 1]?.items ?? nodes.slice(0, i);
+    let commentStart = start;
+    for (let j = preceding.length - 1; j >= 0; j--) {
+      const item = preceding[j];
+      if (item.type !== "Comment") break;
+      const lineStart = lines[item.loc.start.line - 1];
+      if (text.slice(lineStart, lineStart + item.loc.start.column).trim()) break;
+      commentStart = lineStart;
+    }
+    anchors.push({ id: `${key}:${occurrence}`, keys, start, commentStart });
+  }
+  return anchors;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mergesafe-io/connect",
-  "version": "0.4.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.",
+  "version": "0.5.0",
+  "description": "One command connects every AI client on your machine to MergeSafe MCP — Claude Code, Claude Desktop, Codex, Cursor, Windsurf, VS Code and more, globally.",
   "keywords": ["mergesafe", "mcp", "model-context-protocol", "installer"],
   "homepage": "https://app.mergesafe.io",
   "license": "MIT",
@@ -18,5 +18,8 @@
   },
   "scripts": {
     "test": "node --test"
+  },
+  "dependencies": {
+    "@decimalturn/toml-patch": "3.1.2"
   }
 }