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): escape control characters when rendering TOML server blocks (#3964)

Rajat Nagdaa96154f03b65
diff --git a/headroom/mcp_registry/codex.py b/headroom/mcp_registry/codex.py
index 2718ebf56..923ee0571 100644
--- a/headroom/mcp_registry/codex.py
+++ b/headroom/mcp_registry/codex.py
@@ -347,10 +347,37 @@ def _render_block(spec: ServerSpec) -> str:
return "\n".join(lines)
+# TOML basic strings forbid literal control characters other than tab, so a
+# value carrying a newline/carriage-return (e.g. a multi-line PEM key in an
+# env var) must be escaped or the rendered block is unparseable TOML. Only
+# ``\`` and ``"`` were escaped before, so such a value produced invalid TOML
+# and the write guard rejected the whole registration with a misleading
+# "file does not parse" error.
+_TOML_ESCAPES = {
+ "\\": "\\\\",
+ '"': '\\"',
+ "\b": "\\b",
+ "\t": "\\t",
+ "\n": "\\n",
+ "\f": "\\f",
+ "\r": "\\r",
+}
+
+
def _toml_str(s: str) -> str:
"""Render a Python string as a TOML basic string literal."""
- escaped = s.replace("\\", "\\\\").replace('"', '\\"')
- return f'"{escaped}"'
+ out: list[str] = []
+ for ch in s:
+ escape = _TOML_ESCAPES.get(ch)
+ if escape is not None:
+ out.append(escape)
+ elif ch < "\x20" or ch == "\x7f":
+ # Remaining C0 controls (and DEL) have no short escape; TOML requires
+ # the \uXXXX form.
+ out.append(f"\\u{ord(ch):04X}")
+ else:
+ out.append(ch)
+ return '"' + "".join(out) + '"'
def _entry_to_spec(name: str, entry: dict[str, Any]) -> ServerSpec:
diff --git a/headroom/mcp_registry/grok.py b/headroom/mcp_registry/grok.py
index b7363ab0c..d1fe203c6 100644
--- a/headroom/mcp_registry/grok.py
+++ b/headroom/mcp_registry/grok.py
@@ -18,7 +18,7 @@ from typing import Any
from headroom import fsutil
from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec
-from .codex import _evict_foreign_tables, _only_server_changed
+from .codex import _evict_foreign_tables, _only_server_changed, _toml_str
if sys.version_info >= (3, 11):
import tomllib
@@ -201,11 +201,6 @@ def _render_block(spec: ServerSpec) -> str:
return "\n".join(lines)
-def _toml_str(s: str) -> str:
- 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):
diff --git a/tests/test_mcp_registry/test_codex_registrar.py b/tests/test_mcp_registry/test_codex_registrar.py
index 008dfac92..15aa8520c 100644
--- a/tests/test_mcp_registry/test_codex_registrar.py
+++ b/tests/test_mcp_registry/test_codex_registrar.py
@@ -524,3 +524,23 @@ def test_refuses_span_rewrite_that_would_change_other_entries(
assert reg.unregister_server("headroom") is False
assert reg.register_server(_spec(), force=True).status == RegisterStatus.FAILED
assert cfg.read_text() == before
+
+
+def test_register_escapes_control_chars_in_env_value(tmp_path: Path) -> None:
+ """A newline in an env value must be escaped so the block stays valid TOML.
+
+ TOML basic strings forbid literal control characters other than tab, so a
+ multi-line value (e.g. a PEM key in an env var) rendered with only ``\\``
+ and ``"`` escaping produced unparseable TOML. The write guard then rejected
+ the whole registration with a misleading "file does not parse" error.
+ """
+ reg = _make_registrar(tmp_path)
+ pem = "-----BEGIN KEY-----\nabc\n-----END KEY-----"
+
+ result = reg.register_server(_spec(env={"PEM": pem}), force=True)
+
+ assert result.status == RegisterStatus.REGISTERED
+ # The rendered config parses and round-trips the value verbatim.
+ parsed = tomllib.loads(_config_path(tmp_path).read_text())
+ assert parsed["mcp_servers"]["headroom"]["env"]["PEM"] == pem
+ assert reg.get_server("headroom").env["PEM"] == pem
diff --git a/tests/test_mcp_registry/test_grok_registrar.py b/tests/test_mcp_registry/test_grok_registrar.py
index 72a2e3d37..611e2773d 100644
--- a/tests/test_mcp_registry/test_grok_registrar.py
+++ b/tests/test_mcp_registry/test_grok_registrar.py
@@ -93,3 +93,29 @@ def test_refuses_span_rewrite_that_would_change_other_entries(
moved = ServerSpec(name="headroom", command="/opt/python", args=_spec().args)
assert reg.register_server(moved, force=True).status == RegisterStatus.FAILED
assert cfg.read_text() == before
+
+
+def test_register_escapes_control_chars_in_env_value(tmp_path: Path) -> None:
+ """Grok shares the codex TOML escaper: a newline env value must round-trip."""
+ import sys
+
+ if sys.version_info >= (3, 11):
+ import tomllib
+ else: # pragma: no cover
+ import tomli as tomllib
+
+ reg = _make_registrar(tmp_path)
+ pem = "-----BEGIN KEY-----\nabc\n-----END KEY-----"
+ spec = ServerSpec(
+ name="headroom",
+ command="/usr/bin/python",
+ args=("-m", "headroom.cli", "mcp", "serve"),
+ env={"PEM": pem},
+ )
+
+ result = reg.register_server(spec, force=True)
+
+ assert result.status == RegisterStatus.REGISTERED
+ parsed = tomllib.loads(reg._config_file.read_text())
+ assert parsed["mcp_servers"]["headroom"]["env"]["PEM"] == pem
+ assert reg.get_server("headroom").env["PEM"] == pem