apm-cli 0.33.0__tar.gz → 0.35.0__tar.gz

{apm_cli-0.33.0/src/apm_cli.egg-info → apm_cli-0.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apm-cli
-Version: 0.33.0
+Version: 0.35.0
 Summary: MCP configuration tool
 Author-email: Daniel Meppiel <user@example.com>
 License: MIT License
@@ -78,7 +78,7 @@ Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent c
 
 GitHub Copilot | Claude Code | Grok Build | Cursor | OpenCode | Codex | Gemini | Windsurf | Kiro
 
-**[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)** · **[Roadmap](https://github.com/orgs/microsoft/projects/2304/views/5)**
+**[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/quickstart/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/)** · **[Roadmap](https://github.com/orgs/microsoft/projects/2304/views/5)**
 
 ---
 
@@ -95,6 +95,8 @@ AI coding agents need context to be useful — standards, prompts, skills, plugi
 # apm.yml — ships with your project
 name: your-project
 version: 1.0.0
+targets:
+  - copilot # choose the harness(es) this project supports
 dependencies:
   apm:
     # Skills from any repository
@@ -106,7 +108,7 @@ dependencies:
     # A full APM package with instructions, skills, prompts, hooks...
     - microsoft/apm-sample-package#v1.0.0
   mcp:
-    # MCP servers -- installed into every detected client
+    # MCP servers -- installed into every selected target
     - name: io.github.github/github-mcp-server
       transport: http   # MCP transport name, not URL scheme -- connects over HTTPS
 ```
@@ -140,11 +142,11 @@ One command, no configuration -- VS Code and GitHub Copilot read the file automa
 One `apm.yml` describes every primitive your agents need — instructions, skills, prompts, agents, hooks, plugins, MCP servers — and `apm install` reproduces the exact same setup across every client on every machine. `apm.lock.yaml` pins the resolved tree the way `package-lock.json` does for npm.
 
 - **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** -- declared once, deployed across Copilot, Claude, Grok Build, Cursor, OpenCode, Codex, Gemini, Windsurf, Kiro
-- **[Install from anywhere](https://microsoft.github.io/apm/guides/dependencies/)** — GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, Gitea, Gogs, any git host
-- **[Transitive dependencies](https://microsoft.github.io/apm/guides/dependencies/)** — packages can depend on packages; APM resolves the full tree
-- **[Author plugins](https://microsoft.github.io/apm/guides/plugins/)** — build Copilot, Claude, and Cursor plugins with dependency management, then export standard `plugin.json`
-- **[Marketplaces](https://microsoft.github.io/apm/guides/marketplaces/)** — install plugins from curated registries in one command, deployed across all targets and locked
-- **[Pack & distribute](https://microsoft.github.io/apm/guides/pack-distribute/)** — `apm pack` bundles your configuration as a zipped package or a standalone plugin
+- **[Install from anywhere](https://microsoft.github.io/apm/consumer/install-packages/)** — GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, Gitea, Gogs, any git host
+- **[Transitive dependencies](https://microsoft.github.io/apm/consumer/install-packages/#transitive-dependencies-and-the-lockfile)** — packages can depend on packages; APM resolves the full tree
+- **[Author plugins](https://microsoft.github.io/apm/producer/)** — build Copilot, Claude, and Cursor plugins with dependency management, then export standard `plugin.json`
+- **[Marketplaces](https://microsoft.github.io/apm/consumer/installing-from-marketplaces/)** — install plugins from curated registries in one command, deployed across all targets and locked
+- **[Pack & distribute](https://microsoft.github.io/apm/producer/pack-a-bundle/)** — `apm pack` bundles your configuration as a zipped package or a standalone plugin
 - **[CI/CD ready](https://github.com/microsoft/apm-action)** — GitHub Action for automated workflows
 
 ### 2. Secure by default
@@ -152,10 +154,10 @@ One `apm.yml` describes every primitive your agents need — instructions, skill
 Agent context is executable in effect — a prompt is a program for an LLM. APM treats it that way. Every install scans for hidden Unicode that can hijack agent behavior; the lockfile pins integrity hashes; transitive MCP servers are gated by trust prompts.
 
 - **[Content security](https://microsoft.github.io/apm/enterprise/security/)** — `apm install` blocks compromised packages before agents read them; `apm audit` runs the same checks on demand
-- **[Lockfile integrity](https://microsoft.github.io/apm/enterprise/governance/)** — `apm.lock` records resolved sources and content hashes for full provenance
+- **[Lockfile integrity](https://microsoft.github.io/apm/reference/lockfile-spec/)** — `apm.lock` records resolved sources and content hashes for full provenance
 - **[SBOM export](https://microsoft.github.io/apm/reference/cli/lock/)** — `apm lock export --format cyclonedx|spdx` emits a standard inventory of what reached disk, straight from the lockfile — provenance for procurement, not a compliance attestation
-- **[Drift detection](https://microsoft.github.io/apm/guides/drift-detection/)** — `apm audit` rebuilds your agent context in scratch and diffs it against your working tree to catch hand-edits before they ship
-- **[MCP trust boundaries](https://microsoft.github.io/apm/guides/mcp-servers/)** — transitive MCP servers require explicit consent
+- **[Drift detection](https://microsoft.github.io/apm/enterprise/drift-detection/)** — `apm audit` rebuilds your agent context in scratch and diffs it against your working tree to catch hand-edits before they ship
+- **[MCP trust boundaries](https://microsoft.github.io/apm/consumer/install-mcp-servers/)** — transitive MCP servers require explicit consent
 
 ### 3. Governed by policy
 
@@ -244,7 +246,7 @@ Or add an MCP server (wired into Copilot, Claude, Cursor, Codex, OpenCode, Gemin
 apm install --mcp io.github.github/github-mcp-server --transport http   # connects over HTTPS
 ```
 
-See the **[Getting Started guide](https://microsoft.github.io/apm/getting-started/quick-start/)** for the full walkthrough.
+See the **[Getting Started guide](https://microsoft.github.io/apm/quickstart/)** for the full walkthrough.
 
 ## Works with agentrc
 

{apm_cli-0.33.0 → apm_cli-0.35.0}/README.md

@@ -6,7 +6,7 @@ Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent c
 
 GitHub Copilot | Claude Code | Grok Build | Cursor | OpenCode | Codex | Gemini | Windsurf | Kiro
 
-**[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)** · **[Roadmap](https://github.com/orgs/microsoft/projects/2304/views/5)**
+**[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/quickstart/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/)** · **[Roadmap](https://github.com/orgs/microsoft/projects/2304/views/5)**
 
 ---
 
@@ -23,6 +23,8 @@ AI coding agents need context to be useful — standards, prompts, skills, plugi
 # apm.yml — ships with your project
 name: your-project
 version: 1.0.0
+targets:
+  - copilot # choose the harness(es) this project supports
 dependencies:
   apm:
     # Skills from any repository
@@ -34,7 +36,7 @@ dependencies:
     # A full APM package with instructions, skills, prompts, hooks...
     - microsoft/apm-sample-package#v1.0.0
   mcp:
-    # MCP servers -- installed into every detected client
+    # MCP servers -- installed into every selected target
     - name: io.github.github/github-mcp-server
       transport: http   # MCP transport name, not URL scheme -- connects over HTTPS
 ```
@@ -68,11 +70,11 @@ One command, no configuration -- VS Code and GitHub Copilot read the file automa
 One `apm.yml` describes every primitive your agents need — instructions, skills, prompts, agents, hooks, plugins, MCP servers — and `apm install` reproduces the exact same setup across every client on every machine. `apm.lock.yaml` pins the resolved tree the way `package-lock.json` does for npm.
 
 - **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** -- declared once, deployed across Copilot, Claude, Grok Build, Cursor, OpenCode, Codex, Gemini, Windsurf, Kiro
-- **[Install from anywhere](https://microsoft.github.io/apm/guides/dependencies/)** — GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, Gitea, Gogs, any git host
-- **[Transitive dependencies](https://microsoft.github.io/apm/guides/dependencies/)** — packages can depend on packages; APM resolves the full tree
-- **[Author plugins](https://microsoft.github.io/apm/guides/plugins/)** — build Copilot, Claude, and Cursor plugins with dependency management, then export standard `plugin.json`
-- **[Marketplaces](https://microsoft.github.io/apm/guides/marketplaces/)** — install plugins from curated registries in one command, deployed across all targets and locked
-- **[Pack & distribute](https://microsoft.github.io/apm/guides/pack-distribute/)** — `apm pack` bundles your configuration as a zipped package or a standalone plugin
+- **[Install from anywhere](https://microsoft.github.io/apm/consumer/install-packages/)** — GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, Gitea, Gogs, any git host
+- **[Transitive dependencies](https://microsoft.github.io/apm/consumer/install-packages/#transitive-dependencies-and-the-lockfile)** — packages can depend on packages; APM resolves the full tree
+- **[Author plugins](https://microsoft.github.io/apm/producer/)** — build Copilot, Claude, and Cursor plugins with dependency management, then export standard `plugin.json`
+- **[Marketplaces](https://microsoft.github.io/apm/consumer/installing-from-marketplaces/)** — install plugins from curated registries in one command, deployed across all targets and locked
+- **[Pack & distribute](https://microsoft.github.io/apm/producer/pack-a-bundle/)** — `apm pack` bundles your configuration as a zipped package or a standalone plugin
 - **[CI/CD ready](https://github.com/microsoft/apm-action)** — GitHub Action for automated workflows
 
 ### 2. Secure by default
@@ -80,10 +82,10 @@ One `apm.yml` describes every primitive your agents need — instructions, skill
 Agent context is executable in effect — a prompt is a program for an LLM. APM treats it that way. Every install scans for hidden Unicode that can hijack agent behavior; the lockfile pins integrity hashes; transitive MCP servers are gated by trust prompts.
 
 - **[Content security](https://microsoft.github.io/apm/enterprise/security/)** — `apm install` blocks compromised packages before agents read them; `apm audit` runs the same checks on demand
-- **[Lockfile integrity](https://microsoft.github.io/apm/enterprise/governance/)** — `apm.lock` records resolved sources and content hashes for full provenance
+- **[Lockfile integrity](https://microsoft.github.io/apm/reference/lockfile-spec/)** — `apm.lock` records resolved sources and content hashes for full provenance
 - **[SBOM export](https://microsoft.github.io/apm/reference/cli/lock/)** — `apm lock export --format cyclonedx|spdx` emits a standard inventory of what reached disk, straight from the lockfile — provenance for procurement, not a compliance attestation
-- **[Drift detection](https://microsoft.github.io/apm/guides/drift-detection/)** — `apm audit` rebuilds your agent context in scratch and diffs it against your working tree to catch hand-edits before they ship
-- **[MCP trust boundaries](https://microsoft.github.io/apm/guides/mcp-servers/)** — transitive MCP servers require explicit consent
+- **[Drift detection](https://microsoft.github.io/apm/enterprise/drift-detection/)** — `apm audit` rebuilds your agent context in scratch and diffs it against your working tree to catch hand-edits before they ship
+- **[MCP trust boundaries](https://microsoft.github.io/apm/consumer/install-mcp-servers/)** — transitive MCP servers require explicit consent
 
 ### 3. Governed by policy
 
@@ -172,7 +174,7 @@ Or add an MCP server (wired into Copilot, Claude, Cursor, Codex, OpenCode, Gemin
 apm install --mcp io.github.github/github-mcp-server --transport http   # connects over HTTPS
 ```
 
-See the **[Getting Started guide](https://microsoft.github.io/apm/getting-started/quick-start/)** for the full walkthrough.
+See the **[Getting Started guide](https://microsoft.github.io/apm/quickstart/)** for the full walkthrough.
 
 ## Works with agentrc
 

{apm_cli-0.33.0 → apm_cli-0.35.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apm-cli"
-version = "0.33.0"
+version = "0.35.0"
 description = "MCP configuration tool"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -60,7 +60,7 @@ build = [
 ]
 
 [project.scripts]
-apm = "apm_cli.cli:main"
+apm = "apm_cli.entrypoint:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]
@@ -212,6 +212,7 @@ markers = [
     "requires_ado_bearer: requires az CLI logged in + APM_TEST_ADO_BEARER=1",
     "requires_network_integration: requires APM_RUN_INTEGRATION_TESTS=1",
     "requires_windows: requires a Windows host",
+    "requires_windows_native_standard_user: requires the disposable Windows runner's verified non-admin token and symlink denial",
     "requires_apm_binary: requires built apm binary on PATH (or APM_BINARY_PATH)",
     "requires_runtime_codex: requires codex runtime installed",
     "requires_runtime_copilot: requires GitHub Copilot CLI runtime installed",

{apm_cli-0.33.0 → apm_cli-0.35.0}/src/apm_cli/adapters/client/base.py

@@ -1,5 +1,6 @@
 """Base adapter interface for MCP clients."""
 
+import json
 import os
 import re
 from abc import ABC, abstractmethod
@@ -8,7 +9,9 @@ from pathlib import Path
 from typing import Any, ClassVar
 
 from ...models.dependency.mcp import _EXTRA_DENYLIST, TrustedEnvLiteral
+from ...utils.atomic_io import atomic_write_text
 from ...utils.console import _rich_error, _rich_warning
+from ...utils.path_security import has_symlink_component
 
 _INPUT_VAR_RE = re.compile(r"\$\{input:([^}]+)\}")
 
@@ -334,6 +337,7 @@ class MCPClientAdapter(ABC):
         """
         self._project_root = Path(project_root) if project_root is not None else None
         self.user_scope = user_scope
+        self.written_mcp_hashes: dict[str, str] = {}
         # Per-server tracking populated by the env-resolution helpers and
         # consumed by ``configure_mcp_server`` for the post-install summary
         # and the aggregated legacy-syntax deprecation warning. Defined on
@@ -364,12 +368,18 @@ class MCPClientAdapter(ABC):
             return self._project_root
         return Path(os.getcwd())
 
-    def render_server_config(self, server_info: dict) -> dict:
+    def render_server_config(
+        self,
+        server_info: dict,
+        *,
+        env_overrides: dict | None = None,
+        runtime_vars: dict | None = None,
+    ) -> dict:
         """Render one native server entry for exact baseline comparisons."""
         rendered = self._format_server_config(
             server_info,
-            env_overrides={},
-            runtime_vars={},
+            env_overrides=env_overrides or {},
+            runtime_vars=runtime_vars or {},
         )
         if isinstance(rendered, tuple):
             rendered = rendered[0]
@@ -377,6 +387,20 @@ class MCPClientAdapter(ABC):
             raise ValueError("Adapter did not produce a native MCP server mapping")
         return rendered
 
+    def matches_managed_server_config(self, native: object, expected: dict) -> bool:
+        """Compare the native connection with the adapter's rendered baseline."""
+        return native == expected
+
+    def managed_server_config(self, native: dict) -> dict:
+        """Return connection data for an actual-write fingerprint."""
+        return dict(native)
+
+    def project_managed_server_config(
+        self, native: object, *, baseline: dict, requested: dict
+    ) -> object:
+        """Return a comparison-only view for an already recorded managed connection."""
+        return native
+
     @abstractmethod
     def get_config_path(self):
         """Get the path to the MCP configuration file."""
@@ -396,6 +420,71 @@ class MCPClientAdapter(ABC):
         """Get the current MCP configuration."""
         pass
 
+    def validate_config_for_install(self) -> bool:
+        """Allow adapters to refuse unsafe configs before existing-server shortcuts."""
+        return True
+
+    def _read_json_config_for_update(self, config_path: Path) -> dict | None:
+        """Return the JSON object at *config_path* before a merge-and-write.
+
+        A missing or blank file yields ``{}``.  Returns ``None`` after a
+        warning when rewriting the file could lose data, so the caller skips
+        the write: the existing content is not a JSON object (for example
+        JSONC comments), or a user-scope path runs through a symlink, which
+        stale cleanup refuses to rewrite later.
+        """
+        if self.user_scope and has_symlink_component(Path.home(), config_path):
+            _rich_warning(
+                f"Skipped {config_path}: APM does not write MCP config through "
+                "symlinks. Replace the symlink or configure this server manually.",
+                symbol="warning",
+            )
+            return None
+        try:
+            raw = config_path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return {}
+        except (OSError, UnicodeError) as exc:
+            _rich_warning(
+                f"Could not read {config_path}: {exc} -- skipping config write; "
+                "fix the file's permissions or encoding, or add this server manually",
+                symbol="warning",
+            )
+            return None
+        if not raw.strip():
+            return {}
+        try:
+            config = json.loads(raw)
+        except json.JSONDecodeError:
+            config = None
+        if not isinstance(config, dict):
+            _rich_warning(
+                f"Could not parse {config_path} as a JSON object -- skipping config "
+                "write to avoid data loss (comments and trailing commas are not "
+                "preserved); fix the file or add this server manually",
+                symbol="warning",
+            )
+            return None
+        if self.mcp_servers_key in config and not isinstance(config[self.mcp_servers_key], dict):
+            _rich_warning(
+                f"Could not parse {config_path}: {self.mcp_servers_key} must be "
+                "a JSON object -- skipping config write to avoid data loss; "
+                "fix the file or add this server manually",
+                symbol="warning",
+            )
+            return None
+        return config
+
+    @staticmethod
+    def _write_json_config(config_path: Path, config: dict) -> None:
+        """Atomically write *config* as JSON and keep the file owner-only.
+
+        Entries can carry env values resolved at install time.
+        """
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write_text(config_path, json.dumps(config, indent=2), new_file_mode=0o600)
+        os.chmod(config_path, 0o600)
+
     @abstractmethod
     def configure_mcp_server(
         self,
@@ -1050,6 +1139,28 @@ class MCPClientAdapter(ABC):
             return True
         return not (sys.stdin.isatty() and sys.stdout.isatty())
 
+    def _resolve_explicit_environment_values(
+        self,
+        env_vars: dict[str, object],
+        env_overrides: dict[str, str] | None = None,
+    ) -> dict[str, str]:
+        """Translate authored references while preserving explicit env literals.
+
+        Resets placeholder tracking; mid-render callers must preserve prior keys.
+        """
+        resolved: dict[str, str] = {}
+        self._last_env_placeholder_keys = set()
+        for name, value in env_vars.items():
+            if not name or value is None:
+                continue
+            if isinstance(value, TrustedEnvLiteral):
+                resolved[name] = value
+            elif isinstance(value, str):
+                resolved[name] = self._resolve_env_variable(name, value, env_overrides)
+            else:
+                resolved[name] = _stringify_env_literal(value)
+        return resolved
+
     def _resolve_environment_variables(self, env_vars, env_overrides=None):
         """Resolve (or translate) declared environment variables.
 

{apm_cli-0.33.0 → apm_cli-0.35.0}/src/apm_cli/adapters/client/claude.py

@@ -26,7 +26,7 @@ from pathlib import Path
 
 from ...utils.atomic_io import atomic_write_text
 from ...utils.console import _rich_error, _rich_success, _rich_warning
-from ...utils.path_security import PathTraversalError
+from ...utils.path_security import PathTraversalError, validate_path_segments
 from .copilot import CopilotClientAdapter
 
 _log = logging.getLogger(__name__)
@@ -83,6 +83,51 @@ class ClaudeClientAdapter(CopilotClientAdapter):
             config["command"] = self._rewrite_self_defined_skill_command(config["command"])
         return config
 
+    def render_server_config(
+        self,
+        server_info: dict,
+        *,
+        env_overrides: dict | None = None,
+        runtime_vars: dict | None = None,
+    ) -> dict:
+        """Compare against the normalized shape actually written to Claude."""
+        return self._normalize_mcp_entry_for_claude_code(
+            super().render_server_config(
+                server_info, env_overrides=env_overrides, runtime_vars=runtime_vars
+            )
+        )
+
+    def matches_managed_server_config(self, native: object, expected: dict) -> bool:
+        """OAuth metadata is runtime-owned, not part of an APM connection declaration."""
+        if not isinstance(native, dict):
+            return False
+        return self.managed_server_config(native) == expected
+
+    def managed_server_config(self, native: dict) -> dict:
+        """Exclude only the runtime-owned OAuth account from write fingerprints."""
+        return {key: value for key, value in native.items() if key != "oauthAccount"}
+
+    def project_managed_server_config(
+        self, native: object, *, baseline: dict, requested: dict
+    ) -> object:
+        """Exclude a valid native-only cwd from managed reconciliation, never cleanup."""
+        if (
+            not isinstance(native, dict)
+            or native.get("type") != "stdio"
+            or baseline.get("type") != "stdio"
+            or "cwd" in baseline
+            or "cwd" in requested
+        ):
+            return native
+        cwd = native.get("cwd")
+        if not isinstance(cwd, str) or not cwd.strip() or "\x00" in cwd:
+            return native
+        try:
+            validate_path_segments(cwd, context="MCP cwd", allow_current_dir=True)
+        except PathTraversalError:
+            return native
+        return {key: value for key, value in native.items() if key != "cwd"}
+
     @classmethod
     def _is_remote_mcp_entry(cls, entry: dict) -> bool:
         """Return whether *entry* describes a remote (URL-addressed) server."""
@@ -148,7 +193,9 @@ class ClaudeClientAdapter(CopilotClientAdapter):
         }
 
     @classmethod
-    def _merge_mcp_server_dicts(cls, existing_servers: dict, config_updates: dict) -> None:
+    def _merge_mcp_server_dicts(
+        cls, existing_servers: dict, config_updates: dict, managed_fields: set[str] | None = None
+    ) -> None:
         """Merge *config_updates* into *existing_servers* in place.
 
         Per-server entries are shallow-merged: ``{**old, **new}`` so keys present
@@ -164,15 +211,23 @@ class ClaudeClientAdapter(CopilotClientAdapter):
                 continue
             prev = existing_servers.get(name)
             if isinstance(prev, dict):
+                if managed_fields:
+                    prev = {
+                        key: value
+                        for key, value in prev.items()
+                        if key not in managed_fields or key in new_cfg
+                    }
                 merged = {**cls._retained_previous_entry(prev, new_cfg), **new_cfg}
                 existing_servers[name] = merged
             else:
                 existing_servers[name] = dict(new_cfg)
 
-    def _merge_and_normalize_updates(self, data: dict, config_updates: dict) -> None:
+    def _merge_and_normalize_updates(
+        self, data: dict, config_updates: dict, managed_fields: set[str] | None = None
+    ) -> None:
         if "mcpServers" not in data:
             data["mcpServers"] = {}
-        self._merge_mcp_server_dicts(data["mcpServers"], config_updates)
+        self._merge_mcp_server_dicts(data["mcpServers"], config_updates, managed_fields)
         for name in config_updates:
             ent = data["mcpServers"].get(name)
             if isinstance(ent, dict):
@@ -184,7 +239,12 @@ class ClaudeClientAdapter(CopilotClientAdapter):
     def _project_mcp_path(self) -> Path:
         return self.project_root / ".mcp.json"
 
-    def _user_claude_json_path(self) -> Path:
+    @classmethod
+    def resolve_user_claude_unresolved_path(cls) -> Path:
+        """Return the un-normalized path for user-scope Claude Code config.
+
+        Used for symlink pre-checks before canonical resolution.
+        """
         config_dir = os.environ.get("CLAUDE_CONFIG_DIR", "").strip()
         if config_dir:
             config_path = Path(config_dir).expanduser()
@@ -193,9 +253,22 @@ class ClaudeClientAdapter(CopilotClientAdapter):
                     "CLAUDE_CONFIG_DIR must be an absolute path for user-scope MCP "
                     "config; set an absolute path or unset it to use ~/.claude.json."
                 )
-            return config_path.resolve(strict=False) / ".claude.json"
+            return config_path / ".claude.json"
         return Path.home() / ".claude.json"
 
+    @classmethod
+    def resolve_user_claude_json_path(cls, unresolved_path: Path | None = None) -> Path:
+        """Resolve the selected destination, optionally reusing a checked path."""
+        path = (
+            unresolved_path
+            if unresolved_path is not None
+            else cls.resolve_user_claude_unresolved_path()
+        )
+        return path.parent.resolve(strict=False) / path.name
+
+    def _user_claude_json_path(self) -> Path:
+        return self.resolve_user_claude_json_path()
+
     def _should_write_project(self) -> bool:
         return (self.project_root / ".claude").is_dir()
 
@@ -216,9 +289,11 @@ class ClaudeClientAdapter(CopilotClientAdapter):
         except (json.JSONDecodeError, OSError):
             return {"mcpServers": {}}
 
-    def update_config(self, config_updates, enabled=True):
+    def update_config(
+        self, config_updates, enabled=True, *, managed_fields: set[str] | None = None
+    ):
         if self._is_user_scope():
-            return self._merge_user_mcp(config_updates)
+            return self._merge_user_mcp(config_updates, managed_fields=managed_fields)
         if not self._should_write_project():
             _rich_warning(
                 f"Skipped Claude Code project MCP -- .claude/ not found in {self.project_root}"
@@ -236,13 +311,13 @@ class ClaudeClientAdapter(CopilotClientAdapter):
                     data = {}
             else:
                 data = {}
-            self._merge_and_normalize_updates(data, config_updates)
+            self._merge_and_normalize_updates(data, config_updates, managed_fields)
             path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
             return True
         except OSError:
             return False
 
-    def _merge_user_mcp(self, config_updates) -> bool:
+    def _merge_user_mcp(self, config_updates, *, managed_fields: set[str] | None = None) -> bool:
         path = self._user_claude_json_path()
         try:
             if path.is_file():
@@ -255,7 +330,7 @@ class ClaudeClientAdapter(CopilotClientAdapter):
                     data = {}
             else:
                 data = {}
-            self._merge_and_normalize_updates(data, config_updates)
+            self._merge_and_normalize_updates(data, config_updates, managed_fields)
             payload = json.dumps(data, indent=2) + "\n"
             path.parent.mkdir(parents=True, exist_ok=True)
             atomic_write_text(path, payload, new_file_mode=0o600)
@@ -272,6 +347,7 @@ class ClaudeClientAdapter(CopilotClientAdapter):
         env_overrides=None,
         server_info_cache=None,
         runtime_vars=None,
+        managed_fields: set[str] | None = None,
     ):
         if not server_url:
             _rich_error("server_url cannot be empty")
@@ -296,10 +372,16 @@ class ClaudeClientAdapter(CopilotClientAdapter):
             config_key = self._determine_config_key(server_url, server_name)
 
             server_config = self._format_server_config(server_info, env_overrides, runtime_vars)
-            ok = self.update_config({config_key: server_config})
+            from apm_cli.install.mcp.ownership import mcp_native_hash
+
+            fingerprint = mcp_native_hash(
+                self.managed_server_config(self._normalize_mcp_entry_for_claude_code(server_config))
+            )
+            ok = self.update_config({config_key: server_config}, managed_fields=managed_fields)
             if not ok:
                 _rich_error(f"Failed to write MCP config for '{config_key}' to Claude Code")
                 return False
+            self.written_mcp_hashes[server_url] = fingerprint
 
             _rich_success(f"Successfully configured MCP server '{config_key}' for Claude Code")
             return True