affaan-m/ECC · warning

mcp_servers. is a legacy name for (run with --update-mcp to…

Error message

mcp_servers.${legacyName} is a legacy name for ${name} (run with --update-mcp to migrate)

What it means

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.

Solutions

  1. Re-run the script with --update-mcp to migrate the legacy entry to the canonical name
  2. Or manually rename `mcp_servers.<legacyName>` to `mcp_servers.<name>` in the TOML config
  3. Remove the stale legacy entry after migration to avoid duplicate servers
  4. Re-run the merge to confirm `[ok] mcp_servers.<name>`

Example fix

# before
[mcp_servers.old_context7]
command = "npx"
# after (via script or manual rename)
[mcp_servers.context7]
command = "npx"
Defensive patterns

Strategy: validation

Validate before calling

// detect legacy-named server entries before merging
const legacy = ['mcp_servers'].flatMap(t => Object.keys(parse(configText)[t] || {})).filter(n => !canonicalNames.includes(n));
if (legacy.length) console.log('legacy entries need migration:', legacy);

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/765be05f744c9c5b. Report an issue: GitHub.

Appendix: source

Thrown at scripts/codex/merge-mcp-config.js:300

    }

    if (finalEntry) {
      if (updateMcp) {
        // --update-mcp: remove existing section (and legacy alias), will re-add below
        toRemoveLog.push(`mcp_servers.${resolvedLabel}`);
        raw = removeServerFromText(raw, resolvedLabel, existing);
        if (resolvedLabel !== name) {
          raw = removeServerFromText(raw, name, existing);
        }
        if (legacyName && hasCanonical) {
          toRemoveLog.push(`mcp_servers.${legacyName}`);
          raw = removeServerFromText(raw, legacyName, existing);
        }
        toAppend.push(spec.toml);
      } else {
        // Add-only mode: skip, but warn about drift
        if (legacyName && !hasCanonical) {
          warn(`mcp_servers.${legacyName} is a legacy name for ${name} (run with --update-mcp to migrate)`);
        } else if (configDiffers(finalEntry, spec.fields)) {
          warn(`mcp_servers.${name} differs from ECC recommendation (run with --update-mcp to refresh)`);
        } else {
          log(`  [ok] mcp_servers.${name}`);
        }
      }
    } else {
      log(`  [add] mcp_servers.${name}`);
      toAppend.push(spec.toml);
    }
  }

  const hasRemovals = toRemoveLog.length > 0;

  if (toAppend.length === 0 && !hasRemovals) {
    log('All ECC MCP servers already present. Nothing to do.');
    return;
  }

View on GitHub (pinned to 8321021c54)