{"record":{"id":"c152ac89b226125a","repo":"affaan-m/ECC","slug":"mcp-servers-name-differs-from-ecc-recommendatio","errorCode":null,"errorMessage":"mcp_servers.${name} differs from ECC recommendation (run with --update-mcp to refresh)","messagePattern":"mcp_servers\\.(.+?) differs from ECC recommendation \\(run with --update-mcp to refresh\\)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"scripts/codex/merge-mcp-config.js","lineNumber":302,"sourceCode":"    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  }\n\n  const appendText = '\\n' + toAppend.join('\\n\\n') + '\\n';","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/codex/merge-mcp-config.js#L284-L320","documentation":"In merge-mcp-config.js add-only mode, when a recommended MCP server exists in the config but its fields differ from the ECC recommendation (detected by shallow configDiffers comparison), the script skips the update and warns the user to run with --update-mcp to refresh it.","triggerScenarios":"main finds existing `mcp_servers.<name>` (hasCanonical true) and configDiffers(finalEntry, spec.fields) returns true — at least one top-level field (or array, compared by JSON) mismatches the spec — while the script runs without --update-mcp.","commonSituations":"User customized command/args/env of an MCP server after ECC installed it; ECC updated the recommended spec in a new release; hand-edited config missing or altering a recommended field.","solutions":["Run the script with --update-mcp to overwrite the entry with the ECC recommendation","If the customization is intentional, ignore the warning — it is informational drift","Or manually align the TOML fields with the spec in scripts/codex/merge-mcp-config.js","Re-run the merge to confirm the entry logs `[ok]`"],"exampleFix":"// before\n$ node scripts/codex/merge-mcp-config.js\n[ecc-mcp] WARNING: mcp_servers.context7 differs from ECC recommendation...\n// after\n$ node scripts/codex/merge-mcp-config.js --update-mcp\n[ecc-mcp] [ok] mcp_servers.context7","handlingStrategy":"validation","validationCode":"const differs = (existing, recommended) =>\n  Object.keys(recommended).some(k => JSON.stringify(existing[k]) !== JSON.stringify(recommended[k]));\n// run with --update-mcp if differs(existingEntry, spec.fields)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Decide whether local customizations are intentional; if not, run --update-mcp after each ECC update","Track the config file in git so drift is visible in diffs","Re-run the merge periodically and treat warnings as drift reports"],"tags":["codex","mcp","config","drift","scripting"],"backgroundTag":"invalid-config-value","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"}