fix: replace server entry on re-install instead of deep-merging (Codex config corruption)
Problem
Installing a server under a name that already exists in an agent's config file deep-merges the new entry into the old one instead of replacing it, so stale fields from the previous install survive.
The worst case is stdio → remote: an old stdio entry's command/args/env survive alongside the new type/url. For Codex this is fatal — it rejects the whole config with:
invalid configuration: url is not supported for stdio
in `mcp_servers.firecrawl`
which breaks every chat ("Error creating chat") until the user hand-edits ~/.codex/config.toml. This happened in the wild via firecrawl setup mcp (which shells out to add-mcp) on a machine that had an older stdio firecrawl-mcp entry.
Repro (v1.14.0)
mkdir /tmp/codex-home
cat > /tmp/codex-home/config.toml <<'EOF'
[mcp_servers.firecrawl]
command = "npx"
args = [ "-y", "firecrawl-mcp" ]
[mcp_servers.firecrawl.env]
FIRECRAWL_API_KEY = "fc-test"
EOF
CODEX_HOME=/tmp/codex-home npx -y add-mcp "https://mcp.firecrawl.dev/fc-test/v2/mcp" \
--name firecrawl --transport http -g -a codex -y
cat /tmp/codex-home/config.toml
Result — a hybrid entry Codex cannot load:
[mcp_servers.firecrawl]
command = "npx"
args = [ "-y", "firecrawl-mcp" ]
type = "http"
url = "https://mcp.firecrawl.dev/fc-test/v2/mcp"
[mcp_servers.firecrawl.env]
FIRECRAWL_API_KEY = "fc-test"
The same merge-instead-of-replace behavior exists in the JSON and YAML writers; JSON-based agents just happen to tolerate the leftover keys rather than failing hard.
Why replace (not merge, skip, or prompt)
This matches the intended semantics discussed in #12, where replace was described as the default for name conflicts:
replace (current behavior) as default so it's "backwards compatible"
In practice the code deep-merged rather than replaced, which is what this PR fixes — no CLI surface or behavior contract changes, just making name-conflict installs actually produce the new entry. An --on-conflict merge|skip|overwrite flag as sketched in #12 could still be layered on top later; this PR just makes the default sound.
Fix
Add dropReplacedServers(existing, incoming, configKey) in src/formats/utils.ts: before the deepMerge, delete from the existing config any server names the incoming config is about to write. Server entries are now replaced atomically, while everything else in the file (other servers, unrelated settings, JSONC comments via the existing jsonc.modify path) still merges/preserves exactly as before. Wired into all three writers (toml.ts, yaml.ts, json.ts); writeConfig now passes configKey through to the YAML/TOML writers.
After the fix, the repro above produces:
[mcp_servers.firecrawl]
type = "http"
url = "https://mcp.firecrawl.dev/fc-test/v2/mcp"
Tests & housekeeping
- Two e2e regression tests (
tests/e2e/install.test.ts): stdio→remote re-install for Codex/TOML and Cursor/JSON, asserting nocommand/args/envsurvive. Both fail onmainand pass with this change. - Three unit tests for
dropReplacedServersintests/formats-utils.test.ts(replacement + sibling-server preservation, dotted config keys, missing-key no-op). tests/formats-utils.test.tsexisted but was never registered in thetest/test:unitscripts, so its tests didn't run in CI — registered it (its pre-existing tests pass).- CHANGELOG entry and patch version bump to 1.14.1.
typecheck, fulltestsuite, andbuildall pass; touched files are Prettier-clean.