Skip to content

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.

fix(mcp_registry): atomic config writes, no traceback on non-UTF-8 configs, log failed removals (#4130)

Tejas Chopraf2153fec2b8d
diff --git a/headroom/mcp_registry/claude.py b/headroom/mcp_registry/claude.py
index 64a9afab4..d27d09362 100644
--- a/headroom/mcp_registry/claude.py
+++ b/headroom/mcp_registry/claude.py
@@ -34,6 +34,7 @@ import shutil
from pathlib import Path
from typing import Any
+from headroom import fsutil
from headroom._subprocess import run
from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec
@@ -184,6 +185,10 @@ class ClaudeRegistrar(MCPRegistrar):
raise ClaudeConfigMutationError(
f"could not read Claude config {config_path}: {exc}"
) from exc
+ except UnicodeDecodeError as exc:
+ raise ClaudeConfigMutationError(
+ f"Claude config {config_path} is not valid UTF-8; refusing to mutate"
+ ) from exc
try:
config = json.loads(raw)
except json.JSONDecodeError as exc:
@@ -321,27 +326,22 @@ class ClaudeRegistrar(MCPRegistrar):
def _remove_from_file(self, path: Path, server_name: str, scope: str) -> bool:
if not path.exists():
return False
- try:
- config = _read_json(path)
- except OSError:
- return False
+ config = _read_json(path)
servers = self._servers_map(config, scope)
if servers is None or server_name not in servers:
return False
del servers[server_name]
try:
_write_json(path, config)
- except OSError:
+ except OSError as exc:
+ logger.warning("could not remove %r from %s: %s", server_name, path, exc)
return False
return True
def _read_server_entry(self, path: Path, server_name: str, scope: str) -> ServerSpec | None:
if not path.exists():
return None
- try:
- config = _read_json(path)
- except OSError:
- return None
+ config = _read_json(path)
servers = self._servers_map(config, scope)
if servers is None:
return None
@@ -498,7 +498,7 @@ def _read_json(path: Path) -> dict[str, Any]:
try:
with open(path, encoding="utf-8") as f:
data = json.load(f)
- except (OSError, json.JSONDecodeError):
+ except (OSError, json.JSONDecodeError, UnicodeDecodeError):
return {}
if not isinstance(data, dict):
return {}
@@ -561,7 +561,10 @@ def _read_json_for_write(path: Path) -> dict[str, Any]:
"""
if not path.exists():
return {}
- raw = path.read_text(encoding="utf-8") # OSError propagates to the caller
+ try:
+ raw = path.read_text(encoding="utf-8") # OSError propagates to the caller
+ except UnicodeDecodeError as exc:
+ raise _MalformedConfigError(f"not valid UTF-8: {exc}") from exc
if not raw.strip():
return {}
try:
@@ -575,9 +578,7 @@ def _read_json_for_write(path: Path) -> dict[str, Any]:
def _write_json(path: Path, data: dict[str, Any]) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
- with open(path, "w", encoding="utf-8") as f:
- json.dump(data, f, indent=2)
- f.write("\n")
+ fsutil.write_text(path, json.dumps(data, indent=2) + "\n")
def _spec_to_entry(spec: ServerSpec) -> dict[str, Any]:
diff --git a/headroom/mcp_registry/codex.py b/headroom/mcp_registry/codex.py
index 923ee0571..4405ea399 100644
--- a/headroom/mcp_registry/codex.py
+++ b/headroom/mcp_registry/codex.py
@@ -234,7 +234,8 @@ class CodexRegistrar(MCPRegistrar):
return False
try:
fsutil.write_text(self._config_file, new_content)
- except OSError:
+ except OSError as exc:
+ logger.warning("could not remove %r from %s: %s", server_name, self._config_file, exc)
return False
return True
diff --git a/headroom/mcp_registry/grok.py b/headroom/mcp_registry/grok.py
index d1fe203c6..a2e888117 100644
--- a/headroom/mcp_registry/grok.py
+++ b/headroom/mcp_registry/grok.py
@@ -131,7 +131,8 @@ class GrokRegistrar(MCPRegistrar):
return False
try:
fsutil.write_text(self._config_file, new_content)
- except OSError:
+ except OSError as exc:
+ logger.warning("could not remove %r from %s: %s", server_name, self._config_file, exc)
return False
return True
diff --git a/headroom/mcp_registry/ledger.py b/headroom/mcp_registry/ledger.py
index af1d1b634..3a0bcf86a 100644
--- a/headroom/mcp_registry/ledger.py
+++ b/headroom/mcp_registry/ledger.py
@@ -14,7 +14,7 @@ from datetime import datetime, timezone
from pathlib import Path
from typing import Any
-from headroom import paths
+from headroom import fsutil, paths
from .base import ServerSpec
@@ -129,6 +129,10 @@ def _read_ledger(path: Path, *, for_mutation: bool = False) -> dict[str, Any]:
if for_mutation:
raise LedgerMutationError(f"MCP install ledger is unreadable: {path}") from exc
return {}
+ except UnicodeDecodeError as exc:
+ if for_mutation:
+ raise LedgerMutationError(f"MCP install ledger is not valid UTF-8: {path}") from exc
+ return {}
try:
data = json.loads(raw)
except json.JSONDecodeError as exc:
@@ -137,7 +141,7 @@ def _read_ledger(path: Path, *, for_mutation: bool = False) -> dict[str, Any]:
return {}
if not isinstance(data, dict):
if for_mutation:
- raise LedgerMutationError("MCP install ledger must contain a JSON object")
+ raise LedgerMutationError(f"MCP install ledger must contain a JSON object: {path}")
return {}
if for_mutation:
for section in ("agents",):
@@ -168,4 +172,4 @@ def _read_ledger(path: Path, *, for_mutation: bool = False) -> dict[str, Any]:
def _write_ledger(path: Path, data: dict[str, Any]) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
- path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ fsutil.write_text(path, json.dumps(data, indent=2, sort_keys=True) + "\n")
diff --git a/headroom/mcp_registry/opencode.py b/headroom/mcp_registry/opencode.py
index 1b0928d62..6cd470104 100644
--- a/headroom/mcp_registry/opencode.py
+++ b/headroom/mcp_registry/opencode.py
@@ -14,6 +14,7 @@ import shutil
from pathlib import Path
from typing import Any
+from headroom import fsutil
from headroom.install.paths import opencode_config_path
from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec
@@ -57,7 +58,7 @@ def _read_json(path: Path) -> dict[str, Any]:
return {}
try:
raw = path.read_text(encoding="utf-8")
- except OSError:
+ except (OSError, UnicodeDecodeError):
return {}
return _parse_json_loose(raw) or {}
@@ -84,7 +85,10 @@ def _read_json_for_write(path: Path) -> dict[str, Any]:
"""
if not path.exists():
return {}
- raw = path.read_text(encoding="utf-8") # OSError propagates to the caller
+ try:
+ raw = path.read_text(encoding="utf-8") # OSError propagates to the caller
+ except UnicodeDecodeError as exc:
+ raise _MalformedConfigError(f"not valid UTF-8: {exc}") from exc
if not raw.strip():
return {}
data = _parse_json_loose(raw)
@@ -95,9 +99,7 @@ def _read_json_for_write(path: Path) -> dict[str, Any]:
def _write_json(path: Path, data: dict[str, Any]) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
- with open(path, "w", encoding="utf-8") as f:
- json.dump(data, f, indent=2)
- f.write("\n")
+ fsutil.write_text(path, json.dumps(data, indent=2) + "\n")
def _entry_to_spec(name: str, entry: dict[str, Any]) -> ServerSpec:
diff --git a/tests/test_mcp_registry/test_claude_registrar.py b/tests/test_mcp_registry/test_claude_registrar.py
index 5caa1e28c..adf9d5bd4 100644
--- a/tests/test_mcp_registry/test_claude_registrar.py
+++ b/tests/test_mcp_registry/test_claude_registrar.py
@@ -3,6 +3,8 @@
from __future__ import annotations
import json
+import os
+import stat
import subprocess
from pathlib import Path
from unittest.mock import patch
@@ -492,6 +494,55 @@ def test_register_via_file_preserves_malformed_config(tmp_path: Path, contents:
assert cfg.read_text(encoding="utf-8") == contents
+def test_non_utf8_config_fails_cleanly_and_is_left_untouched(tmp_path: Path) -> None:
+ """A ~/.claude.json saved in a non-UTF-8 locale encoding (GBK here) must not
+ crash register/unregister/validate with a raw UnicodeDecodeError; it is
+ treated as malformed and never rewritten."""
+ from headroom.mcp_registry.claude import ClaudeConfigMutationError
+
+ cfg = tmp_path / ".claude.json"
+ original = '{"projects": {"/项目": {}}}'.encode("gbk")
+ cfg.write_bytes(original)
+ reg = _make_registrar(tmp_path, cli=None)
+
+ result = reg.register_server(_spec())
+ assert result.status == RegisterStatus.FAILED
+ assert "not valid JSON" in result.detail
+ assert reg.unregister_server("headroom") is False
+ with pytest.raises(ClaudeConfigMutationError, match="not valid UTF-8"):
+ reg.validate_configs_for_mutation()
+ assert cfg.read_bytes() == original
+
+
[email protected](os.name == "nt", reason="POSIX file modes")
+def test_failed_write_leaves_claude_json_intact(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """~/.claude.json holds OAuth state; a write that fails mid-way (ENOSPC at
+ fsync here) must leave the original bytes and mode, and no temp file."""
+ cfg = tmp_path / ".claude.json"
+ original = json.dumps({"oauthAccount": {"emailAddress": "[email protected]"}, "mcpServers": {}})
+ cfg.write_text(original, encoding="utf-8")
+ cfg.chmod(0o600)
+ reg = _make_registrar(tmp_path, cli=None)
+
+ def no_space(fd: int) -> None:
+ raise OSError(28, "No space left on device")
+
+ monkeypatch.setattr("headroom.fsutil.os.fsync", no_space)
+ result = reg.register_server(_spec())
+ assert result.status == RegisterStatus.FAILED
+ assert "No space left" in result.detail
+
+ assert cfg.read_text(encoding="utf-8") == original
+ assert sorted(p.name for p in tmp_path.iterdir()) == [".claude.json"]
+
+ monkeypatch.undo()
+ assert reg.register_server(_spec()).status == RegisterStatus.REGISTERED
+ assert stat.S_IMODE(cfg.stat().st_mode) == 0o600
+ assert json.loads(cfg.read_text(encoding="utf-8"))["oauthAccount"]
+
+
def test_register_via_file_merges_into_existing_valid_config(tmp_path: Path) -> None:
"""The happy path still merges: unrelated keys are preserved and mcpServers
gains the headroom entry."""
diff --git a/tests/test_mcp_registry/test_ledger.py b/tests/test_mcp_registry/test_ledger.py
index 406fefca5..ece90cf9f 100644
--- a/tests/test_mcp_registry/test_ledger.py
+++ b/tests/test_mcp_registry/test_ledger.py
@@ -117,3 +117,20 @@ def test_record_install_recovers_from_unsafe_ledger_shape(tmp_path, contents):
record_install("claude", _spec(), path=ledger)
assert headroom_installed_matching("claude", _spec(), path=ledger)
+
+
+def test_failed_ledger_write_keeps_the_previous_ledger(monkeypatch, tmp_path):
+ """ENOSPC mid-write must not truncate the ledger or leave a temp file."""
+ ledger = tmp_path / "mcp_installs.json"
+ record_install("claude", _spec(), path=ledger)
+ before = ledger.read_bytes()
+
+ def no_space(fd: int) -> None:
+ raise OSError(28, "No space left on device")
+
+ monkeypatch.setattr("headroom.fsutil.os.fsync", no_space)
+ with pytest.raises(OSError, match="No space left"):
+ clear_install("claude", "serena", path=ledger)
+
+ assert ledger.read_bytes() == before
+ assert [p.name for p in tmp_path.iterdir()] == ["mcp_installs.json"]
diff --git a/tests/test_mcp_registry/test_removal_failures.py b/tests/test_mcp_registry/test_removal_failures.py
new file mode 100644
index 000000000..345746324
--- /dev/null
+++ b/tests/test_mcp_registry/test_removal_failures.py
@@ -0,0 +1,68 @@
+"""A removal whose config write fails returns False and says why, per registrar."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import pytest
+
+from headroom.mcp_registry.base import MCPRegistrar, RegisterStatus, ServerSpec
+from headroom.mcp_registry.claude import ClaudeRegistrar
+from headroom.mcp_registry.codex import CodexRegistrar
+from headroom.mcp_registry.grok import GrokRegistrar
+
+
+def _no_space(fd: int) -> None:
+ raise OSError(28, "No space left on device")
+
+
+ ("make", "config", "logger_name"),
+ [
+ (
+ lambda home: ClaudeRegistrar(claude_cli=None, home_dir=home),
+ ".claude.json",
+ "headroom.mcp_registry.claude",
+ ),
+ (
+ lambda home: CodexRegistrar(home_dir=home),
+ ".codex/config.toml",
+ "headroom.mcp_registry.codex",
+ ),
+ (
+ lambda home: GrokRegistrar(home_dir=home),
+ ".grok/config.toml",
+ "headroom.mcp_registry.grok",
+ ),
+ ],
+ ids=["claude", "codex", "grok"],
+)
+def test_failed_removal_keeps_the_config_and_logs_why(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+ caplog: pytest.LogCaptureFixture,
+ make,
+ config: str,
+ logger_name: str,
+) -> None:
+ monkeypatch.delenv("GROK_HOME", raising=False)
+ monkeypatch.delenv("CODEX_HOME", raising=False)
+ monkeypatch.chdir(tmp_path)
+ registrar: MCPRegistrar = make(tmp_path)
+ spec = ServerSpec(name="headroom", command="/usr/bin/python", args=("-m", "headroom.cli"))
+ assert registrar.register_server(spec).status == RegisterStatus.REGISTERED
+ path = tmp_path / config
+ before = path.read_bytes()
+
+ monkeypatch.setattr("headroom.fsutil.os.fsync", _no_space)
+ with caplog.at_level(logging.WARNING, logger=logger_name):
+ assert registrar.unregister_server("headroom") is False
+
+ assert path.read_bytes() == before
+ messages = [r.getMessage() for r in caplog.records if r.name == logger_name]
+ assert messages
+ assert all(
+ m.startswith(f"could not remove 'headroom' from {path}") and "No space left" in m
+ for m in messages
+ )
diff --git a/tests/test_mcp_registry_opencode.py b/tests/test_mcp_registry_opencode.py
index 766a5ebd2..004aea04b 100644
--- a/tests/test_mcp_registry_opencode.py
+++ b/tests/test_mcp_registry_opencode.py
@@ -170,6 +170,26 @@ def test_register_server_preserves_malformed_config(tmp_path: Path, contents: st
assert config_path.read_text(encoding="utf-8") == contents
+def test_non_utf8_config_fails_cleanly_and_is_left_untouched(tmp_path: Path) -> None:
+ """An opencode.json saved in a non-UTF-8 locale encoding (GBK here) must not
+ crash with a raw UnicodeDecodeError; it is treated as malformed and never
+ rewritten."""
+ from headroom.mcp_registry.base import ServerSpec
+
+ config_path = tmp_path / "opencode.json"
+ original = '{"theme": "主题"}'.encode("gbk")
+ config_path.write_bytes(original)
+ registrar = _registrar(tmp_path)
+
+ spec = ServerSpec(name="headroom", command="headroom", args=("mcp", "serve"))
+ result = registrar.register_server(spec)
+
+ assert result.status == RegisterStatus.FAILED
+ assert "not valid JSON" in result.detail
+ assert registrar.unregister_server("headroom") is False
+ assert config_path.read_bytes() == original
+
+
def test_register_server_preserves_other_keys(tmp_path: Path) -> None:
"""The happy path merges: theme/model and an existing MCP server survive."""
from headroom.mcp_registry.base import ServerSpec