@mergesafe-io/connect 0.3.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,13 +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) |
-| `--with-rules` | Also write agent rules files (`.cursor/rules/mergesafe.mdc`, `AGENTS.md` block) so the AI runs MergeSafe after coding |
+| `--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 |
@@ -64,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,22 +4,20 @@ import path from "node:path";
 
 import { SERVER_NAME } from "./clients.js";
 import { applyEntry, removeEntry } from "./config-file.js";
-import { writeRulesFiles } from "./rules.js";
+import { applyTomlEntry, removeTomlEntry } from "./toml-config.js";
 
-export async function handleInstall(client, key, configPath, dryRun, withRules, cwd) {
+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}`);
-    if (withRules) {
-      console.log("Would also write agent rules files (.cursor/rules/mergesafe.mdc, AGENTS.md).");
-    }
     return;
   }
 
@@ -29,10 +27,6 @@ export async function handleInstall(client, key, configPath, dryRun, withRules,
 
   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) {
@@ -57,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.`);
@@ -75,14 +70,6 @@ export async function handleUninstall(client, configPath, dryRun) {
   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()}`;

package/lib/cli.js

@@ -3,7 +3,7 @@ import os from "node:os";
 import readline from "node:readline/promises";
 import { parseArgs } from "node:util";
 
-import { handleInstall, handleUninstall, reportRules } from "./actions.js";
+import { handleInstall, handleUninstall } from "./actions.js";
 import { SERVER_NAME, getClient, listClientIds } from "./clients.js";
 import { detectClients } from "./detect.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,9 +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)
-  --with-rules     Also write agent rules files (.cursor/rules/mergesafe.mdc,
-                   AGENTS.md block) so the AI runs MergeSafe after coding
+                   (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
@@ -44,7 +43,6 @@ 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 },
@@ -77,7 +75,7 @@ export async function main(argv) {
     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);
+    await handleInstall(client, key, configPath, values["dry-run"]);
   }
 }
 
@@ -106,7 +104,7 @@ async function runAllDetected(values, ctx) {
       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);
+        await handleInstall(client, key, client.configPath(ctx), values["dry-run"]);
       }
     } catch (err) {
       failures.push(`${client.label}: ${err.message}`);
@@ -114,9 +112,6 @@ async function runAllDetected(values, ctx) {
     console.log("");
   }
 
-  if (values["with-rules"] && !values.uninstall && !values["dry-run"]) {
-    await reportRules(ctx.cwd);
-  }
   reportOutcome(detected.length, failures, values.uninstall);
 }
 

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.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.",
+  "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"
   }
 }

package/lib/rules.js

@@ -1,80 +0,0 @@
-/** 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;
-}