agentpack-cli 0.1.15__tar.gz → 0.1.16__tar.gz

{agentpack_cli-0.1.15 → agentpack_cli-0.1.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpack-cli
-Version: 0.1.15
+Version: 0.1.16
 Summary: Token-aware context packing for AI coding agents — Claude, Cursor, Windsurf, and Codex
 License: MIT
 License-File: LICENSE
@@ -44,7 +44,7 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-> **Status: alpha (v0.1.11).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
+> **Status: alpha (v0.1.17).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
 >
 > **Platform note:** macOS and Linux are fully supported. Windows support is not yet implemented (git hooks use POSIX shell; the Claude Code session hooks use `python3`/`rm -f`). Contributions welcome.
 
@@ -297,7 +297,7 @@ Configures:
 - `CLAUDE.md` — tells Claude to read the context pack before each task
 - `.claude/settings.json` — two hooks:
   - `SessionStart`: clears injection sentinel so first prompt gets context
-  - `UserPromptSubmit`: auto-repacks when stale, injects context once per session
+  - `UserPromptSubmit`: detects repo changes via content hash (not file mtime), triggers background repack using your prompt as the task description so keyword scoring matches the current conversation
 
 After this, context is injected automatically into every Claude Code session. No `/agentpack` command needed — it just happens.
 
@@ -354,7 +354,7 @@ The Skill descriptor activates AgentPack automatically — no `--task` flag requ
 |---|---|---|---|---|---|
 | Config file patched | `CLAUDE.md` + `.claude/settings.json` | `.cursorrules` + `.cursor/rules/*.mdc` | `.windsurfrules` | `AGENTS.md` | `.agent/skills/agentpack/SKILL.md` + `GEMINI.md` |
 | Auto-inject on startup | ✅ `UserPromptSubmit` hook | ✅ `alwaysApply` | ✅ rules file | ✅ `AGENTS.md` | ✅ Skill auto-activation |
-| Auto-repack when stale | ✅ hook (snapshot hash, ~1ms when fresh) | ✅ git hooks | ✅ git hooks | ✅ git hooks | ✅ git hooks |
+| Auto-repack when stale | ✅ hook (content hash via `root_hash`, ~1ms when fresh) | ✅ git hooks | ✅ git hooks | ✅ git hooks | ✅ git hooks |
 | Manual repack shortcut | ✅ `/agentpack` slash cmd | ✅ VS Code task | ✅ VS Code task | `agentpack pack` | ✅ VS Code task |
 
 ---
@@ -640,7 +640,7 @@ Options:
 
 ### `agentpack session` _(removed)_
 
-Session management was removed in v0.1.11. `agentpack init` bootstraps the session automatically. Use `agentpack watch` to keep context current. To change the task, edit `.agentpack/task.md`.
+Session management was removed in v0.1.12. `agentpack init` bootstraps the session automatically. Use `agentpack watch` to keep context current. To change the task, edit `.agentpack/task.md`.
 
 ---
 
@@ -826,13 +826,13 @@ Tokens after ignore:  210,000
 
 ### `agentpack stats`
 
-Show session state and token statistics for the last pack.
+Show session state, token statistics, and selection accuracy for the last pack.
 
 ```bash
 agentpack stats
 ```
 
-When a session is active, shows session panel (agent, mode, started, refresh count) above token stats. Also lists top included files by score.
+When a session is active, shows session panel (agent, mode, started, refresh count) above token stats. Also lists top included files by score and avg recall/precision/F1 over the last 10 runs.
 
 ---
 
@@ -910,8 +910,10 @@ agentpack monitor --clear
 | Direct dependency of changed file | +50 |
 | Reverse dependency | +40 |
 | Has related tests | +35 |
+| Knowledge/architecture doc (DECISIONS.md, ADR-*.md, ARCHITECTURE.md, docs/adr/, docs/decisions/, docs/rfcs/) | +30 |
 | Config file | +25 |
 | Recently modified | +20 |
+| High churn (top 10% by commit frequency) | +15 |
 | Large unrelated file | −50 |
 | Ignored/binary | −100 |
 
@@ -960,8 +962,10 @@ content_keyword_max       = 60
 direct_dep                = 50
 reverse_dep               = 40
 related_test              = 35
+knowledge_file            = 30   # DECISIONS.md, ADR-*.md, ARCHITECTURE.md, docs/adr/ etc.
 config_file               = 25
 recently_modified         = 20
+churn_high                = 15   # top 10% by commit frequency
 large_unrelated_penalty   = -50
 ignored_penalty           = -100
 ```

{agentpack_cli-0.1.15 → agentpack_cli-0.1.16}/README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-> **Status: alpha (v0.1.11).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
+> **Status: alpha (v0.1.17).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
 >
 > **Platform note:** macOS and Linux are fully supported. Windows support is not yet implemented (git hooks use POSIX shell; the Claude Code session hooks use `python3`/`rm -f`). Contributions welcome.
 
@@ -258,7 +258,7 @@ Configures:
 - `CLAUDE.md` — tells Claude to read the context pack before each task
 - `.claude/settings.json` — two hooks:
   - `SessionStart`: clears injection sentinel so first prompt gets context
-  - `UserPromptSubmit`: auto-repacks when stale, injects context once per session
+  - `UserPromptSubmit`: detects repo changes via content hash (not file mtime), triggers background repack using your prompt as the task description so keyword scoring matches the current conversation
 
 After this, context is injected automatically into every Claude Code session. No `/agentpack` command needed — it just happens.
 
@@ -315,7 +315,7 @@ The Skill descriptor activates AgentPack automatically — no `--task` flag requ
 |---|---|---|---|---|---|
 | Config file patched | `CLAUDE.md` + `.claude/settings.json` | `.cursorrules` + `.cursor/rules/*.mdc` | `.windsurfrules` | `AGENTS.md` | `.agent/skills/agentpack/SKILL.md` + `GEMINI.md` |
 | Auto-inject on startup | ✅ `UserPromptSubmit` hook | ✅ `alwaysApply` | ✅ rules file | ✅ `AGENTS.md` | ✅ Skill auto-activation |
-| Auto-repack when stale | ✅ hook (snapshot hash, ~1ms when fresh) | ✅ git hooks | ✅ git hooks | ✅ git hooks | ✅ git hooks |
+| Auto-repack when stale | ✅ hook (content hash via `root_hash`, ~1ms when fresh) | ✅ git hooks | ✅ git hooks | ✅ git hooks | ✅ git hooks |
 | Manual repack shortcut | ✅ `/agentpack` slash cmd | ✅ VS Code task | ✅ VS Code task | `agentpack pack` | ✅ VS Code task |
 
 ---
@@ -601,7 +601,7 @@ Options:
 
 ### `agentpack session` _(removed)_
 
-Session management was removed in v0.1.11. `agentpack init` bootstraps the session automatically. Use `agentpack watch` to keep context current. To change the task, edit `.agentpack/task.md`.
+Session management was removed in v0.1.12. `agentpack init` bootstraps the session automatically. Use `agentpack watch` to keep context current. To change the task, edit `.agentpack/task.md`.
 
 ---
 
@@ -787,13 +787,13 @@ Tokens after ignore:  210,000
 
 ### `agentpack stats`
 
-Show session state and token statistics for the last pack.
+Show session state, token statistics, and selection accuracy for the last pack.
 
 ```bash
 agentpack stats
 ```
 
-When a session is active, shows session panel (agent, mode, started, refresh count) above token stats. Also lists top included files by score.
+When a session is active, shows session panel (agent, mode, started, refresh count) above token stats. Also lists top included files by score and avg recall/precision/F1 over the last 10 runs.
 
 ---
 
@@ -871,8 +871,10 @@ agentpack monitor --clear
 | Direct dependency of changed file | +50 |
 | Reverse dependency | +40 |
 | Has related tests | +35 |
+| Knowledge/architecture doc (DECISIONS.md, ADR-*.md, ARCHITECTURE.md, docs/adr/, docs/decisions/, docs/rfcs/) | +30 |
 | Config file | +25 |
 | Recently modified | +20 |
+| High churn (top 10% by commit frequency) | +15 |
 | Large unrelated file | −50 |
 | Ignored/binary | −100 |
 
@@ -921,8 +923,10 @@ content_keyword_max       = 60
 direct_dep                = 50
 reverse_dep               = 40
 related_test              = 35
+knowledge_file            = 30   # DECISIONS.md, ADR-*.md, ARCHITECTURE.md, docs/adr/ etc.
 config_file               = 25
 recently_modified         = 20
+churn_high                = 15   # top 10% by commit frequency
 large_unrelated_penalty   = -50
 ignored_penalty           = -100
 ```

{agentpack_cli-0.1.15 → agentpack_cli-0.1.16}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentpack-cli"
-version = "0.1.15"
+version = "0.1.16"
 description = "Token-aware context packing for AI coding agents — Claude, Cursor, Windsurf, and Codex"
 readme = "README.md"
 requires-python = ">=3.10"

{agentpack_cli-0.1.15 → agentpack_cli-0.1.16}/src/agentpack/__init__.py

@@ -1,3 +1,3 @@
 """AgentPack — token-aware context packing for AI coding agents."""
 
-__version__ = "0.1.14"
+__version__ = "0.1.17"

{agentpack_cli-0.1.15 → agentpack_cli-0.1.16}/src/agentpack/application/pack_service.py

@@ -303,6 +303,7 @@ class PackService:
             budget=plan.budget,
             token_estimate=packed_tokens,
         )
+        excluded_receipts = [r for r in plan.receipts if r.action == "excluded"]
         _record_metrics(
             root,
             task=request.task,
@@ -315,6 +316,8 @@ class PackService:
             changed_count=len(plan.all_changed),
             selected_paths=[sf.path for sf in plan.selected],
             current_changed=plan.all_changed,
+            excluded_count=len(excluded_receipts),
+            excluded_paths=[r.path for r in excluded_receipts if r.reason == "score too low"][:10],
         )
 
         return PackResult(
@@ -404,6 +407,8 @@ def _record_metrics(
     changed_count: int,
     selected_paths: list[str],
     current_changed: set[str],
+    excluded_count: int = 0,
+    excluded_paths: list[str] | None = None,
 ) -> None:
     metrics_path = root / ".agentpack" / "metrics.jsonl"
     accuracy = _compute_selection_accuracy(root, metrics_path, selected_paths, current_changed)
@@ -416,6 +421,8 @@ def _record_metrics(
         "saving_pct": round(saving_pct, 1),
         "selected_files": selected_count,
         "changed_files": changed_count,
+        "excluded_files": excluded_count,
+        "excluded_paths": excluded_paths or [],
         "selected_paths": selected_paths,
         "phases": {k: round(v, 3) for k, v in phase_times.items()},
         "total_s": round(sum(phase_times.values()), 3),

{agentpack_cli-0.1.15 → agentpack_cli-0.1.16}/src/agentpack/commands/doctor.py

@@ -149,6 +149,35 @@ def register(app: typer.Typer) -> None:
         if _local_has_hooks and not _global_has_hooks:
             console.print("  [yellow]![/] Hooks local-only — context won't auto-inject in other repos. Run: agentpack install --agent claude --global")
 
+        # --- MCP server ---
+        console.print("\n[bold]MCP server[/]")
+        mcp_json = root / ".mcp.json"
+        global_claude_settings_for_mcp = Path.home() / ".claude" / "settings.json"
+        _local_has_mcp = False
+        _global_has_mcp = False
+        if mcp_json.exists():
+            try:
+                mcp_data = _json.loads(mcp_json.read_text())
+                if "agentpack" in mcp_data.get("mcpServers", {}):
+                    console.print(f"  [green]✓[/] MCP server registered (local): {mcp_json}")
+                    _local_has_mcp = True
+                else:
+                    console.print("  [yellow]![/] .mcp.json exists but agentpack missing — run: agentpack install --agent claude")
+            except Exception:
+                console.print(f"  [yellow]![/] Could not parse {mcp_json}")
+        else:
+            console.print("  [dim]-[/] .mcp.json not present (run: agentpack install --agent claude)")
+        if global_claude_settings_for_mcp.exists():
+            try:
+                global_data = _json.loads(global_claude_settings_for_mcp.read_text())
+                if "agentpack" in global_data.get("mcpServers", {}):
+                    console.print(f"  [green]✓[/] MCP server registered (global): {global_claude_settings_for_mcp}")
+                    _global_has_mcp = True
+            except Exception:
+                pass
+        if not _local_has_mcp and not _global_has_mcp:
+            console.print("  [yellow]![/] MCP server not registered — mcp__agentpack__* tools unavailable")
+
         # --- Slash command ---
         console.print("\n[bold]Slash command (/agentpack)[/]")
         local_cmd = root / ".claude" / "commands" / "agentpack.md"

{agentpack_cli-0.1.15 → agentpack_cli-0.1.16}/src/agentpack/commands/install.py

@@ -51,6 +51,10 @@ def register(app: typer.Typer) -> None:
             scope = "~/.claude/settings.json" if global_install else ".claude/settings.json"
             console.print(f"[green]{scope} {hook_action}.[/]")
 
+            mcp_action = installer.patch_mcp_server(root, global_install)
+            mcp_scope = "~/.claude/settings.json" if global_install else ".mcp.json"
+            console.print(f"[green]{mcp_scope} mcpServers.agentpack {mcp_action}.[/]")
+
             if slash_command:
                 _install_slash_command(root, global_install)
 
@@ -164,11 +168,14 @@ def register(app: typer.Typer) -> None:
         # --- Agent-specific config ---
         if agent == "claude":
             if not dry_run:
-                hook_action = ClaudeInstaller().patch_claude_settings(root, global_install=True)
+                inst = ClaudeInstaller()
+                hook_action = inst.patch_claude_settings(root, global_install=True)
                 console.print(f"\n[green]~/.claude/settings.json {hook_action}.[/]")
+                mcp_action = inst.patch_mcp_server(root, global_install=True)
+                console.print(f"[green]~/.claude/settings.json mcpServers.agentpack {mcp_action}.[/]")
                 _install_slash_command(root, global_install=True)
             else:
-                console.print("\n[dim]Would patch: ~/.claude/settings.json (hooks)[/]")
+                console.print("\n[dim]Would patch: ~/.claude/settings.json (hooks + mcpServers for global)[/]")
                 console.print("[dim]Would install: ~/.claude/commands/agentpack.md (slash command)[/]")
 
         elif agent == "cursor":

agentpack_cli-0.1.16/src/agentpack/installers/claude.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+_AGENTPACK_BLOCK = """\
+<!-- agentpack:start -->
+## AgentPack
+
+AgentPack MCP server is available. For coding tasks in this repository, call the MCP tool
+before editing files to get task-relevant context without loading the entire codebase.
+
+```
+mcp__agentpack__pack_context(task="<what you're working on>", budget=4000)
+```
+
+Other tools:
+- `mcp__agentpack__explain_file(path)` — score breakdown + symbols for a file
+- `mcp__agentpack__get_related_files(path)` — import-graph neighbours
+- `mcp__agentpack__get_stats()` — token/saving stats for the latest pack
+- `mcp__agentpack__get_context()` — read the pre-built pack (no repack)
+- `mcp__agentpack__refresh()` — refresh using current task.md
+
+If MCP is not available, fall back to the CLI:
+
+```bash
+agentpack pack --agent claude --task "<task>"
+```
+
+Then read `.agentpack/context.claude.md`.
+<!-- agentpack:end -->"""
+
+_BLOCK_RE = re.compile(
+    r"<!-- agentpack:start -->.*?<!-- agentpack:end -->",
+    re.DOTALL,
+)
+
+
+class ClaudeInstaller:
+    """Configures Claude-specific repo and global files."""
+
+    def patch_claude_md(self, root: Path) -> str:
+        """Insert/update AgentPack block in CLAUDE.md. Returns action taken."""
+        claude_md = root / "CLAUDE.md"
+
+        if not claude_md.exists():
+            claude_md.write_text(f"{_AGENTPACK_BLOCK}\n")
+            return "created"
+
+        content = claude_md.read_text()
+        if _BLOCK_RE.search(content):
+            new_content = _BLOCK_RE.sub(_AGENTPACK_BLOCK, content)
+            if new_content != content:
+                claude_md.write_text(new_content)
+                return "updated"
+            return "unchanged"
+
+        claude_md.write_text(content.rstrip() + "\n\n" + _AGENTPACK_BLOCK + "\n")
+        return "appended"
+
+    def patch_claude_settings(self, root: Path, global_install: bool = False) -> str:
+        """Merge agentpack hooks into .claude/settings.json. Returns action taken."""
+        if global_install:
+            settings_path = Path.home() / ".claude" / "settings.json"
+        else:
+            settings_path = root / ".claude" / "settings.json"
+
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+
+        existing: dict = {}
+        if settings_path.exists():
+            try:
+                existing = json.loads(settings_path.read_text())
+            except json.JSONDecodeError:
+                existing = {}
+
+        hooks = existing.setdefault("hooks", {})
+
+        # SessionStart: delete sentinel + kick off background repack so first prompt
+        # gets fresh context without blocking the session.
+        # Use session refresh if session exists (respects task.md), else fall back to pack.
+        sentinel_cmd = (
+            "rm -f .agentpack/.context_injected .agentpack/.mcp_reminded"
+            " && ([ -f .agentpack/session.json ]"
+            " && agentpack session refresh >/dev/null 2>&1"
+            " || agentpack pack --task auto --mode balanced >/dev/null 2>&1) &"
+        )
+        session_start = hooks.setdefault("SessionStart", [])
+        # Replace any stale agentpack session hooks (old cmd only deleted sentinel).
+        for entry in session_start:
+            entry["hooks"] = [
+                h for h in entry.get("hooks", [])
+                if not (".context_injected" in h.get("command", "") and "rm -f" in h.get("command", ""))
+            ]
+        session_start[:] = [e for e in session_start if e.get("hooks")]
+        already_has_session_hook = any(
+            any(h.get("command", "") == sentinel_cmd for h in entry.get("hooks", []))
+            for entry in session_start
+        )
+        if not already_has_session_hook:
+            session_start.append({"hooks": [{"type": "command", "command": sentinel_cmd}]})
+
+        # UserPromptSubmit: tiny MCP reminder — no context injection, no file reads.
+        # MCP server handles actual context retrieval on demand (pull-based).
+        # Background repack keeps the index fresh for MCP queries, using the
+        # user's prompt as the task so keyword scoring matches current work.
+        # root_hash (not md5 of whole file) avoids false "changed" on created_at churn.
+        mcp_reminder_cmd = (
+            "python3 -c \"\n"
+            "import json, pathlib, subprocess, sys\n"
+            "snap = pathlib.Path('.agentpack/snapshots/latest.json')\n"
+            "sentinel = pathlib.Path('.agentpack/.mcp_reminded')\n"
+            "try:\n"
+            "    current_hash = json.loads(snap.read_text()).get('root_hash') if snap.exists() else None\n"
+            "except Exception:\n"
+            "    current_hash = None\n"
+            "reminded_hash = sentinel.read_text().strip() if sentinel.exists() else None\n"
+            "try:\n"
+            "    hook_data = json.loads(sys.stdin.read())\n"
+            "    prompt = hook_data.get('prompt', '')\n"
+            "except Exception:\n"
+            "    prompt = ''\n"
+            "task = (prompt[:200].strip() or 'auto') if prompt else 'auto'\n"
+            # Background repack when repo changed since last pack.
+            "if current_hash != reminded_hash:\n"
+            "    subprocess.Popen(['agentpack', 'pack', '--task', task, '--mode', 'balanced'],\n"
+            "                     stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)\n"
+            "    sentinel.write_text(current_hash or '1')\n"
+            "    msg = 'AgentPack: repo changed — repacking index. Call agentpack_pack_context(task=\\\"...\\\") for fresh context.'\n"
+            "else:\n"
+            "    msg = 'AgentPack MCP ready. Call agentpack_pack_context(task=\\\"...\\\") before editing files.'\n"
+            "print(json.dumps({'hookSpecificOutput': {'hookEventName': 'UserPromptSubmit',\n"
+            "    'additionalContext': msg}}))\n"
+            "\""
+        )
+        user_prompt = hooks.setdefault("UserPromptSubmit", [])
+        # Remove stale agentpack hooks (old injection hooks and old MCP reminder versions).
+        def _is_stale_agentpack_hook(cmd: str) -> bool:
+            return (
+                "context.claude.md" in cmd
+                or ".context_injected" in cmd
+                or (".mcp_reminded" in cmd and "hashlib" in cmd)  # old md5-based reminder
+            )
+        for entry in user_prompt:
+            entry["hooks"] = [
+                h for h in entry.get("hooks", [])
+                if not _is_stale_agentpack_hook(h.get("command", ""))
+            ]
+        user_prompt[:] = [e for e in user_prompt if e.get("hooks")]
+        already_has_prompt_hook = any(
+            any(h.get("command", "") == mcp_reminder_cmd for h in entry.get("hooks", []))
+            for entry in user_prompt
+        )
+        if not already_has_prompt_hook:
+            user_prompt.append({
+                "hooks": [{
+                    "type": "command",
+                    "command": mcp_reminder_cmd,
+                    "timeout": 5,
+                    "statusMessage": "Checking agentpack index...",
+                }]
+            })
+
+        new_content = json.dumps(existing, indent=2) + "\n"
+        if settings_path.exists() and settings_path.read_text() == new_content:
+            return "unchanged"
+        settings_path.write_text(new_content)
+        return "updated"
+
+    def patch_mcp_server(self, root: Path, global_install: bool = False) -> str:
+        """Register agentpack MCP server. Returns action taken.
+
+        Local install writes to .mcp.json (Claude Code's standard per-project
+        MCP config). Global install writes to ~/.claude/settings.json.
+        """
+        agentpack_entry = {"command": "agentpack", "args": ["mcp"]}
+
+        if global_install:
+            settings_path = Path.home() / ".claude" / "settings.json"
+            settings_path.parent.mkdir(parents=True, exist_ok=True)
+
+            existing: dict = {}
+            if settings_path.exists():
+                try:
+                    existing = json.loads(settings_path.read_text())
+                except json.JSONDecodeError:
+                    existing = {}
+
+            mcp_servers = existing.setdefault("mcpServers", {})
+            if mcp_servers.get("agentpack") == agentpack_entry:
+                return "unchanged"
+            mcp_servers["agentpack"] = agentpack_entry
+            settings_path.write_text(json.dumps(existing, indent=2) + "\n")
+            return "updated"
+
+        # Local install: use .mcp.json (read by Claude Code for project MCP servers)
+        mcp_json_path = root / ".mcp.json"
+
+        existing_mcp: dict = {}
+        if mcp_json_path.exists():
+            try:
+                existing_mcp = json.loads(mcp_json_path.read_text())
+            except json.JSONDecodeError:
+                existing_mcp = {}
+
+        mcp_servers = existing_mcp.setdefault("mcpServers", {})
+        if mcp_servers.get("agentpack") == agentpack_entry:
+            self._migrate_mcp_from_claude_settings(root)
+            return "unchanged"
+
+        mcp_servers["agentpack"] = agentpack_entry
+        mcp_json_path.write_text(json.dumps(existing_mcp, indent=2) + "\n")
+        self._migrate_mcp_from_claude_settings(root)
+        return "updated"
+
+    def _migrate_mcp_from_claude_settings(self, root: Path) -> None:
+        """Remove stale mcpServers key from .claude/settings.json if present."""
+        settings_path = root / ".claude" / "settings.json"
+        if not settings_path.exists():
+            return
+        try:
+            existing = json.loads(settings_path.read_text())
+        except json.JSONDecodeError:
+            return
+        if "mcpServers" not in existing:
+            return
+        del existing["mcpServers"]
+        settings_path.write_text(json.dumps(existing, indent=2) + "\n")