mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
## Description Fixes #2787. Scopes Headroom-installed Serena to the wrapped Claude project by default, containing an upstream MCP failure to that project instead of degrading every Claude Code session on the machine. `--code-memory-scope user` / `HEADROOM_CODE_MEMORY_SCOPE=user` retains the prior machine-wide behavior when explicitly requested. The implementation completes ownership semantics across multiple wrapped projects: - Claude MCP registration, lookup, overwrite, and removal are scope-aware. - Legacy ledger-owned user entries migrate safely; user-managed global Serena remains untouched. - Each project gets an independent ledger ownership key, so wrapping project B no longer overwrites project A's ownership. - Unwrapping project A removes only A plus an independently-owned legacy user entry; it cannot orphan B or delete an unowned global entry. - The migration that retires a legacy machine-wide entry now clears the ledger ownership record along with the config entry (see Changes Made) — an ownership record can no longer outlive the entry it authorized. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) ## Changes Made - `headroom/mcp_registry/claude.py`: `ClaudeRegistrar` gained a `scope` argument and reads/writes both `local` (project) and `user` (machine-wide) Claude Code MCP scopes. - `headroom/cli/wrap.py`: `_setup_serena_mcp` registers Serena at `local` scope by default; `--code-memory-scope` (env `HEADROOM_CODE_MEMORY_SCOPE`) restores `user` scope on request. - `headroom/cli/wrap.py`: `_retire_user_scope_serena` migrates a pre-#2787 machine-wide Serena entry on the next wrap, but only when the ledger proves Headroom installed it. - `headroom/cli/wrap.py`: fixed `_retire_user_scope_serena` to clear the ledger's ownership record after removing the migrated entry — previously the record survived the removal, so a user later installing the identical Serena command globally themselves could collide with the stale fingerprint and have their own entry deleted by a later wrap. - `headroom/cli/wrap.py`: `_remove_headroom_installed_serena_mcp` now also clears a scope's ownership record when that scope's live entry is already absent, so a record can't outlive the entry it authorized. - `headroom/mcp_registry/ledger.py`: ledger entries key off a project-scoped `ownership_key` in addition to the legacy global key, so multiple wrapped projects don't clobber each other's ownership records. - Added/extended tests: `tests/test_cli/test_serena_scope.py`, `tests/test_mcp_registry/test_claude_registrar.py`, `tests/test_cli/test_unwrap_claude.py`. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality ### Test Output ```text pytest tests/test_cli/test_serena_scope.py -v 13 passed in 19.29s pytest tests/test_mcp_registry/ tests/test_cli/test_unwrap_claude.py -q 137 passed, 2 failed in 2.16s ``` Both failures are pre-existing and unrelated to this change — they reproduce identically with this PR's diff to `headroom/cli/wrap.py` reverted, on a clean checkout of this branch. `test_unwrap_claude_stops_claude_owned_persistent_deployment` was already confirmed pre-existing on `main` by an independent reviewer on this PR (comment from PrakharSrivastav, 2026-08-13). `test_unwrap_claude_removes_mcp_purges_retired_hook_and_stops_proxy` fails locally on Windows over a hook-config path-comparison mismatch unrelated to Serena scoping; it is not exercised by this diff. ```text ruff check . All checks passed! ruff format --check . All files already formatted. mypy headroom --ignore-missing-imports Success: no issues found in 522 source files ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.13.11, project `.venv` (pytest 9.0.3, mypy 2.3.1, ruff). - Exact command / steps: `pytest tests/test_cli/test_serena_scope.py -v`, then re-ran the two new regression tests (`test_rewrap_migration_clears_the_ledger_so_a_reinstall_is_never_deleted`, `test_remove_serena_clears_a_stale_ownership_record_with_no_live_entry`) with the `headroom/cli/wrap.py` fix reverted via `git stash`, to confirm they fail on the old code and pass on the fix. - Observed result: both new tests fail with `assert not True` (stale ledger record still present) against the pre-fix code, and pass once the `clear_install(...)` calls are added. Full `test_serena_scope.py` suite: 13/13 passed post-fix. `mypy headroom` and `ruff check .` both clean. - Not tested: a real Claude Code installation end-to-end (these tests drive `ClaudeRegistrar` against a `tmp_path` home directory, per the existing pattern in this file); real macOS/Linux CI runners, which is what the GitHub Actions matrix below covers. ## Runtime Rollout Safety - Rollout-managed feature(s): `headroom wrap claude` Serena MCP registration scope only. - Minimum rollout channel: normal patch release; no staged feature flag required. - Stable/default behavior changed: Serena now registers at Claude Code's `local` (project) scope by default instead of `user` (machine-wide) scope; a pre-existing Headroom-installed machine-wide entry is migrated (removed) on the next wrap, with its ledger record now also cleared. - Kill switch / disable path: `--code-memory-scope user` (or `HEADROOM_CODE_MEMORY_SCOPE=user`) restores the previous machine-wide registration. - Unsafe override required: none. - Qualification impact: `tests/test_cli/test_serena_scope.py`, `tests/test_mcp_registry/test_claude_registrar.py`, and `tests/test_cli/test_unwrap_claude.py` must stay green (module to the two pre-existing, environment-specific failures noted under Testing). - Rollback path: human revert of this PR; `--code-memory-scope user` provides an immediate operational fallback to the old registration scope without a code rollback. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have made corresponding changes to the documentation (`README.md`, `docs/content/docs/proxy.mdx`) - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title ## Additional Notes Addresses the code-review finding from JerrettDavis (2026-08-14): the ledger's stale ownership record after migration is now cleared, with a regression test that reproduces the exact fingerprint-collision scenario described in that review and fails on the pre-fix code. --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
co-authored by
Claude Opus 5
JD Davis
parent
2df0c63445
commit
8cfeb692ca
@@ -121,9 +121,10 @@ print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")
|
||||
Launch a wrapped agent session each time, so the setup runs. `headroom wrap`
|
||||
starts a local proxy, installs **[Serena](https://github.com/oraios/serena)** for
|
||||
semantic code navigation, and launches the agent configured to route through
|
||||
Headroom. Serena is registered at user scope (for Claude Code, in
|
||||
`~/.claude.json`), so it stays available in your other projects until you run
|
||||
`headroom unwrap`. Skip it with `--code-memory none`.
|
||||
Headroom. For Claude Code, Serena is registered for the wrapped project only
|
||||
(as a `local`-scope MCP server in `~/.claude.json`). Use
|
||||
`--code-memory-scope user` to make it available in every project, or
|
||||
`--code-memory none` to skip it. `headroom unwrap` removes either registration.
|
||||
|
||||
The `headroom` CLI ships only in the PyPI package. The npm `headroom-ai` package
|
||||
is the TypeScript SDK — a library you import
|
||||
|
||||
@@ -91,6 +91,8 @@ Avoid setting process-wide variables such as `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_P
|
||||
|
||||
`headroom wrap` registers **[Serena](https://github.com/oraios/serena)** as the code-memory MCP for semantic, symbol-level code navigation. Serena runs on demand via `uvx` — Headroom downloads and executes no binary of its own — and indexes the current project locally. Pass `--code-memory none` to register no code-memory MCP.
|
||||
|
||||
For Claude Code, the entry is written at `local` scope, which means it applies to the directory you wrapped and nothing else. That keeps a Serena that cannot start from breaking Claude Code sessions in unrelated projects. Pass `--code-memory-scope user` (or set `HEADROOM_CODE_MEMORY_SCOPE=user`) to register it machine-wide instead, which is how releases before this change behaved. If an earlier version already registered Serena machine-wide, the next `headroom wrap claude` moves it into the project scope for you — but only when Headroom installed that entry itself; a Serena you registered by hand is left alone.
|
||||
|
||||
> **Upgrading from tokensave?** Earlier releases registered a `tokensave` MCP server (a downloaded Rust binary). tokensave has been retired in favour of Serena. On your next `headroom wrap` / `headroom unwrap`, Headroom removes the `tokensave` MCP entry it installed and switches you to Serena — nothing to migrate, since both are just indexes rebuilt from your source. The leftover `tokensave` binary in `~/.local/bin` and any `.tokensave/` folders are unused and safe to delete.
|
||||
|
||||
By default, the proxy uses the shared **ContentRouter** pipeline. It routes text, logs, JSON, code, images, and tool outputs through the currently enabled compressors and preserves reversible CCR markers where applicable.
|
||||
|
||||
+177
-5
@@ -1070,6 +1070,64 @@ _code_memory_option = click.option(
|
||||
)
|
||||
|
||||
|
||||
# --- Code-memory MCP scope (Claude Code only) --------------------------------
|
||||
# Where the code-memory MCP entry is written. Claude Code is the only agent we
|
||||
# wrap that has scopes: 'project' keeps the entry in ``projects[<cwd>]`` of
|
||||
# ~/.claude.json, 'user' puts it in the machine-wide map. Project is the default
|
||||
# because a code-memory server that fails to start at user scope degrades every
|
||||
# Claude Code session on the machine, including projects Headroom never touched
|
||||
# (#2787). Flows through an env var for the same reason as _code_memory_option.
|
||||
_CODE_MEMORY_SCOPE_ENV = "HEADROOM_CODE_MEMORY_SCOPE"
|
||||
_CODE_MEMORY_SCOPE_PROJECT = "project"
|
||||
_CODE_MEMORY_SCOPE_USER = "user"
|
||||
_VALID_CODE_MEMORY_SCOPES = {_CODE_MEMORY_SCOPE_PROJECT, _CODE_MEMORY_SCOPE_USER}
|
||||
|
||||
|
||||
def _resolve_code_memory_scope() -> str:
|
||||
"""Resolve the requested code-memory scope ('project' by default)."""
|
||||
env = os.environ.get(_CODE_MEMORY_SCOPE_ENV, "").strip().lower()
|
||||
if env:
|
||||
if env not in _VALID_CODE_MEMORY_SCOPES:
|
||||
raise click.ClickException(
|
||||
f"{_CODE_MEMORY_SCOPE_ENV} must be one of: "
|
||||
f"{', '.join(sorted(_VALID_CODE_MEMORY_SCOPES))}"
|
||||
)
|
||||
return env
|
||||
return _CODE_MEMORY_SCOPE_PROJECT
|
||||
|
||||
|
||||
def _claude_code_memory_scope() -> str:
|
||||
"""Translate the requested scope into Claude Code's own scope name."""
|
||||
from headroom.mcp_registry.claude import SCOPE_LOCAL, SCOPE_USER
|
||||
|
||||
if _resolve_code_memory_scope() == _CODE_MEMORY_SCOPE_USER:
|
||||
return SCOPE_USER
|
||||
return SCOPE_LOCAL
|
||||
|
||||
|
||||
def _code_memory_scope_flag_callback(ctx: Any, param: Any, value: str | None) -> str | None:
|
||||
"""Click eager callback: mirror ``--code-memory-scope`` into the env var the
|
||||
resolver reads, so no subcommand signature changes."""
|
||||
if value:
|
||||
os.environ[_CODE_MEMORY_SCOPE_ENV] = value
|
||||
return value
|
||||
|
||||
|
||||
_code_memory_scope_option = click.option(
|
||||
"--code-memory-scope",
|
||||
type=click.Choice([_CODE_MEMORY_SCOPE_PROJECT, _CODE_MEMORY_SCOPE_USER]),
|
||||
default=None,
|
||||
expose_value=False,
|
||||
is_eager=True,
|
||||
callback=_code_memory_scope_flag_callback,
|
||||
help=(
|
||||
"Where to register the code-memory MCP: 'project' (default, this "
|
||||
"directory only) or 'user' (every Claude Code session on the machine). "
|
||||
"Also set by HEADROOM_CODE_MEMORY_SCOPE."
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
# Hook-command markers Headroom manages in Claude settings.json. unwrap drops
|
||||
# any hook entry whose command contains one of these. (Retired rtk / lean-ctx
|
||||
# hooks are removed separately, by
|
||||
@@ -2460,6 +2518,8 @@ def _setup_serena_mcp(
|
||||
from headroom.mcp_registry.base import RegisterStatus
|
||||
from headroom.mcp_registry.ledger import headroom_installed_matching, record_install
|
||||
|
||||
ownership_key = getattr(registrar, "ownership_key", lambda name: name)("serena")
|
||||
|
||||
if not registrar.detect():
|
||||
if verbose:
|
||||
click.echo(f" Serena MCP: {registrar.display_name} not detected — skipping")
|
||||
@@ -2477,7 +2537,9 @@ def _setup_serena_mcp(
|
||||
owned_drift = (
|
||||
result.status == RegisterStatus.MISMATCH
|
||||
and not force
|
||||
and headroom_installed_matching(registrar.name, registrar.get_server("serena"))
|
||||
and headroom_installed_matching(
|
||||
registrar.name, registrar.get_server("serena"), ownership_key=ownership_key
|
||||
)
|
||||
)
|
||||
|
||||
# Migrate a stale Headroom-installed entry. register_server won't overwrite
|
||||
@@ -2490,8 +2552,15 @@ def _setup_serena_mcp(
|
||||
if result.status == RegisterStatus.REGISTERED:
|
||||
click.echo(" Serena MCP: migrated previously-installed entry to current spec")
|
||||
|
||||
# Retire the machine-wide entry once the project-scoped one is in place.
|
||||
# Must run before record_install below: the ledger still holds the
|
||||
# fingerprint of the entry that was installed globally, which is how we
|
||||
# recognise it as ours.
|
||||
if result.ok:
|
||||
_retire_user_scope_serena(registrar)
|
||||
|
||||
if result.status == RegisterStatus.REGISTERED:
|
||||
record_install(registrar.name, spec)
|
||||
record_install(registrar.name, spec, ownership_key=ownership_key)
|
||||
|
||||
line = format_result(
|
||||
registrar.name,
|
||||
@@ -2510,6 +2579,11 @@ def _setup_serena_mcp(
|
||||
if line is not None:
|
||||
click.echo(line)
|
||||
|
||||
# Say where it landed, so the scope is discoverable without reading docs.
|
||||
# Only on an actual write (or in verbose): re-wraps should stay quiet.
|
||||
if result.status == RegisterStatus.REGISTERED or verbose:
|
||||
_echo_serena_scope_note(registrar)
|
||||
|
||||
# Serena is the active engine here (we passed the detect/uvx guards): steer
|
||||
# the agent toward symbol-level tools, then warm the symbol cache. Both are
|
||||
# best-effort and non-fatal, and neither blocks the launch: the pre-index
|
||||
@@ -2535,10 +2609,90 @@ def _setup_serena_mcp(
|
||||
_index_serena_project(verbose=verbose)
|
||||
|
||||
|
||||
def _echo_serena_scope_note(registrar: Any) -> None:
|
||||
"""Tell the user which sessions the Serena entry will load in."""
|
||||
from headroom.mcp_registry.claude import SCOPE_LOCAL, SCOPE_USER
|
||||
|
||||
scope = getattr(registrar, "scope", None)
|
||||
if scope == SCOPE_LOCAL:
|
||||
click.echo(
|
||||
" scoped to this project — pass --code-memory-scope user to register it "
|
||||
"for every Claude Code session"
|
||||
)
|
||||
elif scope == SCOPE_USER:
|
||||
click.echo(
|
||||
" registered for every Claude Code session on this machine "
|
||||
"(--code-memory-scope user)"
|
||||
)
|
||||
|
||||
|
||||
def _retire_user_scope_serena(registrar: Any) -> None:
|
||||
"""Remove a machine-wide Serena entry left by a pre-#2787 wrap.
|
||||
|
||||
Headroom used to register Serena at Claude Code's user scope, where a
|
||||
Serena that fails to start breaks *every* Claude Code session on the
|
||||
machine — including projects that were never wrapped (#2783). Now that the
|
||||
entry is written per project, the global one is redundant, so an upgrading
|
||||
user gets it cleaned up on their next wrap instead of carrying the blast
|
||||
radius forever.
|
||||
|
||||
Only entries the ledger proves Headroom installed are removed; a Serena the
|
||||
user registered globally themselves is left exactly where it is. No-ops for
|
||||
registrars without scopes (Codex, Grok, OpenCode) and when the user asked
|
||||
for user scope explicitly.
|
||||
"""
|
||||
from headroom.mcp_registry.claude import SCOPE_LOCAL, SCOPE_USER
|
||||
from headroom.mcp_registry.ledger import clear_install, headroom_installed_matching
|
||||
|
||||
if getattr(registrar, "scope", None) != SCOPE_LOCAL:
|
||||
return
|
||||
try:
|
||||
global_entry = registrar.get_server("serena", scope=SCOPE_USER)
|
||||
except TypeError: # registrar predates scoped reads
|
||||
return
|
||||
if not headroom_installed_matching(registrar.name, global_entry):
|
||||
return
|
||||
if registrar.unregister_server("serena", scope=SCOPE_USER):
|
||||
# Clear the legacy ledger record along with the config entry it
|
||||
# authorized — otherwise its fingerprint outlives the migration and
|
||||
# can later be mistaken for proof that Headroom owns a same-named
|
||||
# entry the user installs globally themselves.
|
||||
clear_install(registrar.name, "serena")
|
||||
click.echo(
|
||||
" Serena MCP: removed the machine-wide entry an earlier wrap installed "
|
||||
"(it now loads only in this project)"
|
||||
)
|
||||
|
||||
|
||||
def _remove_headroom_installed_serena_mcp(registrar: Any) -> str:
|
||||
"""Remove Serena MCP only if the ledger proves Headroom installed it."""
|
||||
from headroom.mcp_registry.ledger import clear_install, headroom_installed_matching
|
||||
|
||||
# Claude can own one Serena entry per project plus a legacy user entry.
|
||||
# Examine each relevant scope independently: an unscoped delete would
|
||||
# remove entries whose scope-specific ledger record did not authorize it.
|
||||
if hasattr(registrar, "ownership_key"):
|
||||
from headroom.mcp_registry.claude import SCOPE_LOCAL, SCOPE_USER
|
||||
|
||||
found_owned = False
|
||||
for scope in (SCOPE_LOCAL, SCOPE_USER):
|
||||
current = registrar.get_server("serena", scope=scope)
|
||||
ownership_key = registrar.ownership_key("serena", scope=scope)
|
||||
if current is None:
|
||||
# Nothing left to protect — an ownership record must not
|
||||
# outlive the entry it authorized.
|
||||
clear_install(registrar.name, "serena", ownership_key=ownership_key)
|
||||
continue
|
||||
if not headroom_installed_matching(
|
||||
registrar.name, current, ownership_key=ownership_key
|
||||
):
|
||||
continue
|
||||
found_owned = True
|
||||
if not registrar.unregister_server("serena", scope=scope):
|
||||
return "failed"
|
||||
clear_install(registrar.name, "serena", ownership_key=ownership_key)
|
||||
return "removed" if found_owned else "not_headroom_owned"
|
||||
|
||||
current = registrar.get_server("serena")
|
||||
if not headroom_installed_matching(registrar.name, current):
|
||||
return "not_headroom_owned"
|
||||
@@ -2596,10 +2750,21 @@ def _remove_headroom_installed_tokensave_mcp(registrar: Any) -> str:
|
||||
"""Remove the tokensave MCP entry only if the ledger proves Headroom installed it."""
|
||||
from headroom.mcp_registry.ledger import clear_install, headroom_installed_matching
|
||||
|
||||
current = registrar.get_server("tokensave")
|
||||
# Headroom only ever installed tokensave machine-wide: it was retired before
|
||||
# #2787 introduced project scope, so its ledger key is the pre-scope (user
|
||||
# scope) one. Pin the ownership check and the delete to that scope — an
|
||||
# unscoped delete now also takes the project entry, which no ledger record
|
||||
# authorizes, and an unscoped read lets a project entry shadow ours.
|
||||
at_user_scope: dict[str, Any] = {}
|
||||
if hasattr(registrar, "ownership_key"): # Claude; the others have no scopes
|
||||
from headroom.mcp_registry.claude import SCOPE_USER
|
||||
|
||||
at_user_scope = {"scope": SCOPE_USER}
|
||||
|
||||
current = registrar.get_server("tokensave", **at_user_scope)
|
||||
if not headroom_installed_matching(registrar.name, current):
|
||||
return "not_headroom_owned"
|
||||
if registrar.unregister_server("tokensave"):
|
||||
if registrar.unregister_server("tokensave", **at_user_scope):
|
||||
clear_install(registrar.name, "tokensave")
|
||||
return "removed"
|
||||
return "failed"
|
||||
@@ -5460,6 +5625,7 @@ def wrap_selfheal(marker: str | None) -> None:
|
||||
help="Skip headroom MCP server registration (compression markers will be unactionable)",
|
||||
)
|
||||
@_code_memory_option
|
||||
@_code_memory_scope_option
|
||||
@click.option(
|
||||
"--no-tokensave",
|
||||
is_flag=True,
|
||||
@@ -5559,6 +5725,7 @@ def claude(
|
||||
headroom wrap claude -- -p # Claude in print mode
|
||||
headroom wrap claude --no-mcp # Skip MCP retrieve tool registration
|
||||
headroom wrap claude --code-memory none # No code-memory MCP
|
||||
headroom wrap claude --code-memory-scope user # Serena in every session, not just here
|
||||
headroom wrap claude --1m # Preserve the 1M context window
|
||||
"""
|
||||
if prepare_only:
|
||||
@@ -5700,10 +5867,15 @@ def claude(
|
||||
click.echo(" Skipping MCP retrieve tool (--no-mcp)")
|
||||
|
||||
# Coding-task compressor: Serena (retires any legacy tokensave entry).
|
||||
# Registered per project by default so a Serena that cannot start takes
|
||||
# down this project's sessions only, never every Claude Code session on
|
||||
# the machine (#2787). --code-memory-scope user restores the old
|
||||
# machine-wide registration. The Headroom MCP registrar above keeps user
|
||||
# scope: it is our own server and every wrap exercises it.
|
||||
from headroom.mcp_registry import CLAUDE_SERENA_CONTEXT, ClaudeRegistrar
|
||||
|
||||
_setup_coding_compressor(
|
||||
ClaudeRegistrar(),
|
||||
ClaudeRegistrar(scope=_claude_code_memory_scope()),
|
||||
serena_context=CLAUDE_SERENA_CONTEXT,
|
||||
serena=serena,
|
||||
no_serena=no_serena,
|
||||
|
||||
+214
-46
@@ -1,13 +1,28 @@
|
||||
"""Claude Code MCP registrar.
|
||||
|
||||
Claude Code 2.x stores user-scope MCP server configuration in
|
||||
``~/.claude.json``, directly under the home directory. The ``claude`` CLI
|
||||
(``claude mcp add/remove/list/get``) owns this file; setting
|
||||
``CLAUDE_CONFIG_DIR`` relocates it to ``$CLAUDE_CONFIG_DIR/.claude.json``.
|
||||
Older Claude Code releases (and the Claude Desktop app) read
|
||||
``~/.claude/mcp.json`` instead. This registrar prefers the CLI for writes
|
||||
when available, and reads the underlying JSON files directly for compare /
|
||||
``get_server`` so it is robust to CLI output format changes.
|
||||
Claude Code 2.x stores MCP server configuration in ``~/.claude.json``,
|
||||
directly under the home directory. The ``claude`` CLI (``claude mcp
|
||||
add/remove/list/get``) owns this file; setting ``CLAUDE_CONFIG_DIR``
|
||||
relocates it to ``$CLAUDE_CONFIG_DIR/.claude.json``. Older Claude Code
|
||||
releases (and the Claude Desktop app) read ``~/.claude/mcp.json`` instead.
|
||||
This registrar prefers the CLI for writes when available, and reads the
|
||||
underlying JSON files directly for compare / ``get_server`` so it is robust
|
||||
to CLI output format changes.
|
||||
|
||||
Two of Claude Code's scopes matter here (see ``claude mcp add --scope``):
|
||||
|
||||
``user``
|
||||
The top-level ``mcpServers`` map. Loads in **every** Claude Code session
|
||||
on the machine, in every directory.
|
||||
``local``
|
||||
``projects[<cwd>].mcpServers``. Loads only for sessions started in that
|
||||
one directory, and takes precedence over a user-scope entry of the same
|
||||
name.
|
||||
|
||||
Scope is a blast-radius decision, not a preference: a server registered at
|
||||
user scope that fails to start degrades every session on the machine, not
|
||||
just the project it was installed for (#2787). Servers whose failure modes
|
||||
we do not control belong at ``local``.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -25,6 +40,14 @@ from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
#: Claude Code scope covering every session on the machine.
|
||||
SCOPE_USER = "user"
|
||||
|
||||
#: Claude Code scope covering only sessions started in one directory.
|
||||
SCOPE_LOCAL = "local"
|
||||
|
||||
_VALID_SCOPES = (SCOPE_USER, SCOPE_LOCAL)
|
||||
|
||||
|
||||
class ClaudeConfigMutationError(ValueError):
|
||||
"""Raised when a Claude config cannot be safely changed."""
|
||||
@@ -42,6 +65,8 @@ class ClaudeRegistrar(MCPRegistrar):
|
||||
claude_cli: str | None | object = ...,
|
||||
home_dir: Path | None = None,
|
||||
config_dir: Path | None = None,
|
||||
scope: str = SCOPE_USER,
|
||||
project_dir: Path | None = None,
|
||||
) -> None:
|
||||
"""Allow overrides for testing.
|
||||
|
||||
@@ -53,7 +78,20 @@ class ClaudeRegistrar(MCPRegistrar):
|
||||
is passed explicitly. It does not isolate CLI subprocess calls (see
|
||||
``claude_cli``) — pass ``claude_cli=None`` alongside ``home_dir`` to
|
||||
keep a test fully off the real ``claude`` binary.
|
||||
|
||||
``scope`` selects where :meth:`register_server` writes: ``"user"``
|
||||
(default, machine-wide) or ``"local"`` (the current project only).
|
||||
Reads and removals span both scopes unless told otherwise, so a
|
||||
caller that switches scope still finds — and can clean up — an entry
|
||||
an earlier release installed elsewhere. ``project_dir`` overrides the
|
||||
directory ``local`` scope resolves to (test seam); real callers rely
|
||||
on the process working directory, which is what Claude Code itself
|
||||
keys sessions by.
|
||||
"""
|
||||
if scope not in _VALID_SCOPES:
|
||||
raise ValueError(f"scope must be one of {_VALID_SCOPES}, got {scope!r}")
|
||||
self.scope = scope
|
||||
self._project_dir_override = project_dir
|
||||
home = home_dir if home_dir is not None else Path.home()
|
||||
modern_dir = _resolve_claude_config_dir(home, config_dir, honor_env=home_dir is None)
|
||||
# Legacy config lives under the real ``.claude`` directory regardless
|
||||
@@ -84,13 +122,22 @@ class ClaudeRegistrar(MCPRegistrar):
|
||||
return True
|
||||
return self._claude_dir.is_dir() or self._modern_config.exists()
|
||||
|
||||
def get_server(self, server_name: str) -> ServerSpec | None:
|
||||
def get_server(self, server_name: str, *, scope: str | None = None) -> ServerSpec | None:
|
||||
"""Return the registered spec, or ``None``.
|
||||
|
||||
With no ``scope``, search project scope first, then user scope — the
|
||||
order Claude Code itself resolves them in, so the answer is the entry
|
||||
the agent would actually launch. Pass ``scope`` to ask about one
|
||||
specific location (e.g. "is there still a user-scope entry to clean
|
||||
up?").
|
||||
"""
|
||||
# Read from disk regardless of whether the CLI is present — the file
|
||||
# format is stable and easier to compare than CLI output.
|
||||
for config_path in (self._modern_config, self._legacy_config):
|
||||
entry = self._read_server_entry(config_path, server_name)
|
||||
if entry is not None:
|
||||
return entry
|
||||
for search_scope in self._scopes(scope):
|
||||
for config_path in self._config_paths(search_scope):
|
||||
entry = self._read_server_entry(config_path, server_name, search_scope)
|
||||
if entry is not None:
|
||||
return entry
|
||||
return None
|
||||
|
||||
def get_plugin_servers(self, server_name: str) -> list[tuple[str, ServerSpec]]:
|
||||
@@ -153,7 +200,10 @@ class ClaudeRegistrar(MCPRegistrar):
|
||||
)
|
||||
|
||||
def register_server(self, spec: ServerSpec, *, force: bool = False) -> RegisterResult:
|
||||
existing = self.get_server(spec.name)
|
||||
# Compare against the entry in the scope we are about to write, not
|
||||
# against any entry anywhere: a leftover user-scope copy must not make
|
||||
# a project-scope registration look like a no-op.
|
||||
existing = self.get_server(spec.name, scope=self.scope)
|
||||
if existing is not None:
|
||||
if _specs_equivalent(existing, spec):
|
||||
return RegisterResult(RegisterStatus.ALREADY, "matches current configuration")
|
||||
@@ -162,30 +212,42 @@ class ClaudeRegistrar(MCPRegistrar):
|
||||
RegisterStatus.MISMATCH,
|
||||
_diff_specs(existing, spec),
|
||||
)
|
||||
# force=True: remove first, then write fresh below.
|
||||
self.unregister_server(spec.name)
|
||||
# force=True: remove first, then write fresh below. Restricted to
|
||||
# the scope we are writing — overwriting the project entry must not
|
||||
# also delete a machine-wide one the user registered themselves.
|
||||
self.unregister_server(spec.name, scope=self.scope)
|
||||
|
||||
if self._claude_cli:
|
||||
return self._register_via_cli(spec)
|
||||
return self._register_via_file(spec)
|
||||
|
||||
def unregister_server(self, server_name: str) -> bool:
|
||||
def unregister_server(self, server_name: str, *, scope: str | None = None) -> bool:
|
||||
"""Remove the named server. Returns True if anything was removed.
|
||||
|
||||
With no ``scope``, remove from user scope *and* the current project's
|
||||
scope, so ``unwrap`` cleans up no matter which one installed the entry
|
||||
(a pre-#2787 release put Serena at user scope). Only the current
|
||||
project is touched — unwrapping one project must not deregister the
|
||||
server in every other project it was wrapped into.
|
||||
"""
|
||||
removed = False
|
||||
if self._claude_cli:
|
||||
result = run(
|
||||
[str(self._claude_cli), "mcp", "remove", server_name, "-s", "user"],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
env=self._claude_cli_env(),
|
||||
)
|
||||
if result.returncode == 0:
|
||||
removed = True
|
||||
else:
|
||||
logger.debug("claude mcp remove failed: %s", result.stderr.strip())
|
||||
# Always clean up both files too — the CLI only touches the modern
|
||||
# config, so a legacy entry (or one it didn't know about) can remain.
|
||||
for config_path in (self._modern_config, self._legacy_config):
|
||||
removed = self._remove_from_file(config_path, server_name) or removed
|
||||
for target_scope in self._scopes(scope):
|
||||
if self._claude_cli:
|
||||
result = run(
|
||||
[str(self._claude_cli), "mcp", "remove", server_name, "-s", target_scope],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
env=self._claude_cli_env(),
|
||||
cwd=self._cli_cwd(target_scope),
|
||||
)
|
||||
if result.returncode == 0:
|
||||
removed = True
|
||||
else:
|
||||
logger.debug("claude mcp remove failed: %s", result.stderr.strip())
|
||||
# Always clean up the files too — the CLI only touches the modern
|
||||
# config, so a legacy entry (or one it didn't know about) can remain.
|
||||
for config_path in self._config_paths(target_scope):
|
||||
removed = self._remove_from_file(config_path, server_name, target_scope) or removed
|
||||
return removed
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
@@ -193,7 +255,7 @@ class ClaudeRegistrar(MCPRegistrar):
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _register_via_cli(self, spec: ServerSpec) -> RegisterResult:
|
||||
cmd = [str(self._claude_cli), "mcp", "add", spec.name, "-s", "user"]
|
||||
cmd = [str(self._claude_cli), "mcp", "add", spec.name, "-s", self.scope]
|
||||
for k, v in spec.env.items():
|
||||
cmd += ["-e", f"{k}={v}"]
|
||||
cmd += ["--", spec.command, *spec.args]
|
||||
@@ -203,9 +265,12 @@ class ClaudeRegistrar(MCPRegistrar):
|
||||
capture_output=True,
|
||||
text=True,
|
||||
env=self._claude_cli_env(),
|
||||
cwd=self._cli_cwd(self.scope),
|
||||
)
|
||||
if result.returncode == 0:
|
||||
return RegisterResult(RegisterStatus.REGISTERED, "via `claude mcp add` (scope: user)")
|
||||
return RegisterResult(
|
||||
RegisterStatus.REGISTERED, f"via `claude mcp add` (scope: {self.scope})"
|
||||
)
|
||||
# CLI failed — try the file fallback rather than giving up.
|
||||
logger.warning("claude mcp add failed: %s", result.stderr.strip())
|
||||
file_result = self._register_via_file(spec)
|
||||
@@ -225,17 +290,20 @@ class ClaudeRegistrar(MCPRegistrar):
|
||||
|
||||
def _register_via_file(self, spec: ServerSpec) -> RegisterResult:
|
||||
# Prefer the modern config path. If only the legacy file exists,
|
||||
# write to that to avoid surprising older clients.
|
||||
# write to that to avoid surprising older clients — but project scope
|
||||
# only exists in the modern config, so it always goes there.
|
||||
target = self._modern_config
|
||||
if not self._modern_config.exists() and self._legacy_config.exists():
|
||||
if (
|
||||
self.scope == SCOPE_USER
|
||||
and not self._modern_config.exists()
|
||||
and self._legacy_config.exists()
|
||||
):
|
||||
target = self._legacy_config
|
||||
|
||||
try:
|
||||
target.parent.mkdir(parents=True, exist_ok=True)
|
||||
config = _read_json_for_write(target)
|
||||
servers = config.get("mcpServers")
|
||||
if not isinstance(servers, dict):
|
||||
config["mcpServers"] = servers = {}
|
||||
servers = self._servers_map_for_write(config)
|
||||
servers[spec.name] = _spec_to_entry(spec)
|
||||
_write_json(target, config)
|
||||
except _MalformedConfigError as exc:
|
||||
@@ -248,17 +316,17 @@ class ClaudeRegistrar(MCPRegistrar):
|
||||
)
|
||||
except OSError as exc:
|
||||
return RegisterResult(RegisterStatus.FAILED, f"could not write {target}: {exc}")
|
||||
return RegisterResult(RegisterStatus.REGISTERED, f"wrote to {target}")
|
||||
return RegisterResult(RegisterStatus.REGISTERED, f"wrote to {target} (scope: {self.scope})")
|
||||
|
||||
def _remove_from_file(self, path: Path, server_name: str) -> bool:
|
||||
def _remove_from_file(self, path: Path, server_name: str, scope: str) -> bool:
|
||||
if not path.exists():
|
||||
return False
|
||||
try:
|
||||
config = _read_json(path)
|
||||
except OSError:
|
||||
return False
|
||||
servers = config.get("mcpServers")
|
||||
if not isinstance(servers, dict) or server_name not in servers:
|
||||
servers = self._servers_map(config, scope)
|
||||
if servers is None or server_name not in servers:
|
||||
return False
|
||||
del servers[server_name]
|
||||
try:
|
||||
@@ -267,25 +335,125 @@ class ClaudeRegistrar(MCPRegistrar):
|
||||
return False
|
||||
return True
|
||||
|
||||
def _read_server_entry(self, path: Path, server_name: str) -> ServerSpec | None:
|
||||
def _read_server_entry(self, path: Path, server_name: str, scope: str) -> ServerSpec | None:
|
||||
if not path.exists():
|
||||
return None
|
||||
try:
|
||||
config = _read_json(path)
|
||||
except OSError:
|
||||
return None
|
||||
servers = config.get("mcpServers")
|
||||
if not isinstance(servers, dict):
|
||||
servers = self._servers_map(config, scope)
|
||||
if servers is None:
|
||||
return None
|
||||
entry = servers.get(server_name)
|
||||
if not isinstance(entry, dict):
|
||||
return None
|
||||
return _entry_to_spec(server_name, entry)
|
||||
|
||||
# ----------------------------------------------------------------------
|
||||
# Scope helpers
|
||||
# ----------------------------------------------------------------------
|
||||
|
||||
def _scopes(self, scope: str | None) -> tuple[str, ...]:
|
||||
"""Scopes to act on: the one requested, or project-then-user."""
|
||||
if scope is not None:
|
||||
if scope not in _VALID_SCOPES:
|
||||
raise ValueError(f"scope must be one of {_VALID_SCOPES}, got {scope!r}")
|
||||
return (scope,)
|
||||
return (SCOPE_LOCAL, SCOPE_USER)
|
||||
|
||||
def _config_paths(self, scope: str) -> tuple[Path, ...]:
|
||||
"""Config files that can hold an entry at ``scope``.
|
||||
|
||||
The legacy ``~/.claude/mcp.json`` has no notion of projects, so it is
|
||||
only consulted for user scope.
|
||||
"""
|
||||
if scope == SCOPE_LOCAL:
|
||||
return (self._modern_config,)
|
||||
return (self._modern_config, self._legacy_config)
|
||||
|
||||
def _project_dir(self) -> Path:
|
||||
"""Directory project scope applies to (the session's working directory)."""
|
||||
if self._project_dir_override is not None:
|
||||
return self._project_dir_override
|
||||
return Path.cwd()
|
||||
|
||||
def ownership_key(self, server_name: str, *, scope: str | None = None) -> str:
|
||||
"""Stable ledger key for one Claude scope without exposing config paths."""
|
||||
target_scope = scope or self.scope
|
||||
if target_scope == SCOPE_USER:
|
||||
# Preserve the pre-scope key so existing installs migrate safely.
|
||||
return server_name
|
||||
project = os.path.normcase(os.path.normpath(str(self._project_dir().resolve())))
|
||||
return f"{server_name}:local:{project}"
|
||||
|
||||
def _project_key(self, config: dict[str, Any]) -> str:
|
||||
"""Key under ``projects`` naming the current directory.
|
||||
|
||||
Claude Code keys this map by the session's working directory as a
|
||||
string — with forward slashes even on Windows. Reuse whatever key an
|
||||
existing entry already uses when it names the same directory, so we
|
||||
never add a second entry Claude Code will not read; otherwise write
|
||||
the forward-slash form it would write itself.
|
||||
"""
|
||||
cwd = self._project_dir()
|
||||
target = os.path.normcase(os.path.normpath(str(cwd)))
|
||||
projects = config.get("projects")
|
||||
if isinstance(projects, dict):
|
||||
for key in projects:
|
||||
if isinstance(key, str) and os.path.normcase(os.path.normpath(key)) == target:
|
||||
return key
|
||||
return cwd.as_posix()
|
||||
|
||||
def _servers_map(self, config: dict[str, Any], scope: str) -> dict[str, Any] | None:
|
||||
"""Return the ``mcpServers`` map for ``scope``, or ``None`` if absent.
|
||||
|
||||
Read-only: the returned dict is the one inside ``config``, so callers
|
||||
on the write path can mutate it, but nothing is created here.
|
||||
"""
|
||||
container: Any = config
|
||||
if scope == SCOPE_LOCAL:
|
||||
projects = config.get("projects")
|
||||
if not isinstance(projects, dict):
|
||||
return None
|
||||
container = projects.get(self._project_key(config))
|
||||
if not isinstance(container, dict):
|
||||
return None
|
||||
servers = container.get("mcpServers")
|
||||
return servers if isinstance(servers, dict) else None
|
||||
|
||||
def _servers_map_for_write(self, config: dict[str, Any]) -> dict[str, Any]:
|
||||
"""Return the ``mcpServers`` map for this registrar's scope, creating it."""
|
||||
container: dict[str, Any] = config
|
||||
if self.scope == SCOPE_LOCAL:
|
||||
projects = config.get("projects")
|
||||
if not isinstance(projects, dict):
|
||||
config["projects"] = projects = {}
|
||||
key = self._project_key(config)
|
||||
project = projects.get(key)
|
||||
if not isinstance(project, dict):
|
||||
projects[key] = project = {}
|
||||
container = project
|
||||
servers = container.get("mcpServers")
|
||||
if not isinstance(servers, dict):
|
||||
container["mcpServers"] = servers = {}
|
||||
return servers
|
||||
|
||||
# ----------------------------------------------------------------------
|
||||
# Helpers
|
||||
# ----------------------------------------------------------------------
|
||||
|
||||
def _cli_cwd(self, scope: str) -> str | None:
|
||||
"""Working directory for a CLI call, or ``None`` to inherit ours.
|
||||
|
||||
``claude mcp add -s local`` keys the entry by the *CLI process's*
|
||||
working directory, so a registrar pointed at a different project
|
||||
directory has to move the subprocess with it.
|
||||
"""
|
||||
if scope != SCOPE_LOCAL or self._project_dir_override is None:
|
||||
return None
|
||||
return str(self._project_dir_override)
|
||||
|
||||
def _claude_cli_env(self) -> dict[str, str] | None:
|
||||
if not self._isolated_cli_env:
|
||||
return None
|
||||
|
||||
@@ -42,7 +42,13 @@ def spec_fingerprint(spec: ServerSpec) -> str:
|
||||
return hashlib.sha256(raw).hexdigest()
|
||||
|
||||
|
||||
def record_install(agent: str, spec: ServerSpec, *, path: Path | None = None) -> None:
|
||||
def record_install(
|
||||
agent: str,
|
||||
spec: ServerSpec,
|
||||
*,
|
||||
path: Path | None = None,
|
||||
ownership_key: str | None = None,
|
||||
) -> None:
|
||||
"""Record that Headroom installed ``spec`` for ``agent``."""
|
||||
ledger_file = path or ledger_path()
|
||||
# Automatic installs must recover from a stale or damaged ledger. The
|
||||
@@ -56,14 +62,20 @@ def record_install(agent: str, spec: ServerSpec, *, path: Path | None = None) ->
|
||||
if not isinstance(agent_entry, dict):
|
||||
agent_entry = {}
|
||||
agents[agent] = agent_entry
|
||||
agent_entry[spec.name] = {
|
||||
agent_entry[ownership_key or spec.name] = {
|
||||
"fingerprint": spec_fingerprint(spec),
|
||||
"installed_at": datetime.now(timezone.utc).isoformat(),
|
||||
}
|
||||
_write_ledger(ledger_file, data)
|
||||
|
||||
|
||||
def clear_install(agent: str, server_name: str, *, path: Path | None = None) -> None:
|
||||
def clear_install(
|
||||
agent: str,
|
||||
server_name: str,
|
||||
*,
|
||||
path: Path | None = None,
|
||||
ownership_key: str | None = None,
|
||||
) -> None:
|
||||
"""Remove one ledger entry if present."""
|
||||
ledger_file = path or ledger_path()
|
||||
data = _read_ledger(ledger_file)
|
||||
@@ -71,9 +83,10 @@ def clear_install(agent: str, server_name: str, *, path: Path | None = None) ->
|
||||
if not isinstance(agents, dict):
|
||||
return
|
||||
agent_entry = agents.get(agent)
|
||||
if not isinstance(agent_entry, dict) or server_name not in agent_entry:
|
||||
key = ownership_key or server_name
|
||||
if not isinstance(agent_entry, dict) or key not in agent_entry:
|
||||
return
|
||||
del agent_entry[server_name]
|
||||
del agent_entry[key]
|
||||
if not agent_entry:
|
||||
del agents[agent]
|
||||
if not agents:
|
||||
@@ -86,6 +99,7 @@ def headroom_installed_matching(
|
||||
current_spec: ServerSpec | None,
|
||||
*,
|
||||
path: Path | None = None,
|
||||
ownership_key: str | None = None,
|
||||
) -> bool:
|
||||
"""Return True when the ledger says Headroom installed ``current_spec``."""
|
||||
if current_spec is None:
|
||||
@@ -93,7 +107,7 @@ def headroom_installed_matching(
|
||||
ledger_file = path or ledger_path()
|
||||
data = _read_ledger(ledger_file)
|
||||
try:
|
||||
entry = data["agents"][agent][current_spec.name]
|
||||
entry = data["agents"][agent][ownership_key or current_spec.name]
|
||||
except (KeyError, TypeError):
|
||||
return False
|
||||
if not isinstance(entry, dict):
|
||||
|
||||
@@ -0,0 +1,329 @@
|
||||
"""Serena is registered for the wrapped project, not the whole machine (#2787).
|
||||
|
||||
Headroom used to register Serena at Claude Code's ``user`` scope, so every
|
||||
Claude Code session on the machine launched it — including sessions in
|
||||
projects that were never wrapped. When Serena could not start, that took down
|
||||
Claude Code everywhere, and the only recovery was ``headroom unwrap claude``
|
||||
(#2783).
|
||||
|
||||
``headroom wrap claude`` now registers Serena at ``local`` scope: it loads
|
||||
only in the directory that was wrapped. ``--code-memory-scope user`` restores
|
||||
the old machine-wide behaviour, and an existing global entry that Headroom
|
||||
installed is retired on the next wrap.
|
||||
|
||||
These tests drive ``_setup_serena_mcp`` with a real ``ClaudeRegistrar`` whose
|
||||
home directory is a tmp_path, so the assertions are about the JSON Claude Code
|
||||
actually reads.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import shutil
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import pytest
|
||||
|
||||
from headroom.cli import wrap as wrap_cli
|
||||
from headroom.mcp_registry import build_serena_spec
|
||||
from headroom.mcp_registry.base import ServerSpec
|
||||
from headroom.mcp_registry.claude import SCOPE_LOCAL, SCOPE_USER, ClaudeRegistrar
|
||||
from headroom.mcp_registry.ledger import record_install
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def _isolate_env(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
|
||||
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
|
||||
monkeypatch.delenv("HEADROOM_CODE_MEMORY_SCOPE", raising=False)
|
||||
# ``_setup_serena_mcp`` bails out early when uvx is missing, which would
|
||||
# skip every path under test on runners without uv installed.
|
||||
real_which = shutil.which
|
||||
monkeypatch.setattr(
|
||||
wrap_cli.shutil,
|
||||
"which",
|
||||
lambda name, *a, **k: "/usr/bin/uvx" if name == "uvx" else real_which(name, *a, **k),
|
||||
)
|
||||
# Everything past registration touches the real home directory or shells
|
||||
# out to uvx. Covered elsewhere; neutralise it so these stay hermetic.
|
||||
monkeypatch.setattr(wrap_cli, "_ensure_serena_dashboard_disabled", lambda *a, **k: None)
|
||||
monkeypatch.setattr(wrap_cli, "_inject_serena_instructions", lambda *a, **k: True)
|
||||
monkeypatch.setattr(wrap_cli, "_index_serena_project", lambda *a, **k: None)
|
||||
|
||||
|
||||
def _registrar(tmp_path: Path, *, scope: str = SCOPE_LOCAL) -> ClaudeRegistrar:
|
||||
"""Real registrar writing into ``tmp_path`` instead of the user's home."""
|
||||
# With no CLI, ``detect`` looks for a ~/.claude directory or config file.
|
||||
(tmp_path / ".claude").mkdir(exist_ok=True)
|
||||
return ClaudeRegistrar(
|
||||
claude_cli=None, # force the file path; never touch the real CLI
|
||||
home_dir=tmp_path,
|
||||
scope=scope,
|
||||
project_dir=tmp_path / "proj",
|
||||
)
|
||||
|
||||
|
||||
def _config(tmp_path: Path) -> dict[str, Any]:
|
||||
return json.loads((tmp_path / ".claude.json").read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
def _project_servers(tmp_path: Path) -> dict[str, Any]:
|
||||
project_key = (tmp_path / "proj").as_posix()
|
||||
return _config(tmp_path)["projects"][project_key]["mcpServers"]
|
||||
|
||||
|
||||
def _seed_global_serena(tmp_path: Path, spec: ServerSpec) -> None:
|
||||
"""Write ``spec`` into the machine-wide map, as a pre-#2787 wrap did."""
|
||||
entry: dict[str, Any] = {"command": spec.command, "args": list(spec.args)}
|
||||
if spec.env:
|
||||
entry["env"] = dict(spec.env)
|
||||
(tmp_path / ".claude.json").write_text(
|
||||
json.dumps({"mcpServers": {"serena": entry}}), encoding="utf-8"
|
||||
)
|
||||
|
||||
|
||||
def test_wrap_registers_serena_for_this_project_only(
|
||||
tmp_path: Path, capsys: pytest.CaptureFixture[str]
|
||||
) -> None:
|
||||
registrar = _registrar(tmp_path)
|
||||
|
||||
wrap_cli._setup_serena_mcp(registrar, context="claude-code", verbose=True)
|
||||
|
||||
assert "serena" in _project_servers(tmp_path)
|
||||
# The machine-wide map is what broke unrelated sessions — stay out of it.
|
||||
assert "mcpServers" not in _config(tmp_path)
|
||||
assert "scoped to this project" in capsys.readouterr().out
|
||||
|
||||
|
||||
def test_rewrap_retires_the_global_entry_headroom_installed(
|
||||
tmp_path: Path, capsys: pytest.CaptureFixture[str]
|
||||
) -> None:
|
||||
"""An upgrading user gets the machine-wide entry cleaned up automatically."""
|
||||
old_spec = build_serena_spec("claude-code")
|
||||
_seed_global_serena(tmp_path, old_spec)
|
||||
record_install("claude", old_spec) # ledger proves Headroom installed it
|
||||
|
||||
wrap_cli._setup_serena_mcp(_registrar(tmp_path), context="claude-code", verbose=True)
|
||||
|
||||
config = _config(tmp_path)
|
||||
assert config["mcpServers"] == {}
|
||||
assert "serena" in _project_servers(tmp_path)
|
||||
assert "removed the machine-wide entry" in capsys.readouterr().out
|
||||
|
||||
|
||||
def test_rewrap_retires_a_stale_global_entry(
|
||||
tmp_path: Path, capsys: pytest.CaptureFixture[str]
|
||||
) -> None:
|
||||
"""The global entry can predate the current spec and still be ours.
|
||||
|
||||
Its fingerprint is the one recorded when it was installed, so the ledger
|
||||
check has to run before the new registration overwrites that record.
|
||||
"""
|
||||
stale = ServerSpec(
|
||||
name="serena",
|
||||
command="uvx",
|
||||
args=("--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"),
|
||||
)
|
||||
_seed_global_serena(tmp_path, stale)
|
||||
record_install("claude", stale)
|
||||
|
||||
wrap_cli._setup_serena_mcp(_registrar(tmp_path), context="claude-code", verbose=True)
|
||||
|
||||
assert _config(tmp_path)["mcpServers"] == {}
|
||||
assert "serena" in _project_servers(tmp_path)
|
||||
assert "removed the machine-wide entry" in capsys.readouterr().out
|
||||
|
||||
|
||||
def test_rewrap_migration_clears_the_ledger_so_a_reinstall_is_never_deleted(
|
||||
tmp_path: Path,
|
||||
) -> None:
|
||||
"""The migration must retire its own ownership claim, not just the entry.
|
||||
|
||||
If the ledger record survived, a user who later installs the *same*
|
||||
Serena command globally themselves would collide with the old
|
||||
fingerprint, and a subsequent wrap would mistake their entry for one
|
||||
Headroom still owns and delete it out from under them.
|
||||
"""
|
||||
from headroom.mcp_registry.ledger import headroom_installed_matching
|
||||
|
||||
old_spec = build_serena_spec("claude-code")
|
||||
_seed_global_serena(tmp_path, old_spec)
|
||||
record_install("claude", old_spec)
|
||||
|
||||
(tmp_path / ".claude").mkdir(exist_ok=True)
|
||||
project_a = tmp_path / "project-a"
|
||||
project_a.mkdir()
|
||||
registrar_a = ClaudeRegistrar(
|
||||
claude_cli=None, home_dir=tmp_path, scope=SCOPE_LOCAL, project_dir=project_a
|
||||
)
|
||||
wrap_cli._setup_serena_mcp(registrar_a, context="claude-code")
|
||||
|
||||
# The migration removed the config entry - the ownership record backing
|
||||
# it must be gone too, not just the entry it pointed at.
|
||||
assert not headroom_installed_matching("claude", old_spec)
|
||||
|
||||
# The user reinstalls the identical command globally themselves.
|
||||
_seed_global_serena(tmp_path, old_spec)
|
||||
|
||||
project_b = tmp_path / "project-b"
|
||||
project_b.mkdir()
|
||||
registrar_b = ClaudeRegistrar(
|
||||
claude_cli=None, home_dir=tmp_path, scope=SCOPE_LOCAL, project_dir=project_b
|
||||
)
|
||||
wrap_cli._setup_serena_mcp(registrar_b, context="claude-code")
|
||||
|
||||
assert _config(tmp_path)["mcpServers"]["serena"]["command"] == old_spec.command
|
||||
|
||||
|
||||
def test_remove_serena_clears_a_stale_ownership_record_with_no_live_entry(
|
||||
tmp_path: Path,
|
||||
) -> None:
|
||||
"""An ownership record must not outlive the config entry it authorized."""
|
||||
from headroom.mcp_registry.ledger import headroom_installed_matching
|
||||
|
||||
registrar = _registrar(tmp_path)
|
||||
ownership_key = registrar.ownership_key("serena", scope=SCOPE_LOCAL)
|
||||
stale_spec = ServerSpec(name="serena", command="uvx", args=("start-mcp-server",))
|
||||
record_install("claude", stale_spec, ownership_key=ownership_key)
|
||||
# Deliberately no live entry: simulates one removed by another path
|
||||
# (e.g. the user's own agent config edit) without going through us.
|
||||
|
||||
status = wrap_cli._remove_headroom_installed_serena_mcp(registrar)
|
||||
|
||||
assert status == "not_headroom_owned"
|
||||
assert not headroom_installed_matching("claude", stale_spec, ownership_key=ownership_key)
|
||||
|
||||
|
||||
def test_rewrap_leaves_a_user_managed_global_entry_alone(
|
||||
tmp_path: Path, capsys: pytest.CaptureFixture[str]
|
||||
) -> None:
|
||||
"""A Serena the user registered globally is theirs, not ours to remove."""
|
||||
user_spec = ServerSpec(name="serena", command="/usr/local/bin/custom-serena")
|
||||
_seed_global_serena(tmp_path, user_spec)
|
||||
# Deliberately no record_install: the ledger has never seen this entry.
|
||||
|
||||
wrap_cli._setup_serena_mcp(_registrar(tmp_path), context="claude-code", verbose=True)
|
||||
|
||||
config = _config(tmp_path)
|
||||
assert config["mcpServers"]["serena"]["command"] == "/usr/local/bin/custom-serena"
|
||||
# The project entry is still written: local scope wins for this directory,
|
||||
# so the user's global Serena keeps working everywhere else.
|
||||
assert "serena" in _project_servers(tmp_path)
|
||||
assert "removed the machine-wide entry" not in capsys.readouterr().out
|
||||
|
||||
|
||||
def test_user_scope_reproduces_the_previous_behaviour(
|
||||
tmp_path: Path, capsys: pytest.CaptureFixture[str]
|
||||
) -> None:
|
||||
registrar = _registrar(tmp_path, scope=SCOPE_USER)
|
||||
|
||||
wrap_cli._setup_serena_mcp(registrar, context="claude-code", verbose=True)
|
||||
|
||||
config = _config(tmp_path)
|
||||
assert "serena" in config["mcpServers"]
|
||||
assert "projects" not in config
|
||||
out = capsys.readouterr().out
|
||||
assert "every Claude Code session on this machine" in out
|
||||
assert "removed the machine-wide entry" not in out
|
||||
|
||||
|
||||
def test_project_ownership_records_do_not_clobber_each_other(
|
||||
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
|
||||
) -> None:
|
||||
"""Wrapping and unwrapping one project must not orphan another project."""
|
||||
project_a = tmp_path / "project-a"
|
||||
project_b = tmp_path / "project-b"
|
||||
project_a.mkdir()
|
||||
project_b.mkdir()
|
||||
(tmp_path / ".claude").mkdir()
|
||||
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
|
||||
registrar_a = ClaudeRegistrar(
|
||||
claude_cli=None, home_dir=tmp_path, scope=SCOPE_LOCAL, project_dir=project_a
|
||||
)
|
||||
registrar_b = ClaudeRegistrar(
|
||||
claude_cli=None, home_dir=tmp_path, scope=SCOPE_LOCAL, project_dir=project_b
|
||||
)
|
||||
|
||||
wrap_cli._setup_serena_mcp(registrar_a, context="claude-code")
|
||||
wrap_cli._setup_serena_mcp(registrar_b, context="claude-code")
|
||||
|
||||
from headroom.mcp_registry.ledger import headroom_installed_matching
|
||||
|
||||
assert set(_config(tmp_path)["projects"]) == {project_a.as_posix(), project_b.as_posix()}
|
||||
assert headroom_installed_matching(
|
||||
"claude",
|
||||
registrar_a.get_server("serena", scope=SCOPE_LOCAL),
|
||||
ownership_key=registrar_a.ownership_key("serena", scope=SCOPE_LOCAL),
|
||||
)
|
||||
assert wrap_cli._remove_headroom_installed_serena_mcp(registrar_a) == "removed"
|
||||
assert registrar_a.get_server("serena", scope=SCOPE_LOCAL) is None
|
||||
assert registrar_b.get_server("serena", scope=SCOPE_LOCAL) is not None
|
||||
assert wrap_cli._remove_headroom_installed_serena_mcp(registrar_b) == "removed"
|
||||
|
||||
|
||||
def test_project_unwrap_does_not_remove_unowned_global_serena(tmp_path: Path) -> None:
|
||||
"""Scope-specific cleanup must not turn project ownership into global authority."""
|
||||
user_spec = ServerSpec(name="serena", command="custom-serena")
|
||||
_seed_global_serena(tmp_path, user_spec)
|
||||
registrar = _registrar(tmp_path)
|
||||
wrap_cli._setup_serena_mcp(registrar, context="claude-code")
|
||||
|
||||
assert wrap_cli._remove_headroom_installed_serena_mcp(registrar) == "removed"
|
||||
assert registrar.get_server("serena", scope=SCOPE_LOCAL) is None
|
||||
assert registrar.get_server("serena", scope=SCOPE_USER) == user_spec
|
||||
|
||||
|
||||
def test_scope_migration_is_skipped_for_registrars_without_scopes(
|
||||
tmp_path: Path, capsys: pytest.CaptureFixture[str]
|
||||
) -> None:
|
||||
"""Codex/Grok/OpenCode registrars have no scope and no scoped reads."""
|
||||
|
||||
class _FakeRegistrar:
|
||||
name = "codex"
|
||||
display_name = "Codex"
|
||||
|
||||
def __init__(self) -> None:
|
||||
self.server: ServerSpec | None = None
|
||||
|
||||
def detect(self) -> bool:
|
||||
return True
|
||||
|
||||
def get_server(self, server_name: str) -> ServerSpec | None:
|
||||
return self.server if server_name == "serena" else None
|
||||
|
||||
def register_server(self, spec: ServerSpec, *, force: bool = False) -> Any:
|
||||
from headroom.mcp_registry.base import RegisterResult, RegisterStatus
|
||||
|
||||
self.server = spec
|
||||
return RegisterResult(RegisterStatus.REGISTERED, "registered")
|
||||
|
||||
registrar = _FakeRegistrar()
|
||||
wrap_cli._setup_serena_mcp(registrar, context="claude-code", verbose=True)
|
||||
|
||||
assert registrar.server is not None
|
||||
out = capsys.readouterr().out
|
||||
assert "removed the machine-wide entry" not in out
|
||||
assert "scoped to this project" not in out
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------
|
||||
# Flag / environment resolution
|
||||
# ----------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_default_scope_is_project(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
assert wrap_cli._resolve_code_memory_scope() == "project"
|
||||
assert wrap_cli._claude_code_memory_scope() == SCOPE_LOCAL
|
||||
|
||||
|
||||
def test_env_var_selects_user_scope(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
monkeypatch.setenv("HEADROOM_CODE_MEMORY_SCOPE", "user")
|
||||
assert wrap_cli._resolve_code_memory_scope() == "user"
|
||||
assert wrap_cli._claude_code_memory_scope() == SCOPE_USER
|
||||
|
||||
|
||||
def test_invalid_env_var_is_rejected(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
monkeypatch.setenv("HEADROOM_CODE_MEMORY_SCOPE", "global")
|
||||
with pytest.raises(Exception) as excinfo:
|
||||
wrap_cli._resolve_code_memory_scope()
|
||||
assert "HEADROOM_CODE_MEMORY_SCOPE" in str(excinfo.value)
|
||||
@@ -0,0 +1,148 @@
|
||||
"""Retiring the legacy tokensave entry stays at user scope (#2992 review).
|
||||
|
||||
tokensave was replaced by Serena and is only ever cleaned up now: ``wrap``
|
||||
retires the entry a prior release installed so the agent stops launching it,
|
||||
and ``unwrap`` does the same. Headroom only ever installed tokensave
|
||||
machine-wide — it was retired before #2787 gave Claude registrations a project
|
||||
scope — so the ledger record authorizing the removal is the pre-scope,
|
||||
user-scope one.
|
||||
|
||||
``ClaudeRegistrar.unregister_server()`` with no scope now deletes from the
|
||||
project *and* the user scope, so an unscoped retirement would take a
|
||||
project-local tokensave the user registered themselves, which no ledger record
|
||||
authorizes. An unscoped read has the mirror problem: a project entry is found
|
||||
first and shadows the machine-wide one Headroom owns, leaving ours behind
|
||||
forever.
|
||||
|
||||
These tests drive the real helpers with a real ``ClaudeRegistrar`` whose home
|
||||
directory is a tmp_path, so the assertions are about the JSON Claude Code
|
||||
actually reads.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import pytest
|
||||
|
||||
from headroom.cli import wrap as wrap_cli
|
||||
from headroom.mcp_registry.base import ServerSpec
|
||||
from headroom.mcp_registry.claude import SCOPE_LOCAL, SCOPE_USER, ClaudeRegistrar
|
||||
from headroom.mcp_registry.ledger import record_install
|
||||
|
||||
HEADROOM_SPEC = ServerSpec(name="tokensave", command="tokensave", args=("mcp",))
|
||||
USER_SPEC = ServerSpec(name="tokensave", command="/usr/local/bin/my-own-tokensave")
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def _isolate_env(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
|
||||
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
|
||||
|
||||
|
||||
def _registrar(tmp_path: Path, *, scope: str = SCOPE_LOCAL) -> ClaudeRegistrar:
|
||||
"""A real registrar pointed at ``tmp_path`` instead of the user's home."""
|
||||
(tmp_path / ".claude").mkdir(exist_ok=True)
|
||||
return ClaudeRegistrar(
|
||||
claude_cli=None, # no CLI path; never touch the real one
|
||||
home_dir=tmp_path,
|
||||
scope=scope,
|
||||
project_dir=tmp_path / "proj",
|
||||
)
|
||||
|
||||
|
||||
def _entry(spec: ServerSpec) -> dict[str, Any]:
|
||||
entry: dict[str, Any] = {"command": spec.command, "args": list(spec.args)}
|
||||
if spec.env:
|
||||
entry["env"] = dict(spec.env)
|
||||
return entry
|
||||
|
||||
|
||||
def _seed(tmp_path: Path, *, global_spec: ServerSpec, project_spec: ServerSpec) -> None:
|
||||
"""A machine-wide tokensave plus a project-scoped one, as Claude Code stores them."""
|
||||
config = {
|
||||
"mcpServers": {"tokensave": _entry(global_spec)},
|
||||
"projects": {
|
||||
(tmp_path / "proj").as_posix(): {"mcpServers": {"tokensave": _entry(project_spec)}}
|
||||
},
|
||||
}
|
||||
(tmp_path / ".claude.json").write_text(json.dumps(config), encoding="utf-8")
|
||||
|
||||
|
||||
def test_retirement_spares_an_identical_user_managed_project_entry(
|
||||
tmp_path: Path, capsys: pytest.CaptureFixture[str]
|
||||
) -> None:
|
||||
"""Same command in both scopes: only the one the ledger authorized goes."""
|
||||
_seed(tmp_path, global_spec=HEADROOM_SPEC, project_spec=HEADROOM_SPEC)
|
||||
record_install("claude", HEADROOM_SPEC) # pre-scope ledger key: "tokensave"
|
||||
registrar = _registrar(tmp_path)
|
||||
|
||||
wrap_cli._disable_tokensave_mcp(registrar)
|
||||
|
||||
assert registrar.get_server("tokensave", scope=SCOPE_USER) is None
|
||||
assert registrar.get_server("tokensave", scope=SCOPE_LOCAL) == HEADROOM_SPEC
|
||||
assert "Removed retired tokensave MCP" in capsys.readouterr().out
|
||||
|
||||
|
||||
def test_a_user_managed_project_entry_does_not_shadow_the_global_one(
|
||||
tmp_path: Path,
|
||||
) -> None:
|
||||
"""A project entry we do not own must not block retiring the one we do."""
|
||||
_seed(tmp_path, global_spec=HEADROOM_SPEC, project_spec=USER_SPEC)
|
||||
record_install("claude", HEADROOM_SPEC)
|
||||
registrar = _registrar(tmp_path)
|
||||
|
||||
assert wrap_cli._remove_headroom_installed_tokensave_mcp(registrar) == "removed"
|
||||
assert registrar.get_server("tokensave", scope=SCOPE_USER) is None
|
||||
assert registrar.get_server("tokensave", scope=SCOPE_LOCAL) == USER_SPEC
|
||||
|
||||
|
||||
def test_unwrap_leaves_a_user_managed_project_entry_alone(tmp_path: Path) -> None:
|
||||
"""unwrap builds a user-scope registrar; it still must not reach into the project."""
|
||||
_seed(tmp_path, global_spec=HEADROOM_SPEC, project_spec=HEADROOM_SPEC)
|
||||
record_install("claude", HEADROOM_SPEC)
|
||||
registrar = _registrar(tmp_path, scope=SCOPE_USER)
|
||||
|
||||
assert wrap_cli._remove_headroom_installed_tokensave_mcp(registrar) == "removed"
|
||||
assert registrar.get_server("tokensave", scope=SCOPE_USER) is None
|
||||
assert registrar.get_server("tokensave", scope=SCOPE_LOCAL) == HEADROOM_SPEC
|
||||
|
||||
|
||||
def test_a_user_managed_global_entry_is_left_in_place(tmp_path: Path) -> None:
|
||||
"""Unchanged behaviour: no ledger record, no removal."""
|
||||
_seed(tmp_path, global_spec=USER_SPEC, project_spec=USER_SPEC)
|
||||
registrar = _registrar(tmp_path)
|
||||
|
||||
assert wrap_cli._remove_headroom_installed_tokensave_mcp(registrar) == "not_headroom_owned"
|
||||
assert registrar.get_server("tokensave", scope=SCOPE_USER) == USER_SPEC
|
||||
assert registrar.get_server("tokensave", scope=SCOPE_LOCAL) == USER_SPEC
|
||||
|
||||
|
||||
def test_registrars_without_scopes_still_retire_tokensave(tmp_path: Path) -> None:
|
||||
"""Codex/Grok/OpenCode registrars have no scope and reject a scoped read."""
|
||||
|
||||
class _FakeRegistrar:
|
||||
name = "codex"
|
||||
display_name = "Codex"
|
||||
|
||||
def __init__(self) -> None:
|
||||
self.server: ServerSpec | None = HEADROOM_SPEC
|
||||
|
||||
def detect(self) -> bool:
|
||||
return True
|
||||
|
||||
def get_server(self, server_name: str) -> ServerSpec | None:
|
||||
return self.server if server_name == "tokensave" else None
|
||||
|
||||
def unregister_server(self, server_name: str) -> bool:
|
||||
if server_name != "tokensave" or self.server is None:
|
||||
return False
|
||||
self.server = None
|
||||
return True
|
||||
|
||||
record_install("codex", HEADROOM_SPEC)
|
||||
registrar = _FakeRegistrar()
|
||||
|
||||
assert wrap_cli._remove_headroom_installed_tokensave_mcp(registrar) == "removed"
|
||||
assert registrar.server is None
|
||||
@@ -205,6 +205,66 @@ def test_unwrap_claude_removes_headroom_installed_serena(
|
||||
assert "Removed Headroom-installed Serena MCP server" in result.output
|
||||
|
||||
|
||||
def test_unwrap_claude_removes_project_scoped_serena(
|
||||
runner: CliRunner,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
tmp_path: Path,
|
||||
) -> None:
|
||||
"""Unwrap must find the Serena entry wherever wrap put it (#2787).
|
||||
|
||||
Wrap now registers Serena under ``projects[<cwd>].mcpServers`` rather than
|
||||
the machine-wide map, so this runs against a real registrar and real config
|
||||
JSON — a fake registrar would not catch a scope mismatch between the two.
|
||||
"""
|
||||
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
|
||||
|
||||
from headroom.mcp_registry import build_serena_spec
|
||||
from headroom.mcp_registry.claude import ClaudeRegistrar
|
||||
from headroom.mcp_registry.ledger import record_install
|
||||
|
||||
project = tmp_path / "proj"
|
||||
project.mkdir()
|
||||
monkeypatch.chdir(project)
|
||||
|
||||
serena_spec = build_serena_spec("claude-code")
|
||||
registrar = ClaudeRegistrar(
|
||||
claude_cli=None, home_dir=tmp_path, scope="local", project_dir=project
|
||||
)
|
||||
record_install(
|
||||
"claude",
|
||||
serena_spec,
|
||||
ownership_key=registrar.ownership_key("serena", scope="local"),
|
||||
)
|
||||
(tmp_path / ".claude.json").write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"projects": {
|
||||
project.as_posix(): {
|
||||
"mcpServers": {
|
||||
"serena": {
|
||||
"command": serena_spec.command,
|
||||
"args": list(serena_spec.args),
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
with (
|
||||
patch("headroom.mcp_registry.ClaudeRegistrar", return_value=registrar),
|
||||
patch("headroom.cli.wrap._remove_claude_managed_hooks", return_value=False),
|
||||
patch("headroom.cli.wrap._stop_local_proxy_for_unwrap"),
|
||||
):
|
||||
result = runner.invoke(main, ["unwrap", "claude"])
|
||||
|
||||
assert result.exit_code == 0, result.output
|
||||
assert "Removed Headroom-installed Serena MCP server" in result.output
|
||||
config = json.loads((tmp_path / ".claude.json").read_text(encoding="utf-8"))
|
||||
assert config["projects"][project.as_posix()]["mcpServers"] == {}
|
||||
|
||||
|
||||
def test_unwrap_claude_keep_flags_skip_cleanup(
|
||||
runner: CliRunner,
|
||||
) -> None:
|
||||
|
||||
@@ -10,7 +10,7 @@ from unittest.mock import patch
|
||||
import pytest
|
||||
|
||||
from headroom.mcp_registry.base import RegisterStatus, ServerSpec
|
||||
from headroom.mcp_registry.claude import ClaudeRegistrar
|
||||
from headroom.mcp_registry.claude import SCOPE_LOCAL, SCOPE_USER, ClaudeRegistrar
|
||||
from headroom.mcp_registry.install import build_headroom_spec
|
||||
|
||||
_RESOLVED_COMMAND = ("/usr/bin/python", "-m", "headroom.cli")
|
||||
@@ -512,6 +512,258 @@ def test_register_via_file_merges_into_existing_valid_config(tmp_path: Path) ->
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------
|
||||
# Project ("local") scope — issue #2787
|
||||
#
|
||||
# A server registered at user scope loads in every Claude Code session on the
|
||||
# machine, so one that fails to start breaks unrelated projects. Project scope
|
||||
# confines it to the directory that was wrapped.
|
||||
# ----------------------------------------------------------------------
|
||||
|
||||
_SERENA_ARGS = ["serena", "start-mcp-server"]
|
||||
|
||||
|
||||
def _local_registrar(
|
||||
tmp_path: Path,
|
||||
*,
|
||||
cli: str | None = None,
|
||||
project_dir: Path | None = None,
|
||||
) -> ClaudeRegistrar:
|
||||
"""Registrar writing project scope, pointed at ``tmp_path`` as $HOME."""
|
||||
return ClaudeRegistrar(
|
||||
claude_cli=cli,
|
||||
home_dir=tmp_path,
|
||||
scope=SCOPE_LOCAL,
|
||||
project_dir=project_dir if project_dir is not None else tmp_path / "proj",
|
||||
)
|
||||
|
||||
|
||||
def _serena_spec(command: str = "uvx") -> ServerSpec:
|
||||
return ServerSpec(name="serena", command=command, args=tuple(_SERENA_ARGS))
|
||||
|
||||
|
||||
def test_rejects_unknown_scope(tmp_path: Path) -> None:
|
||||
with pytest.raises(ValueError):
|
||||
ClaudeRegistrar(claude_cli=None, home_dir=tmp_path, scope="global")
|
||||
|
||||
|
||||
def test_register_local_scope_writes_project_map_not_user_map(tmp_path: Path) -> None:
|
||||
project = tmp_path / "proj"
|
||||
reg = _local_registrar(tmp_path, project_dir=project)
|
||||
|
||||
result = reg.register_server(_serena_spec())
|
||||
|
||||
assert result.status == RegisterStatus.REGISTERED
|
||||
data = json.loads((tmp_path / ".claude.json").read_text(encoding="utf-8"))
|
||||
assert "serena" in data["projects"][project.as_posix()]["mcpServers"]
|
||||
# The machine-wide map is what breaks unrelated sessions — stay out of it.
|
||||
assert "mcpServers" not in data
|
||||
|
||||
|
||||
def test_register_local_scope_reuses_existing_project_key(tmp_path: Path) -> None:
|
||||
"""Claude Code keys ``projects`` by the session's cwd string (forward slashes
|
||||
even on Windows). A second key naming the same directory would leave an entry
|
||||
Claude Code never reads."""
|
||||
project = tmp_path / "proj"
|
||||
cfg = tmp_path / ".claude.json"
|
||||
existing_key = project.as_posix() + "/" # same directory, different spelling
|
||||
cfg.write_text(
|
||||
json.dumps({"projects": {existing_key: {"hasTrustDialogAccepted": True}}}),
|
||||
encoding="utf-8",
|
||||
)
|
||||
reg = _local_registrar(tmp_path, project_dir=project)
|
||||
|
||||
assert reg.register_server(_serena_spec()).status == RegisterStatus.REGISTERED
|
||||
|
||||
data = json.loads(cfg.read_text(encoding="utf-8"))
|
||||
assert list(data["projects"]) == [existing_key]
|
||||
assert "serena" in data["projects"][existing_key]["mcpServers"]
|
||||
assert data["projects"][existing_key]["hasTrustDialogAccepted"] is True
|
||||
|
||||
|
||||
def test_register_local_scope_writes_even_when_user_entry_matches(tmp_path: Path) -> None:
|
||||
"""A leftover user-scope copy must not make the project-scope registration
|
||||
look like a no-op — that would leave the machine-wide entry as the only one."""
|
||||
project = tmp_path / "proj"
|
||||
cfg = tmp_path / ".claude.json"
|
||||
cfg.write_text(
|
||||
json.dumps({"mcpServers": {"serena": {"command": "uvx", "args": _SERENA_ARGS}}}),
|
||||
encoding="utf-8",
|
||||
)
|
||||
reg = _local_registrar(tmp_path, project_dir=project)
|
||||
|
||||
result = reg.register_server(_serena_spec())
|
||||
|
||||
assert result.status == RegisterStatus.REGISTERED
|
||||
data = json.loads(cfg.read_text(encoding="utf-8"))
|
||||
assert "serena" in data["projects"][project.as_posix()]["mcpServers"]
|
||||
# Retiring the global copy is wrap's job (ledger-gated), not the registrar's.
|
||||
assert "serena" in data["mcpServers"]
|
||||
|
||||
|
||||
def test_register_local_scope_never_writes_legacy_config(tmp_path: Path) -> None:
|
||||
"""``~/.claude/mcp.json`` has no projects map, so project scope always goes to
|
||||
the modern config even when only the legacy file exists."""
|
||||
legacy = tmp_path / ".claude" / "mcp.json"
|
||||
legacy.parent.mkdir()
|
||||
legacy.write_text(json.dumps({"mcpServers": {}}), encoding="utf-8")
|
||||
project = tmp_path / "proj"
|
||||
reg = _local_registrar(tmp_path, project_dir=project)
|
||||
|
||||
assert reg.register_server(_serena_spec()).status == RegisterStatus.REGISTERED
|
||||
|
||||
assert json.loads(legacy.read_text(encoding="utf-8"))["mcpServers"] == {}
|
||||
data = json.loads((tmp_path / ".claude.json").read_text(encoding="utf-8"))
|
||||
assert "serena" in data["projects"][project.as_posix()]["mcpServers"]
|
||||
|
||||
|
||||
def test_register_via_cli_passes_local_scope_and_project_cwd(tmp_path: Path) -> None:
|
||||
project = tmp_path / "proj"
|
||||
reg = _local_registrar(tmp_path, cli="/usr/local/bin/claude", project_dir=project)
|
||||
ok = subprocess.CompletedProcess(args=[], returncode=0, stdout="", stderr="")
|
||||
|
||||
with patch("subprocess.run", return_value=ok) as run_mock:
|
||||
result = reg.register_server(_serena_spec())
|
||||
|
||||
assert result.status == RegisterStatus.REGISTERED
|
||||
add_call = run_mock.call_args
|
||||
assert add_call is not None
|
||||
assert add_call.args[0][:6] == [
|
||||
"/usr/local/bin/claude",
|
||||
"mcp",
|
||||
"add",
|
||||
"serena",
|
||||
"-s",
|
||||
"local",
|
||||
]
|
||||
# `claude mcp add -s local` keys the entry by the CLI process's own cwd.
|
||||
assert add_call.kwargs["cwd"] == str(project)
|
||||
|
||||
|
||||
def test_get_server_prefers_project_entry_over_user_entry(tmp_path: Path) -> None:
|
||||
"""Claude Code resolves project scope first, so our reads must too."""
|
||||
project = tmp_path / "proj"
|
||||
cfg = tmp_path / ".claude.json"
|
||||
cfg.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"mcpServers": {"serena": {"command": "global-uvx"}},
|
||||
"projects": {project.as_posix(): {"mcpServers": {"serena": {"command": "uvx"}}}},
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
reg = _local_registrar(tmp_path, project_dir=project)
|
||||
|
||||
unscoped = reg.get_server("serena")
|
||||
assert unscoped is not None and unscoped.command == "uvx"
|
||||
|
||||
scoped_user = reg.get_server("serena", scope=SCOPE_USER)
|
||||
assert scoped_user is not None and scoped_user.command == "global-uvx"
|
||||
|
||||
scoped_local = reg.get_server("serena", scope=SCOPE_LOCAL)
|
||||
assert scoped_local is not None and scoped_local.command == "uvx"
|
||||
|
||||
|
||||
def test_get_server_scoped_read_ignores_other_projects(tmp_path: Path) -> None:
|
||||
cfg = tmp_path / ".claude.json"
|
||||
cfg.write_text(
|
||||
json.dumps(
|
||||
{"projects": {(tmp_path / "elsewhere").as_posix(): {"mcpServers": {"serena": {}}}}}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
reg = _local_registrar(tmp_path, project_dir=tmp_path / "proj")
|
||||
|
||||
assert reg.get_server("serena", scope=SCOPE_LOCAL) is None
|
||||
|
||||
|
||||
def test_force_register_local_scope_leaves_user_entry(tmp_path: Path) -> None:
|
||||
"""force=True replaces the entry in the target scope only.
|
||||
|
||||
Overwriting this project's Serena must not delete a machine-wide one the
|
||||
user registered themselves.
|
||||
"""
|
||||
project = tmp_path / "proj"
|
||||
cfg = tmp_path / ".claude.json"
|
||||
cfg.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"mcpServers": {"serena": {"command": "user-managed-serena"}},
|
||||
"projects": {project.as_posix(): {"mcpServers": {"serena": {"command": "old"}}}},
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
reg = _local_registrar(tmp_path, project_dir=project)
|
||||
|
||||
result = reg.register_server(_serena_spec(), force=True)
|
||||
|
||||
assert result.status == RegisterStatus.REGISTERED
|
||||
data = json.loads(cfg.read_text(encoding="utf-8"))
|
||||
assert data["projects"][project.as_posix()]["mcpServers"]["serena"]["command"] == "uvx"
|
||||
assert data["mcpServers"]["serena"]["command"] == "user-managed-serena"
|
||||
|
||||
|
||||
def test_unregister_removes_both_scopes_by_default(tmp_path: Path) -> None:
|
||||
"""unwrap must clean up regardless of which scope installed the entry."""
|
||||
project = tmp_path / "proj"
|
||||
other = tmp_path / "other"
|
||||
cfg = tmp_path / ".claude.json"
|
||||
cfg.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"mcpServers": {"serena": {"command": "uvx"}},
|
||||
"projects": {
|
||||
project.as_posix(): {"mcpServers": {"serena": {"command": "uvx"}}},
|
||||
other.as_posix(): {"mcpServers": {"serena": {"command": "uvx"}}},
|
||||
},
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
reg = _local_registrar(tmp_path, project_dir=project)
|
||||
|
||||
assert reg.unregister_server("serena") is True
|
||||
|
||||
data = json.loads(cfg.read_text(encoding="utf-8"))
|
||||
assert data["mcpServers"] == {}
|
||||
assert data["projects"][project.as_posix()]["mcpServers"] == {}
|
||||
# Other projects were wrapped separately; unwrapping here must not touch them.
|
||||
assert "serena" in data["projects"][other.as_posix()]["mcpServers"]
|
||||
|
||||
|
||||
def test_unregister_user_scope_leaves_project_entry(tmp_path: Path) -> None:
|
||||
project = tmp_path / "proj"
|
||||
cfg = tmp_path / ".claude.json"
|
||||
cfg.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"mcpServers": {"serena": {"command": "uvx"}},
|
||||
"projects": {project.as_posix(): {"mcpServers": {"serena": {"command": "uvx"}}}},
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
reg = _local_registrar(tmp_path, project_dir=project)
|
||||
|
||||
assert reg.unregister_server("serena", scope=SCOPE_USER) is True
|
||||
|
||||
data = json.loads(cfg.read_text(encoding="utf-8"))
|
||||
assert data["mcpServers"] == {}
|
||||
assert "serena" in data["projects"][project.as_posix()]["mcpServers"]
|
||||
|
||||
|
||||
def test_default_scope_is_user_so_existing_callers_are_unchanged(tmp_path: Path) -> None:
|
||||
reg = _make_registrar(tmp_path, cli=None)
|
||||
assert reg.scope == SCOPE_USER
|
||||
|
||||
assert reg.register_server(_spec()).status == RegisterStatus.REGISTERED
|
||||
|
||||
data = json.loads((tmp_path / ".claude.json").read_text(encoding="utf-8"))
|
||||
assert "headroom" in data["mcpServers"]
|
||||
assert "projects" not in data
|
||||
|
||||
|
||||
# get_plugin_servers() — servers bundled by Claude Code plugins (#3570)
|
||||
# ----------------------------------------------------------------------
|
||||
|
||||
|
||||
Reference in New Issue
Block a user