The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(mcp): an unset ${VAR} env entry counts as absent; set values pass verbatim
Tekniumcaa1ea8d923b
diff --git a/tests/tools/test_mcp_stdio_env_unset_ref.py b/tests/tools/test_mcp_stdio_env_unset_ref.pyindex b577f401219..e7d2006b7ed 100644--- a/tests/tools/test_mcp_stdio_env_unset_ref.py+++ b/tests/tools/test_mcp_stdio_env_unset_ref.py@@ -1,21 +1,47 @@-"""Stdio MCP launch env: an optional ``"VAR": "${VAR}"`` forward never reaches the child literally."""+"""Stdio MCP launch env: an env entry rendered from one unset ``${VAR}`` counts as absent."""+import json+import subprocess+import sysfrom unittest.mock import patch+USER_ENV = {"OPT_DIR": "${OPT_DIR}", "OPT_ENV": "${env:OPT_ENV}", "EMPTY": "${EMPTY}", "SET_DIR": "${SET_DIR}",+ "PARTIAL": "${OPT_DIR}/bin", "PLAIN": "x", "XDG_CONFIG_HOME": "${OPT_CONFIG_HOME}",+ "TERM": "${OPT_TERM}", "RESOLVED_LITERAL": "${ACTUAL_LITERAL}"}+PARENT = {"PATH": "/usr/bin:/bin", "TERM": "parent-term", "XDG_CONFIG_HOME": "/parent/config", "SET_DIR": "/opt/set",+ "EMPTY": "", "ACTUAL_LITERAL": "${STILL_UNSET}"}-def test_unset_whole_placeholder_env_entry_is_dropped():- """An optional ``"VAR": "${VAR}"`` forward never reaches the child as the literal- placeholder: unset drops the key, set passes the value, partial refs keep today's text."""- from tools.mcp_tool_config import _build_safe_env, _interpolate_env_vars- user_env = {"OPT_DIR": "${OPT_DIR}", "OPT_ENV": "${env:OPT_ENV}", "SET_DIR": "${SET_DIR}",- "PARTIAL": "${OPT_DIR}/bin", "PLAIN": "x", "XDG_CONFIG_HOME": "${OPT_CONFIG_HOME}"}- parent = {"PATH": "/usr/bin", "SET_DIR": "/opt/set", "XDG_CONFIG_HOME": "/parent/config"}- with patch.dict("os.environ", parent, clear=True):- result = _build_safe_env(_interpolate_env_vars(user_env))+def _rendered():+ from tools.mcp_tool_config import _interpolate_env_vars+ # Load renders once; connect renders again under the owner's scope.+ return _interpolate_env_vars(_interpolate_env_vars({"command": sys.executable, "env": USER_ENV}))- assert "OPT_DIR" not in result and "OPT_ENV" not in result- assert "XDG_CONFIG_HOME" not in result # unset override does not fall back to the parent's value- assert result["SET_DIR"] == "/opt/set"++def test_unset_whole_ref_counts_as_absent_and_set_values_pass_verbatim():+ from tools.mcp_tool_config import _build_safe_env++ with patch.dict("os.environ", PARENT, clear=True):+ result = _build_safe_env(_rendered()["env"])++ assert not {"OPT_DIR", "OPT_ENV", "EMPTY"} & set(result)+ assert result["XDG_CONFIG_HOME"] == "/parent/config" # as if the line weren't there+ assert result["SET_DIR"] == "/opt/set" and result["PLAIN"] == "x"assert result["PARTIAL"] == "${OPT_DIR}/bin"- assert result["PLAIN"] == "x"+ assert result["RESOLVED_LITERAL"] == "${STILL_UNSET}" # a set value is data, whatever it looks like+++def test_child_spawned_through_the_sdk_merge_sees_the_documented_env():+ from mcp.client.stdio import get_default_environment+ from tools.mcp_tool_transport import _stdio_launch++ with patch.dict("os.environ", PARENT, clear=True):+ command, env, _ = _stdio_launch(_rendered())+ child_env = get_default_environment() | env # what mcp.client.stdio.stdio_client spawns with+ probe = "import json, os; print(json.dumps(dict(os.environ)))"+ seen = json.loads(subprocess.run([command, "-c", probe], env=child_env, capture_output=True, text=True,+ check=True).stdout)++ assert "OPT_DIR" not in seen and "EMPTY" not in seen+ assert seen["TERM"] == "parent-term"+ assert seen["RESOLVED_LITERAL"] == "${STILL_UNSET}"diff --git a/tools/mcp_tool_config.py b/tools/mcp_tool_config.pyindex 070d67bb99f..526b3e1875f 100644--- a/tools/mcp_tool_config.py+++ b/tools/mcp_tool_config.py@@ -181,10 +181,19 @@ _CONTEXT_VAR_RESOLVERS = {"workspaceFolderBasename": _workspace_basename, "pathSeparator": lambda: os.sep, "/": lambda: os.sep}-def _is_unresolved_ref(value: Any) -> bool:- """True when *value* is entirely one env ``${VAR}`` / ``${env:VAR}`` placeholder (not a context var)."""- match = _ENV_VAR_PATTERN.fullmatch(value) if isinstance(value, str) else None- return match is not None and match.group(1).strip() not in _CONTEXT_VAR_RESOLVERS+class _RenderedStr(str):+ """A config string after ``${...}`` rendering, carrying how it resolved, so later steps never+ guess from text that may itself look like ``${...}``. ``missed``: some env reference was unset+ (or empty) and kept its placeholder; a re-render (connect renders again under the owner's fresh+ scope) retries from ``template``, while a fully resolved value is final. ``unset_ref``: the+ template was one whole env reference that missed."""++ def __new__(cls, text: str = "", template: Optional[str] = None, missed: bool = False, unset_ref: bool = False):+ rendered = super().__new__(cls, text)+ rendered.template = text if template is None else template+ rendered.missed = missed+ rendered.unset_ref = unset_ref+ return rendereddef _build_safe_env(user_env: Optional[dict]) -> dict:@@ -207,13 +216,12 @@ def _build_safe_env(user_env: Optional[dict]) -> dict:if key in os.environ:env[key] = os.environ[key]if user_env:- # A value that is still a whole ``${VAR}`` here was unset (or empty) at render time: the- # key is left unset (baseline copy included) so a plugin can forward an optional var- # without the child seeing the literal placeholder (servers that validate it refuse to start).+ # An entry rendered from one whole ``${VAR}`` that is unset (or empty) counts as absent, so+ # a plugin can forward an optional var without the child seeing the literal placeholder.+ # The key keeps its baseline value, if any: the MCP SDK re-adds its own inherited set+ # (PATH, HOME, TERM, ...) at spawn anyway, so popping here would not unset it.for key, value in user_env.items():- if _is_unresolved_ref(value):- env.pop(key, None)- else:+ if not getattr(value, "unset_ref", False):env[key] = valuefrom agent.delegation_context import delegated_child_subprocess_envreturn delegated_child_subprocess_env(env)@@ -546,13 +554,27 @@ def _packaged_npx_entry(command: str, args: list) -> Optional[tuple]:def _interpolate_env_vars(value):"""Recursively resolve ``${VAR}`` / Cursor ``${env:VAR}`` placeholders and context vars. Envrefs resolve from the active profile's secret scope when multiplexing (the routed profile's- value, not another profile's in ``os.environ``). Unset vars keep the literal placeholder."""+ value, not another profile's in ``os.environ``). Unset (or empty) vars keep the literal placeholder;+ a templated string comes back as a ``_RenderedStr`` recording how it resolved."""from agent.secret_scope import get_secret as _get_secretif isinstance(value, str):+ if isinstance(value, _RenderedStr) and not value.missed:+ return value+ template = getattr(value, "template", value)+ missed = []+def _replace(m):resolver = _CONTEXT_VAR_RESOLVERS.get(m.group(1).strip())- return resolver() if resolver is not None else (_get_secret(_env_ref_name(m.group(1)), m.group(0)) or m.group(0))- return _ENV_VAR_PATTERN.sub(_replace, value)+ if resolver is not None:+ return resolver()+ resolved = _get_secret(_env_ref_name(m.group(1)), None)+ if not resolved:+ missed.append(m.group(0))+ return resolved or m.group(0)+ text = _ENV_VAR_PATTERN.sub(_replace, template)+ if text == template and not missed:+ return value+ return _RenderedStr(text, template, missed=bool(missed), unset_ref=missed == [template])if isinstance(value, dict):return {k: _interpolate_env_vars(v) for k, v in value.items()}if isinstance(value, list):diff --git a/website/docs/developer-guide/plugins/index.md b/website/docs/developer-guide/plugins/index.mdindex 3de41889644..b612ee737bf 100644--- a/website/docs/developer-guide/plugins/index.md+++ b/website/docs/developer-guide/plugins/index.md@@ -105,9 +105,10 @@ Values declared in portable MCP `env` are visible package data, not a secretstorage mechanism. Do not place credentials in `mcp.json`.To pass a user's variable through to a stdio server (Hermes otherwise hands MCPservers a filtered environment), declare it as `"NAME": "${NAME}"`. The value-comes from the user's shell or profile `.env`; when the variable is unset, Hermes-leaves `NAME` out of the server's environment rather than passing the literal-`${NAME}`, so optional variables are safe to forward.+comes from the user's shell or profile `.env`; when the variable is unset (or+empty), the entry is treated as if it weren't there: the server doesn't get the+literal `${NAME}`, and `NAME` keeps whatever value the server would have without+that line (usually unset). Optional variables are safe to forward.The current portable subset supports stdio and Streamable HTTP MCP entries.Portable `streamable-http` entries are routed through Hermes' existing nativediff --git a/website/docs/reference/mcp-config-reference.md b/website/docs/reference/mcp-config-reference.mdindex 3613cc9fb54..86b311a1a30 100644--- a/website/docs/reference/mcp-config-reference.md+++ b/website/docs/reference/mcp-config-reference.md@@ -83,7 +83,7 @@ mcp_servers:GITHUB_PERSONAL_ACCESS_TOKEN: "${env:GITHUB_TOKEN}" # same as "${GITHUB_TOKEN}"```-Values resolve from the active profile's secret scope (falling back to the process environment), so put the secret in `~/.hermes/.env`. An unset (or empty) variable keeps its literal placeholder, with two exceptions. A stdio server's `env` entry whose whole value is one reference (`GHIDRA_INSTALL_DIR: "${GHIDRA_INSTALL_DIR}"`) is left out of the server's environment instead, so a config or plugin can forward an optional variable and the server sees it as unset rather than as the text `${GHIDRA_INSTALL_DIR}`; a value that only contains a reference (`"${OPT_DIR}/bin"`) is still passed with the placeholder. And in a remote server's `url` or `headers`: sending a literal `${VAR}` there is a guaranteed 401 that reads as a bad credential, so the connect fails closed instead, with the variable named in the server's status (`MCP server 'name': ${VAR} in url/headers is not set in this profile's .env or secret source`). Fix the profile's `.env` (or its secret source); the next connect attempt renders the reference afresh.+Values resolve from the active profile's secret scope (falling back to the process environment), so put the secret in `~/.hermes/.env`. An unset (or empty) variable keeps its literal placeholder, with two exceptions. A stdio server's `env` entry whose whole value is one reference to an unset variable (`GHIDRA_INSTALL_DIR: "${GHIDRA_INSTALL_DIR}"`) is treated as if the entry weren't there: the server doesn't get the placeholder, and the variable keeps whatever value the server would have without that line (usually unset; basics such as `PATH`, `HOME` or `TERM` keep the value Hermes passes every server). So a config or plugin can forward an optional variable safely. A variable that is set is always passed as is, even if its value happens to look like `${...}`; a value that only contains a reference (`"${OPT_DIR}/bin"`) is still passed with the placeholder. And in a remote server's `url` or `headers`: sending a literal `${VAR}` there is a guaranteed 401 that reads as a bad credential, so the connect fails closed instead, with the variable named in the server's status (`MCP server 'name': ${VAR} in url/headers is not set in this profile's .env or secret source`). Fix the profile's `.env` (or its secret source); the next connect attempt renders the reference afresh.### Context variables