bi-superpowers 1.0.0

package/bin/lib/mcp-config.js

@@ -0,0 +1,835 @@
+/**
+ * Multi-Agent MCP Configuration Writer
+ * =====================================
+ *
+ * Writes the bi-superpowers MCP config (2 servers: powerbi-modeling-mcp
+ * + microsoft-learn) into each supported agent's expected config location
+ * at the user level (home directory).
+ *
+ * Each agent has its own config format and path. This module normalizes
+ * the write operation across all 5 supported agents:
+ *
+ *   | Agent           | Path                                  | Format            |
+ *   |-----------------|---------------------------------------|-------------------|
+ *   | Claude Code     | ~/.claude.json                        | JSON mcpServers   |
+ *   | GitHub Copilot  | ~/.copilot/mcp-config.json            | JSON mcpServers   |
+ *   | Codex           | ~/.codex/config.toml                  | TOML mcp_servers  |
+ *   | Gemini CLI      | ~/.gemini/settings.json               | JSON mcpServers   |
+ *   | Kilo Code       | ~/.config/kilo/kilo.jsonc             | JSON mcp          |
+ *
+ * The launcher path for the Power BI Modeling MCP is resolved to an
+ * absolute path at install time so it works in agents that don't
+ * support Claude Code's `${CLAUDE_PLUGIN_ROOT}` variable.
+ *
+ * @module lib/mcp-config
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { MICROSOFT_LEARN_URL } = require('./microsoft-mcp');
+const MODELING_SERVER_NAME = 'powerbi-modeling-mcp';
+const LEARN_SERVER_NAME = 'microsoft-learn';
+// Tools that need an explicit Codex approval gate.
+// Most are semantic-model mutations. trace_operations is also gated because it
+// can capture query text/metadata and export full event details to a local file.
+const CODEX_POWERBI_APPROVAL_TOOLS = [
+  'calendar_operations',
+  'calculation_group_operations',
+  'column_operations',
+  'culture_operations',
+  'database_operations',
+  'function_operations',
+  'measure_operations',
+  'model_operations',
+  'named_expression_operations',
+  'object_translation_operations',
+  'partition_operations',
+  'perspective_operations',
+  'query_group_operations',
+  'relationship_operations',
+  'security_role_operations',
+  'table_operations',
+  'trace_operations',
+  'transaction_operations',
+  'user_hierarchy_operations',
+];
+// Tools deliberately left ungated in Codex after review. They support model
+// discovery, connection selection, and DAX validation/querying, but do not
+// mutate semantic-model metadata. If Microsoft adds new MCP tools, tests must
+// classify them as approval-gated or explicitly reviewed here.
+const CODEX_POWERBI_REVIEWED_UNGATED_TOOLS = ['connection_operations', 'dax_query_operations'];
+const CODEX_POWERBI_WRITE_TOOLS = CODEX_POWERBI_APPROVAL_TOOLS;
+
+/**
+ * Resolves the absolute path to the Power BI Modeling MCP launcher
+ * inside the installed npm package.
+ */
+function getLauncherAbsolutePath(packageDir) {
+  return path.join(packageDir, 'bin', 'mcp', 'powerbi-modeling-launcher.js');
+}
+
+/**
+ * Safely read a JSON file. Returns null if missing or unparseable.
+ *
+ * NOTE: this swallows parse errors. Do NOT use it before a write — a
+ * silent null on a corrupt user config means a spread merge ends up
+ * replacing the whole config with our 2 servers (data loss). Use
+ * `readJsonStrict` for write paths instead.
+ */
+function readJsonSafe(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Read a JSON file for write paths. Returns null only if the file is
+ * absent or empty. Throws an actionable error if the file exists with
+ * non-empty content but is not parseable — silently overwriting a
+ * user's corrupt config (especially `~/.claude.json`) destroys data.
+ *
+ * @throws {Error} if the file exists but is unreadable or unparseable
+ */
+function readJsonStrict(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `Could not read ${filePath}: ${err.message}. ` + 'Check file permissions and retry.'
+    );
+  }
+  if (raw.trim() === '') return null;
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Refusing to overwrite ${filePath}: file exists but is not valid JSON ` +
+        `(${err.message}). Inspect or move it manually before retrying. ` +
+        `If a previous-install backup exists at ${filePath}.bak, restore from there.`
+    );
+  }
+}
+
+/**
+ * Read a JSONC file for write paths. This accepts JSON with comments and
+ * trailing commas, which is how Kilo Code documents its config format.
+ * Returns null only if the file is absent or empty.
+ *
+ * @throws {Error} if the file exists but cannot be parsed as JSONC
+ */
+function readJsoncStrict(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `Could not read ${filePath}: ${err.message}. ` + 'Check file permissions and retry.'
+    );
+  }
+  if (raw.trim() === '') return null;
+
+  let stripped = '';
+  let inString = false;
+  let escaped = false;
+  let inLineComment = false;
+  let inBlockComment = false;
+
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    const next = raw[i + 1];
+
+    if (inLineComment) {
+      if (ch === '\n' || ch === '\r') {
+        inLineComment = false;
+        stripped += ch;
+      }
+      continue;
+    }
+
+    if (inBlockComment) {
+      if (ch === '*' && next === '/') {
+        inBlockComment = false;
+        i++;
+      }
+      continue;
+    }
+
+    if (inString) {
+      stripped += ch;
+      if (escaped) {
+        escaped = false;
+      } else if (ch === '\\') {
+        escaped = true;
+      } else if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (ch === '"') {
+      inString = true;
+      stripped += ch;
+      continue;
+    }
+
+    if (ch === '/' && next === '/') {
+      inLineComment = true;
+      i++;
+      continue;
+    }
+
+    if (ch === '/' && next === '*') {
+      inBlockComment = true;
+      i++;
+      continue;
+    }
+
+    if (ch === ',') {
+      let lookahead = i + 1;
+      while (lookahead < raw.length && /\s/.test(raw[lookahead])) {
+        lookahead++;
+      }
+      if (lookahead < raw.length && (raw[lookahead] === '}' || raw[lookahead] === ']')) {
+        continue;
+      }
+    }
+
+    stripped += ch;
+  }
+
+  try {
+    return JSON.parse(stripped);
+  } catch (err) {
+    throw new Error(
+      `Refusing to overwrite ${filePath}: file exists but is not valid JSONC ` +
+        `(${err.message}). Inspect or move it manually before retrying. ` +
+        `If a previous-install backup exists at ${filePath}.bak, restore from there.`
+    );
+  }
+}
+
+function describeJsonShape(value) {
+  if (value === null) {
+    return 'null';
+  }
+  if (Array.isArray(value)) {
+    return 'array';
+  }
+  return typeof value;
+}
+
+function isObjectRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function assertObjectRecord(value, description, configPath) {
+  if (isObjectRecord(value)) {
+    return;
+  }
+
+  throw new Error(
+    `Refusing to write MCP config: ${configPath} contains non-object JSON at ${description} ` +
+      `(${describeJsonShape(value)}). Fix or remove that value, then re-run.`
+  );
+}
+
+function hasNonEmptyFileContent(filePath) {
+  return fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf8').trim() !== '';
+}
+
+/**
+ * Reject symlink attacks before writing to a file. We use lstatSync so
+ * we detect the link itself (not what it points to). If a user home has
+ * `~/.claude.json` pointing to `/etc/passwd`, we refuse to write.
+ * @throws {Error} if filePath exists and is a symbolic link
+ */
+function assertNotSymlink(filePath) {
+  if (!fs.existsSync(filePath)) return;
+  if (fs.lstatSync(filePath).isSymbolicLink()) {
+    throw new Error(
+      `Refusing to write MCP config: ${filePath} is a symbolic link. ` +
+        'Remove the symlink and re-run the install.'
+    );
+  }
+}
+
+function normalizeResolvedPath(value) {
+  let resolved = path.resolve(value);
+  if (process.platform === 'win32') {
+    if (resolved.startsWith('\\\\?\\UNC\\')) {
+      resolved = `\\\\${resolved.slice('\\\\?\\UNC\\'.length)}`;
+    } else if (resolved.startsWith('\\\\?\\')) {
+      resolved = resolved.slice('\\\\?\\'.length);
+    }
+    return resolved.toLowerCase();
+  }
+  return resolved;
+}
+
+function resolvesElsewhere(value) {
+  const realpathSync = fs.realpathSync.native || fs.realpathSync;
+  const parent = path.dirname(value);
+  if (parent === value) return false;
+
+  const expectedFromParent = path.join(realpathSync(parent), path.basename(value));
+  return normalizeResolvedPath(realpathSync(value)) !== normalizeResolvedPath(expectedFromParent);
+}
+
+/**
+ * Walk the ancestors of `filePath` up to (but not including) the user's
+ * home directory and reject if any ancestor is a symbolic link or path
+ * redirection. Needed because `assertNotSymlink` only checks the leaf —
+ * a symlink at a parent (e.g. `~/.copilot` → `/tmp/attacker/`) would
+ * still redirect every `.tmp` / `.bak` / final rename through the link,
+ * bypassing the leaf-only hardening.
+ *
+ * Trust boundaries:
+ * - We stop walking at `os.homedir()` itself. If the user's home is a
+ *   symlink, that's their machine setup, not something we can police.
+ * - We also stop if, after `realpathSync`, the ancestor resolves
+ *   outside the home subtree — defensive, covers the case where an
+ *   earlier ancestor already redirected us elsewhere.
+ * - We stop at filesystem root (`path.dirname(x) === x`).
+ *
+ * On Windows, junctions and other reparse-point redirections are also
+ * rejected by comparing the ancestor's resolved path with its real path.
+ *
+ * @throws {Error} if any ancestor of filePath (up to home) is a symlink or redirect
+ */
+function assertNoSymlinkedAncestor(filePath) {
+  const home = os.homedir();
+  const realpathSync = fs.realpathSync.native || fs.realpathSync;
+  const homeResolved = fs.existsSync(home) ? realpathSync(home) : home;
+  const normalizedHomeResolved = normalizeResolvedPath(homeResolved);
+
+  let current = path.dirname(filePath);
+  const visited = new Set();
+
+  while (current && !visited.has(current)) {
+    visited.add(current);
+
+    // Stop at the user's home — trust boundary.
+    if (current === home || current === homeResolved) return;
+    if (
+      fs.existsSync(current) &&
+      normalizeResolvedPath(realpathSync(current)) === normalizedHomeResolved
+    ) {
+      return;
+    }
+
+    if (fs.existsSync(current)) {
+      if (fs.lstatSync(current).isSymbolicLink()) {
+        throw new Error(
+          `Refusing to write MCP config: parent directory ${current} is a symbolic link. ` +
+            'Remove the symlink (or redirect super install at a different path) and retry.'
+        );
+      }
+
+      if (resolvesElsewhere(current)) {
+        throw new Error(
+          `Refusing to write MCP config: parent directory ${current} is redirected. ` +
+            'Remove the symlink, junction, or reparse-point ancestor and retry.'
+        );
+      }
+
+      // Defensive: if realpath has already pulled us outside the home
+      // subtree, stop walking — we're in territory we can't reason about.
+      // Compare with a trailing separator so a sibling like
+      // `C:\Users\bob-evil` is not treated as inside `C:\Users\bob`.
+      const normalizedCurrentResolved = normalizeResolvedPath(realpathSync(current));
+      if (
+        normalizedCurrentResolved !== normalizedHomeResolved &&
+        !normalizedCurrentResolved.startsWith(normalizedHomeResolved + path.sep)
+      ) {
+        return;
+      }
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) return; // filesystem root
+    current = parent;
+  }
+}
+
+/**
+ * Full pre-write safety check: leaf must not be a symlink, and no
+ * ancestor up to `os.homedir()` may be a symlink either. Use this
+ * instead of `assertNotSymlink` on every write path inside the user
+ * home directory.
+ */
+function assertPathSafeForWrite(filePath) {
+  assertNotSymlink(filePath);
+  assertNoSymlinkedAncestor(filePath);
+}
+
+/**
+ * Write any text content to a file using a safe pattern:
+ *
+ *   1. Refuse if the target is a symbolic link (assertNotSymlink).
+ *   2. If the target exists, copy it to `<target>.bak` first. This
+ *      gives the user a one-slot recovery file overwritten on each
+ *      install — enough to recover from a bad merge without
+ *      accumulating stale backups across many install runs.
+ *   3. Write to `<target>.tmp` then atomically rename to the final
+ *      path. `fs.renameSync` is atomic on POSIX and functionally
+ *      atomic for same-volume renames on NTFS, which is the only
+ *      shape we hit when writing into the user home (~/...).
+ *   4. On any error mid-process, best-effort cleanup of the .tmp
+ *      file so we never leave half-written turds behind.
+ *
+ * The atomic + backup pattern matters most for `~/.claude.json` —
+ * Claude Code's primary user config holds project pointers, OAuth
+ * state, conversation history. A crash mid-write or a bad merge
+ * would brick the user's Claude install otherwise.
+ */
+function writeFileAtomic(filePath, content) {
+  assertPathSafeForWrite(filePath);
+  const tmpPath = `${filePath}.tmp`;
+  const backupPath = `${filePath}.bak`;
+  assertPathSafeForWrite(tmpPath);
+  assertPathSafeForWrite(backupPath);
+
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  if (fs.existsSync(filePath)) {
+    try {
+      fs.copyFileSync(filePath, backupPath);
+    } catch (err) {
+      throw new Error(
+        `Could not back up ${filePath} before writing: ${err.message}. ` +
+          'Aborting to avoid losing the existing file.'
+      );
+    }
+  }
+
+  try {
+    fs.writeFileSync(tmpPath, content);
+    fs.renameSync(tmpPath, filePath);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch (_) {
+      // Best-effort cleanup; ignore if there is nothing to remove.
+    }
+    throw err;
+  }
+}
+
+/**
+ * Write a JSON file using the atomic + backup pattern.
+ * Refuses to overwrite symbolic links for safety.
+ */
+function writeJson(filePath, data) {
+  writeFileAtomic(filePath, JSON.stringify(data, null, 2) + '\n');
+}
+
+/**
+ * Escape a string for use inside TOML double-quoted strings.
+ * Covers backslash, quote, and the control characters that TOML spec
+ * requires escaping in basic strings: \b \t \n \f \r
+ *
+ * Note: `\b` in a JS regex is word-boundary, NOT backspace (0x08).
+ * We use \x08 explicitly to match the backspace character itself.
+ */
+function tomlEscape(str) {
+  return (
+    String(str)
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"')
+      // eslint-disable-next-line no-control-regex
+      .replace(/\x08/g, '\\b')
+      .replace(/\t/g, '\\t')
+      .replace(/\n/g, '\\n')
+      .replace(/\f/g, '\\f')
+      .replace(/\r/g, '\\r')
+  );
+}
+
+/**
+ * Escape a string for safe use inside a regex pattern (as a literal).
+ */
+function escapeRegex(str) {
+  return String(str).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// ============================================
+// JSON AGENT CONFIGURATIONS
+// ============================================
+// The 4 JSON-based agents (Claude Code, GitHub Copilot, Gemini CLI,
+// Kilo Code) all follow the same pattern: read existing JSON, merge
+// our 2 servers into a wrapper key, write back. Each agent differs
+// only in:
+//  - The config file path
+//  - The wrapper key (`mcpServers` vs `mcp`)
+//  - Whether the stdio/local entry needs an explicit `type` field
+//  - The HTTP/remote URL field name (`url` vs `httpUrl`)
+//  - Whether the agent wants the local launcher as `command` + `args`
+//    or a single `command` array
+//
+// We describe each agent in a single table and build the writer functions
+// from it so adding a new JSON agent is a one-line change.
+//
+// IMPORTANT: every entry below has a source URL pointing at the official
+// docs where the path/format comes from. If you change any of these,
+// verify the new value against the linked source first. Silent drift is
+// the hardest class of bug in this file because the writes succeed even
+// when the agent never reads the file.
+
+const JSON_AGENT_CONFIGS = {
+  'claude-code': {
+    // Source: https://code.claude.com/docs/en/mcp
+    // "User-scoped servers are stored in ~/.claude.json"
+    // Note: ~/.claude/settings.json does NOT work for MCPs (known docs bug).
+    // stdio entries omit `type` here; HTTP entries include it.
+    configPath: () => path.join(os.homedir(), '.claude.json'),
+    wrapperKey: 'mcpServers',
+    readConfig: readJsonStrict,
+    buildServers: (packageDir) => ({
+      [MODELING_SERVER_NAME]: {
+        command: 'node',
+        args: [getLauncherAbsolutePath(packageDir)],
+      },
+      [LEARN_SERVER_NAME]: {
+        type: 'http',
+        url: MICROSOFT_LEARN_URL,
+      },
+    }),
+  },
+  'github-copilot': {
+    // Source: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers
+    // "MCP servers are saved to ~/.copilot/mcp-config.json"
+    // Copilot uses `mcpServers` and local servers declare `type = local`.
+    configPath: () => path.join(os.homedir(), '.copilot', 'mcp-config.json'),
+    wrapperKey: 'mcpServers',
+    readConfig: readJsonStrict,
+    buildServers: (packageDir) => ({
+      [MODELING_SERVER_NAME]: {
+        type: 'local',
+        command: 'node',
+        args: [getLauncherAbsolutePath(packageDir)],
+      },
+      [LEARN_SERVER_NAME]: {
+        type: 'http',
+        url: MICROSOFT_LEARN_URL,
+      },
+    }),
+  },
+  'gemini-cli': {
+    // Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
+    // "MCP config goes in ~/.gemini/settings.json under mcpServers"
+    // Gemini uses `httpUrl` (NOT `url`) for HTTP transports and omits
+    // `type` — it's inferred from which key is present.
+    configPath: () => path.join(os.homedir(), '.gemini', 'settings.json'),
+    wrapperKey: 'mcpServers',
+    readConfig: readJsonStrict,
+    buildServers: (packageDir) => ({
+      [MODELING_SERVER_NAME]: {
+        command: 'node',
+        args: [getLauncherAbsolutePath(packageDir)],
+      },
+      [LEARN_SERVER_NAME]: {
+        httpUrl: MICROSOFT_LEARN_URL,
+      },
+    }),
+  },
+  kilo: {
+    // Source: https://kilo.ai/docs/automate/mcp/using-in-kilo-code
+    // Kilo Code stores global MCP settings in ~/.config/kilo/kilo.jsonc
+    // under the `mcp` key. Local servers use `type = local` and `command`
+    // as an array; remote servers use `type = remote`.
+    configPath: () => path.join(os.homedir(), '.config', 'kilo', 'kilo.jsonc'),
+    wrapperKey: 'mcp',
+    readConfig: readJsoncStrict,
+    buildServers: (packageDir) => ({
+      [MODELING_SERVER_NAME]: {
+        type: 'local',
+        command: ['node', getLauncherAbsolutePath(packageDir)],
+        enabled: true,
+        timeout: 10000,
+      },
+      [LEARN_SERVER_NAME]: {
+        type: 'remote',
+        url: MICROSOFT_LEARN_URL,
+        enabled: true,
+        timeout: 15000,
+      },
+    }),
+  },
+};
+
+/**
+ * Create a writer function for a JSON-format agent.
+ * The returned function reads the existing config (if any), merges in
+ * our 2 servers, and writes back, preserving all other fields.
+ */
+function makeJsonWriter(agentId) {
+  const agentConfig = JSON_AGENT_CONFIGS[agentId];
+  return function jsonWriter(packageDir) {
+    const configPath = agentConfig.configPath();
+    // Use strict reader on the write path: a silent parse failure here
+    // would discard the user's other config keys (history, OAuth, etc.)
+    // when the empty {} fallback is spread into the new write.
+    const parsedConfig = agentConfig.readConfig(configPath);
+    const existing =
+      parsedConfig === null && !hasNonEmptyFileContent(configPath) ? {} : parsedConfig;
+    // A real agent config is always a JSON object. If the file parses to an array
+    // or a primitive, spreading it ({ ...existing }) would silently corrupt or
+    // erase the user's config — refuse instead.
+    assertObjectRecord(existing, 'the document root', configPath);
+    const wrapperKey = agentConfig.wrapperKey;
+    const existingServers = Object.prototype.hasOwnProperty.call(existing, wrapperKey)
+      ? existing[wrapperKey]
+      : {};
+    assertObjectRecord(existingServers, wrapperKey, configPath);
+
+    const newServers = agentConfig.buildServers(packageDir);
+    const mergedServers = { ...existingServers, ...newServers };
+
+    writeJson(configPath, { ...existing, [wrapperKey]: mergedServers });
+    return configPath;
+  };
+}
+
+// ============================================
+// CODEX (OpenAI) — TOML format
+// ============================================
+// Source: https://developers.openai.com/codex/mcp
+// Also: https://github.com/openai/codex/blob/main/docs/config.md
+// "Codex CLI reads MCP server config from ~/.codex/config.toml, where
+//  each server gets its own section with format [mcp_servers.my-server]"
+//
+// Writes ~/.codex/config.toml, appending [mcp_servers.*] sections.
+// Preserves existing content by removing only our own sections before
+// appending the fresh ones.
+function writeCodexConfig(packageDir) {
+  const configPath = path.join(os.homedir(), '.codex', 'config.toml');
+  assertPathSafeForWrite(configPath);
+  const launcher = getLauncherAbsolutePath(packageDir);
+
+  let existing = '';
+  if (fs.existsSync(configPath)) {
+    existing = fs.readFileSync(configPath, 'utf8');
+  }
+
+  // Remove any previous bi-superpowers MCP sections so re-running install
+  // doesn't duplicate them. Strips each section from its header to the
+  // next [ header or EOF. Server names are escaped for regex safety even
+  // though current values are literal. The optional suffix removes child
+  // sections like [mcp_servers.powerbi-modeling-mcp.tools.measure_operations].
+  const namePattern = [MODELING_SERVER_NAME, LEARN_SERVER_NAME].map(escapeRegex).join('|');
+  const stripPattern = new RegExp(
+    `\\n?\\[mcp_servers\\.(${namePattern})(?:\\.[^\\]]+)?\\][\\s\\S]*?(?=\\n\\[|$)`,
+    'g'
+  );
+  existing = existing.replace(stripPattern, '');
+
+  const writeToolApprovals = CODEX_POWERBI_APPROVAL_TOOLS.map(
+    (toolName) =>
+      `\n[mcp_servers.${MODELING_SERVER_NAME}.tools.${toolName}]\n` + 'approval_mode = "approve"\n'
+  ).join('');
+
+  const newSections =
+    `\n\n[mcp_servers.${MODELING_SERVER_NAME}]\n` +
+    'command = "node"\n' +
+    `args = ["${tomlEscape(launcher)}"]\n` +
+    writeToolApprovals +
+    `\n[mcp_servers.${LEARN_SERVER_NAME}]\n` +
+    `url = "${MICROSOFT_LEARN_URL}"\n`;
+
+  const content = existing.trimEnd() + newSections;
+
+  // Use the same atomic + backup pattern as the JSON writers — a crash
+  // mid-write to ~/.codex/config.toml would brick the user's Codex install.
+  writeFileAtomic(configPath, content);
+  return configPath;
+}
+
+/**
+ * Registry mapping agent IDs to their MCP config writers.
+ * JSON agents are generated from JSON_AGENT_CONFIGS via makeJsonWriter;
+ * Codex is the only TOML-based agent and has its own writer.
+ */
+const MCP_WRITERS = {
+  'claude-code': makeJsonWriter('claude-code'),
+  'github-copilot': makeJsonWriter('github-copilot'),
+  codex: writeCodexConfig,
+  'gemini-cli': makeJsonWriter('gemini-cli'),
+  kilo: makeJsonWriter('kilo'),
+};
+
+/**
+ * Write MCP config for a specific agent.
+ * @param {string} agentId - One of the supported agent IDs
+ * @param {string} packageDir - Absolute path to the installed package
+ * @returns {string|null} The config path written, or null if unknown agent
+ * @throws {Error} If the write fails
+ */
+function writeMcpConfigForAgent(agentId, packageDir) {
+  const writer = MCP_WRITERS[agentId];
+  if (!writer) {
+    return null;
+  }
+  return writer(packageDir);
+}
+
+// ============================================
+// MCP REMOVAL (uninstall)
+// ============================================
+// The removers are the exact inverse of the writers: they delete ONLY our
+// 2 servers (powerbi-modeling-mcp + microsoft-learn, plus Codex's modeling
+// tool-approval subsections) and leave every other server and top-level
+// key untouched. Same safety guarantees as the writers — strict parsing so
+// a corrupt config is refused rather than clobbered, atomic + backup write.
+
+/**
+ * Create a remover function for a JSON-format agent. Reads the existing
+ * config, deletes only our 2 servers from the wrapper key, and writes the
+ * rest back unchanged. Never removes the user's other servers or keys. If
+ * removing our servers empties the wrapper key, the empty `{}` is left in
+ * place rather than restructuring the user's document.
+ *
+ * @param {string} agentId
+ * @returns {function(): { configPath: string, existed: boolean, removed: string[] }}
+ */
+function makeJsonRemover(agentId) {
+  const agentConfig = JSON_AGENT_CONFIGS[agentId];
+  return function jsonRemover() {
+    const configPath = agentConfig.configPath();
+    if (!fs.existsSync(configPath)) {
+      return { configPath, existed: false, removed: [] };
+    }
+    // Strict reader on the write path: refuse to touch a corrupt config
+    // rather than risk discarding the user's other keys.
+    const existing = agentConfig.readConfig(configPath);
+    if (!isObjectRecord(existing)) {
+      return { configPath, existed: true, removed: [] };
+    }
+    const wrapperKey = agentConfig.wrapperKey;
+    const servers = existing[wrapperKey];
+    if (!isObjectRecord(servers)) {
+      return { configPath, existed: true, removed: [] };
+    }
+
+    const removed = [];
+    for (const name of [MODELING_SERVER_NAME, LEARN_SERVER_NAME]) {
+      if (Object.prototype.hasOwnProperty.call(servers, name)) {
+        delete servers[name];
+        removed.push(name);
+      }
+    }
+    if (removed.length === 0) {
+      return { configPath, existed: true, removed: [] };
+    }
+
+    writeJson(configPath, existing);
+    return { configPath, existed: true, removed };
+  };
+}
+
+/**
+ * Remove our 2 MCP sections (and the modeling tool-approval subsections)
+ * from the Codex TOML config, preserving every other section. Reuses the
+ * same strip pattern writeCodexConfig uses before re-appending, so the
+ * two stay in lockstep.
+ *
+ * @returns {{ configPath: string, existed: boolean, removed: string[] }}
+ */
+function removeCodexConfig() {
+  const configPath = path.join(os.homedir(), '.codex', 'config.toml');
+  if (!fs.existsSync(configPath)) {
+    return { configPath, existed: false, removed: [] };
+  }
+  assertPathSafeForWrite(configPath);
+  const before = fs.readFileSync(configPath, 'utf8');
+
+  const namePattern = [MODELING_SERVER_NAME, LEARN_SERVER_NAME].map(escapeRegex).join('|');
+  const stripPattern = new RegExp(
+    `\\n?\\[mcp_servers\\.(${namePattern})(?:\\.[^\\]]+)?\\][\\s\\S]*?(?=\\n\\[|$)`,
+    'g'
+  );
+  const after = before.replace(stripPattern, '');
+  if (after === before) {
+    return { configPath, existed: true, removed: [] };
+  }
+
+  const removed = [];
+  if (before.includes(`[mcp_servers.${MODELING_SERVER_NAME}]`)) {
+    removed.push(MODELING_SERVER_NAME);
+  }
+  if (before.includes(`[mcp_servers.${LEARN_SERVER_NAME}]`)) {
+    removed.push(LEARN_SERVER_NAME);
+  }
+
+  // If only whitespace remains, write a truly empty file; otherwise
+  // normalize to a single trailing newline.
+  const trimmed = after.trim();
+  writeFileAtomic(configPath, trimmed === '' ? '' : `${after.trimEnd()}\n`);
+  return { configPath, existed: true, removed };
+}
+
+/**
+ * Registry mapping agent IDs to their MCP config removers. Mirrors
+ * MCP_WRITERS so install and uninstall cover exactly the same agents.
+ */
+const MCP_REMOVERS = {
+  'claude-code': makeJsonRemover('claude-code'),
+  'github-copilot': makeJsonRemover('github-copilot'),
+  codex: removeCodexConfig,
+  'gemini-cli': makeJsonRemover('gemini-cli'),
+  kilo: makeJsonRemover('kilo'),
+};
+
+/**
+ * Remove our MCP config for a specific agent.
+ * @param {string} agentId - One of the supported agent IDs
+ * @returns {{ configPath: string, existed: boolean, removed: string[] }|null}
+ *   Removal result, or null if the agent ID is unknown.
+ * @throws {Error} If the rewrite fails
+ */
+function removeMcpConfigForAgent(agentId) {
+  const remover = MCP_REMOVERS[agentId];
+  if (!remover) {
+    return null;
+  }
+  return remover();
+}
+
+module.exports = {
+  writeMcpConfigForAgent,
+  removeMcpConfigForAgent,
+  MCP_WRITERS,
+  MCP_REMOVERS,
+  MODELING_SERVER_NAME,
+  LEARN_SERVER_NAME,
+  MICROSOFT_LEARN_URL,
+  CODEX_POWERBI_APPROVAL_TOOLS,
+  CODEX_POWERBI_REVIEWED_UNGATED_TOOLS,
+  CODEX_POWERBI_WRITE_TOOLS,
+  // Exported for testing
+  readJsonSafe,
+  readJsonStrict,
+  readJsoncStrict,
+  describeJsonShape,
+  isObjectRecord,
+  assertObjectRecord,
+  hasNonEmptyFileContent,
+  writeJson,
+  writeFileAtomic,
+  tomlEscape,
+  escapeRegex,
+  assertNotSymlink,
+  assertNoSymlinkedAncestor,
+  assertPathSafeForWrite,
+  getLauncherAbsolutePath,
+};