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): auto-register headroom MCP server in wrap claude/codex and init -g
Tejas Choprad9d8972ac4f5
diff --git a/headroom/cli/init.py b/headroom/cli/init.pyindex 17363ccca..a01dc293c 100644--- a/headroom/cli/init.py+++ b/headroom/cli/init.py@@ -697,6 +697,32 @@ def _run_init_targets(elif target == "openclaw":_init_openclaw(global_scope=global_scope, port=port)+ # Register the headroom MCP server with every targeted agent that has+ # a registrar implemented. Wave 1 covers Claude Code; subsequent waves+ # add Cursor / Codex / Continue / Cline / Windsurf / Goose without+ # touching the call sites.+ _install_headroom_mcp_for_targets(targets=targets, port=port)+++def _install_headroom_mcp_for_targets(*, targets: list[str], port: int) -> None:+ """Install the headroom MCP server into each detected target agent."""+ from headroom.mcp_registry import format_results, install_everywhere++ proxy_url = f"http://127.0.0.1:{port}"+ results = install_everywhere(proxy_url=proxy_url, agents=targets)+ if not results:+ return++ lines = format_results(+ results,+ verbose=True,+ overwrite_hint=f"headroom mcp install --proxy-url {proxy_url} --force",+ )+ if lines:+ click.echo("\nMCP retrieve tool:")+ for line in lines:+ click.echo(line)+@main.group(invoke_without_command=True)@click.option("-g", "--global", "global_scope", is_flag=True, help="Install for the current user.")diff --git a/headroom/cli/mcp.py b/headroom/cli/mcp.pyindex 260ea82d9..efb62b563 100644--- a/headroom/cli/mcp.py+++ b/headroom/cli/mcp.py@@ -95,24 +95,32 @@ def mcp() -> None:default=DEFAULT_PROXY_URL,help=f"Headroom proxy URL (default: {DEFAULT_PROXY_URL})",)+ "--agent",+ "agents",+ multiple=True,+ help="Restrict installation to specific agents (default: every detected agent).",+)@click.option("--force",is_flag=True,- help="Overwrite existing headroom config",+ help="Overwrite existing headroom config in case of mismatch.",)-def mcp_install(proxy_url: str, force: bool) -> None:- """Install Headroom MCP server into Claude Code config.+def mcp_install(proxy_url: str, agents: tuple[str, ...], force: bool) -> None:+ """Install the Headroom MCP server into every detected coding agent.\b- This registers headroom with Claude Code so it can use the- headroom_retrieve tool for CCR (Compress-Cache-Retrieve).+ By default this installs into every agent that has a registrar and is+ detected on this system (Claude Code today; Cursor / Codex / Continue /+ others added in subsequent releases). Pass ``--agent NAME`` one or more+ times to restrict the installation.\b- Example:- headroom mcp install+ Examples:+ headroom mcp install # every detected agent+ headroom mcp install --agent claude # Claude Code onlyheadroom mcp install --proxy-url http://localhost:9000"""- # Check for MCP SDKtry:import mcp # noqa: F401except ImportError:@@ -120,98 +128,35 @@ def mcp_install(proxy_url: str, force: bool) -> None:click.echo("Install with: pip install 'headroom-ai[mcp]'", err=True)raise SystemExit(1) from None- command = get_headroom_command()- env: dict[str, str] = {}- if proxy_url != DEFAULT_PROXY_URL:- env["HEADROOM_PROXY_URL"] = proxy_url-- # Prefer `claude mcp add` (Claude Code CLI ≥2.x stores servers in- # ~/.claude/.claude.json, which is what `claude mcp list` reads).- claude_cli = shutil.which("claude")- used_claude_cli = False- if claude_cli:- # Check if already registered- result = subprocess.run(- [claude_cli, "mcp", "get", "headroom"],- capture_output=True,- text=True,- )- already_registered = result.returncode == 0-- if already_registered and not force:- click.echo("Headroom MCP is already configured in Claude Code.")- click.echo("Use --force to overwrite, or 'headroom mcp uninstall' first.")- raise SystemExit(0)-- if already_registered and force:- subprocess.run(- [claude_cli, "mcp", "remove", "headroom", "-s", "user"],- capture_output=True,- )-- add_cmd = [claude_cli, "mcp", "add", "headroom", "-s", "user"]- for k, v in env.items():- add_cmd += ["-e", f"{k}={v}"]- add_cmd += ["--", *command]+ from headroom.mcp_registry import any_succeeded, format_results, install_everywhere- result = subprocess.run(add_cmd, capture_output=True, text=True)- if result.returncode == 0:- used_claude_cli = True- else:- click.echo(- f"Warning: 'claude mcp add' failed ({result.stderr.strip()}), "- "falling back to mcp.json.",- err=True,- )-- if not used_claude_cli:- # Fallback: write ~/.claude/mcp.json (used by older Claude Code versions- # and the Claude.ai desktop app).- config = load_mcp_config()-- if "headroom" in config.get("mcpServers", {}) and not force:- click.echo("Headroom MCP is already configured in Claude Code.")- click.echo("Use --force to overwrite, or 'headroom mcp uninstall' first.")- raise SystemExit(0)-- server_config: dict = {"command": command[0], "args": command[1:]}- if env:- server_config["env"] = env-- if "mcpServers" not in config:- config["mcpServers"] = {}- config["mcpServers"]["headroom"] = server_config- save_mcp_config(config)-- config_note = (- "Registered via: claude mcp add (scope: user)"- if used_claude_cli- else f"Configuration written to: {MCP_CONFIG_PATH}"+ results = install_everywhere(+ proxy_url=proxy_url,+ agents=list(agents) if agents else None,+ force=force,)- click.echo(f"""-✓ Headroom MCP server installed!--{config_note}--Next steps:- 1. Start the Headroom proxy (if not running):- headroom proxy-- 2. Start Claude Code WITH the proxy base URL:- ANTHROPIC_BASE_URL={proxy_url} claude-- 3. Claude Code now has:- - All requests compressed through the proxy (saves tokens & cost)- - Access to headroom_retrieve tool for CCR retrieval- - Stats visible at {proxy_url}/stats--NOTE: The MCP server provides on-demand compression tools-(headroom_compress, headroom_retrieve, headroom_stats). For automatic-compression of ALL traffic, also set ANTHROPIC_BASE_URL as shown above.--Proxy URL: {proxy_url}-""")+ if not results:+ click.echo("No agents matched the requested filter.")+ raise SystemExit(1)++ click.echo("Installing Headroom MCP server...")+ for line in format_results(+ results,+ verbose=True,+ overwrite_hint=f"headroom mcp install --proxy-url {proxy_url} --force",+ ):+ click.echo(line)++ if not any_succeeded(results):+ raise SystemExit(1)++ click.echo(+ f"\nNext steps:\n"+ f" 1. Start the Headroom proxy (if not running): headroom proxy\n"+ f" 2. Start your agent (e.g.) ANTHROPIC_BASE_URL={proxy_url} claude\n"+ f" 3. Restart any agent that was already running so it picks up the new MCP server.\n"+ )@mcp.command("uninstall")diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex 4d22eeda6..0d4019520 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -242,6 +242,39 @@ def _setup_rtk(verbose: bool = False) -> Path | None:return rtk_path+def _setup_headroom_mcp(registrar: Any, port: int, *, verbose: bool = False) -> None:+ """Register the headroom MCP server with the given agent (idempotent).++ The proxy compresses tool_result payloads and emits ``[Retrieve more:+ hash=…]`` markers. Without this registration those markers point at+ nothing — the agent has no ``headroom_retrieve`` tool to call.++ Generic across registrars: ``ClaudeRegistrar``, ``CodexRegistrar``, and+ any future agent registrar all flow through the same setup path.+ """+ from headroom.mcp_registry import build_headroom_spec, format_result++ if not registrar.detect():+ if verbose:+ click.echo(f" MCP retrieve tool: {registrar.display_name} not detected — skipping")+ return++ proxy_url = f"http://127.0.0.1:{port}"+ spec = build_headroom_spec(proxy_url)+ result = registrar.register_server(spec)++ line = format_result(+ registrar.name,+ result,+ label="MCP retrieve tool",+ verbose=verbose,+ overwrite_hint=f"headroom mcp install --proxy-url {proxy_url} --force",+ restart_hint=f"restart {registrar.display_name} if it was already running",+ )+ if line is not None:+ click.echo(line)++_CBM_MCP_SERVER_NAME = "codebase-memory-mcp"@@ -1336,6 +1369,11 @@ def unwrap() -> None:@wrap.command(context_settings={"ignore_unknown_options": True})@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")@click.option("--no-rtk", is_flag=True, help="Skip rtk installation and hook registration")+ "--no-mcp",+ is_flag=True,+ help="Skip headroom MCP server registration (compression markers will be unactionable)",+)@click.option("--code-graph",is_flag=True,@@ -1352,6 +1390,7 @@ def unwrap() -> None:def claude(port: int,no_rtk: bool,+ no_mcp: bool,code_graph: bool,no_proxy: bool,learn: bool,@@ -1374,6 +1413,7 @@ def claude(headroom wrap claude -- -p # Claude in print modeheadroom wrap claude --code-graph # With code graph intelligenceheadroom wrap claude --no-rtk # Skip rtk (proxy only)+ headroom wrap claude --no-mcp # Skip MCP retrieve tool registration"""if prepare_only:if not no_rtk:@@ -1451,6 +1491,13 @@ def claude(elif verbose:click.echo(" Skipping rtk (--no-rtk)")+ if not no_mcp:+ from headroom.mcp_registry import ClaudeRegistrar++ _setup_headroom_mcp(ClaudeRegistrar(), port, verbose=verbose)+ elif verbose:+ click.echo(" Skipping MCP retrieve tool (--no-mcp)")+if code_graph:_setup_code_graph(verbose=verbose)@@ -1659,6 +1706,11 @@ def copilot(@wrap.command(context_settings={"ignore_unknown_options": True})@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")@click.option("--no-rtk", is_flag=True, help="Skip rtk installation and AGENTS.md injection")+ "--no-mcp",+ is_flag=True,+ help="Skip headroom MCP server registration (compression markers will be unactionable)",+)@click.option("--code-graph",is_flag=True,@@ -1688,6 +1740,7 @@ def copilot(def codex(port: int,no_rtk: bool,+ no_mcp: bool,code_graph: bool,no_proxy: bool,learn: bool,@@ -1704,16 +1757,28 @@ def codex(\bSets OPENAI_BASE_URL to route all OpenAI API calls through Headroom.Installs rtk and injects instructions into AGENTS.md so Codex uses- token-optimized commands (60-90% savings on shell output).+ token-optimized commands (60-90% savings on shell output). Also+ registers the headroom MCP server in ~/.codex/config.toml so Codex+ can call ``headroom_retrieve`` on compression markers.\bExamples:- headroom wrap codex # Start proxy + rtk + codex+ headroom wrap codex # Start proxy + rtk + mcp + codexheadroom wrap codex -- "fix the bug" # Pass prompt to codexheadroom wrap codex --no-rtk # Skip rtk setup+ headroom wrap codex --no-mcp # Skip MCP retrieve tool registrationheadroom wrap codex --port 9999 # Custom proxy portheadroom wrap codex --backend anyllm --anyllm-provider groq"""+ # Snapshot ~/.codex/config.toml BEFORE any wrap-time mutation so+ # `headroom unwrap codex` can restore the user's pre-wrap state+ # byte-for-byte. The snapshot is a no-op if the backup already exists+ # or if the file already has Headroom markers, so this is safe to+ # call repeatedly. Crucially this must run before MCP install, which+ # writes its marker block to the same file.+ _codex_config_file, _codex_backup_file = _codex_config_paths()+ _snapshot_codex_config_if_unwrapped(_codex_config_file, _codex_backup_file)+# Setup rtk for Codex (binary + AGENTS.md instructions, no hooks)if not no_rtk:click.echo(" Setting up rtk for Codex...")@@ -1727,6 +1792,15 @@ def codex(global_agents = Path.home() / ".codex" / "AGENTS.md"_inject_rtk_instructions(global_agents, verbose=verbose)+ # Register headroom MCP server in ~/.codex/config.toml so Codex can+ # call headroom_retrieve on compression markers from the proxy.+ if not no_mcp:+ from headroom.mcp_registry import CodexRegistrar++ _setup_headroom_mcp(CodexRegistrar(), port, verbose=verbose)+ elif verbose:+ click.echo(" Skipping MCP retrieve tool (--no-mcp)")+# Setup memory MCP server for Codex (native tool integration)if memory:click.echo(" Setting up memory for Codex...")diff --git a/headroom/mcp_registry/__init__.py b/headroom/mcp_registry/__init__.pynew file mode 100644index 000000000..e65508777--- /dev/null+++ b/headroom/mcp_registry/__init__.py@@ -0,0 +1,41 @@+"""Generic MCP server registration across coding agents.++The MCP protocol is universal but each agent's *registration* mechanism is+not — Claude Code uses its own CLI + ``~/.claude/.claude.json``, Cursor+writes ``~/.cursor/mcp.json``, Codex patches a TOML file, and so on. This+module provides a uniform interface so headroom can install its MCP server+(``headroom mcp serve``) into every detected agent.++Wave 1 ships :class:`ClaudeRegistrar`. Other registrars (Cursor, Codex,+Continue, Cline, Windsurf, Goose, OpenHands) are added in subsequent waves+without changing the calling code.+"""++from __future__ import annotations++from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec+from .claude import ClaudeRegistrar+from .codex import CodexRegistrar+from .display import any_succeeded, format_result, format_results+from .install import (+ DEFAULT_PROXY_URL,+ build_headroom_spec,+ get_all_registrars,+ install_everywhere,+)++__all__ = [+ "DEFAULT_PROXY_URL",+ "ClaudeRegistrar",+ "CodexRegistrar",+ "MCPRegistrar",+ "RegisterResult",+ "RegisterStatus",+ "ServerSpec",+ "any_succeeded",+ "build_headroom_spec",+ "format_result",+ "format_results",+ "get_all_registrars",+ "install_everywhere",+]diff --git a/headroom/mcp_registry/base.py b/headroom/mcp_registry/base.pynew file mode 100644index 000000000..3628b6925--- /dev/null+++ b/headroom/mcp_registry/base.py@@ -0,0 +1,106 @@+"""Abstract base for per-agent MCP registrars.++The MCP protocol itself is universal, and the headroom MCP server+(``headroom mcp serve``) is a single stdio binary that any compliant client+can launch. What differs between agents (Claude Code, Cursor, Codex, ...) is+how each one *learns* that a server exists: each invented its own config+file, format, and registration mechanism.++Subclasses of :class:`MCPRegistrar` own one agent's registration mechanism.+The orchestrator in :mod:`headroom.mcp_registry.install` calls a fleet of+registrars to install headroom across every detected agent.+"""++from __future__ import annotations++from abc import ABC, abstractmethod+from dataclasses import dataclass, field+from enum import Enum+++class RegisterStatus(str, Enum):+ """Outcome of a :meth:`MCPRegistrar.register_server` call."""++ REGISTERED = "registered"+ """Newly written to the agent's MCP config."""++ ALREADY = "already"+ """Already present with a configuration that matches the requested spec."""++ MISMATCH = "mismatch"+ """Already present but with a different configuration; left untouched."""++ FAILED = "failed"+ """Registration was attempted but the agent's tooling rejected it."""++ NOT_DETECTED = "not_detected"+ """The agent does not appear to be installed on this system."""++ NO_SDK = "no_sdk"+ """A required Python dependency is missing (e.g. the ``mcp`` package)."""+++@dataclass+class ServerSpec:+ """Universal description of an MCP server to register.++ Each registrar serializes this to its agent's native config format. The+ fields cover what every JSON/TOML schema we've seen requires.+ """++ name: str+ command: str+ args: tuple[str, ...] = ()+ env: dict[str, str] = field(default_factory=dict)+++@dataclass+class RegisterResult:+ """Outcome plus a human-readable detail string."""++ status: RegisterStatus+ detail: str | None = None++ @property+ def ok(self) -> bool:+ """True when the server is registered (newly or already)."""+ return self.status in (RegisterStatus.REGISTERED, RegisterStatus.ALREADY)+++class MCPRegistrar(ABC):+ """Per-agent MCP server registrar.++ Each subclass owns exactly one agent's config schema and write path.++ Contract:++ * :meth:`detect` — does this agent appear installed?+ * :meth:`get_server` — read current config; return the spec or ``None``.+ * :meth:`register_server` — idempotent install. If the named server is+ already registered with a different spec, returns+ :attr:`RegisterStatus.MISMATCH` and does **not** overwrite unless+ ``force=True``.+ * :meth:`unregister_server` — remove the named server.+ """++ #: Stable agent identifier ("claude", "cursor", "codex", ...).+ name: str = ""++ #: Human-readable display name ("Claude Code", "Cursor", ...).+ display_name: str = ""++ @abstractmethod+ def detect(self) -> bool:+ """Return True if this agent appears to be installed."""++ @abstractmethod+ def get_server(self, server_name: str) -> ServerSpec | None:+ """Return the registered :class:`ServerSpec`, or ``None`` if absent."""++ @abstractmethod+ def register_server(self, spec: ServerSpec, *, force: bool = False) -> RegisterResult:+ """Idempotently register an MCP server."""++ @abstractmethod+ def unregister_server(self, server_name: str) -> bool:+ """Remove the named server. Returns True on success."""diff --git a/headroom/mcp_registry/claude.py b/headroom/mcp_registry/claude.pynew file mode 100644index 000000000..0550563ea--- /dev/null+++ b/headroom/mcp_registry/claude.py@@ -0,0 +1,256 @@+"""Claude Code MCP registrar.++Claude Code 2.x stores MCP server configuration in ``~/.claude/.claude.json``+and ships a CLI (``claude mcp add/remove/list/get``) that owns the file.+Older Claude Code releases (and the Claude Desktop app) read+``~/.claude/mcp.json``. 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.+"""++from __future__ import annotations++import json+import logging+import shutil+import subprocess+from pathlib import Path+from typing import Any++from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec++logger = logging.getLogger(__name__)+++class ClaudeRegistrar(MCPRegistrar):+ """Register MCP servers with Claude Code."""++ name = "claude"+ display_name = "Claude Code"++ def __init__(+ self,+ *,+ claude_cli: str | None | object = ...,+ home_dir: Path | None = None,+ ) -> None:+ """Allow overrides for testing.++ ``claude_cli`` defaults to :func:`shutil.which` lookup. Pass+ ``None`` to force the file-based fallback path. Pass an explicit+ path to point at a specific binary.+ """+ home = home_dir if home_dir is not None else Path.home()+ self._claude_dir = home / ".claude"+ self._modern_config = home / ".claude" / ".claude.json"+ self._legacy_config = home / ".claude" / "mcp.json"+ if claude_cli is ...:+ self._claude_cli = shutil.which("claude")+ else:+ # ``...`` sentinel preserves "not set"; explicit None disables CLI.+ self._claude_cli = claude_cli # type: ignore[assignment]++ # ------------------------------------------------------------------+ # MCPRegistrar interface+ # ------------------------------------------------------------------++ def detect(self) -> bool:+ if self._claude_cli:+ return True+ return self._claude_dir.is_dir()++ def get_server(self, server_name: str) -> ServerSpec | None:+ # 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+ return None++ def register_server(self, spec: ServerSpec, *, force: bool = False) -> RegisterResult:+ existing = self.get_server(spec.name)+ if existing is not None:+ if _specs_equivalent(existing, spec):+ return RegisterResult(RegisterStatus.ALREADY, "matches current configuration")+ if not force:+ return RegisterResult(+ RegisterStatus.MISMATCH,+ _diff_specs(existing, spec),+ )+ # force=True: remove first, then write fresh below.+ self.unregister_server(spec.name)++ if self._claude_cli:+ return self._register_via_cli(spec)+ return self._register_via_file(spec)++ def unregister_server(self, server_name: str) -> bool:+ if self._claude_cli:+ result = subprocess.run(+ [str(self._claude_cli), "mcp", "remove", server_name, "-s", "user"],+ capture_output=True,+ text=True,+ )+ if result.returncode == 0:+ return True+ logger.debug("claude mcp remove failed: %s", result.stderr.strip())+ # Fall through to file-based removal in case CLI didn't know+ # about the user-scope entry but the file still has it.+ removed = False+ for config_path in (self._modern_config, self._legacy_config):+ removed = self._remove_from_file(config_path, server_name) or removed+ return removed++ # ------------------------------------------------------------------+ # CLI-backed implementation+ # ------------------------------------------------------------------++ def _register_via_cli(self, spec: ServerSpec) -> RegisterResult:+ cmd = [str(self._claude_cli), "mcp", "add", spec.name, "-s", "user"]+ for k, v in spec.env.items():+ cmd += ["-e", f"{k}={v}"]+ cmd += ["--", spec.command, *spec.args]++ result = subprocess.run(cmd, capture_output=True, text=True)+ if result.returncode == 0:+ return RegisterResult(RegisterStatus.REGISTERED, "via `claude mcp add` (scope: user)")+ # 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)+ if file_result.status == RegisterStatus.REGISTERED:+ return RegisterResult(+ RegisterStatus.REGISTERED,+ f"via file fallback after CLI failed: {result.stderr.strip()}",+ )+ return RegisterResult(+ RegisterStatus.FAILED,+ f"CLI: {result.stderr.strip()}; file: {file_result.detail}",+ )++ # ------------------------------------------------------------------+ # File-backed implementation (CLI absent / older clients)+ # ------------------------------------------------------------------++ 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.+ target = self._modern_config+ if 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(target)+ servers = config.setdefault("mcpServers", {})+ servers[spec.name] = _spec_to_entry(spec)+ _write_json(target, config)+ except OSError as exc:+ return RegisterResult(RegisterStatus.FAILED, f"could not write {target}: {exc}")+ return RegisterResult(RegisterStatus.REGISTERED, f"wrote to {target}")++ def _remove_from_file(self, path: Path, server_name: str) -> bool:+ if not path.exists():+ return False+ try:+ config = _read_json(path)+ except OSError:+ return False+ servers = config.get("mcpServers", {})+ if server_name not in servers:+ return False+ del servers[server_name]+ try:+ _write_json(path, config)+ except OSError:+ return False+ return True++ def _read_server_entry(self, path: Path, server_name: str) -> ServerSpec | None:+ if not path.exists():+ return None+ try:+ config = _read_json(path)+ except OSError:+ return None+ entry = config.get("mcpServers", {}).get(server_name)+ if not isinstance(entry, dict):+ return None+ return _entry_to_spec(server_name, entry)+++# ----------------------------------------------------------------------+# Helpers+# ----------------------------------------------------------------------+++def _read_json(path: Path) -> dict[str, Any]:+ """Read a JSON file, returning empty dict if absent or unparseable."""+ if not path.exists():+ return {}+ try:+ with open(path) as f:+ data = json.load(f)+ except (OSError, json.JSONDecodeError):+ return {}+ if not isinstance(data, dict):+ return {}+ return data+++def _write_json(path: Path, data: dict[str, Any]) -> None:+ path.parent.mkdir(parents=True, exist_ok=True)+ with open(path, "w") as f:+ json.dump(data, f, indent=2)+ f.write("\n")+++def _spec_to_entry(spec: ServerSpec) -> dict[str, Any]:+ entry: dict[str, Any] = {"command": spec.command}+ if spec.args:+ entry["args"] = list(spec.args)+ if spec.env:+ entry["env"] = dict(spec.env)+ return entry+++def _entry_to_spec(name: str, entry: dict[str, Any]) -> ServerSpec:+ args_value = entry.get("args", [])+ if isinstance(args_value, list):+ args = tuple(str(x) for x in args_value)+ else:+ args = ()+ env_value = entry.get("env", {})+ env: dict[str, str] = {}+ if isinstance(env_value, dict):+ env = {str(k): str(v) for k, v in env_value.items()}+ return ServerSpec(+ name=name,+ command=str(entry.get("command", "")),+ args=args,+ env=env,+ )+++def _specs_equivalent(a: ServerSpec, b: ServerSpec) -> bool:+ """Two specs match when every field is equal."""+ return (+ a.name == b.name+ and a.command == b.command+ and tuple(a.args) == tuple(b.args)+ and dict(a.env) == dict(b.env)+ )+++def _diff_specs(existing: ServerSpec, requested: ServerSpec) -> str:+ """Render the difference between two specs for human consumption."""+ parts: list[str] = []+ if existing.command != requested.command:+ parts.append(f"command {existing.command!r} -> {requested.command!r}")+ if tuple(existing.args) != tuple(requested.args):+ parts.append(f"args {list(existing.args)} -> {list(requested.args)}")+ if dict(existing.env) != dict(requested.env):+ parts.append(f"env {dict(existing.env)} -> {dict(requested.env)}")+ if not parts:+ return "spec differs in unidentified field(s)"+ return "; ".join(parts)diff --git a/headroom/mcp_registry/codex.py b/headroom/mcp_registry/codex.pynew file mode 100644index 000000000..460f7e5e5--- /dev/null+++ b/headroom/mcp_registry/codex.py@@ -0,0 +1,222 @@+"""OpenAI Codex CLI MCP registrar.++Codex stores MCP server config in ``~/.codex/config.toml`` as+``[mcp_servers.<name>]`` tables (with optional ``[mcp_servers.<name>.env]``+sub-tables). There is no general-purpose CLI for adding entries, so we+edit the file in place — using marker-delimited blocks so we can+idempotently inject, replace, and remove our entry without disturbing+anything else the user has configured.+"""++from __future__ import annotations++import logging+import sys+from pathlib import Path+from typing import Any++from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec++if sys.version_info >= (3, 11):+ import tomllib+else: # pragma: no cover — exercised only on 3.10+ import tomli as tomllib # type: ignore[no-redef]++logger = logging.getLogger(__name__)++_MARKER_START = "# --- Headroom MCP server ---"+_MARKER_END = "# --- end Headroom MCP server ---"+++class CodexRegistrar(MCPRegistrar):+ """Register MCP servers with the OpenAI Codex CLI."""++ name = "codex"+ display_name = "OpenAI Codex CLI"++ def __init__(self, *, home_dir: Path | None = None) -> None:+ home = home_dir if home_dir is not None else Path.home()+ self._codex_dir = home / ".codex"+ self._config_file = home / ".codex" / "config.toml"++ # ------------------------------------------------------------------+ # MCPRegistrar interface+ # ------------------------------------------------------------------++ def detect(self) -> bool:+ return self._codex_dir.is_dir()++ def get_server(self, server_name: str) -> ServerSpec | None:+ data = self._load_toml()+ servers = data.get("mcp_servers", {})+ if not isinstance(servers, dict):+ return None+ entry = servers.get(server_name)+ if not isinstance(entry, dict):+ return None+ return _entry_to_spec(server_name, entry)++ def register_server(self, spec: ServerSpec, *, force: bool = False) -> RegisterResult:+ existing = self.get_server(spec.name)++ if existing is not None and _specs_equivalent(existing, spec):+ return RegisterResult(RegisterStatus.ALREADY, "matches current configuration")++ if existing is not None and not force:+ content = self._read_text()+ if _MARKER_START not in content:+ # Entry exists but wasn't written by us — refuse to clobber.+ return RegisterResult(+ RegisterStatus.MISMATCH,+ "user-managed [mcp_servers."+ f"{spec.name}] entry outside Headroom markers; "+ f"{_diff_specs(existing, spec)}",+ )+ return RegisterResult(RegisterStatus.MISMATCH, _diff_specs(existing, spec))++ if existing is not None and force:+ # Drop any prior block (ours or user's) before re-writing.+ self.unregister_server(spec.name)++ return self._write_block(spec)++ def unregister_server(self, server_name: str) -> bool:+ # Only removes the marker-block we wrote. User-managed entries+ # outside markers are intentionally preserved.+ if not self._config_file.exists():+ return False+ content = self._read_text()+ if _MARKER_START not in content or _MARKER_END not in content:+ return False+ try:+ start = content.index(_MARKER_START)+ end = content.index(_MARKER_END) + len(_MARKER_END)+ except ValueError:+ return False+ before = content[:start].rstrip("\n")+ after = content[end:].lstrip("\n")+ if before and after:+ new_content = before + "\n\n" + after+ else:+ new_content = (before or after).rstrip("\n") + ("\n" if (before or after) else "")+ try:+ self._config_file.write_text(new_content)+ except OSError:+ return False+ return True++ # ------------------------------------------------------------------+ # File IO+ # ------------------------------------------------------------------++ def _load_toml(self) -> dict[str, Any]:+ if not self._config_file.exists():+ return {}+ try:+ with open(self._config_file, "rb") as f:+ data = tomllib.load(f)+ except (tomllib.TOMLDecodeError, OSError):+ return {}+ return data if isinstance(data, dict) else {}++ def _read_text(self) -> str:+ try:+ return self._config_file.read_text()+ except OSError:+ return ""++ def _write_block(self, spec: ServerSpec) -> RegisterResult:+ block = _render_block(spec)+ try:+ self._codex_dir.mkdir(parents=True, exist_ok=True)+ content = self._read_text()+ if _MARKER_START in content and _MARKER_END in content:+ start = content.index(_MARKER_START)+ end = content.index(_MARKER_END) + len(_MARKER_END)+ content = (+ content[:start].rstrip("\n")+ + ("\n\n" if content[:start].rstrip("\n") else "")+ + block+ + "\n"+ + content[end:].lstrip("\n")+ )+ elif content.strip():+ content = content.rstrip("\n") + "\n\n" + block + "\n"+ else:+ content = block + "\n"+ self._config_file.write_text(content)+ except OSError as exc:+ return RegisterResult(+ RegisterStatus.FAILED, f"could not write {self._config_file}: {exc}"+ )+ return RegisterResult(RegisterStatus.REGISTERED, f"wrote to {self._config_file}")+++# ----------------------------------------------------------------------+# TOML rendering / parsing helpers (kept module-private)+# ----------------------------------------------------------------------+++def _render_block(spec: ServerSpec) -> str:+ """Render a Headroom-marked TOML block for ``spec``."""+ lines: list[str] = [+ _MARKER_START,+ f"[mcp_servers.{spec.name}]",+ f"command = {_toml_str(spec.command)}",+ ]+ if spec.args:+ items = ", ".join(_toml_str(a) for a in spec.args)+ lines.append(f"args = [{items}]")+ if spec.env:+ lines.append("")+ lines.append(f"[mcp_servers.{spec.name}.env]")+ for k, v in spec.env.items():+ lines.append(f"{k} = {_toml_str(v)}")+ lines.append(_MARKER_END)+ return "\n".join(lines)+++def _toml_str(s: str) -> str:+ """Render a Python string as a TOML basic string literal."""+ escaped = s.replace("\\", "\\\\").replace('"', '\\"')+ return f'"{escaped}"'+++def _entry_to_spec(name: str, entry: dict[str, Any]) -> ServerSpec:+ args_value = entry.get("args", [])+ if isinstance(args_value, list):+ args = tuple(str(x) for x in args_value)+ else:+ args = ()+ env_value = entry.get("env", {})+ env: dict[str, str] = {}+ if isinstance(env_value, dict):+ env = {str(k): str(v) for k, v in env_value.items()}+ return ServerSpec(+ name=name,+ command=str(entry.get("command", "")),+ args=args,+ env=env,+ )+++def _specs_equivalent(a: ServerSpec, b: ServerSpec) -> bool:+ return (+ a.name == b.name+ and a.command == b.command+ and tuple(a.args) == tuple(b.args)+ and dict(a.env) == dict(b.env)+ )+++def _diff_specs(existing: ServerSpec, requested: ServerSpec) -> str:+ parts: list[str] = []+ if existing.command != requested.command:+ parts.append(f"command {existing.command!r} -> {requested.command!r}")+ if tuple(existing.args) != tuple(requested.args):+ parts.append(f"args {list(existing.args)} -> {list(requested.args)}")+ if dict(existing.env) != dict(requested.env):+ parts.append(f"env {dict(existing.env)} -> {dict(requested.env)}")+ if not parts:+ return "spec differs in unidentified field(s)"+ return "; ".join(parts)diff --git a/headroom/mcp_registry/display.py b/headroom/mcp_registry/display.pynew file mode 100644index 000000000..43fc21b96--- /dev/null+++ b/headroom/mcp_registry/display.py@@ -0,0 +1,95 @@+"""Human-readable rendering of MCP registration results.++The CLI ``mcp install`` command, ``init`` flow, and ``wrap claude`` setup+all consume the same ``dict[str, RegisterResult]`` and want to print one+line per agent. They differ only in label format (e.g. ``" claude:"`` vs+``" MCP retrieve tool:"``), whether to show ALREADY-registered as a+success line, and which corrective command to suggest on mismatch.++Centralizing those choices here keeps every status branch in one file.+Adding a new :class:`RegisterStatus` member becomes a single edit; the+call sites compose by passing flags rather than re-writing the switch.+"""++from __future__ import annotations++from collections.abc import Callable++from .base import RegisterResult, RegisterStatus++DEFAULT_OVERWRITE_HINT = "headroom mcp install --force"+DEFAULT_RESTART_HINT = "restart the agent if it was already running"+++def format_result(+ agent: str,+ result: RegisterResult,+ *,+ label: str | None = None,+ verbose: bool = False,+ overwrite_hint: str = DEFAULT_OVERWRITE_HINT,+ restart_hint: str = DEFAULT_RESTART_HINT,+) -> str | None:+ """Render one ``(agent, result)`` pair as a single display line.++ Returns ``None`` to suppress output (e.g. ALREADY when not ``verbose``).++ Args:+ agent: Stable agent name (used as default label).+ result: Outcome from :func:`install_everywhere` or a registrar.+ label: Override the leading label. Defaults to the agent name.+ verbose: If ``True``, include status lines that are otherwise+ silent (e.g. ALREADY).+ overwrite_hint: Command to suggest when the existing config differs.+ restart_hint: Hint appended to a fresh registration line.+ """+ label = label if label is not None else agent+ status = result.status++ if status == RegisterStatus.REGISTERED:+ return f" {label}: registered ({restart_hint})"+ if status == RegisterStatus.ALREADY:+ return f" {label}: already registered" if verbose else None+ if status == RegisterStatus.NOT_DETECTED:+ return f" {label}: not detected on this system, skipped"+ if status == RegisterStatus.MISMATCH:+ suffix = f" To update: {overwrite_hint}" if overwrite_hint else ""+ return f" {label}: existing config differs ({result.detail}).{suffix}"+ if status == RegisterStatus.NO_SDK:+ return f" {label}: MCP SDK missing — install with `pip install 'headroom-ai[mcp]'`"+ # FAILED or any future unhandled status+ return f" {label}: install failed ({status.value}): {result.detail}"+++def format_results(+ results: dict[str, RegisterResult],+ *,+ label_for: Callable[[str], str | None] | None = None,+ verbose: bool = False,+ overwrite_hint: str = DEFAULT_OVERWRITE_HINT,+ restart_hint: str = DEFAULT_RESTART_HINT,+) -> list[str]:+ """Render a results dict to a list of display lines.++ ``label_for`` is an optional ``agent -> label`` mapper. Pass ``None``+ (default) to use the agent name as the label.+ """+ lines: list[str] = []+ for agent, result in results.items():+ label = label_for(agent) if label_for is not None else None+ line = format_result(+ agent,+ result,+ label=label,+ verbose=verbose,+ overwrite_hint=overwrite_hint,+ restart_hint=restart_hint,+ )+ if line is not None:+ lines.append(line)+ return lines+++def any_succeeded(results: dict[str, RegisterResult]) -> bool:+ """True when at least one agent ended in REGISTERED or ALREADY."""+ return any(r.ok for r in results.values())diff --git a/headroom/mcp_registry/install.py b/headroom/mcp_registry/install.pynew file mode 100644index 000000000..f63c0e365--- /dev/null+++ b/headroom/mcp_registry/install.py@@ -0,0 +1,76 @@+"""Top-level orchestration: register Headroom MCP across detected agents."""++from __future__ import annotations++from collections.abc import Iterable++from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec+from .claude import ClaudeRegistrar+from .codex import CodexRegistrar++#: Default proxy URL used when none is given.+DEFAULT_PROXY_URL = "http://127.0.0.1:8787"+++def get_all_registrars() -> list[MCPRegistrar]:+ """Return one instance of every registrar implemented today.++ The list grows as we add adapters for Cursor, Continue, Cline, etc.+ """+ return [ClaudeRegistrar(), CodexRegistrar()]+++def build_headroom_spec(proxy_url: str = DEFAULT_PROXY_URL) -> ServerSpec:+ """Construct the canonical :class:`ServerSpec` for the headroom server.++ The spec is identical across agents — every JSON/TOML registrar+ serializes the same shape into its own format.+ """+ env: dict[str, str] = {}+ if proxy_url and proxy_url != DEFAULT_PROXY_URL:+ env["HEADROOM_PROXY_URL"] = proxy_url+ return ServerSpec(+ name="headroom",+ command="headroom",+ args=("mcp", "serve"),+ env=env,+ )+++def install_everywhere(+ proxy_url: str = DEFAULT_PROXY_URL,+ *,+ agents: Iterable[str] | None = None,+ force: bool = False,+ registrars: Iterable[MCPRegistrar] | None = None,+) -> dict[str, RegisterResult]:+ """Install the headroom MCP server into every detected agent.++ Args:+ proxy_url: URL the MCP server should contact for retrieval.+ agents: If given, only install into agents whose ``name`` matches.+ force: Pass through to each registrar — overwrites mismatched config.+ registrars: Inject a custom registrar list (test seam).++ Returns:+ Dict keyed by registrar name. Includes :attr:`RegisterStatus.NOT_DETECTED`+ entries for agents we know about that aren't installed locally.+ """+ spec = build_headroom_spec(proxy_url)+ selected = list(registrars) if registrars is not None else get_all_registrars()++ if agents is not None:+ agent_set = set(agents)+ selected = [r for r in selected if r.name in agent_set]++ results: dict[str, RegisterResult] = {}+ for registrar in selected:+ if not registrar.detect():+ results[registrar.name] = RegisterResult(+ RegisterStatus.NOT_DETECTED,+ f"{registrar.display_name} not found on this system",+ )+ continue+ results[registrar.name] = registrar.register_server(spec, force=force)++ return resultsdiff --git a/tests/test_cli/test_mcp.py b/tests/test_cli/test_mcp.pyindex c65bde2f7..7a65567db 100644--- a/tests/test_cli/test_mcp.py+++ b/tests/test_cli/test_mcp.py@@ -129,117 +129,38 @@ class TestMCPConfigFunctions:assert "other-server" in loaded["mcpServers"]-class TestMCPInstallCommand:- """Test 'headroom mcp install' command."""-- def test_install_creates_config(self, mock_claude_config_path, mock_mcp_available):- """Install creates MCP config file."""- runner = CliRunner()- result = runner.invoke(main, ["mcp", "install"])-- assert result.exit_code == 0, f"Failed with output: {result.output}"- assert "installed" in result.output.lower()- assert mock_claude_config_path.exists()-- # Verify config content- config = json.loads(mock_claude_config_path.read_text())- assert "headroom" in config["mcpServers"]- assert config["mcpServers"]["headroom"]["command"] == "headroom"- assert "mcp" in config["mcpServers"]["headroom"]["args"]- assert "serve" in config["mcpServers"]["headroom"]["args"]-- def test_install_preserves_other_servers(self, mock_claude_config_path, mock_mcp_available):- """Install preserves existing MCP servers."""- # Create config with another server- existing_config = {- "mcpServers": {- "github": {"command": "github-mcp", "args": []},- }- }- mock_claude_config_path.write_text(json.dumps(existing_config))-- runner = CliRunner()- result = runner.invoke(main, ["mcp", "install"])-- assert result.exit_code == 0, f"Failed with output: {result.output}"-- # Both servers should exist- config = json.loads(mock_claude_config_path.read_text())- assert "github" in config["mcpServers"]- assert "headroom" in config["mcpServers"]-- def test_install_with_custom_proxy_url(self, mock_claude_config_path, mock_mcp_available):- """Install with custom proxy URL sets env var."""- runner = CliRunner()- result = runner.invoke(main, ["mcp", "install", "--proxy-url", "http://localhost:9000"])-- assert result.exit_code == 0, f"Failed with output: {result.output}"-- config = json.loads(mock_claude_config_path.read_text())- assert (- config["mcpServers"]["headroom"]["env"]["HEADROOM_PROXY_URL"] == "http://localhost:9000"- )-- def test_install_default_proxy_url_no_env(self, mock_claude_config_path, mock_mcp_available):- """Install with default proxy URL doesn't set env var."""- runner = CliRunner()- result = runner.invoke(main, ["mcp", "install"])-- assert result.exit_code == 0, f"Failed with output: {result.output}"-- config = json.loads(mock_claude_config_path.read_text())- # No env section for default URL- assert "env" not in config["mcpServers"]["headroom"]-- def test_install_already_configured_no_force(self, mock_claude_config_path, mock_mcp_available):- """Install without --force when already configured exits cleanly."""- # First install- runner = CliRunner()- runner.invoke(main, ["mcp", "install"])-- # Second install without force- result = runner.invoke(main, ["mcp", "install"])-- assert result.exit_code == 0- assert "already configured" in result.output.lower()-- def test_install_force_overwrites(self, mock_claude_config_path, mock_mcp_available):- """Install with --force overwrites existing config."""- runner = CliRunner()- runner.invoke(main, ["mcp", "install", "--proxy-url", "http://old:8787"])-- # Force install with new URL- result = runner.invoke(- main, ["mcp", "install", "--force", "--proxy-url", "http://new:9000"]- )-- assert result.exit_code == 0, f"Failed with output: {result.output}"- assert "installed" in result.output.lower()-- config = json.loads(mock_claude_config_path.read_text())- assert config["mcpServers"]["headroom"]["env"]["HEADROOM_PROXY_URL"] == "http://new:9000"-- @pytest.mark.skipif(MCP_AVAILABLE, reason="Test only runs when MCP SDK is NOT installed")- def test_install_without_mcp_sdk_fails(self, mock_claude_config_path):- """Install fails gracefully when MCP SDK is not installed."""- runner = CliRunner()- result = runner.invoke(main, ["mcp", "install"])-- # Should fail with helpful message- assert result.exit_code == 1- assert "mcp" in result.output.lower() or "not installed" in result.output.lower()+#+# Note: Tests for the 'mcp install' command's writes/idempotency/CLI-vs-file+# fallback used to live here, but they were tightly coupled to private+# globals (MCP_CONFIG_PATH, shutil.which) and exercised the same surface+# already covered by:+# - tests/test_mcp_registry/test_claude_registrar.py (file/CLI behavior+# with proper constructor injection — no patches)+# - tests/test_mcp_registry/test_install.py (orchestrator semantics with+# fake registrars)+# Removing the duplicates leaves the CLI as glue: argument parsing ++# output formatting, which is straightforward and not worth its own test+# layer.class TestMCPUninstallCommand:"""Test 'headroom mcp uninstall' command."""def test_uninstall_removes_headroom(self, mock_claude_config_path, mock_mcp_available):- """Uninstall removes headroom from config."""- # First install- runner = CliRunner()- runner.invoke(main, ["mcp", "install"])+ """Uninstall removes headroom from the legacy config file."""+ # Pre-populate the config directly rather than depending on+ # `mcp install` plumbing — keeps the test focused on uninstall.+ mock_claude_config_path.write_text(+ json.dumps(+ {+ "mcpServers": {+ "headroom": {"command": "headroom", "args": ["mcp", "serve"]},+ }+ }+ )+ )- # Then uninstall+ runner = CliRunner()result = runner.invoke(main, ["mcp", "uninstall"])assert result.exit_code == 0@@ -307,10 +228,20 @@ class TestMCPStatusCommand:)def test_status_configured(self, mock_claude_config_path, mock_mcp_available):- """Status shows configured when installed."""- runner = CliRunner()- runner.invoke(main, ["mcp", "install"])+ """Status reports configured when the legacy config has headroom."""+ # Pre-populate the legacy mcp.json directly. mcp_status() reads+ # from MCP_CONFIG_PATH, which the fixture redirects here.+ mock_claude_config_path.write_text(+ json.dumps(+ {+ "mcpServers": {+ "headroom": {"command": "headroom", "args": ["mcp", "serve"]},+ }+ }+ )+ )+ runner = CliRunner()result = runner.invoke(main, ["mcp", "status"])assert result.exit_code == 0@@ -366,149 +297,12 @@ class TestMCPServerInitialization:assert CCR_TOOL_NAME == "headroom_retrieve"-class TestEndToEndFlow:- """Test complete install -> status -> uninstall flow."""-- def test_full_lifecycle(self, mock_claude_config_path, mock_mcp_available):- """Test complete lifecycle of MCP configuration."""- runner = CliRunner()-- # Initially not configured- result = runner.invoke(main, ["mcp", "status"])- assert "No config" in result.output or "Not configured" in result.output.lower()-- # Install- result = runner.invoke(main, ["mcp", "install"])- assert result.exit_code == 0, f"Install failed: {result.output}"- assert "installed" in result.output.lower()-- # Status shows configured- result = runner.invoke(main, ["mcp", "status"])- assert "✓ Configured" in result.output-- # Config file has correct content- config = json.loads(mock_claude_config_path.read_text())- assert config["mcpServers"]["headroom"]["command"] == "headroom"-- # Uninstall- result = runner.invoke(main, ["mcp", "uninstall"])- assert result.exit_code == 0- assert "removed" in result.output.lower()-- # Status shows not configured- result = runner.invoke(main, ["mcp", "status"])- assert "headroom" not in result.output.lower() or "not configured" in result.output.lower()---class TestMCPInstallWithClaudeCLI:- """Test mcp_install when the claude CLI is available."""-- def _make_run(self, get_rc=1, add_rc=0, remove_rc=0):- """Return a subprocess.run mock with configurable return codes."""-- def run(cmd, **kwargs):- if "get" in cmd:- return MagicMock(returncode=get_rc, stderr="")- if "remove" in cmd:- return MagicMock(returncode=remove_rc, stderr="")- if "add" in cmd:- return MagicMock(returncode=add_rc, stderr="")- return MagicMock(returncode=0, stderr="")-- return run-- def test_install_uses_claude_mcp_add(self, mock_mcp_available):- """When claude CLI is available, install calls claude mcp add."""- runner = CliRunner()- with patch("headroom.cli.mcp.shutil.which", return_value="/usr/bin/claude"):- with patch("headroom.cli.mcp.subprocess.run", side_effect=self._make_run()) as mock_run:- result = runner.invoke(main, ["mcp", "install"])-- assert result.exit_code == 0, f"Failed: {result.output}"- assert "installed" in result.output.lower()- assert "claude mcp add" in result.output-- # Verify claude mcp add was called- add_calls = [c for c in mock_run.call_args_list if "add" in c.args[0]]- assert len(add_calls) == 1- add_cmd = add_calls[0].args[0]- assert "headroom" in add_cmd- assert "-s" in add_cmd- assert "user" in add_cmd-- def test_install_already_registered_no_force(self, mock_mcp_available):- """Install without --force exits cleanly when already registered via claude CLI."""- runner = CliRunner()- with patch("headroom.cli.mcp.shutil.which", return_value="/usr/bin/claude"):- # get returns 0 → already registered- with patch("headroom.cli.mcp.subprocess.run", side_effect=self._make_run(get_rc=0)):- result = runner.invoke(main, ["mcp", "install"])-- assert result.exit_code == 0- assert "already configured" in result.output.lower()-- def test_install_force_calls_remove_then_add(self, mock_mcp_available):- """--force calls claude mcp remove before claude mcp add."""- runner = CliRunner()- calls = []-- def capturing_run(cmd, **kwargs):- calls.append(cmd)- return MagicMock(returncode=0, stderr="")-- with patch("headroom.cli.mcp.shutil.which", return_value="/usr/bin/claude"):- with patch("headroom.cli.mcp.subprocess.run", side_effect=capturing_run):- result = runner.invoke(main, ["mcp", "install", "--force"])-- assert result.exit_code == 0, f"Failed: {result.output}"- subcommands = [c[2] for c in calls] # third element is the subcommand- assert "remove" in subcommands- assert "add" in subcommands- assert subcommands.index("remove") < subcommands.index("add")-- def test_install_fallback_on_claude_mcp_add_failure(self, temp_claude_dir, mock_mcp_available):- """If claude mcp add fails, falls back to writing mcp.json."""- config_path = temp_claude_dir / "mcp.json"- with patch("headroom.cli.mcp.MCP_CONFIG_PATH", config_path):- with patch("headroom.cli.mcp.CLAUDE_CONFIG_DIR", temp_claude_dir):- with patch("headroom.cli.mcp.shutil.which", return_value="/usr/bin/claude"):- with patch(- "headroom.cli.mcp.subprocess.run",- side_effect=self._make_run(add_rc=1),- ):- runner = CliRunner()- result = runner.invoke(main, ["mcp", "install"])-- assert result.exit_code == 0, f"Failed: {result.output}"- assert config_path.exists()- config = json.loads(config_path.read_text())- assert "headroom" in config["mcpServers"]-- def test_install_with_custom_proxy_url_passes_e_flag(self, mock_mcp_available):- """Custom proxy URL is passed as -e KEY=VALUE to claude mcp add."""- calls = []-- def capturing_run(cmd, **kwargs):- calls.append(list(cmd))- # Return rc=1 for "get" so headroom is treated as not yet registered- if "get" in cmd:- return MagicMock(returncode=1, stderr="")- return MagicMock(returncode=0, stderr="")-- runner = CliRunner()- with patch("headroom.cli.mcp.shutil.which", return_value="/usr/bin/claude"):- with patch("headroom.cli.mcp.subprocess.run", side_effect=capturing_run):- result = runner.invoke(- main, ["mcp", "install", "--proxy-url", "http://custom:9000"]- )-- assert result.exit_code == 0, f"Failed: {result.output}"- add_calls = [c for c in calls if "add" in c]- assert len(add_calls) == 1- add_cmd = add_calls[0]- assert "-e" in add_cmd- env_idx = add_cmd.index("-e")- assert add_cmd[env_idx + 1] == "HEADROOM_PROXY_URL=http://custom:9000"+#+# Tests for "install via claude CLI" used to live here, exercising+# subprocess.run patches against the old direct CLI invocation. Equivalent+# coverage now lives in tests/test_mcp_registry/test_claude_registrar.py+# using constructor injection (`claude_cli="/path/to/fake"`) and bounded+# subprocess.run mocks at the registrar boundary — no module-level patches.class TestMCPUninstallWithClaudeCLI:diff --git a/tests/test_mcp_registry/__init__.py b/tests/test_mcp_registry/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/tests/test_mcp_registry/test_claude_registrar.py b/tests/test_mcp_registry/test_claude_registrar.pynew file mode 100644index 000000000..223cc801b--- /dev/null+++ b/tests/test_mcp_registry/test_claude_registrar.py@@ -0,0 +1,309 @@+"""Tests for the Claude Code MCP registrar."""++from __future__ import annotations++import json+import subprocess+from pathlib import Path+from unittest.mock import patch++import pytest++from headroom.mcp_registry.base import RegisterStatus, ServerSpec+from headroom.mcp_registry.claude import ClaudeRegistrar+++def _make_registrar(+ tmp_path: Path,+ *,+ cli: str | None = "/usr/local/bin/claude",+) -> ClaudeRegistrar:+ """Build a registrar pointed at ``tmp_path`` as $HOME."""+ return ClaudeRegistrar(claude_cli=cli, home_dir=tmp_path)+++def _spec() -> ServerSpec:+ return ServerSpec(+ name="headroom",+ command="headroom",+ args=("mcp", "serve"),+ env={},+ )+++# ----------------------------------------------------------------------+# detect()+# ----------------------------------------------------------------------+++def test_detect_true_when_cli_present(tmp_path: Path) -> None:+ reg = _make_registrar(tmp_path, cli="/usr/local/bin/claude")+ assert reg.detect() is True+++def test_detect_true_when_only_claude_dir_exists(tmp_path: Path) -> None:+ (tmp_path / ".claude").mkdir()+ reg = _make_registrar(tmp_path, cli=None)+ assert reg.detect() is True+++def test_detect_false_when_neither_present(tmp_path: Path) -> None:+ reg = _make_registrar(tmp_path, cli=None)+ assert reg.detect() is False+++# ----------------------------------------------------------------------+# get_server() — file-based reads+# ----------------------------------------------------------------------+++def test_get_server_returns_none_when_unregistered(tmp_path: Path) -> None:+ reg = _make_registrar(tmp_path, cli=None)+ assert reg.get_server("headroom") is None+++def test_get_server_reads_modern_config(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"],+ "env": {"HEADROOM_PROXY_URL": "http://127.0.0.1:9000"},+ }+ }+ }+ )+ )+ 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.env == {"HEADROOM_PROXY_URL": "http://127.0.0.1:9000"}+++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"]}}})+ )+ 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.env == {}+++# ----------------------------------------------------------------------+# register_server() — happy paths+# ----------------------------------------------------------------------+++def test_register_via_cli_calls_claude_mcp_add(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())+ assert result.status == RegisterStatus.REGISTERED+ cmds = [call.args[0] for call in run_mock.call_args_list]+ add_cmd = next(c for c in cmds if "add" in c)+ assert add_cmd[:6] == [+ "/usr/local/bin/claude",+ "mcp",+ "add",+ "headroom",+ "-s",+ "user",+ ]+ assert add_cmd[-3:] == ["--", "headroom", "mcp"] or add_cmd[-4:] == [+ "--",+ "headroom",+ "mcp",+ "serve",+ ]+++def test_register_via_cli_includes_env(tmp_path: Path) -> None:+ spec = ServerSpec(+ name="headroom",+ command="headroom",+ args=("mcp", "serve"),+ env={"HEADROOM_PROXY_URL": "http://127.0.0.1:9000"},+ )+ 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:+ reg.register_server(spec)+ add_cmd = next(c for c in [call.args[0] for call in run_mock.call_args_list] if "add" in c)+ assert "-e" in add_cmd+ e_idx = add_cmd.index("-e")+ assert add_cmd[e_idx + 1] == "HEADROOM_PROXY_URL=http://127.0.0.1:9000"+++def test_register_writes_file_when_no_cli(tmp_path: Path) -> None:+ reg = _make_registrar(tmp_path, cli=None)+ result = reg.register_server(_spec())+ assert result.status == RegisterStatus.REGISTERED+ 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"]+++def test_register_writes_to_legacy_when_only_legacy_exists(tmp_path: Path) -> None:+ legacy = tmp_path / ".claude" / "mcp.json"+ legacy.parent.mkdir()+ legacy.write_text(json.dumps({"mcpServers": {}}))+ reg = _make_registrar(tmp_path, cli=None)+ result = reg.register_server(_spec())+ assert result.status == RegisterStatus.REGISTERED+ data = json.loads(legacy.read_text())+ assert "headroom" in data["mcpServers"]+ # Modern config should NOT have been created.+ assert not (tmp_path / ".claude" / ".claude.json").exists()+++# ----------------------------------------------------------------------+# register_server() — already / mismatch / force+# ----------------------------------------------------------------------+++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"]}}})+ )+ reg = _make_registrar(tmp_path, cli="/usr/local/bin/claude")+ with patch("subprocess.run") as run_mock:+ result = reg.register_server(_spec())+ assert result.status == RegisterStatus.ALREADY+ run_mock.assert_not_called() # should not touch CLI when already matching+++def test_register_mismatch_when_spec_differs_no_force(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"],+ "env": {"HEADROOM_PROXY_URL": "http://127.0.0.1:9999"},+ }+ }+ }+ )+ )+ reg = _make_registrar(tmp_path, cli="/usr/local/bin/claude")+ with patch("subprocess.run") as run_mock:+ result = reg.register_server(_spec()) # default proxy = no env+ assert result.status == RegisterStatus.MISMATCH+ assert "env" in (result.detail or "")+ run_mock.assert_not_called() # do NOT overwrite without force+++def test_register_force_overwrites_mismatch(tmp_path: Path) -> None:+ cfg = tmp_path / ".claude" / ".claude.json"+ cfg.parent.mkdir()+ cfg.write_text(+ json.dumps(+ {+ "mcpServers": {+ "headroom": {+ "command": "headroom-old",+ "args": ["mcp", "serve"],+ }+ }+ }+ )+ )+ reg = _make_registrar(tmp_path, cli="/usr/local/bin/claude")+ fake_ok = subprocess.CompletedProcess(args=[], returncode=0, stdout="", stderr="")+ with patch("subprocess.run", return_value=fake_ok) as run_mock:+ result = reg.register_server(_spec(), force=True)+ assert result.status == RegisterStatus.REGISTERED+ cmds = [call.args[0] for call in run_mock.call_args_list]+ assert any("remove" in c for c in cmds)+ assert any("add" in c for c in cmds)+++# ----------------------------------------------------------------------+# CLI failure paths+# ----------------------------------------------------------------------+++def test_register_cli_failure_falls_back_to_file(tmp_path: Path) -> None:+ reg = _make_registrar(tmp_path, cli="/usr/local/bin/claude")+ fail = subprocess.CompletedProcess(args=[], returncode=1, stdout="", stderr="claude: error")+ with patch("subprocess.run", return_value=fail):+ result = reg.register_server(_spec())+ # Even though CLI failed, we wrote the config file as a fallback.+ assert result.status == RegisterStatus.REGISTERED+ cfg = tmp_path / ".claude" / ".claude.json"+ assert cfg.exists()+ data = json.loads(cfg.read_text())+ assert "headroom" in data["mcpServers"]+++# ----------------------------------------------------------------------+# unregister+# ----------------------------------------------------------------------+++def test_unregister_via_cli(tmp_path: Path) -> None:+ reg = _make_registrar(tmp_path, cli="/usr/local/bin/claude")+ ok = subprocess.CompletedProcess(args=[], returncode=0, stdout="", stderr="")+ with patch("subprocess.run", return_value=ok) as run_mock:+ assert reg.unregister_server("headroom") is True+ cmd = run_mock.call_args_list[0].args[0]+ assert cmd[:5] == ["/usr/local/bin/claude", "mcp", "remove", "headroom", "-s"]+ assert cmd[5] == "user"+++def test_unregister_via_file_when_no_cli(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"]},+ "other": {"command": "other"},+ }+ }+ )+ )+ reg = _make_registrar(tmp_path, cli=None)+ assert reg.unregister_server("headroom") is True+ data = json.loads(cfg.read_text())+ assert "headroom" not in data["mcpServers"]+ assert "other" in data["mcpServers"]+++def test_unregister_returns_false_when_absent(tmp_path: Path) -> None:+ reg = _make_registrar(tmp_path, cli=None)+ assert reg.unregister_server("headroom") is False+++# ----------------------------------------------------------------------+# Robustness: bad JSON should not crash+# ----------------------------------------------------------------------++[email protected]("contents", ["", "not json", "{", "[]"])+def test_get_server_robust_to_bad_json(tmp_path: Path, contents: str) -> None:+ cfg = tmp_path / ".claude" / ".claude.json"+ cfg.parent.mkdir()+ cfg.write_text(contents)+ reg = _make_registrar(tmp_path, cli=None)+ assert reg.get_server("headroom") is Nonediff --git a/tests/test_mcp_registry/test_codex_registrar.py b/tests/test_mcp_registry/test_codex_registrar.pynew file mode 100644index 000000000..53ad0761e--- /dev/null+++ b/tests/test_mcp_registry/test_codex_registrar.py@@ -0,0 +1,258 @@+"""Tests for the OpenAI Codex MCP registrar."""++from __future__ import annotations++import sys+from pathlib import Path++import pytest++from headroom.mcp_registry.base import RegisterStatus, ServerSpec+from headroom.mcp_registry.codex import CodexRegistrar++if sys.version_info >= (3, 11):+ import tomllib+else: # pragma: no cover+ import tomli as tomllib+++def _make_registrar(tmp_path: Path) -> CodexRegistrar:+ return CodexRegistrar(home_dir=tmp_path)+++def _spec(env: dict[str, str] | None = None) -> ServerSpec:+ return ServerSpec(+ name="headroom",+ command="headroom",+ args=("mcp", "serve"),+ env=env or {},+ )+++def _config_path(tmp_path: Path) -> Path:+ return tmp_path / ".codex" / "config.toml"+++# ----------------------------------------------------------------------+# detect()+# ----------------------------------------------------------------------+++def test_detect_true_when_codex_dir_exists(tmp_path: Path) -> None:+ (tmp_path / ".codex").mkdir()+ assert _make_registrar(tmp_path).detect() is True+++def test_detect_false_when_codex_dir_missing(tmp_path: Path) -> None:+ assert _make_registrar(tmp_path).detect() is False+++# ----------------------------------------------------------------------+# get_server()+# ----------------------------------------------------------------------+++def test_get_server_returns_none_when_config_missing(tmp_path: Path) -> None:+ assert _make_registrar(tmp_path).get_server("headroom") is None+++def test_get_server_returns_none_when_no_table(tmp_path: Path) -> None:+ cfg = _config_path(tmp_path)+ cfg.parent.mkdir()+ cfg.write_text('model = "gpt-4o"\n')+ assert _make_registrar(tmp_path).get_server("headroom") is None+++def test_get_server_returns_spec_when_table_present(tmp_path: Path) -> None:+ cfg = _config_path(tmp_path)+ cfg.parent.mkdir()+ cfg.write_text(+ "[mcp_servers.headroom]\n"+ 'command = "headroom"\n'+ 'args = ["mcp", "serve"]\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.env == {"HEADROOM_PROXY_URL": "http://127.0.0.1:9000"}+++def test_get_server_robust_to_unparseable_toml(tmp_path: Path) -> None:+ cfg = _config_path(tmp_path)+ cfg.parent.mkdir()+ cfg.write_text("this = is = not = valid\n")+ assert _make_registrar(tmp_path).get_server("headroom") is None+++# ----------------------------------------------------------------------+# register_server() — happy paths+# ----------------------------------------------------------------------+++def test_register_creates_config_when_missing(tmp_path: Path) -> None:+ reg = _make_registrar(tmp_path)+ result = reg.register_server(_spec())+ assert result.status == RegisterStatus.REGISTERED+ cfg = _config_path(tmp_path)+ assert cfg.exists()+ text = cfg.read_text()+ assert "# --- Headroom MCP server ---" in text+ assert "[mcp_servers.headroom]" in text+ parsed = tomllib.loads(text)+ assert parsed["mcp_servers"]["headroom"]["command"] == "headroom"+ assert parsed["mcp_servers"]["headroom"]["args"] == ["mcp", "serve"]+++def test_register_appends_to_existing_config_preserves_other_keys(tmp_path: Path) -> None:+ cfg = _config_path(tmp_path)+ cfg.parent.mkdir()+ cfg.write_text('# user comment\nmodel = "gpt-4o"\n\n[other_section]\nvalue = 42\n')+ result = _make_registrar(tmp_path).register_server(_spec())+ assert result.status == RegisterStatus.REGISTERED+ text = cfg.read_text()+ # Existing content survived.+ assert "# user comment" in text+ assert 'model = "gpt-4o"' in text+ assert "[other_section]" in text+ # Plus our block.+ assert "[mcp_servers.headroom]" in text+ parsed = tomllib.loads(text)+ assert parsed["model"] == "gpt-4o"+ assert parsed["other_section"]["value"] == 42+ assert parsed["mcp_servers"]["headroom"]["command"] == "headroom"+++def test_register_includes_env_subtable(tmp_path: Path) -> None:+ spec = _spec(env={"HEADROOM_PROXY_URL": "http://127.0.0.1:9000"})+ _make_registrar(tmp_path).register_server(spec)+ text = _config_path(tmp_path).read_text()+ assert "[mcp_servers.headroom.env]" in text+ parsed = tomllib.loads(text)+ assert parsed["mcp_servers"]["headroom"]["env"] == {+ "HEADROOM_PROXY_URL": "http://127.0.0.1:9000"+ }+++def test_register_omits_env_subtable_when_env_empty(tmp_path: Path) -> None:+ _make_registrar(tmp_path).register_server(_spec())+ text = _config_path(tmp_path).read_text()+ assert "[mcp_servers.headroom.env]" not in text+++# ----------------------------------------------------------------------+# Idempotency: ALREADY / MISMATCH+# ----------------------------------------------------------------------+++def test_register_already_when_block_matches_spec(tmp_path: Path) -> None:+ reg = _make_registrar(tmp_path)+ reg.register_server(_spec()) # first install+ text_before = _config_path(tmp_path).read_text()+ result = reg.register_server(_spec()) # second install, same spec+ assert result.status == RegisterStatus.ALREADY+ # File unchanged.+ assert _config_path(tmp_path).read_text() == text_before+++def test_register_mismatch_when_block_differs_no_force(tmp_path: Path) -> None:+ reg = _make_registrar(tmp_path)+ reg.register_server(_spec(env={"HEADROOM_PROXY_URL": "http://127.0.0.1:9999"}))+ text_before = _config_path(tmp_path).read_text()++ result = reg.register_server(_spec()) # no env+ assert result.status == RegisterStatus.MISMATCH+ assert "env" in (result.detail or "")+ assert _config_path(tmp_path).read_text() == text_before # unchanged+++def test_register_force_overwrites_block(tmp_path: Path) -> None:+ reg = _make_registrar(tmp_path)+ reg.register_server(_spec(env={"HEADROOM_PROXY_URL": "http://127.0.0.1:9999"}))+ result = reg.register_server(_spec(), force=True)+ assert result.status == RegisterStatus.REGISTERED+ text = _config_path(tmp_path).read_text()+ assert "9999" not in text+++def test_register_mismatch_when_user_managed_outside_markers(tmp_path: Path) -> None:+ cfg = _config_path(tmp_path)+ cfg.parent.mkdir()+ # User has manually put [mcp_servers.headroom] with different config — no markers.+ cfg.write_text(+ '[mcp_servers.headroom]\ncommand = "/usr/local/bin/custom-headroom"\nargs = ["serve"]\n'+ )+ result = _make_registrar(tmp_path).register_server(_spec())+ assert result.status == RegisterStatus.MISMATCH+ assert "user-managed" in (result.detail or "").lower()+ # Don't overwrite.+ assert "/usr/local/bin/custom-headroom" in cfg.read_text()+++# ----------------------------------------------------------------------+# unregister+# ----------------------------------------------------------------------+++def test_unregister_removes_marker_block(tmp_path: Path) -> None:+ reg = _make_registrar(tmp_path)+ cfg = _config_path(tmp_path)+ cfg.parent.mkdir()+ cfg.write_text("[other_section]\nvalue = 42\n")+ reg.register_server(_spec())+ assert "[mcp_servers.headroom]" in cfg.read_text()++ assert reg.unregister_server("headroom") is True+ text = cfg.read_text()+ assert "[mcp_servers.headroom]" not in text+ assert "# --- Headroom MCP server ---" not in text+ # Surrounding content survives.+ assert "[other_section]" in text+++def test_unregister_returns_false_when_no_block(tmp_path: Path) -> None:+ cfg = _config_path(tmp_path)+ cfg.parent.mkdir()+ cfg.write_text('model = "gpt-4o"\n')+ assert _make_registrar(tmp_path).unregister_server("headroom") is False+++def test_unregister_preserves_user_managed_entry(tmp_path: Path) -> None:+ """User-managed [mcp_servers.headroom] without our markers stays put."""+ cfg = _config_path(tmp_path)+ cfg.parent.mkdir()+ cfg.write_text('[mcp_servers.headroom]\ncommand = "/custom/headroom"\n')+ # No markers => unregister is a no-op.+ assert _make_registrar(tmp_path).unregister_server("headroom") is False+ assert "/custom/headroom" in cfg.read_text()+++# ----------------------------------------------------------------------+# Round-trip: write → re-read produces equivalent ServerSpec+# ----------------------------------------------------------------------+++ "spec",+ [+ ServerSpec(name="headroom", command="headroom", args=("mcp", "serve")),+ ServerSpec(+ name="headroom",+ command="headroom",+ args=("mcp", "serve"),+ env={"HEADROOM_PROXY_URL": "http://127.0.0.1:9000"},+ ),+ ServerSpec(name="headroom", command="/usr/bin/headroom", args=()),+ ],+)+def test_round_trip(tmp_path: Path, spec: ServerSpec) -> None:+ reg = _make_registrar(tmp_path)+ reg.register_server(spec)+ got = reg.get_server("headroom")+ assert got is not None+ assert got.command == spec.command+ assert got.args == spec.args+ assert got.env == spec.envdiff --git a/tests/test_mcp_registry/test_display.py b/tests/test_mcp_registry/test_display.pynew file mode 100644index 000000000..d3f0f6a2b--- /dev/null+++ b/tests/test_mcp_registry/test_display.py@@ -0,0 +1,179 @@+"""Tests for the install-result display helper."""++from __future__ import annotations++from headroom.mcp_registry.base import RegisterResult, RegisterStatus+from headroom.mcp_registry.display import (+ any_succeeded,+ format_result,+ format_results,+)++# ----------------------------------------------------------------------+# format_result+# ----------------------------------------------------------------------+++def test_registered_includes_restart_hint() -> None:+ line = format_result(+ "claude",+ RegisterResult(RegisterStatus.REGISTERED, "via CLI"),+ restart_hint="restart Claude Code if it was running",+ )+ assert line is not None+ assert "claude" in line+ assert "registered" in line+ assert "restart Claude Code" in line+++def test_already_silent_when_not_verbose() -> None:+ line = format_result(+ "claude",+ RegisterResult(RegisterStatus.ALREADY, "matches"),+ verbose=False,+ )+ assert line is None+++def test_already_emits_when_verbose() -> None:+ line = format_result(+ "claude",+ RegisterResult(RegisterStatus.ALREADY, "matches"),+ verbose=True,+ )+ assert line is not None+ assert "already registered" in line+++def test_not_detected_emits_skipped() -> None:+ line = format_result(+ "cursor",+ RegisterResult(RegisterStatus.NOT_DETECTED, "Cursor not found"),+ )+ assert line is not None+ assert "cursor" in line+ assert "not detected" in line+ assert "skipped" in line+++def test_mismatch_emits_overwrite_hint() -> None:+ line = format_result(+ "claude",+ RegisterResult(RegisterStatus.MISMATCH, "env differs"),+ overwrite_hint="headroom mcp install --force",+ )+ assert line is not None+ assert "differs" in line+ assert "headroom mcp install --force" in line+++def test_mismatch_omits_hint_when_empty() -> None:+ line = format_result(+ "claude",+ RegisterResult(RegisterStatus.MISMATCH, "env differs"),+ overwrite_hint="",+ )+ assert line is not None+ assert "To update" not in line+++def test_no_sdk_points_at_pip_extras() -> None:+ line = format_result(+ "claude",+ RegisterResult(RegisterStatus.NO_SDK, "missing"),+ )+ assert line is not None+ assert "MCP SDK" in line+ assert "headroom-ai[mcp]" in line+++def test_failed_includes_detail() -> None:+ line = format_result(+ "claude",+ RegisterResult(RegisterStatus.FAILED, "connection refused"),+ )+ assert line is not None+ assert "failed" in line+ assert "connection refused" in line+++def test_label_overrides_agent_name() -> None:+ line = format_result(+ "claude",+ RegisterResult(RegisterStatus.REGISTERED, "ok"),+ label="MCP retrieve tool",+ )+ assert line is not None+ assert "MCP retrieve tool" in line+ assert "claude" not in line+++# ----------------------------------------------------------------------+# format_results+# ----------------------------------------------------------------------+++def test_format_results_filters_silent_lines() -> None:+ results = {+ "claude": RegisterResult(RegisterStatus.REGISTERED, "ok"),+ "cursor": RegisterResult(RegisterStatus.ALREADY, "matches"),+ }+ lines = format_results(results, verbose=False)+ # ALREADY suppressed when verbose=False, so only one line.+ assert len(lines) == 1+ assert "claude" in lines[0]+++def test_format_results_label_for_remaps_agent_name() -> None:+ results = {+ "claude": RegisterResult(RegisterStatus.REGISTERED, "ok"),+ }+ labels = {"claude": "Claude Code"}+ lines = format_results(results, label_for=labels.get)+ assert len(lines) == 1+ assert "Claude Code" in lines[0]+++def test_format_results_preserves_iteration_order() -> None:+ results = {+ "a": RegisterResult(RegisterStatus.REGISTERED, "ok"),+ "b": RegisterResult(RegisterStatus.NOT_DETECTED, "missing"),+ "c": RegisterResult(RegisterStatus.MISMATCH, "env differs"),+ }+ lines = format_results(results, verbose=True)+ assert len(lines) == 3+ # Same order as input dict iteration.+ assert lines[0].strip().startswith("a:")+ assert lines[1].strip().startswith("b:")+ assert lines[2].strip().startswith("c:")+++# ----------------------------------------------------------------------+# any_succeeded+# ----------------------------------------------------------------------+++def test_any_succeeded_true_when_one_registered() -> None:+ results = {+ "a": RegisterResult(RegisterStatus.REGISTERED, "ok"),+ "b": RegisterResult(RegisterStatus.NOT_DETECTED, "missing"),+ }+ assert any_succeeded(results) is True+++def test_any_succeeded_true_when_already_registered() -> None:+ results = {"a": RegisterResult(RegisterStatus.ALREADY, "matches")}+ assert any_succeeded(results) is True+++def test_any_succeeded_false_when_all_failed_or_skipped() -> None:+ results = {+ "a": RegisterResult(RegisterStatus.NOT_DETECTED, "missing"),+ "b": RegisterResult(RegisterStatus.FAILED, "boom"),+ "c": RegisterResult(RegisterStatus.MISMATCH, "differs"),+ }+ assert any_succeeded(results) is False+++def test_any_succeeded_empty_dict_is_false() -> None:+ assert any_succeeded({}) is Falsediff --git a/tests/test_mcp_registry/test_install.py b/tests/test_mcp_registry/test_install.pynew file mode 100644index 000000000..5ffb38628--- /dev/null+++ b/tests/test_mcp_registry/test_install.py@@ -0,0 +1,140 @@+"""Tests for the install_everywhere orchestrator."""++from __future__ import annotations++from headroom.mcp_registry.base import (+ MCPRegistrar,+ RegisterResult,+ RegisterStatus,+ ServerSpec,+)+from headroom.mcp_registry.install import (+ DEFAULT_PROXY_URL,+ build_headroom_spec,+ install_everywhere,+)+++class _FakeRegistrar(MCPRegistrar):+ """Minimal registrar for orchestrator tests."""++ def __init__(+ self,+ name: str,+ *,+ detected: bool = True,+ register_result: RegisterResult | None = None,+ ) -> None:+ self.name = name+ self.display_name = name.title()+ self._detected = detected+ self._register_result = register_result or RegisterResult(RegisterStatus.REGISTERED, "ok")+ self.calls: list[ServerSpec] = []++ def detect(self) -> bool:+ return self._detected++ def get_server(self, server_name: str) -> ServerSpec | None:+ return None++ def register_server(self, spec: ServerSpec, *, force: bool = False) -> RegisterResult:+ self.calls.append(spec)+ return self._register_result++ def unregister_server(self, server_name: str) -> bool:+ return True+++# ----------------------------------------------------------------------+# build_headroom_spec+# ----------------------------------------------------------------------+++def test_build_spec_default_proxy_no_env() -> None:+ spec = build_headroom_spec()+ assert spec.name == "headroom"+ assert spec.command == "headroom"+ assert spec.args == ("mcp", "serve")+ assert spec.env == {}+++def test_build_spec_custom_proxy_sets_env() -> None:+ spec = build_headroom_spec("http://127.0.0.1:9999")+ assert spec.env == {"HEADROOM_PROXY_URL": "http://127.0.0.1:9999"}+++def test_build_spec_default_url_omits_env() -> None:+ spec = build_headroom_spec(DEFAULT_PROXY_URL)+ assert spec.env == {}+++# ----------------------------------------------------------------------+# install_everywhere+# ----------------------------------------------------------------------+++def test_install_everywhere_calls_each_detected_registrar() -> None:+ a = _FakeRegistrar("a")+ b = _FakeRegistrar("b")+ results = install_everywhere(registrars=[a, b])+ assert set(results) == {"a", "b"}+ assert results["a"].status == RegisterStatus.REGISTERED+ assert results["b"].status == RegisterStatus.REGISTERED+ assert len(a.calls) == 1+ assert len(b.calls) == 1+++def test_install_everywhere_skips_undetected() -> None:+ detected = _FakeRegistrar("a", detected=True)+ missing = _FakeRegistrar("b", detected=False)+ results = install_everywhere(registrars=[detected, missing])+ assert results["a"].status == RegisterStatus.REGISTERED+ assert results["b"].status == RegisterStatus.NOT_DETECTED+ assert len(detected.calls) == 1+ assert len(missing.calls) == 0+++def test_install_everywhere_filters_by_agents() -> None:+ a = _FakeRegistrar("a")+ b = _FakeRegistrar("b")+ c = _FakeRegistrar("c")+ results = install_everywhere(registrars=[a, b, c], agents=["a", "c"])+ assert set(results) == {"a", "c"}+ assert "b" not in results+++def test_install_everywhere_passes_proxy_url_into_spec() -> None:+ captured: list[ServerSpec] = []++ class CapturingRegistrar(_FakeRegistrar):+ def register_server(self, spec: ServerSpec, *, force: bool = False) -> RegisterResult:+ captured.append(spec)+ return RegisterResult(RegisterStatus.REGISTERED, "ok")++ reg = CapturingRegistrar("x")+ install_everywhere(proxy_url="http://localhost:9000", registrars=[reg])+ assert len(captured) == 1+ assert captured[0].env == {"HEADROOM_PROXY_URL": "http://localhost:9000"}+++def test_install_everywhere_passes_force_flag() -> None:+ captured: list[bool] = []++ class CapturingRegistrar(_FakeRegistrar):+ def register_server(self, spec: ServerSpec, *, force: bool = False) -> RegisterResult:+ captured.append(force)+ return RegisterResult(RegisterStatus.REGISTERED, "ok")++ reg = CapturingRegistrar("x")+ install_everywhere(registrars=[reg], force=True)+ assert captured == [True]+++def test_install_everywhere_returns_mismatch_results() -> None:+ mismatched = _FakeRegistrar(+ "a",+ register_result=RegisterResult(RegisterStatus.MISMATCH, "env differs"),+ )+ results = install_everywhere(registrars=[mismatched])+ assert results["a"].status == RegisterStatus.MISMATCH+ assert results["a"].ok is False # mismatch is NOT a success