The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs(codex): clarify explicit MCP pin refresh and verify shared recommendation
affaan-m1c41fa7c0077
diff --git a/README.md b/README.mdindex 117552c2b..a49497089 100644--- a/README.md+++ b/README.md@@ -1515,9 +1515,14 @@ npm install && bash scripts/sync-ecc-to-codex.shcp .codex/config.toml ~/.codex/config.toml```-The sync script safely merges ECC MCP servers into your existing `~/.codex/config.toml` using an **add-only** strategy: it never removes or modifies your existing servers. Run with `--dry-run` to preview changes, or `--update-mcp` to force-refresh ECC servers to the latest recommended config.+Normal MCP sync preserves existing server settings and warns when they differ from ECC's recommendation. An existing `chrome-devtools-mcp@latest` entry therefore stays unchanged; updating the repository alone does not adopt the recommended `[email protected]` pin. Existing legacy-sync users can preview and explicitly apply the refresh from the updated ECC checkout:-For Context7, ECC uses the canonical Codex section name `[mcp_servers.context7]` while still launching the `@upstash/context7-mcp` package. If you already have a legacy `[mcp_servers.context7-mcp]` entry, `--update-mcp` migrates it to the canonical section name.+```bash+bash scripts/sync-ecc-to-codex.sh --dry-run --update-mcp+bash scripts/sync-ecc-to-codex.sh --update-mcp+```++Review the preview before applying: `--update-mcp` replaces the entire recommended `chrome-devtools` server section, including custom command arguments and nested settings. Unrelated user-managed servers remain in place. Retired defaults such as Context7 are not refreshed or migrated by this flag.Codex macOS app:- Open this repository as your workspace.@@ -1533,7 +1538,7 @@ Codex macOS app:| Config | 1 | `.codex/config.toml`: top-level approvals/sandbox/web_search, MCP servers, notifications, profiles || AGENTS.md | 2 | Root (universal) + `.codex/AGENTS.md` (Codex-specific supplement) || Skills | 32 | `.agents/skills/`: SKILL.md + agents/openai.yaml per skill |-| MCP Servers | 6 | GitHub, Context7, Exa, Memory, Playwright, Sequential Thinking (7 with Supabase via `--update-mcp` sync) |+| MCP Servers | 6 legacy reference entries | GitHub, Context7, Exa, Memory, Playwright, Sequential Thinking. Current managed sync recommends `chrome-devtools`; see the explicit refresh instructions above. || Profiles | 2 | `strict` (read-only sandbox) and `yolo` (full auto-approve) || Agent Roles | 3 | `.codex/agents/`: explorer, reviewer, docs-researcher |diff --git a/tests/scripts/codex-hooks.test.js b/tests/scripts/codex-hooks.test.jsindex 920e4d3eb..2844e80d0 100644--- a/tests/scripts/codex-hooks.test.js+++ b/tests/scripts/codex-hooks.test.js@@ -918,6 +918,12 @@ if (const parsed = TOML.parse(merged);assert.strictEqual(parsed.mcp_servers['chrome-devtools'].command, 'npx');assert.deepStrictEqual(parsed.mcp_servers['chrome-devtools'].args, ['[email protected]']);+ const rootMcp = JSON.parse(fs.readFileSync(path.join(repoRoot, '.mcp.json'), 'utf8'));+ const rootPackages = rootMcp.mcpServers['chrome-devtools'].args.filter(arg =>+ arg.startsWith('chrome-devtools-mcp@'));+ assert.deepStrictEqual(rootPackages, parsed.mcp_servers['chrome-devtools'].args,+ 'root MCP and generated Codex TOML must use the same connector pin');+ assert.deepStrictEqual(rootPackages, ['[email protected]']);assert.strictEqual(parsed.mcp_servers['chrome-devtools'].startup_timeout_sec, 30);// No retired server may be (re-)emitted — exa's url form broke Codex (#2224).assert.strictEqual(parsed.mcp_servers.exa, undefined);@@ -937,6 +943,51 @@ if (passed++;else failed++;+if (+ test('merge-mcp-config preserves an existing latest entry until explicit recommendation refresh', () => {+ const tempDir = createTempDir('mcp-merge-explicit-refresh-');+ const configPath = path.join(tempDir, 'config.toml');+ const original = [+ '# User-maintained configuration',+ '[mcp_servers.chrome-devtools]',+ 'command = "npx"',+ 'args = ["chrome-devtools-mcp@latest", "--custom-browser-argument"]',+ 'startup_timeout_sec = 75',+ '[mcp_servers.chrome-devtools.env]',+ 'CUSTOM_BROWSER_SETTING = "preserve-until-explicit-refresh"',+ '',+ '[mcp_servers.user_tool]',+ 'command = "custom-launcher"',+ 'args = ["--user-setting"]',+ '',+ ].join('\n');++ try {+ fs.writeFileSync(configPath, original);+ const preserved = runNode(mergeMcpConfigScript, [configPath], deterministicPackageEnv);+ assert.strictEqual(preserved.status, 0, `${preserved.stdout}\n${preserved.stderr}`);+ assert.match(preserved.stderr, /chrome-devtools differs from ECC recommendation/);+ assert.match(preserved.stderr, /--update-mcp to refresh/);+ assert.strictEqual(fs.readFileSync(configPath, 'utf8'), original,+ 'normal sync must preserve existing latest and customized settings byte-for-byte');++ const refreshed = runNode(mergeMcpConfigScript, [configPath, '--update-mcp'], deterministicPackageEnv);+ assert.strictEqual(refreshed.status, 0, `${refreshed.stdout}\n${refreshed.stderr}`);+ assert.match(refreshed.stdout, /\[update\] mcp_servers\.chrome-devtools/);+ const updated = TOML.parse(fs.readFileSync(configPath, 'utf8'));+ assert.deepStrictEqual(updated.mcp_servers['chrome-devtools'], {+ command: 'npx', args: ['[email protected]'], startup_timeout_sec: 30,+ }, 'explicit refresh replaces the whole recommended section, including custom subsettings');+ assert.deepStrictEqual(updated.mcp_servers.user_tool, TOML.parse(original).mcp_servers.user_tool,+ 'unrelated user-managed server settings remain untouched');+ } finally {+ cleanup(tempDir);+ }+ })+)+ passed++;+else failed++;+if (test('merge-mcp-config repairs the invalid exa url entry from earlier ECC versions (#2224)', () => {const tempDir = createTempDir('mcp-merge-exa-repair-');