Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(mcp): register managed installs with a resolvable headroom command (#1386)
Rod Boev22def931770e
diff --git a/e2e/init/run.py b/e2e/init/run.pyindex b28c8315b..95166ed8b 100644--- a/e2e/init/run.py+++ b/e2e/init/run.py@@ -43,6 +43,7 @@ from e2e._lib import ( # noqa: E402run_cases,)from headroom.cli import init as init_cli # noqa: E402+from headroom.install.runtime import resolve_headroom_command # noqa: E402# ----- helpers reused across cases --------------------------------------------@@ -51,6 +52,30 @@ from headroom.cli import init as init_cli # noqa: E402REPO_ROOT_IN_CONTAINER = Path("/workspace")+def _expected_headroom_mcp_calls(proxy_url: str) -> list[list[str]]:+ # The harness restores PATH before assertions, but `headroom init` ran with a+ # scrubbed PATH where the console-script entrypoint may be unavailable.+ prefix = [+ "mcp",+ "add",+ "headroom",+ "-s",+ "user",+ "-e",+ f"HEADROOM_PROXY_URL={proxy_url}",+ "--",+ ]+ variants = [+ [*prefix, *resolve_headroom_command(), "mcp", "serve"],+ [*prefix, sys.executable, "-m", "headroom.cli", "mcp", "serve"],+ ]+ deduped: list[list[str]] = []+ for variant in variants:+ if variant not in deduped:+ deduped.append(variant)+ return deduped++def _read_jsonl(path: Path) -> list[dict[str, object]]:if not path.exists():return []@@ -111,24 +136,16 @@ def _verify_claude_local(ctx: CaseContext) -> None:# being dead pointers for users who never ran `headroom mcp install`).# The `-e HEADROOM_PROXY_URL=…` arg is only emitted when the proxy# port differs from the 8787 default; this case uses --port 9011.- expected = [+ expected_prefix = [["plugin", "marketplace", "add", str(REPO_ROOT_IN_CONTAINER)],["plugin", "install", "headroom@headroom-marketplace", "--scope", "local"],- [- "mcp",- "add",- "headroom",- "-s",- "user",- "-e",- "HEADROOM_PROXY_URL=http://127.0.0.1:9011",- "--",- "headroom",- "mcp",- "serve",- ],]- if claude_calls != expected:+ expected_mcp_calls = _expected_headroom_mcp_calls("http://127.0.0.1:9011")+ if (+ len(claude_calls) != 3+ or claude_calls[:2] != expected_prefix+ or claude_calls[2] not in expected_mcp_calls+ ):raise AssertionError(f"Unexpected Claude install commands: {claude_calls}")diff --git a/headroom/mcp_registry/install.py b/headroom/mcp_registry/install.pyindex 89b1b7d03..49834e1b8 100644--- a/headroom/mcp_registry/install.py+++ b/headroom/mcp_registry/install.py@@ -4,6 +4,8 @@ from __future__ import annotationsfrom collections.abc import Iterable+from headroom.install.runtime import resolve_headroom_command+from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpecfrom .claude import ClaudeRegistrarfrom .codex import CodexRegistrar@@ -30,10 +32,11 @@ def build_headroom_spec(proxy_url: str = DEFAULT_PROXY_URL) -> ServerSpec:env: dict[str, str] = {}if proxy_url and proxy_url != DEFAULT_PROXY_URL:env["HEADROOM_PROXY_URL"] = proxy_url+ command = resolve_headroom_command()return ServerSpec(name="headroom",- command="headroom",- args=("mcp", "serve"),+ command=command[0],+ args=(*command[1:], "mcp", "serve"),env=env,)diff --git a/tests/test_cli/test_wrap_codex.py b/tests/test_cli/test_wrap_codex.pyindex 41ea3aa67..44cbe3c74 100644--- a/tests/test_cli/test_wrap_codex.py+++ b/tests/test_cli/test_wrap_codex.py@@ -15,10 +15,12 @@ from pathlib import Pathfrom unittest.mock import patchimport pytest+import tomllibfrom click.testing import CliRunnerfrom headroom.cli import wrap as wrap_modfrom headroom.cli.main import main+from headroom.mcp_registry.install import build_headroom_specdef _set_test_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:@@ -1010,9 +1012,13 @@ def test_wrap_codex_prepare_only_updates_stale_mcp_proxy_url(assert result.exit_code == 0, result.outputcontent = config_file.read_text(encoding="utf-8")+ parsed = tomllib.loads(content)+ expected = build_headroom_spec()+ headroom_mcp = parsed["mcp_servers"]["headroom"]assert "[mcp_servers.headroom]" in content- assert 'command = "headroom"' in content- assert 'args = ["mcp", "serve"]' in content+ assert headroom_mcp["command"] == expected.command+ assert headroom_mcp["args"] == list(expected.args)+ assert "env" not in headroom_mcp or "HEADROOM_PROXY_URL" not in headroom_mcp["env"]assert "http://127.0.0.1:9000" not in contentdiff --git a/tests/test_mcp_registry/test_claude_registrar.py b/tests/test_mcp_registry/test_claude_registrar.pyindex ad44bcde9..12a1e2f68 100644--- a/tests/test_mcp_registry/test_claude_registrar.py+++ b/tests/test_mcp_registry/test_claude_registrar.py@@ -11,6 +11,10 @@ import pytestfrom headroom.mcp_registry.base import RegisterStatus, ServerSpecfrom headroom.mcp_registry.claude import ClaudeRegistrar+from headroom.mcp_registry.install import build_headroom_spec++_RESOLVED_COMMAND = ("/usr/bin/python", "-m", "headroom.cli")+_RESOLVED_ARGS = ("-m", "headroom.cli", "mcp", "serve")def _make_registrar(@@ -25,12 +29,20 @@ def _make_registrar(def _spec() -> ServerSpec:return ServerSpec(name="headroom",- command="headroom",- args=("mcp", "serve"),+ command="/usr/bin/python",+ args=("-m", "headroom.cli", "mcp", "serve"),env={},)+def _install_spec(monkeypatch: pytest.MonkeyPatch) -> ServerSpec:+ monkeypatch.setattr(+ "headroom.mcp_registry.install.resolve_headroom_command",+ lambda: list(_RESOLVED_COMMAND),+ )+ return build_headroom_spec()++# ----------------------------------------------------------------------# detect()# ----------------------------------------------------------------------@@ -70,8 +82,8 @@ def test_get_server_reads_modern_config(tmp_path: Path) -> None:{"mcpServers": {"headroom": {- "command": "headroom",- "args": ["mcp", "serve"],+ "command": _RESOLVED_COMMAND[0],+ "args": list(_RESOLVED_ARGS),"env": {"HEADROOM_PROXY_URL": "http://127.0.0.1:9000"},}}@@ -81,8 +93,8 @@ def test_get_server_reads_modern_config(tmp_path: Path) -> None:reg = _make_registrar(tmp_path, cli=None)got = reg.get_server("headroom")assert got is not None- assert got.command == "headroom"- assert got.args == ("mcp", "serve")+ assert got.command == _RESOLVED_COMMAND[0]+ assert got.args == _RESOLVED_ARGSassert got.env == {"HEADROOM_PROXY_URL": "http://127.0.0.1:9000"}@@ -90,13 +102,22 @@ def test_get_server_falls_back_to_legacy(tmp_path: Path) -> None:cfg = tmp_path / ".claude" / "mcp.json"cfg.parent.mkdir()cfg.write_text(- json.dumps({"mcpServers": {"headroom": {"command": "headroom", "args": ["mcp", "serve"]}}})+ json.dumps(+ {+ "mcpServers": {+ "headroom": {+ "command": _RESOLVED_COMMAND[0],+ "args": list(_RESOLVED_ARGS),+ }+ }+ }+ ))reg = _make_registrar(tmp_path, cli=None)got = reg.get_server("headroom")assert got is not None- assert got.command == "headroom"- assert got.args == ("mcp", "serve")+ assert got.command == _RESOLVED_COMMAND[0]+ assert got.args == _RESOLVED_ARGSassert got.env == {}@@ -105,14 +126,23 @@ def test_get_server_reads_claude_config_dir() -> None:cfg = tmp_path / ".claude.json"cfg.write_text(- json.dumps({"mcpServers": {"headroom": {"command": "headroom", "args": ["mcp", "serve"]}}})+ json.dumps(+ {+ "mcpServers": {+ "headroom": {+ "command": _RESOLVED_COMMAND[0],+ "args": list(_RESOLVED_ARGS),+ }+ }+ }+ ))monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path))reg = ClaudeRegistrar(claude_cli=None)got = reg.get_server("headroom")assert got is not None- assert got.command == "headroom"- assert got.args == ("mcp", "serve")+ assert got.command == _RESOLVED_COMMAND[0]+ assert got.args == _RESOLVED_ARGS# ----------------------------------------------------------------------@@ -120,11 +150,13 @@ def test_get_server_reads_claude_config_dir(# -----------------------------------------------------------------------def test_register_via_cli_calls_claude_mcp_add(tmp_path: Path) -> None:+def test_register_via_cli_calls_claude_mcp_add(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:reg = _make_registrar(tmp_path, cli="/usr/local/bin/claude")fake_result = subprocess.CompletedProcess(args=[], returncode=0, stdout="", stderr="")with patch("subprocess.run", return_value=fake_result) as run_mock:- result = reg.register_server(_spec())+ result = reg.register_server(_install_spec(monkeypatch))assert result.status == RegisterStatus.REGISTEREDcmds = [call.args[0] for call in run_mock.call_args_list]add_cmd = next(c for c in cmds if "add" in c)@@ -136,19 +168,18 @@ def test_register_via_cli_calls_claude_mcp_add(tmp_path: Path) -> None:"-s","user",]- assert add_cmd[-3:] == ["--", "headroom", "mcp"] or add_cmd[-4:] == [+ assert add_cmd[-(len(_RESOLVED_ARGS) + 2) :] == ["--",- "headroom",- "mcp",- "serve",+ _RESOLVED_COMMAND[0],+ *_RESOLVED_ARGS,]def test_register_via_cli_includes_env(tmp_path: Path) -> None:spec = ServerSpec(name="headroom",- command="headroom",- args=("mcp", "serve"),+ command=_RESOLVED_COMMAND[0],+ args=_RESOLVED_ARGS,env={"HEADROOM_PROXY_URL": "http://127.0.0.1:9000"},)reg = _make_registrar(tmp_path, cli="/usr/local/bin/claude")@@ -168,8 +199,8 @@ def test_register_writes_file_when_no_cli(tmp_path: Path) -> None:cfg = tmp_path / ".claude" / ".claude.json"data = json.loads(cfg.read_text())assert "headroom" in data["mcpServers"]- assert data["mcpServers"]["headroom"]["command"] == "headroom"- assert data["mcpServers"]["headroom"]["args"] == ["mcp", "serve"]+ assert data["mcpServers"]["headroom"]["command"] == _RESOLVED_COMMAND[0]+ assert data["mcpServers"]["headroom"]["args"] == list(_RESOLVED_ARGS)def test_register_writes_to_legacy_when_only_legacy_exists(tmp_path: Path) -> None:@@ -194,7 +225,7 @@ def test_register_writes_to_claude_config_dir(assert result.status == RegisterStatus.REGISTEREDcfg = tmp_path / ".claude.json"data = json.loads(cfg.read_text())- assert data["mcpServers"]["headroom"]["command"] == "headroom"+ assert data["mcpServers"]["headroom"]["command"] == _RESOLVED_COMMAND[0]assert not (tmp_path / ".claude" / ".claude.json").exists()@@ -207,7 +238,16 @@ def test_register_already_when_spec_matches(tmp_path: Path) -> None:cfg = tmp_path / ".claude" / ".claude.json"cfg.parent.mkdir()cfg.write_text(- json.dumps({"mcpServers": {"headroom": {"command": "headroom", "args": ["mcp", "serve"]}}})+ json.dumps(+ {+ "mcpServers": {+ "headroom": {+ "command": _RESOLVED_COMMAND[0],+ "args": list(_RESOLVED_ARGS),+ }+ }+ }+ ))reg = _make_registrar(tmp_path, cli="/usr/local/bin/claude")with patch("subprocess.run") as run_mock:@@ -224,8 +264,8 @@ def test_register_mismatch_when_spec_differs_no_force(tmp_path: Path) -> None:{"mcpServers": {"headroom": {- "command": "headroom",- "args": ["mcp", "serve"],+ "command": _RESOLVED_COMMAND[0],+ "args": list(_RESOLVED_ARGS),"env": {"HEADROOM_PROXY_URL": "http://127.0.0.1:9999"},}}@@ -305,7 +345,7 @@ def test_unregister_via_file_when_no_cli(tmp_path: Path) -> None:json.dumps({"mcpServers": {- "headroom": {"command": "headroom", "args": ["mcp", "serve"]},+ "headroom": {"command": _RESOLVED_COMMAND[0], "args": list(_RESOLVED_ARGS)},"other": {"command": "other"},}}@@ -331,7 +371,7 @@ def test_unregister_removes_from_claude_config_dir(json.dumps({"mcpServers": {- "headroom": {"command": "headroom", "args": ["mcp", "serve"]},+ "headroom": {"command": _RESOLVED_COMMAND[0], "args": list(_RESOLVED_ARGS)},"other": {"command": "other"},}}diff --git a/tests/test_mcp_registry/test_codex_registrar.py b/tests/test_mcp_registry/test_codex_registrar.pyindex 7032bf854..6a48b4d2b 100644--- a/tests/test_mcp_registry/test_codex_registrar.py+++ b/tests/test_mcp_registry/test_codex_registrar.py@@ -9,6 +9,7 @@ import pytestfrom headroom.mcp_registry.base import RegisterStatus, ServerSpecfrom headroom.mcp_registry.codex import CodexRegistrar+from headroom.mcp_registry.install import build_headroom_specif sys.version_info >= (3, 11):import tomllib@@ -16,6 +17,10 @@ else: # pragma: no coverimport tomli as tomllib+_RESOLVED_COMMAND = ("/usr/bin/python", "-m", "headroom.cli")+_RESOLVED_ARGS = ("-m", "headroom.cli", "mcp", "serve")++def _make_registrar(tmp_path: Path) -> CodexRegistrar:return CodexRegistrar(home_dir=tmp_path)@@ -23,12 +28,20 @@ def _make_registrar(tmp_path: Path) -> CodexRegistrar:def _spec(env: dict[str, str] | None = None) -> ServerSpec:return ServerSpec(name="headroom",- command="headroom",- args=("mcp", "serve"),+ command=_RESOLVED_COMMAND[0],+ args=_RESOLVED_ARGS,env=env or {},)+def _install_spec(monkeypatch: pytest.MonkeyPatch) -> ServerSpec:+ monkeypatch.setattr(+ "headroom.mcp_registry.install.resolve_headroom_command",+ lambda: list(_RESOLVED_COMMAND),+ )+ return build_headroom_spec()++def _serena_spec() -> ServerSpec:return ServerSpec(name="serena",@@ -111,16 +124,16 @@ def test_get_server_returns_spec_when_table_present(tmp_path: Path) -> None:cfg.parent.mkdir()cfg.write_text("[mcp_servers.headroom]\n"- 'command = "headroom"\n'- 'args = ["mcp", "serve"]\n'+ f"command = {_RESOLVED_COMMAND[0]!r}\n"+ f"args = {list(_RESOLVED_ARGS)!r}\n""\n""[mcp_servers.headroom.env]\n"'HEADROOM_PROXY_URL = "http://127.0.0.1:9000"\n')got = _make_registrar(tmp_path).get_server("headroom")assert got is not None- assert got.command == "headroom"- assert got.args == ("mcp", "serve")+ assert got.command == _RESOLVED_COMMAND[0]+ assert got.args == _RESOLVED_ARGSassert got.env == {"HEADROOM_PROXY_URL": "http://127.0.0.1:9000"}@@ -136,9 +149,11 @@ def test_get_server_robust_to_unparseable_toml(tmp_path: Path) -> None:# -----------------------------------------------------------------------def test_register_creates_config_when_missing(tmp_path: Path) -> None:+def test_register_creates_config_when_missing(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:reg = _make_registrar(tmp_path)- result = reg.register_server(_spec())+ result = reg.register_server(_install_spec(monkeypatch))assert result.status == RegisterStatus.REGISTEREDcfg = _config_path(tmp_path)assert cfg.exists()@@ -146,8 +161,8 @@ def test_register_creates_config_when_missing(tmp_path: Path) -> None:assert "# --- Headroom MCP server ---" in textassert "[mcp_servers.headroom]" in textparsed = tomllib.loads(text)- assert parsed["mcp_servers"]["headroom"]["command"] == "headroom"- assert parsed["mcp_servers"]["headroom"]["args"] == ["mcp", "serve"]+ assert parsed["mcp_servers"]["headroom"]["command"] == _RESOLVED_COMMAND[0]+ assert parsed["mcp_servers"]["headroom"]["args"] == list(_RESOLVED_ARGS)def test_register_appends_to_existing_config_preserves_other_keys(tmp_path: Path) -> None:@@ -166,7 +181,7 @@ def test_register_appends_to_existing_config_preserves_other_keys(tmp_path: Pathparsed = tomllib.loads(text)assert parsed["model"] == "gpt-4o"assert parsed["other_section"]["value"] == 42- assert parsed["mcp_servers"]["headroom"]["command"] == "headroom"+ assert parsed["mcp_servers"]["headroom"]["command"] == _RESOLVED_COMMAND[0]def test_register_includes_env_subtable(tmp_path: Path) -> None:@@ -193,7 +208,7 @@ def test_register_headroom_and_serena_coexist(tmp_path: Path) -> None:assert "# --- Headroom MCP server: serena ---" in textparsed = tomllib.loads(text)- assert parsed["mcp_servers"]["headroom"]["command"] == "headroom"+ assert parsed["mcp_servers"]["headroom"]["command"] == _RESOLVED_COMMAND[0]assert parsed["mcp_servers"]["serena"]["command"] == "uvx"@@ -326,11 +341,11 @@ def test_unregister_preserves_user_managed_entry(tmp_path: Path) -> None:@pytest.mark.parametrize("spec",[- ServerSpec(name="headroom", command="headroom", args=("mcp", "serve")),+ ServerSpec(name="headroom", command=_RESOLVED_COMMAND[0], args=_RESOLVED_ARGS),ServerSpec(name="headroom",- command="headroom",- args=("mcp", "serve"),+ command=_RESOLVED_COMMAND[0],+ args=_RESOLVED_ARGS,env={"HEADROOM_PROXY_URL": "http://127.0.0.1:9000"},),ServerSpec(name="headroom", command="/usr/bin/headroom", args=()),diff --git a/tests/test_mcp_registry/test_install.py b/tests/test_mcp_registry/test_install.pyindex af5cfcd43..674199992 100644--- a/tests/test_mcp_registry/test_install.py+++ b/tests/test_mcp_registry/test_install.py@@ -51,10 +51,14 @@ class _FakeRegistrar(MCPRegistrar):# -----------------------------------------------------------------------def test_build_spec_default_proxy_no_env() -> None:+def test_build_spec_default_proxy_no_env(monkeypatch) -> None:+ monkeypatch.setattr(+ "headroom.mcp_registry.install.resolve_headroom_command",+ lambda: ["/opt/headroom/bin/headroom"],+ )spec = build_headroom_spec()assert spec.name == "headroom"- assert spec.command == "headroom"+ assert spec.command == "/opt/headroom/bin/headroom"assert spec.args == ("mcp", "serve")assert spec.env == {}@@ -69,6 +73,17 @@ def test_build_spec_default_url_omits_env() -> None:assert spec.env == {}+def test_build_spec_falls_back_to_python_module_when_no_binary(monkeypatch) -> None:+ monkeypatch.setattr("headroom.install.runtime.shutil.which", lambda name: None)+ monkeypatch.setattr("headroom.install.runtime.sys.executable", "/usr/bin/python")++ spec = build_headroom_spec()++ assert spec.command == "/usr/bin/python"+ assert spec.args == ("-m", "headroom.cli", "mcp", "serve")+ assert spec.env == {}++def test_build_serena_spec_uses_agent_context() -> None:spec = build_serena_spec("codex")assert spec.name == "serena"