Skip to content

fix(mcp): honor CLAUDE_CONFIG_DIR in Claude user-scope stale cleanup - #3148

Merged
Daniel Meppiel (danielmeppiel) merged 9 commits into
microsoft:mainfrom
bodapatisaikrishna:fix/claude-config-dir-stale-cleanup
Oct 16, 2026
Merged

Daniel Meppiel (danielmeppiel) merged 9 commits into
microsoft:mainfrom
bodapatisaikrishna:fix/claude-config-dir-stale-cleanup

Conversation

@bodapatisaikrishna

@bodapatisaikrishna Sai krishna Bodapati (bodapatisaikrishna) commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Description

User-scope Claude MCP stale cleanup was hardcoded to ~/.claude.json, ignoring CLAUDE_CONFIG_DIR during server removal and modifying the default profile instead of the active one. This makes cleanup resolve the destination consistently through ClaudeClientAdapter, keeping profiles isolated and preserving symlink checks.

The coordinated consolidation preserves the original contributor history and credits dajiaohuang's lifecycle, static-owner, mutation, isolation, and guidance contributions from #3238 in commit 364b0f4. It does not import early symlink normalization or claim to repair #3128's separate installation-state symptom.

Issue and approved scope

Issue: #3127

Human scope-approval comment: #3127 (comment)

Does this PR complete the issue, or what remains?
Fixes #3127. Completes the issue.

Type of change

  • Bug fix
  • New feature
  • Documentation
  • Maintenance / refactor

Testing

  • Tested locally

  • All existing tests pass

  • Added tests for new functionality (if applicable)

  • uv run --frozen --extra dev pytest tests/spec_conformance -p no:randomly --no-header -q --basetemp="$PWD/.worker-evidence/pytest-spec-recovery": 312 passed, 2 skipped.

  • uv run --frozen --extra dev python -m tests.spec_conformance.orphan_check: passed, 129 requirements aligned.

  • uv run --frozen --extra dev python -m tests.spec_conformance.gen_statement: passed, generated statements committed and subsequent regeneration clean.

  • Focused union: 196 passed, 4 subtests passed; quality contracts: 64 passed. After the final faithful main merge, the exact-head consumer/negative/conformance/owner selection passed 15 tests and all seven canonical lint gates plus the architecture boundary passed.

  • Five mutation groups failed with their protections removed, then passed after restoration. The new conformance regression fails specifically on out-of-root byte changes when cleanup is restored to the old hardcoded home path.

  • Actual CI at 7514c3ce7f24d40ec67ca72b66a4ab7290d10bcd: CI, Spec conformance, CodeQL, Docs, NOTICE, and aggregate check passed. One unchanged Windows trusted-tool test timed out invoking gh.exe --version; the permitted single failed-job retry passed without code or assertion changes.

Spec conformance (OpenAPM v0.1)

If this PR changes behaviour that an OpenAPM v0.1 req-XXX covers,
confirm the three-step ritual in the
development guide:

  • Spec edit: docs/src/content/docs/specs/openapm-v0.1.md updated
    (new/changed <a id="req-XXX"></a> anchor + prose + Appendix C
    row).
  • Manifest edit: docs/src/content/docs/specs/manifests/openapm-v0.1.requirements.yml
    updated.
  • Test edit: a @pytest.mark.req("req-XXX") test under
    tests/spec_conformance/ added or extended.
  • CONFORMANCE.{md,json} regenerated via
    uv run --extra dev python -m tests.spec_conformance.gen_statement
    and committed.
  • N/A -- this PR does not change OpenAPM-observable behaviour.

This corrects the implementation of existing req-tg-002: "No target's installer MAY write files outside its registered root(s)." The Target Registry already specifies that Claude user scope honors CLAUDE_CONFIG_DIR; cleanup must not write the default configuration outside that selected root. The new real-files conformance test verifies default and other-profile bytes stay unchanged while selected-profile cleanup preserves user-owned entries and unrelated settings.

The normative text and requirements manifest intentionally remain unchanged: no new requirement, capability, or exception is introduced. Mode B passes through genuine existing-requirement regression coverage, with no waiver.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

@danielmeppiel

Copy link
Copy Markdown
Collaborator

Thanks Sai krishna Bodapati (@bodapatisaikrishna) for contributing this fix for #3127. We had overlapping local work, which is now parked and remains unpushed; no competing PR will be opened. We will keep your PR as the candidate for this fix.

Please continue here through the normal maintainer review and feedback process. This acknowledgment is coordination only, not a review approval or merge decision.


Generated by autopilot-issue-delivery-worker. This comment is AI-generated and may contain errors.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

Review effort: Lite
Findings: 1 High severity

Open (1)
What changed in this PR

Fixes Claude MCP user-scope stale cleanup to honor CLAUDE_CONFIG_DIR (instead of always targeting ~/.claude.json), ensuring stale server removal applies to the active Claude profile and preserves symlink safety checks.

Changes:

  • Resolve Claude user-scope config path via ClaudeClientAdapter/ClientFactory during stale cleanup (and keep symlink pre-checks).
  • Improve _clean_claude_config labeling so logs/errors reflect the actual config location.
  • Add/extend unit tests and update docs to explicitly include stale cleanup behavior under CLAUDE_CONFIG_DIR.
File Description
tests/​unit/​test_mcp_integrator_remove_stale.py Adds regression tests for honoring CLAUDE_CONFIG_DIR and rejecting symlinked Claude configs.
tests/​unit/​test_claude_mcp.py Adds additional Claude user-scope tests (custom dir, preserving settings, relative-dir rejection, symlink cases).
src/​apm_cli/​integration/​mcp_integrator.py Updates stale cleanup flow to resolve the correct Claude user config path and improves labeling/logging.
src/​apm_cli/​adapters/​client/​claude.py Introduces helper methods to resolve the Claude user config path (including an “unresolved” path for symlink checks).
docs/​src/​content/​docs/​reference/​environment-variables.md Clarifies CLAUDE_CONFIG_DIR applies to both installation and stale cleanup for MCP servers.
docs/​src/​content/​docs/​consumer/​install-mcp-servers.md Updates guidance to include stale cleanup behavior when CLAUDE_CONFIG_DIR is set.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Resolve user-scope Claude MCP config destinations through ClaudeClientAdapter in MCPIntegrator.remove_stale, matching install behavior when CLAUDE_CONFIG_DIR is set. Preserve default and other profiles during removal, and reject symlinked config paths.
Preserve the contributor cleanup candidate while evaluating overlap with PR 3238. No PR-specific code changes in this merge.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: f79e464c-180e-4be3-9056-0773aa679a1a
@danielmeppiel

Daniel Meppiel (danielmeppiel) commented Oct 15, 2026 •

Copy link
Copy Markdown
Collaborator

APM Review Panel: ship_now

Claude user-scope cleanup now shares installation's selected destination without losing path protections, with mutation-backed lifecycle and conformance coverage.

panel-mode=delta; personas=python-architect,test-coverage-expert,apm-ceo

cc Sai krishna Bodapati (@bodapatisaikrishna) Sergio Sisternes (@sergio-sisternes-epam) -- the consolidated advisory is ready for your review.

The earlier consolidation question is resolved: #3148 remains the accepted #3127 cleanup vehicle. Original contributor history is preserved, and dajiaohuang's useful #3238 lifecycle, static-owner, mutation, isolation, and documentation contributions are credited in 364b0f4. The unsafe early normalization from #3238 was not imported. Installation and cleanup share one adapter environment reader; cleanup checks the unresolved path before canonicalization.

The final delta adds a genuine existing req-tg-002 registered-root containment regression, not a waiver or a new normative requirement. Restoring the old hardcoded home destination makes its outside-root byte assertion fail. Actual spec conformance now passes, as do all other standard technical workflows at 7514c3ce7f24d40ec67ca72b66a4ab7290d10bcd. The sole prior follow-up, observing actual CI, is complete.

This establishes the #3127 cleanup repair, not the separate #3128 installation-state symptom. #3238's readiness was withdrawn. Recommended disposition: after this surviving repair lands, treat its overlapping cleanup implementation as redundant while keeping #3128 reproduction-led.

Aligned with: secure-by-default path refusal and outside-root preservation; one canonical destination authority; existing-requirement conformance; preserved contributor credit.

Panel summary

Persona B R N Takeaway
Python Architect 0 0 0 One destination authority, correct pre-resolution refusal, and genuine existing registered-root requirement applicability.
Test Coverage Expert 0 0 0 Real CLI lifecycle/negative coverage plus mutation-proven conformance containment; no uncovered scoped promise.

Counts describe review findings, not automatic shipping decisions.

Recommendation

ship_now from the review perspective. No deferred findings remain. The existing review requests for danielmeppiel and sergio-sisternes-epam remain unchanged; no worker merged or closed either PR or issue.

Folded in this run

  • Consolidated adapter ownership, preserved symlink/path refusal, and added credited lifecycle, static, mutation, isolation, and guidance coverage -- 364b0f4.
  • Repaired the actual Mode B failure with existing req-tg-002 real-files conformance coverage and regenerated statements -- 8f3aaa1; no waiver.

Copilot signals reviewed

  • tests/unit/test_mcp_integrator_remove_stale.py: the reported implicit-class-binding concern did not reproduce. The contributor had already changed the fixture to classmethod; no remaining code action.

Regression-trap evidence (mutation-break gate)

  • Hardcoded-home routing broke the real custom-profile CLI lifecycle and architecture baseline.
  • Early normalization broke symlink-directory refusal and the architecture baseline.
  • Disabling the static rule broke both architecture traps.
  • Disabling path/absolute validation broke all three negative CLI cases.
  • Hardcoded-home routing broke the conformance test specifically at outside-root byte preservation.

All protections were restored before commit. Local union: 196 passed, 4 subtests passed; quality contracts: 64 passed; full conformance: 312 passed, 2 skipped, with 129 requirements aligned. Final exact-head consumer/negative/conformance/owner selection: 15 passed. Both deterministically detected canonical owners have executed exact-head functional evidence, and completion schema plus semantic owner verification passed.

Lint contract

All seven current canonical lint gates passed at the published head, plus the architecture boundary. Ruff reported no diagnostics and 1944 files already formatted; pylint duplication, auth boundary, YAML I/O, file-length, and portable-path checks passed.

CI

All six standard technical workflows completed successfully at the exact published head:

One unchanged Windows trusted-tool test timed out invoking gh.exe --version. Its single permitted failed-job retry passed, followed by one aggregate refresh. No timeout, assertion, code, or check was weakened. Two CI recovery iterations were consumed: the conformance repair and this bounded retry.

Mergeability status

GitHub reports MERGEABLE; required human review remains outstanding. Tested integrated base: 4037af112df9727df33ab0ac12fe0740001e0a53. Later main: ee08bb59b9a7bce67fb4010e4af8652c4c53a7de. A fresh merge-tree compatibility preview is clean; the only overlapping path is the packaged commands guide. Published-head CI was not restarted merely for that compatible main advance.

Convergence

Three outer iterations; two Copilot classification rounds; no deferred review findings. Ready for maintainer review.

Full per-persona findings

Python Architect

No findings.

Test Coverage Expert

No findings.

This panel is advisory. The maintainer and author decide shipping.


Generated by autopilot-pr-merge-worker. This comment is AI-generated and may contain errors.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: f79e464c-180e-4be3-9056-0773aa679a1a
Keep PR microsoft#3148 as the accepted microsoft#3127 cleanup repair. Reuse the lifecycle, owner-rule, mutation, isolation and guidance contributions from microsoft#3238 (1087df2, 02df846 and 1269b1a), without importing its pre-check symlink normalization. Installation and removal share one adapter destination authority; removal checks the unresolved path first. Add actual CLI negative cases and prove behavioral/static guards by mutation. This does not claim a microsoft#3128 installation-state repair.

Co-authored-by: dajiaohuang <mikewushuwen@outlook.com>

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: f79e464c-180e-4be3-9056-0773aa679a1a
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: f79e464c-180e-4be3-9056-0773aa679a1a
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: f79e464c-180e-4be3-9056-0773aa679a1a
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: f79e464c-180e-4be3-9056-0773aa679a1a
Bind the existing req-tg-002 installer-write containment contract to a real-files cleanup regression. The Target Registry already honors CLAUDE_CONFIG_DIR. Prove default and other-profile bytes survive a selected-root cleanup, then regenerate conformance evidence. Hardcoding the former home path fails the outside-root byte assertion. No waiver or new normative requirement is introduced.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: f79e464c-180e-4be3-9056-0773aa679a1a
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: f79e464c-180e-4be3-9056-0773aa679a1a
@danielmeppiel
Daniel Meppiel (danielmeppiel) merged commit c07a19d into microsoft:main Oct 16, 2026
35 of 37 checks passed
Daniel Meppiel (danielmeppiel) added a commit to dajiaohuang/apm that referenced this pull request Oct 16, 2026
Preserve microsoft#3148 user-scope containment and conformance while retaining the proposed frozen-local amendment. No feature reimplementation or hash policy change.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: f79e464c-180e-4be3-9056-0773aa679a1a
Daniel Meppiel (danielmeppiel) added a commit to nefayran/apm that referenced this pull request Oct 16, 2026
Preserve microsoft#3148 alongside the reviewed tag-source conflict reconciliation.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: f79e464c-180e-4be3-9056-0773aa679a1a
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Oct 16, 2026
…3251)

Restore the release-gate integration suite (nightly + tag) to green:

- runtime: route runtime setup/version/uninstall children through
  external_process_env so a frozen binary's bundled LD_LIBRARY_PATH /
  DYLD_* never leak into the setup script's python3 (ensurepip failed
  under the PyInstaller binary).
- tests: align fixtures with contracts merged since v0.33.0 --
  grok-bot skills_rel_root/supports on MagicMock targets (#3106), Cursor
  native flat hooks (#3149), frozen installs that never rewrite the
  lockfile (#2384), manifestless SKILL.md probe (#3064), unknown apm.yml
  key warning (#3222), resolved Claude config path (#3148), and the
  build-ID owner guard mutation case (#3113).
- flakes: skip transient git maintenance files when snapshotting a bare
  fixture repo; widen multiprocess lock-test timeouts for slow runners.

Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 761bf207-57da-41d0-bd3f-ffecbb97b83a
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] User-scope stale MCP cleanup ignores CLAUDE_CONFIG_DIR: removed servers stay configured

3 participants