Skip to content

[FEATURE] Harden the copilot root .mcp.json move: heal gate, pre-ownership locks, canonicaliser and UX follow-ups #3881

Closed

Description

Proposals are welcome before implementation. For substantive changes, wait
for a responsible human maintainer to approve the scope and identify a review
contact. An automated recommendation, label alone, or silence is not approval.
See Contributing.

Is your feature request related to a problem? Please describe.
The review panel on #3875 (copilot project MCP moves to root .mcp.json; vscode becomes a deprecated alias) raised several hardening items. They fell outside that PR's scope:

  1. Retired-destination heal gate. The heal from .github/mcp.json and .vscode/mcp.json runs only when the previous lock's apm_version is below 0.37 (lock_predates_root_mcp_json). The lock writer keeps apm_version on semantically equal writes, so per-name settling, not the version gate, is what stops repeat heals. The gate also depends on the release actually shipping as 0.37. Replace the version check with a durable marker, for example a recorded destination per server.
  2. Heal for pre-ownership locks. Locks without mcp_target_servers (APM 0.2x era) never prove ownership, so their .github/mcp.json entries are not healed. Decide whether a fingerprint-only heal is safe for them.
  3. Derive SHARED_PROJECT_MCP_DESTINATIONS from the adapters' config paths, instead of a hand-maintained frozenset.
  4. One skill-launcher helper. CopilotProjectClientAdapter and ClaudeClientAdapter each resolve the self-defined launcher path. Extract one helper.
  5. Unify the target canonicalisers. canonical_target_token, canonical_target_name and canonical_target_subset should be one owner function plus thin views.
  6. Static env values in a shared, committed .mcp.json. Optionally warn when a literal env value looks like a secret (a sensitive key name), because .mcp.json is usually committed. security.md already documents this risk.
  7. Install output polish. Mark the deprecated vscode in --target help text. Remove the duplicated "Targeting" line when a deprecated alias is used. Do not leave an empty .github/ directory after the heal.

Describe the solution you'd like
Small, separately reviewable PRs. Each should keep the #3875 lifecycle suite (tests/integration/test_copilot_root_mcp_json_lifecycle.py) green.

Describe alternatives you've considered
Folding these into #3875. The panel deferred them to keep that BREAKING PR reviewable.

Additional context
Sources: the python-architect, supply-chain-security-expert and devx-ux-expert findings on #3875.

Activity

  1. danielmeppiel commented on Nov 19, 2026

    @danielmeppiel
    CollaboratorAuthor

    Decision: approve
    Area: integration
    Scope: Harden the copilot root .mcp.json move from #3875 without changing what a successful install writes: (1) replace the lock apm_version heal gate (lock_predates_root_mcp_json) with a durable per-server marker; (2) keep pre-ownership locks (no mcp_target_servers) report-only, never fingerprint-healed, with a test proving their retired entries are kept and reported; (3) derive SHARED_PROJECT_MCP_DESTINATIONS from the adapters' config paths; (4) one launcher-path helper for the Copilot project and Claude adapters; (5) one target canonicaliser owner with thin views for canonical_target_token / canonical_target_name / canonical_target_subset; (6) warn when a literal env value under a sensitive key name is written to a shared project .mcp.json; (7) mark vscode deprecated in --target help, drop the duplicated Targeting line for a deprecated alias, do not leave an empty .github/ after the heal; plus the merge-time deferrals from #3875 (identical foreign root entry counted as a replacement, one retire helper, the frozen check, the dot-segment nit, the dual-retired-file name).
    Done when: Each item is fixed or shown moot on main with file:line evidence; heal no longer reads apm_version; a guard and MutationCase protect each new single owner (canonicaliser, shared-destination derivation, launcher helper); fail-before tests for every behavior fix; tests/integration/test_copilot_root_mcp_json_lifecycle.py and the heal/determinism lifecycle suites stay green; docs and one new-style CHANGELOG line for user-visible output changes.
    Out of scope: Changing MCP destinations, the vscode alias semantics, or the shared-ownership rules; spec text (tracked in #3880).
    Review contact: Daniel Meppiel (@danielmeppiel)

  2. danielmeppiel commented on Nov 19, 2026

    @danielmeppiel
    CollaboratorAuthor

    Decision: approve
    Area: integration
    Scope: Supersedes the earlier record on this issue (pruned by Daniel, 2026-11-19). Fix only defects in the copilot root .mcp.json move (#3875) that can lose, adopt or corrupt a user's MCP entries, or leave APM-written entries stranded: for example an identical foreign root entry counted as APM's replacement, a heal gate that can skip or repeat the heal, or a retire path that removes an entry APM cannot show it wrote. Each fix needs a reproduced failure first. Everything else in the issue (canonicaliser unification, shared-destination derivation, launcher helper, sensitive-env warning, UX nits) is not planned.
    Done when: Every item that meets the data-safety bar is fixed with a fail-before test, or shown not reproducible on main with evidence; tests/integration/test_copilot_root_mcp_json_lifecycle.py and the heal/determinism lifecycle suites stay green; minimal PR.
    Out of scope: Refactors, UX polish, warnings, spec text.
    Review contact: Daniel Meppiel (@danielmeppiel)

  3. danielmeppiel commented on Nov 19, 2026

    @danielmeppiel
    CollaboratorAuthor

    Decision: approve
    Area: project
    Scope: Supersedes the earlier record on this issue (pruned by Daniel, 2026-11-19). Fix only defects in the copilot root .mcp.json move (#3875) that can lose, adopt or corrupt a user's MCP entries, or leave APM-written entries stranded: for example an identical foreign root entry counted as APM's replacement, a heal gate that can skip or repeat the heal, or a retire path that removes an entry APM cannot show it wrote. Each fix needs a reproduced failure first. Everything else in the issue (canonicaliser unification, shared-destination derivation, launcher helper, sensitive-env warning, UX nits) is not planned.
    Done when: Every item that meets the data-safety bar is fixed with a fail-before test, or shown not reproducible on main with evidence; tests/integration/test_copilot_root_mcp_json_lifecycle.py and the heal/determinism lifecycle suites stay green; minimal PR.
    Out of scope: Refactors, UX polish, warnings, spec text.
    Review contact: Daniel Meppiel (@danielmeppiel)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    status/acceptedHuman scope approval; verify the issue's approval record and review contact before work.type/featureNew capability, new flag, new primitive.

    Type

    No type

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions