mcp_tool_config.py 37 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740
  1. """MCP server config loading and stdio launch environment: ${VAR}/Cursor-style
  2. interpolation, hidden-whitespace and suspicious-entry filtering, the filtered
  3. subprocess env, command resolution, the cached-npx binary shortcut and the shared stderr log."""
  4. import codecs
  5. import hashlib
  6. import json
  7. import logging
  8. import os
  9. import re
  10. import shutil
  11. import subprocess
  12. import sys
  13. import threading
  14. from pathlib import Path
  15. from typing import Any, Dict, List, Optional, Set, Tuple
  16. from hermes_cli.stderr_timestamp import stamp_line, timestamp
  17. from tools.mcp_tool_common import _env_ref_name, _prepend_path
  18. logger = logging.getLogger("tools.mcp_tool")
  19. _mcp_stderr_log_fh: dict[str, Any] = {} # profile home key -> handle
  20. _mcp_stderr_log_lock = threading.Lock()
  21. def _get_mcp_stderr_log() -> Any:
  22. """Shared append-mode handle for MCP subprocess stderr, cached until shutdown PER PROFILE HOME (a
  23. multiplexed gateway's secondary profile must log under ITS ``logs/``, not the launch profile's). Must
  24. expose a real fd (asyncio wires the child's stderr to it); falls back to ``/dev/null``, then real stderr."""
  25. from hermes_constants import get_hermes_home, hermes_home_key, mkdir_under_hermes_home
  26. home_key = hermes_home_key()
  27. with _mcp_stderr_log_lock:
  28. fh = _mcp_stderr_log_fh.get(home_key)
  29. if fh is None or fh.closed:
  30. try:
  31. log_dir = get_hermes_home() / "logs"
  32. mkdir_under_hermes_home(log_dir)
  33. # Line-buffered so output lands promptly; errors="replace" tolerates garbled binary.
  34. fh = open(log_dir / "mcp-stderr.log", "a", encoding="utf-8", errors="replace", buffering=1)
  35. fh.fileno() # confirm a real fd before committing
  36. except Exception as exc: # pragma: no cover — best-effort fallback
  37. logger.debug("Failed to open MCP stderr log, using devnull: %s", exc)
  38. try:
  39. fh = open(os.devnull, "w", encoding="utf-8")
  40. except Exception:
  41. fh = sys.stderr
  42. _mcp_stderr_log_fh[home_key] = fh
  43. return fh
  44. def _close_mcp_stderr_logs(*, scope: Optional[str] = None) -> None:
  45. """Release cached parent handles after the selected MCP transports have stopped."""
  46. with _mcp_stderr_log_lock:
  47. keys = list(_mcp_stderr_log_fh) if scope is None else [scope]
  48. for key in keys:
  49. fh = _mcp_stderr_log_fh.pop(key, None)
  50. # The last-resort fallback is borrowed, not owned by MCP.
  51. if fh is None or fh is sys.stderr or fh is sys.__stderr__:
  52. continue
  53. try:
  54. fh.close()
  55. except OSError:
  56. logger.warning("Could not close MCP stderr log for %s", key, exc_info=True)
  57. class _StderrTee:
  58. """A stdio child's stderr, copied into the shared log one stamped line at a time while the last few KB
  59. stay readable (raw), so a server that dies at startup can say why on the MCP status surfaces instead of
  60. only in the log (#124264). ``sink`` is handed to the child; ``close()`` returns the captured tail."""
  61. _TAIL_BYTES = 16384
  62. def __init__(self, log_fh: Any):
  63. read_fd, write_fd = os.pipe()
  64. self.sink = os.fdopen(write_fd, "wb", buffering=0)
  65. self._log, self._tail = log_fh, bytearray()
  66. self._reader = threading.Thread(target=self._pump, args=(read_fd,), name="mcp-stderr", daemon=True)
  67. self._reader.start()
  68. def _pump(self, read_fd: int) -> None:
  69. decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
  70. pending = ""
  71. with os.fdopen(read_fd, "rb", buffering=0) as source:
  72. while chunk := source.read(65536):
  73. self._tail = (self._tail + chunk)[-self._TAIL_BYTES:]
  74. # Stamp whole lines only; a partial line waits for its newline (or EOF).
  75. *lines, pending = (pending + decoder.decode(chunk)).split("\n")
  76. self._write_lines(lines)
  77. if rest := pending + decoder.decode(b"", final=True):
  78. self._write_lines([rest])
  79. def _write_lines(self, lines: list[str]) -> None:
  80. if not lines:
  81. return
  82. try:
  83. self._log.write("".join(stamp_line(line) for line in lines))
  84. self._log.flush()
  85. except (OSError, ValueError): # log closed at shutdown: keep draining the child
  86. pass
  87. def close(self, timeout: float = 2.0) -> str:
  88. """Close our write end and give the reader *timeout* to drain (a surviving grandchild can keep
  89. the pipe open); the tail read so far."""
  90. self.sink.close()
  91. self._reader.join(timeout)
  92. return self._tail.decode("utf-8", errors="replace")
  93. def _write_stderr_log_header(server_name: str) -> None:
  94. """Session marker so operators can find each server's output in the shared log; it leads with the
  95. same stamp as every server line (``_StderrTee``) so ``hermes logs mcp --since`` can filter it."""
  96. fh = _get_mcp_stderr_log()
  97. try:
  98. fh.write(f"\n{timestamp()} ===== starting MCP server '{server_name}' =====\n")
  99. fh.flush()
  100. except Exception:
  101. pass
  102. def _tail_server_stderr(server_name: str, *, max_bytes: int = 8192, max_lines: int = 8) -> str:
  103. """Trailing lines this server last wrote to the shared stderr log; ``''`` when none.
  104. A connect failure that only says ``Connection closed`` hides why the child died
  105. (#125300: a ``ModuleNotFoundError`` sat in the log while the agent log stayed mute).
  106. Best-effort: the segment header must still be inside the read window, and another
  107. server's output past that header is fair game — the header lines carry the name."""
  108. try:
  109. fh = _get_mcp_stderr_log()
  110. path = getattr(fh, "name", None)
  111. if not path or path == os.devnull:
  112. return ""
  113. with open(path, "rb") as raw:
  114. raw.seek(0, os.SEEK_END)
  115. size = raw.tell()
  116. raw.seek(max(0, size - max_bytes))
  117. chunk = raw.read().decode("utf-8", "replace")
  118. cut = chunk.rfind(f"starting MCP server '{server_name}'")
  119. if cut < 0:
  120. return ""
  121. lines = [line for line in chunk[cut:].splitlines() if line.strip()]
  122. return "\n".join(lines[-max_lines:]) if lines else ""
  123. except Exception:
  124. return ""
  125. # Env vars safe to pass to stdio subprocesses (no secrets).
  126. _SAFE_ENV_KEYS = frozenset({"PATH", "HOME", "USER", "LANG", "LC_ALL", "TERM", "SHELL", "TMPDIR"})
  127. # Windows process/location vars needed by launcher-style tools (e.g. Docker Desktop's MCP plugin discovery).
  128. _SAFE_ENV_KEYS_CASE_INSENSITIVE = frozenset({
  129. "ALLUSERSPROFILE", "APPDATA", "COMMONPROGRAMFILES", "COMMONPROGRAMFILES(X86)",
  130. "COMMONPROGRAMW6432", "COMPUTERNAME", "COMSPEC", "HOMEDRIVE", "HOMEPATH",
  131. "LOCALAPPDATA", "NUMBER_OF_PROCESSORS", "OS", "PATHEXT", "PROCESSOR_ARCHITECTURE",
  132. "PROGRAMDATA", "PROGRAMFILES", "PROGRAMFILES(X86)", "PROGRAMW6432", "PUBLIC",
  133. "SYSTEMDRIVE", "SYSTEMROOT", "TEMP", "TMP", "USERDOMAIN", "USERNAME",
  134. "USERPROFILE", "WINDIR"})
  135. # ${VAR_NAME} interpolation; any non-} chars allowed so MY-VAR / my.var work.
  136. _ENV_VAR_PATTERN = re.compile(r"\$\{([^}]+)\}")
  137. def _workspace_folder() -> str:
  138. """Absolute workspace root for ``${workspaceFolder}``: the session's authoritative root
  139. (terminal cwd / task override / $TERMINAL_CWD), else cwd."""
  140. try:
  141. from tools.file_tools_paths import _authoritative_workspace_root
  142. root = _authoritative_workspace_root()
  143. except Exception:
  144. root = None
  145. return root or os.getcwd()
  146. def _workspace_basename() -> str:
  147. root = _workspace_folder()
  148. return os.path.basename(root.rstrip("/\\")) or root
  149. # Cursor's case-sensitive context vars -> resolver.
  150. _CONTEXT_VAR_RESOLVERS = {
  151. "userHome": lambda: os.path.expanduser("~"), "workspaceFolder": lambda: _workspace_folder(),
  152. "workspaceFolderBasename": _workspace_basename, "pathSeparator": lambda: os.sep, "/": lambda: os.sep}
  153. class _RenderedStr(str):
  154. """A config string after ``${...}`` rendering, carrying how it resolved, so later steps never
  155. guess from text that may itself look like ``${...}``. ``missed``: some env reference was unset
  156. (or empty) and kept its placeholder; a re-render (connect renders again under the owner's fresh
  157. scope) retries from ``template``, while a fully resolved value is final. ``unset_ref``: the
  158. template was one whole env reference that missed."""
  159. def __new__(cls, text: str = "", template: Optional[str] = None, missed: bool = False, unset_ref: bool = False):
  160. rendered = super().__new__(cls, text)
  161. rendered.template = text if template is None else template
  162. rendered.missed = missed
  163. rendered.unset_ref = unset_ref
  164. return rendered
  165. def _build_safe_env(user_env: Optional[dict]) -> dict:
  166. """Filtered env for stdio subprocesses so API keys/tokens don't leak: the safe baseline
  167. keys, ``XDG_*``, vars injected by an external secret source (users configured that backend
  168. precisely so subprocesses can consume them), plus the server config's own ``env``."""
  169. from agent.secret_scope import get_secret
  170. from hermes_cli.env_loader import secret_source_names
  171. env = {
  172. key: value for key, value in os.environ.items()
  173. if key in _SAFE_ENV_KEYS or key.upper() in _SAFE_ENV_KEYS_CASE_INSENSITIVE or key.startswith("XDG_")}
  174. # Source-tagged names are process-wide (any profile's hydration tags them) while os.environ
  175. # holds only the LAUNCH profile's values, so the value must come from the active profile's
  176. # secret scope; a profile that lacks the name gets nothing, never another profile's token.
  177. for key in secret_source_names():
  178. value = get_secret(key)
  179. if value is not None:
  180. env[key] = value
  181. for key in ("HERMES_KANBAN_DB", "HERMES_KANBAN_BOARD"):
  182. if key in os.environ:
  183. env[key] = os.environ[key]
  184. # Pin the ACTIVE (served) profile's home so a stdio child never falls back to the
  185. # platform-default home (issue #18594). Without it a child spawned by a multiplexed host
  186. # or a dashboard/desktop backend serving ``--open-profile`` resolves HERMES_HOME to the
  187. # LAUNCH profile's home (or the platform default) and writes to the wrong profile — and a
  188. # Python child that imports hermes_constants trips the ``_warn_profile_fallback_once``
  189. # guard. Resolve at call time: ``get_hermes_home()`` honours the served-profile
  190. # contextvar, which does not cross the process boundary, while ``os.environ`` holds only
  191. # the launch profile's home. An explicit server ``env.HERMES_HOME`` still wins below.
  192. from hermes_constants import get_hermes_home
  193. env["HERMES_HOME"] = str(get_hermes_home())
  194. if user_env:
  195. # An entry rendered from one whole ``${VAR}`` that is unset (or empty) counts as absent, so
  196. # a plugin can forward an optional var without the child seeing the literal placeholder.
  197. # The key keeps its baseline value, if any: the MCP SDK re-adds its own inherited set
  198. # (PATH, HOME, TERM, ...) at spawn anyway, so popping here would not unset it.
  199. for key, value in user_env.items():
  200. if not getattr(value, "unset_ref", False):
  201. env[key] = value
  202. from agent.delegation_context import delegated_child_subprocess_env
  203. return delegated_child_subprocess_env(env)
  204. def _which_with_config_pathext(command: str, path_arg, env: dict):
  205. """Resolve *command* under the config env's PATHEXT (Windows only; ``shutil.which`` uses the PARENT's).
  206. The extension walk mirrors ``which`` itself (existing-suffix short-circuit, configured
  207. extensions in order) but reads nothing from and writes nothing to ``os.environ``: swapping
  208. the parent's PATHEXT around a ``which`` call would publish this server's per-profile value
  209. to every other thread for the duration, and a ``finally``-restore cannot undo that window."""
  210. cfg_pathext = next((v for k, v in env.items() if k.upper() == "PATHEXT" and isinstance(v, str) and v.strip()), None)
  211. if not cfg_pathext or cfg_pathext == os.environ.get("PATHEXT"):
  212. return None
  213. # PATHEXT is Windows-defined: ";"-separated even when resolved off-Windows
  214. exts = [ext for ext in cfg_pathext.split(";") if ext]
  215. candidates = [command + ext for ext in exts]
  216. if not candidates or any(command.lower().endswith(ext.lower()) for ext in exts):
  217. candidates = [command]
  218. directories = str(path_arg or "").split(os.pathsep)
  219. if sys.platform == "win32" and os.curdir not in directories:
  220. directories.insert(0, os.curdir) # Windows resolves from the cwd first
  221. for raw in directories:
  222. directory = raw or os.curdir # POSIX: an empty PATH component means the cwd
  223. if not os.path.isdir(directory):
  224. continue
  225. for candidate in candidates:
  226. resolved = os.path.join(directory, candidate)
  227. if os.path.isfile(resolved) and os.access(resolved, os.F_OK | os.X_OK):
  228. return resolved
  229. return None
  230. # Bare MCP launchers Hermes ships through PM, keyed to the package that provides them.
  231. _MANAGED_LAUNCHERS = {"npx": "npm", "npm": "npm", "node": "npm", "uv": "uv", "uvx": "uv"}
  232. def _managed_launcher(command: str) -> Optional[tuple[str, list[str]]]:
  233. """PM's executable for a bare launcher name and the toolchain dirs its children need first on
  234. PATH (npx's ``env node``, uvx's sibling uv). Never the user's copy: a missing managed tool is
  235. provisioned through PM, which raises naming the remedy when it may not. None only when PM
  236. ships no build for this platform (Termux), where the platform's own copy IS the toolchain."""
  237. import pm
  238. package = _MANAGED_LAUNCHERS[command]
  239. if pm.get_package(package).missing_reason(pm.current_target()) is not None:
  240. return None
  241. pm.ensure(package)
  242. if package == "uv":
  243. launcher = pm.uv_launcher(command)
  244. dirs = [str(launcher.parent)] if launcher is not None else []
  245. else:
  246. from hermes_constants import with_hermes_node_path
  247. dirs = [d for d in with_hermes_node_path({"PATH": ""})["PATH"].split(os.pathsep) if d]
  248. executable = shutil.which(command, path=os.pathsep.join(dirs)) if dirs else None
  249. if executable is None:
  250. raise RuntimeError(f"Hermes-managed {command} is not installed; run `hermes pm install {package}`")
  251. return executable, dirs
  252. def _outside_package(launcher: str, managed: str, dirs: list[str]) -> tuple[str, list[str]]:
  253. """Hermes's npm/node *launcher* and toolchain *dirs*, swapped for PM's copies outside a
  254. sealed Windows payload (``pm.user_facing.copies``). npm starts each package bin through
  255. cmd.exe, and cmd.exe cannot start the packaged ``node.exe``."""
  256. from pm.user_facing import copies
  257. moved = copies(dirs)
  258. if moved == dirs:
  259. return managed, dirs
  260. # Plain which(): Hermes's own copy dirs hold one real node.exe/npx.cmd, so the parent's
  261. # PATHEXT is the right question (unlike a user server's config env, see _which_with_config_pathext).
  262. return shutil.which(launcher, path=os.pathsep.join(moved)) or managed, moved
  263. def _is_hermes_managed_bin_dir(directory: str) -> bool:
  264. """True for the bin dirs Hermes' bootstrap prepends to this process's PATH: anything
  265. under the active hermes home (the sealed payload's venv, ``<home>/bin``, PM store
  266. runtimes) plus the running interpreter's own bin dir (a repo checkout's venv)."""
  267. try:
  268. resolved = Path(directory).resolve()
  269. except OSError:
  270. return False
  271. if resolved == Path(sys.executable).resolve().parent:
  272. return True
  273. from hermes_constants import get_hermes_home
  274. try:
  275. home = Path(get_hermes_home()).resolve()
  276. except Exception:
  277. return False
  278. return resolved == home / "bin" or home in resolved.parents
  279. _WINDOWS_DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC"
  280. def _pathext_suffixes(env: Optional[dict] = None, *, windows: Optional[bool] = None) -> list:
  281. """Executable suffixes a bare name resolves through, in order. The child env's PATHEXT
  282. comes first (``shutil.which`` reads the PARENT's, so a per-profile config value never
  283. reaches a plain ``which`` — same source as ``_which_with_config_pathext``), then the
  284. parent's, then the OS default. POSIX appends nothing. ``windows`` injectable for the
  285. same testability reason as ``_npx_bin_candidates``."""
  286. is_windows = os.name == "nt" if windows is None else windows
  287. if not is_windows:
  288. return [""]
  289. for source in (env or {}, os.environ):
  290. value = next((v for k, v in source.items()
  291. if k.upper() == "PATHEXT" and isinstance(v, str) and v.strip()), None)
  292. if value:
  293. exts = [ext for ext in value.split(";") if ext]
  294. if exts:
  295. return exts
  296. return [ext for ext in _WINDOWS_DEFAULT_PATHEXT.split(";") if ext]
  297. def _first_user_which_hit(command: str, path_arg: Optional[str],
  298. env: Optional[dict] = None, *, windows: Optional[bool] = None) -> Optional[str]:
  299. """First PATH hit for *command* OUTSIDE Hermes-managed bin dirs, or ``None``.
  300. ``shutil.which`` stops at the first hit, and bootstrap prepends the managed runtime's
  301. bin dir, so a bare ``python3`` resolves to the bundled interpreter — which lacks the
  302. user's packages and kills the server on import (#125300). Candidates run through
  303. ``_pathext_suffixes`` rather than the npx cache layout's ``.cmd``/``.exe`` pair: a user
  304. install may only ship a ``.bat``/``.py`` wrapper, and missing it here would silently
  305. fall back to the managed hit this exists to step past."""
  306. exts = _pathext_suffixes(env, windows=windows)
  307. if any(ext and command.lower().endswith(ext.lower()) for ext in exts):
  308. names = [command]
  309. else:
  310. names = [command + ext for ext in exts]
  311. for directory in str(path_arg or "").split(os.pathsep):
  312. if not directory or _is_hermes_managed_bin_dir(directory):
  313. continue
  314. for name in names:
  315. candidate = os.path.join(directory, name)
  316. if os.path.isfile(candidate) and os.access(candidate, os.F_OK | os.X_OK):
  317. return candidate
  318. return None
  319. def _resolve_stdio_command(command: str, env: dict) -> tuple[str, dict]:
  320. """Resolve a stdio command against the exact subprocess env (bare launchers under a filtered PATH).
  321. Bare ``npx``/``npm``/``node``/``uv``/``uvx`` resolve to Hermes's PM-managed copies with their
  322. toolchain dirs first on the child PATH, never the user's (an absolute ``command:`` stays the
  323. user's choice). Anything else resolves on the child env's PATH only: ``shutil.which`` with
  324. ``path=None`` silently falls back to the PARENT's ``os.environ["PATH"]``, letting a command
  325. "resolve" against an env the child will never be spawned with. An absent child PATH is a
  326. miss; an explicitly empty one keeps its cwd-only meaning (same distinction the child's
  327. ``execvp`` will see); a miss stays as-written for an honest spawn failure."""
  328. resolved_command = os.path.expanduser(str(command).strip())
  329. resolved_env = dict(env or {})
  330. launcher = re.sub(r"\.(cmd|exe)$", "", resolved_command, flags=re.IGNORECASE) # Windows spellings
  331. managed = _managed_launcher(launcher) if launcher in _MANAGED_LAUNCHERS else None
  332. if managed is not None:
  333. resolved_command, dirs = managed
  334. if _MANAGED_LAUNCHERS[launcher] == "npm":
  335. resolved_command, dirs = _outside_package(launcher, resolved_command, dirs)
  336. # Moved to the front even when already on PATH behind a user's copy.
  337. keys = {os.path.normcase(d) for d in dirs}
  338. rest = [p for p in resolved_env.get("PATH", "").split(os.pathsep) if p and os.path.normcase(p) not in keys]
  339. resolved_env["PATH"] = os.pathsep.join([*dirs, *rest])
  340. return resolved_command, resolved_env
  341. if os.sep not in resolved_command:
  342. path_arg = resolved_env.get("PATH")
  343. which_hit = shutil.which(resolved_command, path=path_arg) if path_arg is not None else None
  344. if which_hit is None and sys.platform == "win32" and resolved_env:
  345. which_hit = _which_with_config_pathext(resolved_command, path_arg, resolved_env)
  346. # A bare command keeps the USER's PATH semantics: bootstrap prepends the managed
  347. # runtime's bin dir to this process's PATH, so the first hit for a bare ``python3``
  348. # is Hermes' bundled interpreter, which lacks the user's packages and dies on import
  349. # (#125300). Step past managed dirs to the user's own hit; the explicit launcher
  350. # family keeps the managed-first resolution (that is the point of
  351. # ``_launcher_fallback``), and a managed-only PATH keeps the managed hit.
  352. if which_hit and resolved_command not in {"npx", "npm", "node", "uv", "uvx"}:
  353. which_hit = _first_user_which_hit(resolved_command, path_arg, resolved_env) or which_hit
  354. if which_hit:
  355. resolved_command = which_hit
  356. command_dir = os.path.dirname(resolved_command)
  357. if command_dir:
  358. resolved_env = _prepend_path(resolved_env, command_dir)
  359. return resolved_command, resolved_env
  360. def _npx_bin_candidates(bin_dir: str, name: str, *, windows: Optional[bool] = None) -> list:
  361. """Launcher paths to try for *name* inside an npx cache's ``.bin``, in order. On Windows that
  362. directory holds the extensionless sh script plus ``<name>.cmd``/``<name>.ps1``; the sh one
  363. cannot be spawned there and ``os.access(X_OK)`` is only an existence check, so select by
  364. extension (same precedence as ``hermes_constants._candidate_node_command_names``). ``windows``
  365. is injectable so the branch is testable without patching ``os.name`` process-wide."""
  366. is_windows = os.name == "nt" if windows is None else windows
  367. if is_windows:
  368. return [os.path.join(bin_dir, name + ext) for ext in (".cmd", ".exe")]
  369. return [os.path.join(bin_dir, name)]
  370. def _npx_cached_bin(args: list) -> Optional[tuple]:
  371. """Resolve ``npx -y <pkg>`` to the already-installed binary, or None.
  372. ``npx`` resolves the package and then FORKS, staying resident as the real server's parent
  373. for nothing (~48 MB private memory per MCP server, measured); Hermes already supervises the
  374. child (shared death supervisor). When the package is in npx's cache we spawn its binary
  375. directly. Deliberately conservative — None (caller keeps plain ``npx``, so a cold machine
  376. still installs) for a cache miss, a version pin (``pkg@1.2.3``), extra npx flags, a manifest
  377. without one obvious bin, or any unreadable cache entry. Returns ``(binary_path, remaining_args)``."""
  378. if not isinstance(args, list) or not args:
  379. return None
  380. rest = list(args)
  381. while rest and rest[0] in ("-y", "--yes"):
  382. rest.pop(0)
  383. if not rest:
  384. return None
  385. # `npx pkg -y` (flag AFTER the spec) would hand the server a flag npx would have eaten.
  386. if any(str(a) in ("-y", "--yes") for a in rest[1:]):
  387. return None
  388. spec = str(rest[0])
  389. # Scoped names keep their leading '@', so only an '@' AFTER the scope is a version separator.
  390. if "@" in (spec.removeprefix("@")):
  391. return None
  392. if not spec or spec.startswith("-"):
  393. return None
  394. cache_root = os.environ.get("npm_config_cache") or os.path.join(os.path.expanduser("~"), ".npm")
  395. npx_root = os.path.join(cache_root, "_npx")
  396. if not os.path.isdir(npx_root):
  397. return None
  398. try:
  399. entries = os.listdir(npx_root)
  400. except OSError:
  401. return None
  402. for entry in entries:
  403. manifest = os.path.join(npx_root, entry, "package.json")
  404. try:
  405. with open(manifest, "r", encoding="utf-8-sig") as fh:
  406. deps = (json.load(fh) or {}).get("dependencies") or {}
  407. except (OSError, ValueError, TypeError):
  408. continue
  409. if spec not in deps:
  410. continue
  411. pkg_json = os.path.join(npx_root, entry, "node_modules", spec, "package.json")
  412. try:
  413. with open(pkg_json, "r", encoding="utf-8-sig") as fh:
  414. bin_field = (json.load(fh) or {}).get("bin")
  415. except (OSError, ValueError, TypeError):
  416. continue
  417. if isinstance(bin_field, str):
  418. names = [os.path.basename(spec)]
  419. elif isinstance(bin_field, dict) and len(bin_field) == 1:
  420. names = list(bin_field.keys())
  421. else:
  422. continue # zero or several bins: which one npx would pick is not ours to guess
  423. bin_dir = os.path.join(npx_root, entry, "node_modules", ".bin")
  424. for candidate in _npx_bin_candidates(bin_dir, names[0]):
  425. if os.path.exists(candidate) and os.access(candidate, os.X_OK):
  426. return candidate, rest[1:]
  427. return None
  428. def _packaged_npx_entry(command: str, args: list) -> Optional[tuple]:
  429. """``(node.exe, [bin script, *args])`` for ``npx [-y] <pkg> ...`` when *command* is a sealed
  430. Windows payload's own npx, else None.
  431. That npx starts the package bin through cmd.exe, and cmd.exe cannot start the packaged
  432. ``node.exe`` (``pm.user_facing``). Hermes gets here only without a host Node and without
  433. a copy that PM may make. The payload's Python CAN start the packaged ``node.exe``, so the
  434. package is installed with npm's own script and the bin's script runs on that node.
  435. Install scripts stay off, because npm runs them through cmd.exe too. None keeps plain
  436. npx (an honest failure) for any other argv shape, a non-registry spec (git, URL, path:
  437. npm installs those under a name the spec does not show), a failed install, or an
  438. unclear bin.
  439. Like npx, only an exact version is reused as installed. Any other spec re-resolves on
  440. each start and keeps the previous install when npm cannot run (offline).
  441. """
  442. from pm.user_facing import _sealed_dirs, applies
  443. if not applies() or not isinstance(args, list):
  444. return None
  445. npm_dirs = {os.path.normcase(d): d for d in _sealed_dirs("npm")}
  446. npm_dir = npm_dirs.get(os.path.normcase(os.path.dirname(str(command))))
  447. node = shutil.which("node", path=os.pathsep.join(_sealed_dirs("node")))
  448. npm_cli = os.path.join(npm_dir or "", "node_modules", "npm", "bin", "npm-cli.js")
  449. if npm_dir is None or node is None or not os.path.isfile(npm_cli):
  450. return None
  451. rest = list(args)
  452. while rest and rest[0] in ("-y", "--yes"):
  453. rest.pop(0)
  454. spec = str(rest[0]) if rest else ""
  455. if not spec or spec.startswith("-") or any(str(a) in ("-y", "--yes") for a in rest[1:]):
  456. return None
  457. if ":" in spec or spec.startswith((".", "/", "\\", "~")) or ("/" in spec and not spec.startswith("@")):
  458. return None
  459. scope, _, bare = spec.rpartition("/") if spec.startswith("@") else ("", "", spec)
  460. base, _, version = bare.partition("@")
  461. name = (f"{scope}/" if scope else "") + base
  462. from hermes_constants import get_hermes_home
  463. prefix = Path(get_hermes_home()) / "cache" / "mcp-npx" / hashlib.sha256(spec.encode()).hexdigest()[:16]
  464. manifest = prefix / "node_modules" / name / "package.json"
  465. exact = re.fullmatch(r"\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]+)?", version) is not None
  466. if not (exact and manifest.is_file()):
  467. install = [node, npm_cli, "install", "--prefix", str(prefix), "--no-save", "--ignore-scripts",
  468. "--no-audit", "--no-fund", "--loglevel=error", spec]
  469. try:
  470. result = subprocess.run(install, capture_output=True, text=True, encoding="utf-8", errors="replace",
  471. stdin=subprocess.DEVNULL, timeout=600, check=False)
  472. except (subprocess.SubprocessError, OSError) as exc: # hang, unwritable prefix, AV lock, node not startable
  473. result = subprocess.CompletedProcess(install, 1, "", str(exc))
  474. if result.returncode != 0 or not manifest.is_file():
  475. logger.warning("npm install of %s with the packaged node failed: %s", spec,
  476. (result.stderr or result.stdout).strip()[-500:])
  477. if not manifest.is_file():
  478. return None
  479. try:
  480. bin_field = (json.loads(manifest.read_text(encoding="utf-8-sig")) or {}).get("bin")
  481. except (OSError, ValueError):
  482. return None
  483. if isinstance(bin_field, dict):
  484. bin_field = bin_field.get(base) or (
  485. next(iter(bin_field.values())) if len(bin_field) == 1 else None)
  486. if not isinstance(bin_field, str):
  487. return None
  488. return node, [str(manifest.parent / bin_field), *rest[1:]]
  489. def _interpolate_env_vars(value):
  490. """Recursively resolve ``${VAR}`` / Cursor ``${env:VAR}`` placeholders and context vars. Env
  491. refs resolve from the active profile's secret scope when multiplexing (the routed profile's
  492. value, not another profile's in ``os.environ``). Unset (or empty) vars keep the literal placeholder;
  493. a templated string comes back as a ``_RenderedStr`` recording how it resolved."""
  494. from agent.secret_scope import get_secret as _get_secret
  495. if isinstance(value, str):
  496. if isinstance(value, _RenderedStr) and not value.missed:
  497. return value
  498. template = getattr(value, "template", value)
  499. missed = []
  500. def _replace(m):
  501. resolver = _CONTEXT_VAR_RESOLVERS.get(m.group(1).strip())
  502. if resolver is not None:
  503. return resolver()
  504. resolved = _get_secret(_env_ref_name(m.group(1)), None)
  505. if not resolved:
  506. missed.append(m.group(0))
  507. return resolved or m.group(0)
  508. if not _ENV_VAR_PATTERN.search(template):
  509. return value
  510. text = _ENV_VAR_PATTERN.sub(_replace, template)
  511. return _RenderedStr(text, template, missed=bool(missed), unset_ref=missed == [template])
  512. if isinstance(value, dict):
  513. return {k: _interpolate_env_vars(v) for k, v in value.items()}
  514. if isinstance(value, list):
  515. return [_interpolate_env_vars(v) for v in value]
  516. return value
  517. def _require_rendered_remote(server_name: str, config: dict) -> dict:
  518. """*config* back, unless it is a remote server whose ``url`` / ``headers`` still carry a literal
  519. ``${VAR}`` after rendering: sending that is a guaranteed 401 that reads as a bad credential
  520. (#119092), so fail closed naming the variable instead."""
  521. if "url" not in config:
  522. return config
  523. values = [config.get("url") or "", *(config.get("headers") or {}).values()]
  524. unresolved = sorted({m.group(1) for value in values for m in _ENV_VAR_PATTERN.finditer(str(value))})
  525. if unresolved:
  526. refs = ", ".join(f"${{{ref}}}" for ref in unresolved)
  527. unset = ValueError(f"MCP server '{server_name}': {refs} in url/headers is not set in this profile's "
  528. ".env or secret source")
  529. unset.failure_class = "missing_credentials" # type: ignore[attr-defined]
  530. raise unset
  531. return config
  532. # (server_name, dotted key path) pairs already warned about: config loads repeat per discovery pass.
  533. _whitespace_warned: set[tuple[str, str]] = set()
  534. def _warn_hidden_whitespace(server_name: str, config: dict) -> list[str]:
  535. """Warn once per (server, key path) about string values with leading/trailing whitespace (a
  536. pasted newline causes opaque auth failures). Advisory only: values are never mutated (could be
  537. intentional) nor logged (often secrets). Returns flagged paths."""
  538. flagged: list[str] = []
  539. def _walk(value: Any, path: str) -> None:
  540. if isinstance(value, str) and value != value.strip():
  541. flagged.append(path)
  542. elif isinstance(value, dict):
  543. for k, v in value.items():
  544. _walk(v, f"{path}.{k}" if path else str(k))
  545. elif isinstance(value, list):
  546. for i, v in enumerate(value):
  547. _walk(v, f"{path}[{i}]")
  548. _walk(config, "")
  549. for key_path in flagged:
  550. if (server_name, key_path) not in _whitespace_warned:
  551. _whitespace_warned.add((server_name, key_path))
  552. logger.warning(
  553. "MCP server '%s': config value '%s' has hidden leading or trailing whitespace — this often "
  554. "causes authentication or connection failures. Check for stray spaces/newlines in config.yaml "
  555. "(or the referenced env var).", server_name, key_path)
  556. return flagged
  557. def _malformed_cost_table(name: str, cfg: Any) -> Optional[str]:
  558. """Why a server's ``tool_costs``/``spend_limit``/``cost_unit`` is unusable, else None. A budget the
  559. user declared must never be silently dropped while its server keeps spending, so the server is skipped."""
  560. from tools.mcp_tool_costs import config_cost_policy
  561. try:
  562. config_cost_policy(name, cfg if isinstance(cfg, dict) else None)
  563. except ValueError as exc:
  564. return str(exc)
  565. return None
  566. def _filter_suspicious_mcp_servers(servers: dict[str, dict]) -> dict[str, dict]:
  567. """Drop exfiltration-shaped MCP configs, and servers with a malformed cost table, before any stdio spawn path."""
  568. try:
  569. from hermes_cli.mcp_security import validate_mcp_server_entry
  570. except Exception:
  571. validate_mcp_server_entry = None
  572. safe_servers = {}
  573. for name, cfg in servers.items():
  574. issues = validate_mcp_server_entry(name, cfg) if validate_mcp_server_entry and isinstance(cfg, dict) else None
  575. if issues:
  576. logger.warning("Skipping suspicious MCP server '%s': %s", name, "; ".join(issues))
  577. elif (bad_costs := _malformed_cost_table(name, cfg)) is not None:
  578. logger.error("Skipping MCP server '%s': %s (fix tool_costs/spend_limit/cost_unit in config.yaml)",
  579. name, bad_costs)
  580. else:
  581. safe_servers[name] = cfg
  582. return safe_servers
  583. def _portable_mcp_servers(safe_servers: dict[str, dict], rejected: frozenset[str] = frozenset()) -> None:
  584. """Merge plugin-provided (portable) MCP servers into *safe_servers*; native config wins on a clash. Never raises.
  585. The package's declared costs are facts about its server, so a same-name native entry (the way a user widens
  586. a package server's trust) keeps them unless it sets the cost key itself; ``spend_limit: 0`` turns the limit off."""
  587. from agent.secret_scope import UnscopedSecretError
  588. from tools.mcp_tool_costs import CONFIG_KEYS
  589. try:
  590. from hermes_cli.plugins import discover_plugins, get_plugin_manager
  591. discover_plugins()
  592. portable = get_plugin_manager().get_portable_mcp_servers()
  593. for name, cfg in _filter_suspicious_mcp_servers(portable).items():
  594. if name in rejected: # the user's own entry for this name has a malformed budget: stay off
  595. logger.warning("Portable MCP server '%s' skipped: the native entry of that name was rejected", name)
  596. elif name in safe_servers:
  597. native = safe_servers[name]
  598. carried = {k: cfg[k] for k in CONFIG_KEYS if k in cfg and k not in native}
  599. if carried:
  600. safe_servers[name] = {**native, **carried}
  601. logger.warning("Portable MCP server '%s' conflicts with native config; using the native entry "
  602. "with the package's declared %s", name, ", ".join(carried))
  603. else:
  604. logger.warning("Portable MCP server '%s' conflicts with native config; skipping", name)
  605. else:
  606. # Rendered like native entries: a raw ``${VAR}`` here reads as a changed definition
  607. # on every transport rebuild and swaps the running header for the literal placeholder.
  608. try:
  609. safe_servers[name] = _interpolate_env_vars(dict(cfg))
  610. except UnscopedSecretError:
  611. # Unscoped multiplex load: keep the raw templates (as before rendering here) rather
  612. # than end the merge; connect re-renders under the owner's scope and fails closed.
  613. logger.debug("Portable MCP server '%s' left unrendered: no secret scope bound", name)
  614. safe_servers[name] = dict(cfg)
  615. except Exception:
  616. logger.debug("Failed to load portable MCP servers", exc_info=True)
  617. def _load_mcp_config() -> dict[str, dict]:
  618. """``mcp_servers`` from config.yaml as ``{name: config}`` (empty on error / safe mode), ``${VAR}`` interpolated."""
  619. from agent.safe_worker_policy import safe_worker_enabled
  620. if safe_worker_enabled():
  621. return {}
  622. try:
  623. from hermes_cli.config import load_config
  624. from utils import env_var_enabled as _env_enabled
  625. if _env_enabled("HERMES_SAFE_MODE"):
  626. return {}
  627. servers = load_config().get("mcp_servers")
  628. try: # ensure .env vars are available for interpolation
  629. from hermes_cli.env_loader import load_hermes_dotenv
  630. load_hermes_dotenv()
  631. except Exception:
  632. pass
  633. safe_servers: dict[str, dict] = {}
  634. servers = servers if isinstance(servers, dict) else {}
  635. kept = _filter_suspicious_mcp_servers(servers)
  636. for name, cfg in kept.items():
  637. interpolated = _interpolate_env_vars(cfg)
  638. if isinstance(interpolated, dict):
  639. _warn_hidden_whitespace(name, interpolated)
  640. safe_servers[name] = interpolated
  641. # A same-name package must not revive a server whose native budget was rejected (a mistyped
  642. # tighter limit would fall back to the package's looser one while the server keeps spending).
  643. rejected = frozenset(n for n in servers if n not in kept and _malformed_cost_table(n, servers[n]) is not None)
  644. _portable_mcp_servers(safe_servers, rejected)
  645. return safe_servers
  646. except Exception as exc:
  647. logger.debug("Failed to load MCP config: %s", exc)
  648. return {}