mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
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:
@@ -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)
|
||||
|
||||
|
||||
@@ -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")
|
||||
|
||||
@@ -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
@@ -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
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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") == []
|
||||
|
||||
Reference in New Issue
Block a user