{"record":{"id":"765be05f744c9c5b","repo":"affaan-m/ECC","slug":"mcp-servers-legacyname-is-a-legacy-name-for-n","errorCode":null,"errorMessage":"mcp_servers.${legacyName} is a legacy name for ${name} (run with --update-mcp to migrate)","messagePattern":"mcp_servers\\.(.+?) is a legacy name for (.+?) \\(run with --update-mcp to migrate\\)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"scripts/codex/merge-mcp-config.js","lineNumber":300,"sourceCode":"    }\n\n    if (finalEntry) {\n      if (updateMcp) {\n        // --update-mcp: remove existing section (and legacy alias), will re-add below\n        toRemoveLog.push(`mcp_servers.${resolvedLabel}`);\n        raw = removeServerFromText(raw, resolvedLabel, existing);\n        if (resolvedLabel !== name) {\n          raw = removeServerFromText(raw, name, existing);\n        }\n        if (legacyName && hasCanonical) {\n          toRemoveLog.push(`mcp_servers.${legacyName}`);\n          raw = removeServerFromText(raw, legacyName, existing);\n        }\n        toAppend.push(spec.toml);\n      } else {\n        // Add-only mode: skip, but warn about drift\n        if (legacyName && !hasCanonical) {\n          warn(`mcp_servers.${legacyName} is a legacy name for ${name} (run with --update-mcp to migrate)`);\n        } else if (configDiffers(finalEntry, spec.fields)) {\n          warn(`mcp_servers.${name} differs from ECC recommendation (run with --update-mcp to refresh)`);\n        } else {\n          log(`  [ok] mcp_servers.${name}`);\n        }\n      }\n    } else {\n      log(`  [add] mcp_servers.${name}`);\n      toAppend.push(spec.toml);\n    }\n  }\n\n  const hasRemovals = toRemoveLog.length > 0;\n\n  if (toAppend.length === 0 && !hasRemovals) {\n    log('All ECC MCP servers already present. Nothing to do.');\n    return;\n  }","sourceCodeStart":282,"sourceCodeEnd":318,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/codex/merge-mcp-config.js#L282-L318","documentation":"In merge-mcp-config.js add-only mode, when a recommended MCP server is absent in canonical form but an entry under its legacy name exists, the script skips it and warns that the legacy name should be migrated with --update-mcp. It does not duplicate the server under both names; the user is told to migrate explicitly.","triggerScenarios":"main iterates recommended server specs; the canonical `mcp_servers.<name>` is missing (hasCanonical false), a legacy-named entry exists (legacyName truthy), and the script runs without --update-mcp so it cannot rewrite the entry.","commonSituations":"An older ECC install created the server under a name that was later renamed; user runs the merge script after upgrading ECC but forgets --update-mcp.","solutions":["Re-run the script with --update-mcp to migrate the legacy entry to the canonical name","Or manually rename `mcp_servers.<legacyName>` to `mcp_servers.<name>` in the TOML config","Remove the stale legacy entry after migration to avoid duplicate servers","Re-run the merge to confirm `[ok] mcp_servers.<name>`"],"exampleFix":"# before\n[mcp_servers.old_context7]\ncommand = \"npx\"\n# after (via script or manual rename)\n[mcp_servers.context7]\ncommand = \"npx\"","handlingStrategy":"validation","validationCode":"// detect legacy-named server entries before merging\nconst legacy = ['mcp_servers'].flatMap(t => Object.keys(parse(configText)[t] || {})).filter(n => !canonicalNames.includes(n));\nif (legacy.length) console.log('legacy entries need migration:', legacy);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run with --update-mcp whenever ECC renames an MCP server","Grep the config for old server names after upgrades","Keep one canonical entry per MCP server"],"tags":["codex","mcp","config","migration","deprecated"],"backgroundTag":"deprecated-api-usage","analyzedSha":"8321021c54d670126ce3b2969d5deb880b4b0c2a","analyzedAt":"2026-09-16T10:08:13.343Z","contentChangedAt":"2026-09-16T10:08:13.343Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}