@concept-ai/workspace 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# Concept Workspace MCP Installer
+
+Install Concept Workspace MCP into terminal agents.
+
+## Codex
+
+Run:
+
+```bash
+npm exec --yes --package @concept-ai/workspace@latest -- concept-workspace-mcp install codex
+```
+
+The installer writes the Codex MCP server entry with the required OAuth scopes:
+
+```toml
+[mcp_servers.concept]
+url = "https://workspace-api.concept.dev/mcp"
+scopes = ["openid", "profile", "email", "offline_access"]
+```
+
+After the config is written, the installer offers to run:
+
+```bash
+codex mcp login concept
+```
+
+You should not need to pass `--scopes` to `codex mcp login`.
+
+## Claude Code
+
+Run:
+
+```bash
+npm exec --yes --package @concept-ai/workspace@latest -- concept-workspace-mcp install claude-code
+```
+
+The installer registers Concept Workspace with Claude Code. When the `claude`
+CLI is available, it delegates to:
+
+```bash
+claude mcp add --transport http --scope user concept https://workspace-api.concept.dev/mcp
+```
+
+If the `claude` CLI is not available, it falls back to writing Claude Code's
+user config with:
+
+```json
+{
+  "mcpServers": {
+    "concept": {
+      "type": "http",
+      "url": "https://workspace-api.concept.dev/mcp"
+    }
+  }
+}
+```
+
+Claude Code opens the OAuth sign-in flow the first time it uses a Workspace
+tool. The Claude Code config does not need a `scopes` field because Claude Code
+discovers scopes from Workspace MCP metadata.
+
+## Troubleshooting
+
+If an MCP client was already running before install, quit and restart it so it
+reloads the updated config. If Codex still reports an OAuth refresh error after
+a clean install, run:
+
+```bash
+codex mcp logout concept
+codex mcp login concept
+```
+
+## Local tarball validation
+
+Before publishing, validate the packed artifact through `npx` with temporary
+agent config directories:
+
+```bash
+tmp="$(mktemp -d)"
+npm pack --workspace @concept-ai/workspace --pack-destination "$tmp"
+
+CODEX_HOME="$tmp/codex" \
+  npx --yes --package "$tmp"/concept-ai-workspace-0.1.0.tgz \
+  concept-workspace-mcp install codex --no-login --yes
+CODEX_HOME="$tmp/codex" codex mcp get concept
+
+CODEX_HOME="$tmp/codex" \
+  npx --yes --package "$tmp"/concept-ai-workspace-0.1.0.tgz \
+  concept-workspace-mcp install codex --dry-run --no-login --yes
+
+CLAUDE_CONFIG_DIR="$tmp/claude" \
+  npx --yes --package "$tmp"/concept-ai-workspace-0.1.0.tgz \
+  concept-workspace-mcp install claude-code --no-cli --yes
+```
+
+Inspect `$tmp/codex/config.toml` for the Workspace MCP URL plus required
+Codex OAuth scopes. Inspect `$tmp/claude/.claude.json` for
+`mcpServers.concept.type = "http"`, the Workspace MCP URL, and no `scopes`
+field.
+
+If the `claude` CLI is installed, also validate CLI delegation:
+
+```bash
+CLAUDE_CONFIG_DIR="$tmp/claude-cli" \
+  npx --yes --package "$tmp"/concept-ai-workspace-0.1.0.tgz \
+  concept-workspace-mcp install claude-code --yes
+CLAUDE_CONFIG_DIR="$tmp/claude-cli" claude mcp get concept
+```
+
+## Publishing
+
+First-time publish for the renamed npm package:
+
+```bash
+npm run test --workspace @concept-ai/workspace
+npm pack --dry-run --workspace @concept-ai/workspace
+npm publish --workspace @concept-ai/workspace --access public
+```
+
+This package is the canonical npm installer for Concept Workspace.

package/bin/concept-workspace-mcp.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { main } from '../src/cli.mjs';
+
+try {
+  const exitCode = await main(process.argv.slice(2), {
+    stderr: process.stderr,
+    stdin: process.stdin,
+    stdout: process.stdout,
+  });
+  process.exitCode = exitCode;
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@concept-ai/workspace",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "concept-workspace-mcp": "bin/concept-workspace-mcp.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test/run-tests.mjs",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "smol-toml": "^1.3.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/claude-code-config.mjs

@@ -0,0 +1,130 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { DEFAULT_CODEX_MCP_SERVER_NAME, DEFAULT_WORKSPACE_MCP_URL } from './codex-config.mjs';
+
+export function resolveClaudeConfigPath({ claudeConfigDir } = {}) {
+  const root = claudeConfigDir || process.env.CLAUDE_CONFIG_DIR || os.homedir();
+  return path.join(root, '.claude.json');
+}
+
+export async function readClaudeConfig(configPath) {
+  try {
+    const metadata = await stat(configPath);
+    if (!metadata.isFile()) {
+      throw new Error(`Claude Code config path is not a regular file: ${configPath}`);
+    }
+    return await readFile(configPath, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return '';
+    }
+    throw error;
+  }
+}
+
+export function planClaudeCodeMcpInstall({
+  sourceText = '',
+  name = DEFAULT_CODEX_MCP_SERVER_NAME,
+  url = DEFAULT_WORKSPACE_MCP_URL,
+  force = false,
+} = {}) {
+  assertNonEmptyString(name, 'Claude Code MCP server name');
+  assertNonEmptyString(url, 'Claude Code MCP URL');
+
+  const parsed = parseJsonConfig(sourceText);
+  const mcpServers = parsed.mcpServers ?? {};
+  if (!isPlainObject(mcpServers)) {
+    throw new Error('Existing Claude Code config has invalid mcpServers value; expected an object.');
+  }
+
+  const existing = mcpServers[name];
+  if (existing !== undefined && !isPlainObject(existing)) {
+    throw new Error(`Existing Claude Code MCP server "${name}" is invalid; expected an object.`);
+  }
+
+  const existingUrl = typeof existing?.url === 'string' ? existing.url : null;
+  if (existingUrl && existingUrl !== url && !force) {
+    throw new Error(
+      `Claude Code MCP server "${name}" already exists and points at ${existingUrl}. Re-run with --force to replace it.`,
+    );
+  }
+
+  const nextConfig = {
+    ...parsed,
+    mcpServers: {
+      ...mcpServers,
+      [name]: {
+        type: 'http',
+        url,
+      },
+    },
+  };
+  const text = `${JSON.stringify(nextConfig, null, 2)}\n`;
+
+  return {
+    action: existing === undefined ? 'create' : (text === normalizeJsonText(parsed) ? 'unchanged' : 'update'),
+    changed: text !== sourceText,
+    entryExisted: existing !== undefined,
+    text,
+  };
+}
+
+export async function writeFileAtomic(configPath, text) {
+  await mkdir(path.dirname(configPath), { recursive: true });
+  try {
+    const metadata = await stat(configPath);
+    if (!metadata.isFile()) {
+      throw new Error(`Claude Code config path is not a regular file: ${configPath}`);
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+
+  const tempPath = path.join(
+    path.dirname(configPath),
+    `.${path.basename(configPath)}.${process.pid}.${randomUUID()}.tmp`,
+  );
+  try {
+    await writeFile(tempPath, text, { mode: 0o600 });
+    await rename(tempPath, configPath);
+  } catch (error) {
+    await rm(tempPath, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+function parseJsonConfig(sourceText) {
+  if (!sourceText.trim()) {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(sourceText);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to parse existing Claude Code config: ${detail}`);
+  }
+  if (!isPlainObject(parsed)) {
+    throw new Error('Existing Claude Code config must be a JSON object.');
+  }
+  return parsed;
+}
+
+function normalizeJsonText(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function assertNonEmptyString(value, label) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${label} must be a non-empty string.`);
+  }
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}

package/src/cli.mjs

@@ -0,0 +1,287 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+
+import {
+  DEFAULT_CODEX_MCP_SCOPES,
+  DEFAULT_CODEX_MCP_SERVER_NAME,
+  DEFAULT_WORKSPACE_MCP_URL,
+  planCodexMcpInstall,
+  readCodexConfig,
+  resolveCodexConfigPath,
+  writeFileAtomic as writeCodexFileAtomic,
+} from './codex-config.mjs';
+import {
+  planClaudeCodeMcpInstall,
+  readClaudeConfig,
+  resolveClaudeConfigPath,
+  writeFileAtomic as writeClaudeFileAtomic,
+} from './claude-code-config.mjs';
+
+const USAGE = `Usage:
+  concept-workspace-mcp install codex [options]
+  concept-workspace-mcp install claude-code [options]
+
+Shared options:
+  --name <name>        MCP server name. Default: concept
+  --url <url>          MCP URL. Default: https://workspace-api.concept.dev/mcp
+  --force              Replace an existing same-name server with a different URL.
+  --dry-run            Print planned changes without writing.
+  --yes                Do not prompt in interactive mode.
+  --help               Print usage.
+
+Codex options:
+  --codex-home <path>  Override Codex home.
+  --login              Run codex mcp login after config write.
+  --no-login           Only print the login command.
+
+Claude Code options:
+  --claude-config-dir <path>  Override Claude Code config dir.
+  --scope <scope>             claude mcp add scope. Default: user.
+  --no-cli                    Skip claude CLI delegation and write JSON directly.
+`;
+
+const SHARED_FLAGS = new Set(['force', 'dry-run', 'yes', 'help']);
+const SHARED_VALUES = new Set(['name', 'url']);
+const CODEX_FLAGS = new Set(['login', 'no-login']);
+const CODEX_VALUES = new Set(['codex-home']);
+const CLAUDE_FLAGS = new Set(['no-cli']);
+const CLAUDE_VALUES = new Set(['claude-config-dir', 'scope']);
+const CLAUDE_SCOPES = new Set(['user', 'local', 'project']);
+
+export async function main(argv, io = {}) {
+  const context = createContext(io);
+
+  try {
+    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+      context.stdout.write(USAGE);
+      return 0;
+    }
+
+    const [command, host, ...rawOptions] = argv;
+    if (command !== 'install' || !['codex', 'claude-code'].includes(host)) {
+      context.stderr.write(USAGE);
+      return 1;
+    }
+
+    const options = parseOptions(rawOptions, host);
+    if (options.help) {
+      context.stdout.write(USAGE);
+      return 0;
+    }
+
+    if (host === 'codex') {
+      return await installCodex(options, context);
+    }
+    return await installClaudeCode(options, context);
+  } catch (error) {
+    context.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+}
+
+async function installCodex(options, context) {
+  if (options.login && options.noLogin) {
+    throw new Error('Use either --login or --no-login, not both.');
+  }
+
+  const name = options.name ?? DEFAULT_CODEX_MCP_SERVER_NAME;
+  const url = options.url ?? DEFAULT_WORKSPACE_MCP_URL;
+  const configPath = resolveCodexConfigPath({ codexHome: options.codexHome });
+  const sourceText = await readCodexConfig(configPath);
+  const plan = planCodexMcpInstall({
+    force: options.force,
+    name,
+    scopes: DEFAULT_CODEX_MCP_SCOPES,
+    sourceText,
+    url,
+  });
+
+  if (options.dryRun) {
+    context.stdout.write(`Dry run: would ${plan.changed ? 'write' : 'leave unchanged'} Codex config at ${configPath}\n`);
+    return 0;
+  }
+
+  if (plan.changed) {
+    await writeCodexFileAtomic(configPath, plan.text);
+    context.stdout.write(`Installed Concept Workspace MCP for Codex at ${configPath}\n`);
+  } else {
+    context.stdout.write(`Codex MCP config already up to date at ${configPath}\n`);
+  }
+
+  const loginCommand = `codex mcp login ${name}`;
+  const shouldLogin = await shouldRunCodexLogin(options, context, name);
+  if (!shouldLogin) {
+    context.stdout.write(`Run this to sign in:\n${loginCommand}\n`);
+    return 0;
+  }
+
+  const result = await context.runCommand('codex', ['mcp', 'login', name], { stdio: 'inherit' });
+  if (isCommandNotFound(result)) {
+    context.stderr.write(`codex executable was not found. Run this after installing Codex:\n${loginCommand}\n`);
+    return 127;
+  }
+  if (result.code !== 0) {
+    context.stderr.write(`codex mcp login failed with exit code ${result.code ?? 1}.\n`);
+    return result.code ?? 1;
+  }
+  return 0;
+}
+
+async function shouldRunCodexLogin(options, context, name) {
+  if (options.noLogin) {
+    return false;
+  }
+  if (options.login || options.yes) {
+    return true;
+  }
+  if (!context.stdin?.isTTY) {
+    return false;
+  }
+
+  const answer = await context.prompt(`Run codex mcp login ${name} now? [Y/n] `);
+  return answer.trim() === '' || answer.trim().toLowerCase() === 'y';
+}
+
+async function installClaudeCode(options, context) {
+  const name = options.name ?? DEFAULT_CODEX_MCP_SERVER_NAME;
+  const url = options.url ?? DEFAULT_WORKSPACE_MCP_URL;
+  const scope = options.scope ?? 'user';
+  if (!CLAUDE_SCOPES.has(scope)) {
+    throw new Error(`Claude Code scope must be one of: ${[...CLAUDE_SCOPES].join(', ')}.`);
+  }
+
+  if (options.dryRun) {
+    context.stdout.write(`Dry run: would install Concept Workspace MCP for Claude Code as "${name}".\n`);
+    return 0;
+  }
+
+  if (!options.noCli) {
+    const args = ['mcp', 'add', '--transport', 'http', '--scope', scope, name, url];
+    const result = await context.runCommand('claude', args, { stdio: 'inherit' });
+    if (result.code === 0) {
+      context.stdout.write('Open Claude Code and use any Workspace tool; authorize in browser when prompted.\n');
+      return 0;
+    }
+
+    const reason = isCommandNotFound(result)
+      ? 'claude executable was not found'
+      : `claude mcp add failed with exit code ${result.code ?? 1}`;
+    context.stderr.write(`${reason}; falling back to direct JSON config write.\n`);
+
+    try {
+      await installClaudeCodeJsonFallback(options, context, { name, url });
+      context.stdout.write('Open Claude Code and use any Workspace tool; authorize in browser when prompted.\n');
+      return 0;
+    } catch (error) {
+      throw new Error(`${reason}; JSON fallback also failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  await installClaudeCodeJsonFallback(options, context, { name, url });
+  context.stdout.write('Open Claude Code and use any Workspace tool; authorize in browser when prompted.\n');
+  return 0;
+}
+
+async function installClaudeCodeJsonFallback(options, context, { name, url }) {
+  const configPath = resolveClaudeConfigPath({ claudeConfigDir: options.claudeConfigDir });
+  const sourceText = await readClaudeConfig(configPath);
+  const plan = planClaudeCodeMcpInstall({
+    force: options.force,
+    name,
+    sourceText,
+    url,
+  });
+
+  if (plan.changed) {
+    await writeClaudeFileAtomic(configPath, plan.text);
+    context.stdout.write(`Installed Concept Workspace MCP for Claude Code at ${configPath}\n`);
+  } else {
+    context.stdout.write(`Claude Code MCP config already up to date at ${configPath}\n`);
+  }
+}
+
+function parseOptions(rawOptions, host) {
+  const options = {};
+  const flags = new Set([...SHARED_FLAGS]);
+  const values = new Set([...SHARED_VALUES]);
+
+  if (host === 'codex') {
+    for (const flag of CODEX_FLAGS) flags.add(flag);
+    for (const value of CODEX_VALUES) values.add(value);
+  } else {
+    for (const flag of CLAUDE_FLAGS) flags.add(flag);
+    for (const value of CLAUDE_VALUES) values.add(value);
+  }
+
+  for (let index = 0; index < rawOptions.length; index += 1) {
+    const raw = rawOptions[index];
+    if (!raw.startsWith('--')) {
+      throw new Error(`Unexpected argument: ${raw}`);
+    }
+
+    const [namePart, inlineValue] = raw.slice(2).split(/=(.*)/s, 2);
+    const property = optionPropertyName(namePart);
+    if (flags.has(namePart)) {
+      if (inlineValue !== undefined) {
+        throw new Error(`Option --${namePart} does not take a value.`);
+      }
+      options[property] = true;
+      continue;
+    }
+
+    if (!values.has(namePart)) {
+      throw new Error(`Unknown option for ${host}: --${namePart}`);
+    }
+
+    const value = inlineValue ?? rawOptions[index + 1];
+    if (!value || value.startsWith('--')) {
+      throw new Error(`Option --${namePart} requires a value.`);
+    }
+    options[property] = value;
+    if (inlineValue === undefined) {
+      index += 1;
+    }
+  }
+
+  return options;
+}
+
+function optionPropertyName(name) {
+  return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+function createContext(io) {
+  const stdin = io.stdin ?? process.stdin;
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  return {
+    stdin,
+    stdout,
+    stderr,
+    prompt: io.prompt ?? defaultPrompt(stdin, stdout),
+    runCommand: io.runCommand ?? runCommand,
+  };
+}
+
+function defaultPrompt(stdin, stdout) {
+  return async (question) => {
+    const readline = createInterface({ input: stdin, output: stdout });
+    try {
+      return await readline.question(question);
+    } finally {
+      readline.close();
+    }
+  };
+}
+
+function runCommand(command, args, options) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, options);
+    child.on('error', (error) => resolve({ code: null, error }));
+    child.on('close', (code) => resolve({ code }));
+  });
+}
+
+function isCommandNotFound(result) {
+  return result.error?.code === 'ENOENT';
+}

package/src/codex-config.mjs

@@ -0,0 +1,260 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { parse } from 'smol-toml';
+
+export const DEFAULT_CODEX_MCP_SERVER_NAME = 'concept';
+export const DEFAULT_WORKSPACE_MCP_URL = 'https://workspace-api.concept.dev/mcp';
+export const DEFAULT_CODEX_MCP_SCOPES = ['openid', 'profile', 'email', 'offline_access'];
+
+const BARE_TOML_KEY_PATTERN = /^[A-Za-z0-9_-]+$/;
+const REQUIRED_KEYS = new Set(['url', 'scopes']);
+
+export function resolveCodexConfigPath({ codexHome } = {}) {
+  const root = codexHome || process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(root, 'config.toml');
+}
+
+export async function readCodexConfig(configPath) {
+  try {
+    const metadata = await stat(configPath);
+    if (!metadata.isFile()) {
+      throw new Error(`Codex config path is not a regular file: ${configPath}`);
+    }
+    return await readFile(configPath, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return '';
+    }
+    throw error;
+  }
+}
+
+export function planCodexMcpInstall({
+  sourceText = '',
+  name = DEFAULT_CODEX_MCP_SERVER_NAME,
+  url = DEFAULT_WORKSPACE_MCP_URL,
+  scopes = DEFAULT_CODEX_MCP_SCOPES,
+  force = false,
+} = {}) {
+  assertBareTomlKey(name, 'Codex MCP server name');
+  assertNonEmptyString(url, 'Codex MCP URL');
+  assertScopeList(scopes);
+
+  const parsed = parseToml(sourceText, 'existing Codex config');
+  const existingServer = readExistingServer(parsed, name);
+  const existingUrl = typeof existingServer?.url === 'string' ? existingServer.url : null;
+  const tableExists = Boolean(existingServer);
+  const urlConflicts = tableExists && existingUrl !== url;
+
+  if (urlConflicts && !force) {
+    const detail = existingUrl
+      ? `it points at ${existingUrl}`
+      : 'it does not have a URL';
+    throw new Error(
+      `Codex MCP server "${name}" already exists and ${detail}. Re-run with --force to replace it.`,
+    );
+  }
+
+  const preserveExistingKeys = tableExists && !urlConflicts;
+  const tableText = buildCodexServerTable({
+    existingServer: preserveExistingKeys ? existingServer : null,
+    name,
+    scopes,
+    url,
+  });
+  const block = findCodexServerTableBlock(sourceText, name);
+  const nextText = block
+    ? replaceBlock(sourceText, block, tableText)
+    : appendBlock(sourceText, tableText);
+
+  parseToml(nextText, 'generated Codex config');
+
+  return {
+    action: block ? (nextText === sourceText ? 'unchanged' : 'update') : 'create',
+    changed: nextText !== sourceText,
+    tableExisted: Boolean(block),
+    text: nextText,
+  };
+}
+
+export async function writeFileAtomic(configPath, text) {
+  await mkdir(path.dirname(configPath), { recursive: true });
+  try {
+    const metadata = await stat(configPath);
+    if (!metadata.isFile()) {
+      throw new Error(`Codex config path is not a regular file: ${configPath}`);
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+
+  const tempPath = path.join(
+    path.dirname(configPath),
+    `.${path.basename(configPath)}.${process.pid}.${randomUUID()}.tmp`,
+  );
+  try {
+    await writeFile(tempPath, text, { mode: 0o600 });
+    await rename(tempPath, configPath);
+  } catch (error) {
+    await rm(tempPath, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+function parseToml(sourceText, label) {
+  if (!sourceText.trim()) {
+    return {};
+  }
+  try {
+    return parse(sourceText);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to parse ${label}: ${detail}`);
+  }
+}
+
+function readExistingServer(parsed, name) {
+  const servers = parsed.mcp_servers;
+  if (servers === undefined) {
+    return null;
+  }
+  if (!isPlainObject(servers)) {
+    throw new Error('Existing Codex config has invalid mcp_servers value; expected a table.');
+  }
+  const server = servers[name];
+  if (server === undefined) {
+    return null;
+  }
+  if (!isPlainObject(server)) {
+    throw new Error(`Existing Codex MCP server "${name}" is invalid; expected a table.`);
+  }
+  return server;
+}
+
+function buildCodexServerTable({ existingServer, name, scopes, url }) {
+  const lines = [
+    `[mcp_servers.${name}]`,
+    `url = ${formatTomlValue(url)}`,
+    `scopes = ${formatTomlValue(scopes)}`,
+  ];
+
+  if (existingServer) {
+    for (const key of Object.keys(existingServer).filter((key) => !REQUIRED_KEYS.has(key)).sort()) {
+      assertBareTomlKey(key, `Codex MCP server "${name}" key`);
+      lines.push(`${key} = ${formatTomlValue(existingServer[key])}`);
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function findCodexServerTableBlock(sourceText, name) {
+  const lines = sourceText.match(/^.*(?:\n|$)/gm) ?? [];
+  const lineRecords = [];
+  const targetHeader = new RegExp(`^\\s*\\[\\s*mcp_servers\\s*\\.\\s*${escapeRegExp(name)}\\s*\\]\\s*(?:#.*)?$`);
+  const anyHeader = /^\s*\[[^\]]+\]\s*(?:#.*)?$/;
+  let offset = 0;
+  let start = -1;
+  let startIndex = -1;
+  let end = sourceText.length;
+
+  for (const [index, line] of lines.entries()) {
+    lineRecords.push({
+      line,
+      start: offset,
+    });
+    const lineWithoutNewline = line.replace(/\n$/, '');
+    if (start === -1) {
+      if (targetHeader.test(lineWithoutNewline)) {
+        start = offset;
+        startIndex = index;
+      }
+    } else if (anyHeader.test(lineWithoutNewline)) {
+      let endIndex = index;
+      while (endIndex > startIndex + 1 && isTableBoundaryTrivia(lineRecords[endIndex - 1].line)) {
+        endIndex -= 1;
+      }
+      end = lineRecords[endIndex].start;
+      break;
+    }
+    offset += line.length;
+  }
+
+  if (start === -1) {
+    return null;
+  }
+  return { end, start };
+}
+
+function isTableBoundaryTrivia(line) {
+  const trimmed = line.trim();
+  return trimmed === '' || trimmed.startsWith('#');
+}
+
+function replaceBlock(sourceText, block, replacement) {
+  return `${sourceText.slice(0, block.start)}${replacement}${sourceText.slice(block.end)}`;
+}
+
+function appendBlock(sourceText, block) {
+  if (!sourceText.trim()) {
+    return block;
+  }
+  let prefix = sourceText;
+  if (!prefix.endsWith('\n')) {
+    prefix += '\n';
+  }
+  if (!prefix.endsWith('\n\n')) {
+    prefix += '\n';
+  }
+  return `${prefix}${block}`;
+}
+
+function assertBareTomlKey(value, label) {
+  assertNonEmptyString(value, label);
+  if (!BARE_TOML_KEY_PATTERN.test(value)) {
+    throw new Error(`${label} must contain only letters, numbers, underscores, and hyphens.`);
+  }
+}
+
+function assertNonEmptyString(value, label) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${label} must be a non-empty string.`);
+  }
+}
+
+function assertScopeList(scopes) {
+  if (!Array.isArray(scopes) || scopes.length === 0) {
+    throw new Error('Codex MCP scopes must be a non-empty string array.');
+  }
+  for (const scope of scopes) {
+    assertNonEmptyString(scope, 'Codex MCP scope');
+  }
+}
+
+function formatTomlValue(value) {
+  if (typeof value === 'string') {
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'boolean') {
+    return value ? 'true' : 'false';
+  }
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(formatTomlValue).join(', ')}]`;
+  }
+  throw new Error(`Unsupported Codex MCP config value: ${JSON.stringify(value)}`);
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}