fix(mcp): report a plugin-provided Serena that reconcile cannot see

Claude Code also launches MCP servers bundled by enabled plugins
(`plugin:serena:serena` in `claude mcp list`), declared in the plugin's
own `.mcp.json` under `~/.claude/plugins/cache`. `ClaudeRegistrar` only
reads `mcpServers`, so with the marketplace `serena` plugin installed
`headroom mcp reconcile` reported the Headroom entry as consistent while
two Serena servers ran, and the plugin's spec has none of Headroom's
flags (`--project-from-cwd`, `--context`, `--open-web-dashboard False`).

Add a read-only `ClaudeRegistrar.get_plugin_servers()` that walks
`installed_plugins.json` (user-scope records, honoring `enabledPlugins`
so `claude plugin disable` silences it) and reads each plugin's
`.mcp.json` in both of its documented shapes. `mcp reconcile` now prints
the plugin entry and the `claude plugin disable <id>` command. Nothing is
removed: Headroom does not mutate third-party plugins.

Fixes #3570
This commit is contained in:
Ayushraj06-bit
2026-09-14 06:17:31 +05:30
parent aa4739e54a
commit a81f3dc4b9
6 changed files with 371 additions and 1 deletions
+1 -1
View File
@@ -187,7 +187,7 @@ Install Headroom so it's globally on PATH — `uv tool install "headroom-ai[mcp]
## Architecture
For user-managed Serena drift, run `headroom mcp reconcile` to inspect the current recommendation. Add `--adopt` only when you want Headroom to replace the Serena entry.
For user-managed Serena drift, run `headroom mcp reconcile` to inspect the current recommendation. Add `--adopt` only when you want Headroom to replace the Serena entry. If an enabled Claude Code plugin (such as `serena` from the `claude-plugins-official` marketplace) also bundles a Serena server, `reconcile` reports it and prints the `claude plugin disable` command; Headroom never edits third-party plugins.
### MCP only (no proxy)
+12
View File
@@ -260,6 +260,18 @@ def mcp_reconcile(adopt: bool) -> None:
click.echo(f" recommendation: {recommended.command} {' '.join(recommended.args)}")
if observed is not None and observed != recommended:
click.echo(" action: use --adopt to replace it")
# A Serena bundled by an enabled Claude Code plugin runs alongside the
# entry above (``claude mcp list`` shows it as ``plugin:serena:serena``)
# with none of Headroom's flags. It is a third-party plugin, so it is
# never removed here — point at the command that disables it (#3570).
for plugin_id, spec in registrar.get_plugin_servers("serena"):
click.echo(
f" plugin: {plugin_id} also provides a Serena MCP server "
f"({spec.command} {' '.join(spec.args)})"
)
click.echo(
f" action: disable it so only one Serena runs: claude plugin disable {plugin_id}"
)
@mcp.command("status")
+54
View File
@@ -64,6 +64,11 @@ class ClaudeRegistrar(MCPRegistrar):
self._isolated_cli_env = home_dir is not None or config_dir is not None
self._modern_config = modern_dir / ".claude.json"
self._legacy_config = self._claude_dir / "mcp.json"
# Unlike the legacy file, plugin state and settings.json do move with
# CLAUDE_CONFIG_DIR; without the override they live under ``~/.claude``.
state_dir = modern_dir if modern_dir != home else self._claude_dir
self._settings = state_dir / "settings.json"
self._installed_plugins = state_dir / "plugins" / "installed_plugins.json"
if claude_cli is ...:
self._claude_cli = shutil.which("claude")
else:
@@ -88,6 +93,41 @@ class ClaudeRegistrar(MCPRegistrar):
return entry
return None
def get_plugin_servers(self, server_name: str) -> list[tuple[str, ServerSpec]]:
"""Return ``(plugin_id, spec)`` for each enabled plugin bundling ``server_name``.
Claude Code also launches MCP servers declared in an installed
plugin's ``.mcp.json`` (``claude mcp list`` shows them as
``plugin:<plugin>:<server>``). They never appear under ``mcpServers``,
so :meth:`get_server` cannot see them and Headroom cannot tell that a
plugin duplicates an entry it manages (#3570). Read-only. Only
user-scope installs are considered: a project-scoped record carries
``projectPath`` and is enabled per project.
"""
installed = _read_json(self._installed_plugins).get("plugins")
if not isinstance(installed, dict):
return []
enabled = _read_json(self._settings).get("enabledPlugins")
if not isinstance(enabled, dict):
enabled = {}
found: list[tuple[str, ServerSpec]] = []
for plugin_id, records in installed.items():
# ``claude plugin disable`` flips this flag and keeps the install
# record; a disabled plugin does not start its servers.
if enabled.get(plugin_id) is False or not isinstance(records, list):
continue
for record in records:
if not isinstance(record, dict) or record.get("projectPath"):
continue
install_path = record.get("installPath")
if not isinstance(install_path, str) or not install_path:
continue
entry = _read_plugin_mcp_entry(Path(install_path) / ".mcp.json", server_name)
if entry is not None:
found.append((plugin_id, _entry_to_spec(server_name, entry)))
break
return found
def validate_configs_for_mutation(self) -> None:
"""Validate every Claude config root before an explicit mutation."""
seen: set[Path] = set()
@@ -301,6 +341,20 @@ def _read_json(path: Path) -> dict[str, Any]:
return data
def _read_plugin_mcp_entry(path: Path, server_name: str) -> dict[str, Any] | None:
"""Look up ``server_name`` in a plugin's ``.mcp.json``.
Plugins in the official marketplace use both documented shapes: a
top-level ``mcpServers`` object and a flat ``{name: entry}`` map.
"""
config = _read_json(path)
servers = config.get("mcpServers", config)
if not isinstance(servers, dict):
return None
entry = servers.get(server_name)
return entry if isinstance(entry, dict) else None
class _MalformedConfigError(Exception):
"""The target config file exists but is not a parseable JSON object.
+32
View File
@@ -0,0 +1,32 @@
{
"issue": 3570,
"url": "https://github.com/headroomlabs-ai/headroom/issues/3570",
"captured_from": "claude plugin install serena@claude-plugins-official (Claude Code 2.1.238)",
"plugin_id": "serena@claude-plugins-official",
"plugin_mcp_json": {
"serena": {
"command": "uvx",
"args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"]
}
},
"installed_plugins_json": {
"version": 2,
"plugins": {
"serena@claude-plugins-official": [
{
"scope": "user",
"installPath": "<installPath>",
"version": "022b3c274938",
"installedAt": "2026-09-13T23:38:36.229Z",
"lastUpdated": "2026-09-13T23:38:36.229Z",
"gitCommitSha": "022b3c274938ddfb9fd928fc582eb9b9ed0f537f"
}
]
}
},
"settings_json": {
"enabledPlugins": {
"serena@claude-plugins-official": true
}
}
}
+70
View File
@@ -289,3 +289,73 @@ def test_mcp_install_force_preserves_user_managed_serena(monkeypatch, tmp_path:
assert result.exit_code == 0, result.output
assert json.loads(config.read_text())["mcpServers"]["serena"] == before
PLUGIN_FIXTURE = Path(__file__).parents[1] / "fixtures" / "headroom-issue-3570.json"
def _install_plugin_serena(tmp_path: Path, *, enabled: bool = True) -> list[Path]:
"""Mirror ``claude plugin install serena@claude-plugins-official`` on disk.
Returns the three files Claude Code owns so tests can assert Headroom
never touches them.
"""
fixture = json.loads(PLUGIN_FIXTURE.read_text())
claude_dir = tmp_path / ".claude"
install_path = claude_dir / "plugins" / "cache" / "claude-plugins-official" / "serena" / "v1"
install_path.mkdir(parents=True)
mcp_json = install_path / ".mcp.json"
mcp_json.write_text(json.dumps(fixture["plugin_mcp_json"]))
installed = fixture["installed_plugins_json"]
installed["plugins"][fixture["plugin_id"]][0]["installPath"] = str(install_path)
registry = claude_dir / "plugins" / "installed_plugins.json"
registry.write_text(json.dumps(installed))
settings = claude_dir / "settings.json"
settings.write_text(json.dumps({"enabledPlugins": {fixture["plugin_id"]: enabled}}))
return [mcp_json, registry, settings]
def test_issue_fixture_plugin_serena_is_reported_base_fail_head_pass(monkeypatch, tmp_path: Path):
"""#3570: a plugin-provided Serena is invisible to ``get_server`` but must be reported."""
config, _ = _setup(monkeypatch, tmp_path)
data = json.loads(config.read_text())
recommended = build_serena_spec("claude-code")
data["mcpServers"]["serena"] = {"command": recommended.command, "args": list(recommended.args)}
config.write_text(json.dumps(data))
plugin_files = _install_plugin_serena(tmp_path)
fixture = json.loads(PLUGIN_FIXTURE.read_text())
before = [(p.read_bytes(), os.stat(p).st_mtime_ns) for p in plugin_files]
result = CliRunner().invoke(main, ["mcp", "reconcile"])
assert result.exit_code == 0, result.output
assert "observed: present" in result.output
plugin_cmd = " ".join(["uvx", *fixture["plugin_mcp_json"]["serena"]["args"]])
assert f"plugin: {fixture['plugin_id']} also provides a Serena MCP server ({plugin_cmd})" in (
result.output
)
assert f"claude plugin disable {fixture['plugin_id']}" in result.output
assert "use --adopt" not in result.output
assert [(p.read_bytes(), os.stat(p).st_mtime_ns) for p in plugin_files] == before
def test_reconcile_is_quiet_once_plugin_serena_is_disabled(monkeypatch, tmp_path: Path):
_setup(monkeypatch, tmp_path)
_install_plugin_serena(tmp_path, enabled=False)
result = CliRunner().invoke(main, ["mcp", "reconcile"])
assert result.exit_code == 0, result.output
assert "plugin:" not in result.output
assert "claude plugin disable" not in result.output
def test_adopt_leaves_plugin_serena_files_untouched(monkeypatch, tmp_path: Path):
_setup(monkeypatch, tmp_path)
plugin_files = _install_plugin_serena(tmp_path)
before = [p.read_bytes() for p in plugin_files]
result = CliRunner().invoke(main, ["mcp", "reconcile", "--adopt"])
assert result.exit_code == 0, result.output
assert [p.read_bytes() for p in plugin_files] == before
@@ -509,3 +509,205 @@ def test_register_via_file_merges_into_existing_valid_config(tmp_path: Path) ->
assert data["projects"] == {"/x": {"y": 1}}
assert data["oauthAccount"] == {"id": "abc"}
assert "headroom" in data["mcpServers"]
# ----------------------------------------------------------------------
# get_plugin_servers() — servers bundled by Claude Code plugins (#3570)
# ----------------------------------------------------------------------
_ISSUE_3570 = json.loads(
(Path(__file__).parents[1] / "fixtures" / "headroom-issue-3570.json").read_text()
)
_PLUGIN_ID = _ISSUE_3570["plugin_id"]
_PLUGIN_SERENA_ARGS = tuple(_ISSUE_3570["plugin_mcp_json"]["serena"]["args"])
def _install_plugin(
claude_dir: Path,
*,
plugin_id: str = _PLUGIN_ID,
mcp_json: str | None = None,
enabled: bool | None = True,
records: list[dict] | None = None,
) -> Path:
"""Lay out a plugin the way ``claude plugin install`` does under ``claude_dir``.
Returns the plugin's install path. ``mcp_json`` overrides the raw
``.mcp.json`` text (``None`` writes the fixture's flat-map form).
``enabled=None`` writes no ``enabledPlugins`` entry at all.
"""
install_path = claude_dir / "plugins" / "cache" / "market" / plugin_id / "v1"
install_path.mkdir(parents=True, exist_ok=True)
if mcp_json is None:
mcp_json = json.dumps(_ISSUE_3570["plugin_mcp_json"])
(install_path / ".mcp.json").write_text(mcp_json, encoding="utf-8")
registry = claude_dir / "plugins" / "installed_plugins.json"
installed = (
json.loads(registry.read_text()) if registry.exists() else {"version": 2, "plugins": {}}
)
if records is None:
record = dict(_ISSUE_3570["installed_plugins_json"]["plugins"][_PLUGIN_ID][0])
record["installPath"] = str(install_path)
records = [record]
installed["plugins"][plugin_id] = records
registry.write_text(json.dumps(installed), encoding="utf-8")
if enabled is not None:
settings = claude_dir / "settings.json"
data = json.loads(settings.read_text()) if settings.exists() else {}
data.setdefault("enabledPlugins", {})[plugin_id] = enabled
settings.write_text(json.dumps(data), encoding="utf-8")
return install_path
def test_get_plugin_servers_empty_without_plugins(tmp_path: Path) -> None:
reg = _make_registrar(tmp_path, cli=None)
assert reg.get_plugin_servers("serena") == []
def test_get_plugin_servers_sees_serena_that_get_server_cannot(tmp_path: Path) -> None:
_install_plugin(tmp_path / ".claude")
reg = _make_registrar(tmp_path, cli=None)
assert reg.get_server("serena") is None
assert reg.get_plugin_servers("serena") == [
(_PLUGIN_ID, ServerSpec(name="serena", command="uvx", args=_PLUGIN_SERENA_ARGS))
]
def test_get_plugin_servers_reads_mcp_servers_wrapped_shape(tmp_path: Path) -> None:
wrapped = json.dumps({"mcpServers": _ISSUE_3570["plugin_mcp_json"]})
_install_plugin(tmp_path / ".claude", mcp_json=wrapped)
reg = _make_registrar(tmp_path, cli=None)
got = reg.get_plugin_servers("serena")
assert [plugin_id for plugin_id, _ in got] == [_PLUGIN_ID]
assert got[0][1].args == _PLUGIN_SERENA_ARGS
def test_get_plugin_servers_skips_disabled_plugin(tmp_path: Path) -> None:
"""``claude plugin disable`` keeps the install record and flips the flag."""
_install_plugin(tmp_path / ".claude", enabled=False)
reg = _make_registrar(tmp_path, cli=None)
assert reg.get_plugin_servers("serena") == []
@pytest.mark.parametrize("settings", [None, "{}", '{"enabledPlugins": null}', "not json"])
def test_get_plugin_servers_treats_missing_flag_as_enabled(
tmp_path: Path, settings: str | None
) -> None:
claude_dir = tmp_path / ".claude"
_install_plugin(claude_dir, enabled=None)
if settings is not None:
(claude_dir / "settings.json").write_text(settings, encoding="utf-8")
reg = _make_registrar(tmp_path, cli=None)
assert [plugin_id for plugin_id, _ in reg.get_plugin_servers("serena")] == [_PLUGIN_ID]
def test_get_plugin_servers_skips_project_scoped_record(tmp_path: Path) -> None:
claude_dir = tmp_path / ".claude"
install_path = claude_dir / "plugins" / "cache" / "market" / _PLUGIN_ID / "v1"
_install_plugin(
claude_dir,
records=[
{
"scope": "project",
"installPath": str(install_path),
"projectPath": str(tmp_path / "proj"),
}
],
)
reg = _make_registrar(tmp_path, cli=None)
assert reg.get_plugin_servers("serena") == []
def test_get_plugin_servers_reports_each_plugin_once(tmp_path: Path) -> None:
claude_dir = tmp_path / ".claude"
install_path = claude_dir / "plugins" / "cache" / "market" / _PLUGIN_ID / "v1"
_install_plugin(
claude_dir,
records=[
{"scope": "user", "installPath": str(install_path)},
{"scope": "managed", "installPath": str(install_path)},
],
)
reg = _make_registrar(tmp_path, cli=None)
assert [plugin_id for plugin_id, _ in reg.get_plugin_servers("serena")] == [_PLUGIN_ID]
def test_get_plugin_servers_reports_every_plugin_in_registry_order(tmp_path: Path) -> None:
claude_dir = tmp_path / ".claude"
_install_plugin(claude_dir, plugin_id="serena@other")
_install_plugin(claude_dir)
reg = _make_registrar(tmp_path, cli=None)
got = reg.get_plugin_servers("serena")
assert [plugin_id for plugin_id, _ in got] == ["serena@other", _PLUGIN_ID]
assert all(spec.args == _PLUGIN_SERENA_ARGS for _, spec in got)
def test_get_plugin_servers_matches_only_the_requested_name(tmp_path: Path) -> None:
_install_plugin(tmp_path / ".claude")
reg = _make_registrar(tmp_path, cli=None)
assert reg.get_plugin_servers("headroom") == []
def test_get_plugin_servers_reads_explicit_config_dir(tmp_path: Path) -> None:
config_dir = tmp_path / "relocated"
_install_plugin(config_dir)
_install_plugin(tmp_path / ".claude", plugin_id="serena@home")
reg = ClaudeRegistrar(claude_cli=None, home_dir=tmp_path, config_dir=config_dir)
assert [plugin_id for plugin_id, _ in reg.get_plugin_servers("serena")] == [_PLUGIN_ID]
def test_get_plugin_servers_reads_claude_config_dir_env(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
config_dir = tmp_path / "relocated"
_install_plugin(config_dir)
monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(config_dir))
monkeypatch.setattr(Path, "home", lambda: tmp_path)
reg = ClaudeRegistrar(claude_cli=None)
assert [plugin_id for plugin_id, _ in reg.get_plugin_servers("serena")] == [_PLUGIN_ID]
@pytest.mark.parametrize(
"contents",
[
"",
"not json",
"[]",
'{"plugins": []}',
'{"plugins": {"x": {}}}',
'{"plugins": {"x": [null]}}',
'{"plugins": {"x": [{}]}}',
'{"plugins": {"x": [{"installPath": ""}]}}',
'{"plugins": {"x": [{"installPath": 5}]}}',
],
)
def test_get_plugin_servers_robust_to_bad_registry(tmp_path: Path, contents: str) -> None:
registry = tmp_path / ".claude" / "plugins" / "installed_plugins.json"
registry.parent.mkdir(parents=True)
registry.write_text(contents, encoding="utf-8")
reg = _make_registrar(tmp_path, cli=None)
assert reg.get_plugin_servers("serena") == []
@pytest.mark.parametrize(
"mcp_json",
["", "not json", "[]", '{"mcpServers": []}', '{"serena": "oops"}', '{"other": {}}'],
)
def test_get_plugin_servers_robust_to_bad_plugin_mcp_json(tmp_path: Path, mcp_json: str) -> None:
_install_plugin(tmp_path / ".claude", mcp_json=mcp_json)
reg = _make_registrar(tmp_path, cli=None)
assert reg.get_plugin_servers("serena") == []
def test_get_plugin_servers_tolerates_missing_install_path(tmp_path: Path) -> None:
_install_plugin(
tmp_path / ".claude",
records=[{"scope": "user", "installPath": str(tmp_path / "gone")}],
)
reg = _make_registrar(tmp_path, cli=None)
assert reg.get_plugin_servers("serena") == []