mcp_tool_registration.py 36 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654
  1. """Registering a connected (or schema-cached) MCP server's tools into the tool registry:
  2. include/exclude filtering, trust-tier metadata capture, utility-tool selection, name-collision
  3. resolution and the schema-cache write-through. Both entry points (``_register_server_tools``
  4. live, ``_register_from_cache_sync`` lazy) build ``_Candidate`` records for ``_register_candidates``."""
  5. import hashlib
  6. import json
  7. import logging
  8. import threading
  9. from dataclasses import dataclass
  10. from types import SimpleNamespace
  11. from typing import TYPE_CHECKING, Any, Callable, Dict, Iterable, List, Optional
  12. from tools.mcp_tool_common import _parse_boolish, _core, _resolve_tool_timeout, mcp_field, mcp_server_enabled
  13. from tools import mcp_tool_config as _config
  14. from tools import mcp_tool_events as _events
  15. from tools import mcp_tool_handlers as _handlers
  16. from tools import mcp_tool_schema as _schema
  17. from tools.mcp_tool_handlers import (
  18. _make_check_fn, _make_get_prompt_handler, _make_list_prompts_handler,
  19. _make_list_resources_handler, _make_read_resource_handler)
  20. from tools.mcp_tool_schema import (
  21. _UTILITY_CAPABILITY_ATTRS, _build_utility_schemas, _normalize_name_filter, matches_name_filter)
  22. from tools.mcp_tool_scope import _key_name, _key_scope, _resolve_server_key, _server_key
  23. if TYPE_CHECKING: # pragma: no cover
  24. from tools.mcp_tool import MCPServerTask
  25. logger = logging.getLogger("tools.mcp_tool")
  26. _SCOPE_REFRESH_LOCKS = tuple(threading.RLock() for _ in range(16))
  27. _UTILITY_ORIGIN_PREFIX = "generated utility "
  28. # Utility tool key -> handler factory; each takes (server_name, tool_timeout).
  29. _UTILITY_HANDLER_FACTORIES = {
  30. "list_resources": _make_list_resources_handler, "read_resource": _make_read_resource_handler,
  31. "list_prompts": _make_list_prompts_handler, "get_prompt": _make_get_prompt_handler,
  32. "list_event_types": _events._make_list_event_types_handler, "subscribe_event": _events._make_subscribe_event_handler,
  33. "unsubscribe_event": _events._make_unsubscribe_event_handler}
  34. def _normalize_server_trust(value: Any) -> str:
  35. """Config ``trust`` -> tier. None -> ``full`` (compat default); unrecognized -> ``untrusted`` (fail closed)."""
  36. if value is None:
  37. return _core._TRUST_FULL
  38. text = str(value).strip().lower()
  39. if text in (_core._TRUST_FULL, _core._TRUST_UNTRUSTED):
  40. return text
  41. logger.warning("MCP trust: unrecognized trust value %r — treating as 'untrusted' (valid values: full, untrusted)",
  42. value)
  43. return _core._TRUST_UNTRUSTED
  44. def _annotation_read_only_hint(mcp_tool: Any) -> bool:
  45. """True only when annotations (SDK object or cache dict) carry an exact ``True`` read-only hint;
  46. unknown = write-capable. mcp 2.x exposes the attribute as ``read_only_hint`` (camelCase is only a
  47. serialization alias), so reading camelCase alone gated every read on an untrusted server."""
  48. annotations = getattr(mcp_tool, "annotations", None)
  49. if isinstance(annotations, dict):
  50. hint = annotations.get("readOnlyHint", annotations.get("read_only_hint"))
  51. else:
  52. hint = mcp_field(annotations, "read_only_hint", "readOnlyHint")
  53. return hint is True
  54. def _record_cost_policy(server_name: str, config: dict, key) -> None:
  55. """Declared ``tool_costs``/``spend_limit`` for *key*. Load-time validation already dropped malformed
  56. entries (``_filter_suspicious_mcp_servers``); a direct caller's bad table still fails loudly. Caller holds
  57. ``_core._lock``."""
  58. from tools.mcp_tool_costs import config_cost_policy
  59. policy = config_cost_policy(server_name, config)
  60. if policy is None:
  61. _core._server_cost_policies.pop(key, None)
  62. else:
  63. _core._server_cost_policies[key] = policy
  64. def _record_tool_trust_metadata(server_name: str, config: dict, tools: list[Any], key=None) -> None:
  65. """Capture per-server trust and per-tool readOnlyHint at discovery — the security boundary: the call-time gate
  66. classifies from data we control, never re-read server-supplied state. *key* is the connection (default: the
  67. registering profile's own); the ``trust`` policy is recorded under it for the profile that owns it — an
  68. adopting profile records its own policy in ``_record_scope_trust``."""
  69. with _core._lock:
  70. if key is None:
  71. key = _server_key(server_name)
  72. _core._server_trust_levels[key] = _normalize_server_trust((config or {}).get("trust"))
  73. _record_cost_policy(server_name, config, key)
  74. hints = _core._tool_read_only_hints.setdefault(key, {})
  75. hints.update({t.name: _annotation_read_only_hint(t) for t in tools if getattr(t, "name", None)})
  76. def _warn_unknown_cost_keys(server_name: str, key, tool_names: list[str]) -> None:
  77. """Live discovery only: the schema cache omits tools the user's include/exclude filter dropped, so a valid
  78. cost for a filtered tool would read as unknown there."""
  79. from tools.mcp_tool_costs import unknown_cost_keys
  80. if unknown := unknown_cost_keys(_core._server_cost_policies.get(key), tool_names):
  81. logger.warning("MCP server '%s': tool_costs names %s, which the server does not offer, so those calls "
  82. "carry no cost and no spend limit. Use the server's own tool names (without Hermes' "
  83. "'mcp_%s_' prefix).", server_name, unknown, server_name)
  84. def _record_scope_trust(server_name: str, config: dict, scope: str) -> None:
  85. """``trust`` (and the cost policy) is the CONSUMING profile's policy, never the connection's: an
  86. ``untrusted`` profile that adopts a ``full`` profile's live connection must still be asked before every
  87. write-capable call."""
  88. with _core._lock:
  89. key = _server_key(server_name, scope, current=False)
  90. _core._server_trust_levels[key] = _normalize_server_trust((config or {}).get("trust"))
  91. _record_cost_policy(server_name, config, key)
  92. def _track_mcp_tool_server(tool_name: str, server_name: str) -> None:
  93. """Remember the exact raw MCP server that registered *tool_name*."""
  94. with _core._lock:
  95. _core._mcp_tool_server_names[tool_name] = server_name
  96. def _forget_mcp_tool_server(tool_name: str) -> None:
  97. """Forget MCP server provenance for a deregistered tool."""
  98. with _core._lock:
  99. _core._mcp_tool_server_names.pop(tool_name, None)
  100. def _server_key_for_task(server) -> object:
  101. """Connection key of a live ``MCPServerTask`` (teardown runs on the MCP loop without the
  102. discovering profile's context, so the key is found by identity, never re-derived)."""
  103. with _core._lock:
  104. for key, live in _core._servers.items():
  105. if live is server:
  106. return key
  107. return _server_key(server.name)
  108. def _deregister_mcp_tool_all_scopes(server, tool_name: str) -> None:
  109. """Deregister one server tool from every profile overlay that owns it. *server* is the
  110. live task or a connection key."""
  111. from tools.registry import registry
  112. key = server if isinstance(server, (str, tuple)) else _server_key_for_task(server)
  113. with _core._lock:
  114. scopes = set(_core._server_tool_scopes.get(key, ()))
  115. if not scopes:
  116. scopes = {_core._server_registry_scope(key)}
  117. for scope in scopes:
  118. registry.deregister(tool_name, scope=scope)
  119. _forget_mcp_tool_server(tool_name)
  120. _restore_server_toolset_alias(key)
  121. def _restore_server_toolset_alias(key) -> None:
  122. """Keep the process-global alias while any profile still owns tools of a server with this
  123. name — including another profile's same-named connection (the alias is per NAME; the
  124. registry deregister dropped it after checking only one scope)."""
  125. from tools.registry import registry
  126. server_name = _key_name(key)
  127. with _core._lock:
  128. owned = [(server, set(_core._server_tool_scopes.get(k, ())))
  129. for k, server in _core._servers.items() if _key_name(k) == server_name]
  130. if any(
  131. registry.snapshot_registration(tool_name, scope=scope) is not None
  132. for server, scopes in owned for scope in scopes
  133. for tool_name in getattr(server, "_registered_tool_names", ())
  134. ):
  135. registry.register_toolset_alias(server_name, f"mcp-{server_name}")
  136. def _remove_server_scope(key, scope: str) -> None:
  137. """Remove one profile's MCP overlay for a shared live connection."""
  138. from tools.registry import registry
  139. server_name = _key_name(key)
  140. for tool_name in registry.get_tool_names_for_toolset(f"mcp-{server_name}"):
  141. registry.deregister(tool_name, scope=scope)
  142. with _core._lock:
  143. scopes = set(_core._server_tool_scopes.get(key, ()))
  144. scopes.discard(scope)
  145. if scopes:
  146. _core._server_tool_scopes[key] = scopes
  147. else:
  148. _core._server_tool_scopes.pop(key, None)
  149. _core._server_trust_levels.pop(_server_key(server_name, scope, current=False), None)
  150. _core._server_cost_policies.pop(_server_key(server_name, scope, current=False), None)
  151. _restore_server_toolset_alias(key)
  152. def _select_utility_schemas(server_name: str, server: "MCPServerTask", config: dict) -> list[dict]:
  153. """Utility schemas allowed by config (``tools.resources``/``tools.prompts``) and advertised
  154. capabilities. ``initialize_result.capabilities`` is the truth (sub-object non-None iff the
  155. family is served); without it fall back to the legacy session-method check, which never
  156. filters anything since ClientSession defines all four methods."""
  157. tools_filter = config.get("tools") or {}
  158. enabled = {f: _parse_boolish(tools_filter.get(f), default=True) for f in ("resources", "prompts")}
  159. advertised = getattr(getattr(server, "initialize_result", None), "capabilities", None)
  160. def _skip_reason(handler_key: str) -> Optional[str]:
  161. family = _UTILITY_CAPABILITY_ATTRS[handler_key]
  162. if family == "events": # opt-in: the SDK drops the server's ``events`` capability
  163. return None if _events.events_enabled(config) else "events not enabled"
  164. if not enabled[family]:
  165. return f"{family} disabled"
  166. if advertised is not None:
  167. if getattr(advertised, family, None) is None:
  168. return f"server does not advertise '{family}' capability"
  169. return None
  170. # Legacy gate (no initialize_result): the ClientSession method shares the handler key.
  171. return None if hasattr(server.session, handler_key) else f"session lacks {handler_key}"
  172. selected: list[dict] = []
  173. for entry in _build_utility_schemas(server_name):
  174. reason = _skip_reason(entry["handler_key"])
  175. if reason:
  176. logger.debug("MCP server '%s': skipping utility '%s' (%s)", server_name, entry["handler_key"], reason)
  177. else:
  178. selected.append(entry)
  179. return selected
  180. def _existing_tool_names() -> list[str]:
  181. """Tool names for all connected servers plus lazy (cache-registered) servers, whose tools live only in the registry."""
  182. scope = _core._mcp_registry_scope()
  183. if scope is not None:
  184. from tools.registry import registry
  185. with _core._lock:
  186. server_names = [
  187. _key_name(key) for key in _core._servers
  188. if _core._server_visible_in_scope(key, scope)
  189. ]
  190. server_names.extend(
  191. _key_name(key) for key in _core._lazy_server_tool_names
  192. if key not in _core._servers and _core._server_visible_in_scope(key, scope)
  193. )
  194. return sorted({
  195. tool_name
  196. for server_name in server_names
  197. for tool_name in registry.get_tool_names_for_toolset(f"mcp-{server_name}")
  198. })
  199. names: list[str] = []
  200. for server in _core._servers.values():
  201. names.extend(server._registered_tool_names if hasattr(server, "_registered_tool_names")
  202. else (_schema._convert_mcp_schema(server.name, t)["name"] for t in server._tools))
  203. with _core._lock:
  204. names.extend(n for key, tool_names in _core._lazy_server_tool_names.items()
  205. if key not in _core._servers for n in tool_names)
  206. return names
  207. def _make_tool_filter(name: str, config: dict) -> Callable[[str], bool]:
  208. """Include/exclude predicate for a server's tool names: ``tools.include`` is a whitelist (``[]`` = register
  209. nothing), ``tools.exclude`` a blacklist; entries are exact names or fnmatch globs; include wins over exclude."""
  210. tools_filter = config.get("tools") or {}
  211. # Selective tool loading: honour include/exclude lists from config. Rules (matching issue #690 spec,
  212. # extended with glob support): tools.include — whitelist: only matching tool names are registered
  213. # tools.exclude — blacklist: all tools EXCEPT matching ones are registered entries may be exact names or
  214. # fnmatch globs (e.g. "*_radar_*") include takes precedence over exclude include: [] → register nothing
  215. # (an explicit empty whitelist, as written by the install checklist's "uncheck everything" path) Neither
  216. # set → register all tools (backward-compatible default)
  217. include_raw = tools_filter.get("include")
  218. include_set = _normalize_name_filter(include_raw, f"mcp_servers.{name}.tools.include")
  219. exclude_set = _normalize_name_filter(tools_filter.get("exclude"), f"mcp_servers.{name}.tools.exclude")
  220. if isinstance(include_raw, (str, list, tuple, set)):
  221. return lambda tool_name: matches_name_filter(tool_name, include_set)
  222. return lambda tool_name: not (exclude_set and matches_name_filter(tool_name, exclude_set))
  223. def _cached_tools(raws: Iterable[Any]) -> list[SimpleNamespace]:
  224. """Schema-cache rows -> stand-ins for MCP Tool objects; rows that are not dicts or lack a name
  225. are dropped. Missing or non-dict ``annotations`` (older cache files) fail closed to write-capable."""
  226. return [SimpleNamespace(name=raw["name"], description=raw.get("description") or "",
  227. inputSchema=raw["inputSchema"] if isinstance(raw.get("inputSchema"), dict) else {},
  228. annotations=raw["annotations"] if isinstance(raw.get("annotations"), dict) else None)
  229. for raw in raws if isinstance(raw, dict) and raw.get("name")]
  230. @dataclass
  231. class _Candidate:
  232. """One registration attempt (native tool or generated utility); ``origin`` is the provenance text in diagnostics."""
  233. registry_name: str
  234. origin: str
  235. schema: dict
  236. handler: Callable
  237. @property
  238. def is_utility(self) -> bool:
  239. return self.origin.startswith(_UTILITY_ORIGIN_PREFIX)
  240. def _tool_candidates(name: str, tools: Iterable[Any], should_register: Callable[[str], bool],
  241. tool_timeout) -> list[_Candidate]:
  242. """Native tools (live SDK objects or cache stand-ins) -> candidates. The injection scan runs on
  243. BOTH paths: the cache file is user-writable JSON."""
  244. out: list[_Candidate] = []
  245. for t in tools:
  246. if not should_register(t.name):
  247. logger.debug("MCP server '%s': skipping tool '%s' (filtered by config)", name, t.name)
  248. continue
  249. _schema._scan_mcp_description(name, t.name, t.description or "")
  250. schema = _schema._convert_mcp_schema(name, t)
  251. handler = _handlers._make_tool_handler(name, t.name, tool_timeout, native_images=True)
  252. out.append(_Candidate(schema["name"], f"tool {t.name!r}", schema, handler))
  253. return out
  254. def _utility_candidates(name: str, entries: Iterable[Any], tool_timeout) -> list[_Candidate]:
  255. """``{schema, handler_key}`` rows (live selection or cache) -> candidates; malformed rows dropped."""
  256. out: list[_Candidate] = []
  257. for raw in entries:
  258. schema, key = (raw.get("schema"), raw.get("handler_key")) if isinstance(raw, dict) else (None, None)
  259. if isinstance(schema, dict) and key in _UTILITY_HANDLER_FACTORIES and schema.get("name"):
  260. out.append(_Candidate(schema["name"], f"{_UTILITY_ORIGIN_PREFIX}{key!r}", schema,
  261. _UTILITY_HANDLER_FACTORIES[key](name, tool_timeout)))
  262. return out
  263. def _resolve_name_collisions(name: str, candidates: list[_Candidate]) -> list[_Candidate]:
  264. """Preflight name collisions: exact duplicates dropped silently; a utility normalizing onto
  265. a native tool's name is shadowed (native wins); any other multi-origin collision skips every
  266. colliding entry (fail closed). Returns survivors in order."""
  267. unique: list[_Candidate] = []
  268. origins_by_name: dict[str, set[str]] = {}
  269. for c in candidates:
  270. origins = origins_by_name.setdefault(c.registry_name, set())
  271. if c.origin in origins:
  272. logger.debug("MCP server '%s': duplicate registration candidate %s for '%s'; keeping one",
  273. name, c.origin, c.registry_name)
  274. continue
  275. origins.add(c.origin)
  276. unique.append(c)
  277. ambiguous: dict[str, list[str]] = {}
  278. shadowed: set[tuple[str, str]] = set()
  279. # A generated resource/prompt utility that normalizes onto a server-native tool's name must not knock
  280. # that native tool out of the registry: the native tool is the capability the user connected the server
  281. # for, while the generated utility (read_resource/list_resources/list_prompts/get_prompt) is optional
  282. # sugar that only matters when the server exposes no such tool of its own (#87112). Resolve that
  283. # specific collision in favour of the native tool — keep it, drop the shadowed utility — and fall back
  284. # to the conservative skip-everything only for genuinely ambiguous collisions (two or more native tools
  285. # normalizing to one name, which we cannot disambiguate). The four utility keys are distinct, so a
  286. # colliding set holds at most one utility origin.
  287. for registry_name, origins in origins_by_name.items():
  288. if len(origins) <= 1:
  289. continue
  290. utility_origins = sorted(o for o in origins if o.startswith(_UTILITY_ORIGIN_PREFIX))
  291. native_origins = sorted(origins - set(utility_origins))
  292. if len(native_origins) == 1 and utility_origins:
  293. shadowed.update((registry_name, o) for o in utility_origins)
  294. logger.info(
  295. "MCP server '%s': generated utility %s normalizes onto server-native %s — keeping the native tool "
  296. "and dropping the utility (the utility only applies when the server has no such tool of its own)",
  297. name, ", ".join(utility_origins), native_origins[0])
  298. else:
  299. ambiguous[registry_name] = sorted(origins)
  300. for registry_name, origins in sorted(ambiguous.items()):
  301. logger.error("MCP server '%s': name normalization collision for '%s' from %s; skipping every colliding "
  302. "entry instead of choosing an arbitrary handler", name, registry_name, ", ".join(origins))
  303. return [c for c in unique if c.registry_name not in ambiguous and (c.registry_name, c.origin) not in shadowed]
  304. def _register_candidates(name: str, candidates: list[_Candidate], *, check_fn: Callable,
  305. scope: Callable[[], Optional[str]], lazy: bool, key=None, execution_timeout=None) -> list[str]:
  306. """Register candidates under toolset ``mcp-{name}``; returns the names that landed. The
  307. ownership pre-check is advisory (servers connect in parallel): ``registry.register()`` is
  308. the atomic gate and its verdict is re-read after every call. *key* is the connection whose
  309. ``_server_tool_scopes`` records the registering scope (default: this scope's own)."""
  310. from tools.registry import registry
  311. toolset_name = f"mcp-{name}"
  312. registered: list[str] = []
  313. scope_value = scope()
  314. if key is None:
  315. key = _server_key(name, scope_value, current=False)
  316. for c in candidates:
  317. existing_toolset = registry.get_toolset_for_tool(c.registry_name)
  318. if existing_toolset and existing_toolset != toolset_name: # foreign owner: skip, preserve it
  319. if lazy:
  320. if not c.is_utility:
  321. logger.warning("MCP server '%s' (lazy): cached tool '%s' collides with toolset '%s' — skipping",
  322. name, c.registry_name, existing_toolset)
  323. elif existing_toolset.startswith("mcp-"):
  324. logger.error("MCP server '%s': %s normalizes to '%s', already owned by MCP toolset '%s' — skipping to "
  325. "preserve the existing owner", name, c.origin, c.registry_name, existing_toolset)
  326. else:
  327. logger.warning("MCP server '%s': %s (→ '%s') collides with built-in tool in toolset '%s' — skipping to "
  328. "preserve built-in", name, c.origin, c.registry_name, existing_toolset)
  329. continue
  330. registry.register(
  331. name=c.registry_name, toolset=toolset_name, schema=c.schema, handler=c.handler, check_fn=check_fn,
  332. is_async=False, description=c.schema.get("description") or "", scope=scope_value,
  333. execution_timeout=execution_timeout)
  334. if registry.get_toolset_for_tool(c.registry_name) == toolset_name:
  335. _track_mcp_tool_server(c.registry_name, name)
  336. if scope_value is not None:
  337. with _core._lock:
  338. _core._server_tool_scopes.setdefault(key, set()).add(scope_value)
  339. registered.append(c.registry_name)
  340. elif not lazy:
  341. logger.error("MCP server '%s': registration of %s as '%s' was rejected by the registry; "
  342. "skipping provenance/count updates", name, c.origin, c.registry_name)
  343. if registered:
  344. registry.register_toolset_alias(name, toolset_name)
  345. return registered
  346. def _write_schema_cache(name: str, server: "MCPServerTask", config: dict, should_register) -> None:
  347. """Write-through: persist the manifest so the next startup registers this server lazily (no spawn). Never raises."""
  348. try:
  349. # Write-through (#56832): refresh the on-disk schema cache after a live connect so the next startup
  350. # can lazily register this server without spawning it. Cache failures never break registration.
  351. from tools.mcp_schema_cache import config_fingerprint, write_cache_entry
  352. tools_payload = []
  353. for t in server._tools:
  354. if not should_register(t.name):
  355. continue
  356. # mcp 2.0 renamed every Tool model field to snake_case and left camelCase as a
  357. # *serialization* alias only, which pydantic does not apply to attribute access: a bare
  358. # camelCase getattr returns None on 2.x instead of raising. That silently wrote an empty
  359. # ``inputSchema`` into the schema cache on every write-through, so a ``lazy: true`` server
  360. # registered from cache with every parameter stripped. ``mcp_field`` reads both spellings.
  361. schema_obj = mcp_field(t, "input_schema", "inputSchema")
  362. tools_payload.append({
  363. "name": t.name, "description": t.description or "",
  364. "inputSchema": schema_obj if isinstance(schema_obj, dict) else {},
  365. "annotations": {"readOnlyHint": _annotation_read_only_hint(t)}, # lazy path trust-gates identically
  366. })
  367. utility_payload = [{"schema": e["schema"], "handler_key": e["handler_key"]}
  368. for e in _select_utility_schemas(name, server, config)]
  369. cache_meta = getattr(server, "_list_cache_meta", None) or {}
  370. write_cache_entry(name, config_fingerprint(config), tools=tools_payload, utility_tools=utility_payload,
  371. ttl_ms=cache_meta.get("ttl_ms"), cache_scope=cache_meta.get("cache_scope"))
  372. except Exception as exc:
  373. logger.debug("MCP schema cache write failed for '%s': %s", name, exc)
  374. def _register_server_tools(name: str, server: "MCPServerTask", config: dict) -> list[str]:
  375. """Register a connected server's tools plus utilities (initial discovery and list_changed
  376. refresh); returns the names. Toolset aliases derive from the live registry, not
  377. ``toolsets.TOOLSETS``; lossy normalization collisions (``read-file``/``read_file``) fail closed."""
  378. should_register = _make_tool_filter(name, config)
  379. key = _server_key_for_task(server)
  380. _record_tool_trust_metadata(name, config, server._tools, key)
  381. _warn_unknown_cost_keys(name, key, [t.name for t in server._tools if getattr(t, "name", None)])
  382. candidates = _tool_candidates(name, server._tools, should_register, server.tool_timeout)
  383. candidates += _utility_candidates(name, _select_utility_schemas(name, server, config), server.tool_timeout)
  384. # Judged by the connection's owner scope (the ``(scope, name)`` key the registration below
  385. # publishes into), never by the bare name resolved in the caller's context.
  386. if (_core._server_registry_scope(key) or '').startswith('editor-session:'):
  387. import json
  388. from hermes_state_runtime import RuntimeStoreError
  389. manifest = json.dumps({c.registry_name: c.schema for c in candidates}, sort_keys=True)
  390. frozen = getattr(server, '_editor_frozen_manifest', manifest)
  391. if manifest != frozen:
  392. raise RuntimeStoreError('acp_mcp_schema_changed')
  393. server._editor_frozen_manifest = frozen
  394. registered = _register_candidates(
  395. name, _resolve_name_collisions(name, candidates),
  396. check_fn=_make_check_fn(name), scope=lambda: _core._server_registry_scope(key), lazy=False, key=key,
  397. execution_timeout=config.get("timeout"))
  398. if registered and not (_core._server_registry_scope(key) or '').startswith('editor-session:'):
  399. _write_schema_cache(name, server, config, should_register)
  400. return registered
  401. def _connection_identity(config: dict) -> tuple:
  402. """What makes one live connection reusable for another profile: the route fingerprint PLUS
  403. everything that authenticates or secures it (``config_fingerprint`` deliberately excludes
  404. credentials so the schema cache survives a token rotation). Two profiles pointing at the same URL
  405. with different headers/env/auth/client certificates/TLS policy are two identities; borrowing
  406. across them would call tools as the other user, or under the other profile's ``ssl_verify`` /
  407. ``strict_redirect_headers``."""
  408. from tools.mcp_schema_cache import config_fingerprint
  409. def _frozen(value):
  410. return json.dumps(value or {}, sort_keys=True, default=str)
  411. return (config_fingerprint(config), _frozen(config.get("env")), _frozen(config.get("headers")),
  412. _auth_type(config), _frozen(config.get("client_cert")), _frozen(config.get("client_key")),
  413. config.get("ssl_verify", True), bool(config.get("strict_redirect_headers")))
  414. def _auth_type(config: dict) -> str:
  415. return (config.get("auth") or "").lower().strip()
  416. def _identity_digest(resolved: list) -> str:
  417. """Only the hash of a connection's resolved inputs is kept: they carry secrets."""
  418. return hashlib.sha256(json.dumps(resolved, sort_keys=True, default=str).encode()).hexdigest()
  419. def _adopter_identity_digest(server_name: str, config: dict) -> str | None:
  420. """Digest of what a connection is opened with that the config does not show, resolved in the
  421. CURRENT profile's scope by the transport's own resolvers: a stdio child's executable (bare
  422. ``npx``/``node`` may resolve under the profile's home), env (external secret-source values) and
  423. default cwd; an HTTP connection's URL and headers after a ``server_json`` live endpoint and
  424. ``identity_header`` (``value_from: profile``). The transport publishes the digest of the very
  425. inputs each attempt connects with; an adopter recomputes it here. A resolver failure refuses
  426. adoption for this server only, never discovery for the whole scope. None is the one refuse
  427. sentinel: no connectable config, no live endpoint, or a resolver failure."""
  428. from tools.mcp_tool_transport import LiveEndpointUnavailable, _connect_inputs
  429. if "url" not in config and not config.get("command"): # the transport refuses it before resolving
  430. return None
  431. try:
  432. inputs, _ = _connect_inputs(server_name, config)
  433. except LiveEndpointUnavailable: # the transport cannot connect either; never equal to a live one
  434. return None
  435. except Exception as exc: # fail closed for this server; the others still adopt
  436. logger.warning("MCP server '%s': cannot resolve this profile's connection identity (%s); "
  437. "not adopting another profile's connection", server_name, exc)
  438. return None
  439. return _identity_digest(inputs)
  440. def _same_server_route(server: Any, config: dict, *, cross_profile: bool = False,
  441. resolved_identity: str | None = None) -> bool:
  442. """Whether *server* matches *config*. Across profiles the static config is not enough: OAuth
  443. tokens live in the owner's token store (never reusable), and secret-source env, the profile
  444. identity header and the default cwd resolve per profile, so the adopter's resolution
  445. (*resolved_identity*, computed by the caller outside the registry lock; None refuses) must hash
  446. to what the owner connected with. Within one profile the connection is the profile's: its
  447. default cwd resolves in the connection task's own context, never per session."""
  448. if _connection_identity(getattr(server, "_config", {}) or {}) != _connection_identity(config):
  449. return False
  450. if not cross_profile:
  451. return True
  452. # Identities match, so both sides carry the same normalised auth type.
  453. recorded = getattr(server, "_resolved_identity", None)
  454. return (_auth_type(config) != "oauth" and recorded is not None
  455. and resolved_identity is not None and recorded == resolved_identity)
  456. def register_connected_into_current_scope(servers: dict) -> int:
  457. """Serialize shared-scope reconciliation and registration for one discovery pass."""
  458. scope = _core._mcp_registry_scope()
  459. if scope is None:
  460. return 0
  461. with _SCOPE_REFRESH_LOCKS[hash(scope) % len(_SCOPE_REFRESH_LOCKS)]:
  462. return _register_connected_into_current_scope(servers)
  463. def _register_connected_into_current_scope(servers: dict) -> int:
  464. """Heal the current profile's MCP overlay from already-connected shared servers.
  465. A shared live connection remains owned by the profile that opened it, but a profile with the
  466. same route must still receive its callable tool entries. The current profile's config is the
  467. allowlist, and route fingerprints prevent borrowing a differently-authenticated connection.
  468. Missing or changed config entries remove only this profile's overlay.
  469. """
  470. from tools.registry import registry
  471. scope = _core._mcp_registry_scope()
  472. if scope is None:
  473. return 0
  474. # Callers that connect a subset (plugin go-live, a connector, orphan re-registration) pass only
  475. # those names. A name they omit is judged against this profile's own config, or connecting one
  476. # server would strip every other server's tools from the profile while their connections live on.
  477. with _core._lock:
  478. omitted = {_key_name(key) for key, scopes in _core._server_tool_scopes.items()
  479. if scope in scopes and _key_name(key) not in servers}
  480. # Only a name another profile holds a connection for reaches a cross-profile comparison.
  481. foreign = {_key_name(key) for key in _core._servers if _key_scope(key) != scope}
  482. # Resolving what this profile would connect with does PATH lookups, secret-scope reads and
  483. # live-endpoint probes: do it only for names that can be compared across profiles, once each,
  484. # before taking the global registry lock. A foreign key that appears after the snapshot has
  485. # no digest here and is refused until the next pass. A routed profile reconciles after
  486. # ``discover_mcp_tools`` released its temporary owner scope (#113746), so the config load and
  487. # the resolution bind THIS profile's own secret scope; unscoped, a source-tagged secret read
  488. # would refuse a share whose values are equal.
  489. from tools.mcp_tool_discovery import _owner_secret_scope
  490. with _owner_secret_scope():
  491. profile_servers = _config._load_mcp_config() if omitted else {}
  492. judged = {**{name: profile_servers.get(name) for name in omitted}, **servers}
  493. resolved_ids = {name: _adopter_identity_digest(name, config)
  494. for name, config in judged.items()
  495. if name in foreign and config is not None and mcp_server_enabled(config)}
  496. with _core._lock:
  497. stale = []
  498. for key, scopes in _core._server_tool_scopes.items():
  499. if scope not in scopes:
  500. continue
  501. name = _key_name(key)
  502. if name not in judged:
  503. continue # attached after the config read; the next pass judges it
  504. server = _core._servers.get(key)
  505. config = judged[name]
  506. cross_profile = _key_scope(key) != scope
  507. if (config is None or not mcp_server_enabled(config) or server is None
  508. or getattr(server, "session", None) is None
  509. or not _same_server_route(server, config, cross_profile=cross_profile,
  510. resolved_identity=resolved_ids.get(name))):
  511. stale.append(key)
  512. for key in stale:
  513. _remove_server_scope(key, scope)
  514. registered_servers = 0
  515. for name, config in servers.items():
  516. if not mcp_server_enabled(config):
  517. continue
  518. with _core._lock:
  519. if _server_key(name, scope, current=False) in _core._servers:
  520. continue # this profile has its own connection for the name
  521. # Any other profile's live connection with the same route AND credentials is shareable.
  522. shared = [(key, live) for key, live in _core._servers.items()
  523. if _key_name(key) == name and getattr(live, "session", None) is not None
  524. and _same_server_route(live, config, cross_profile=True,
  525. resolved_identity=resolved_ids.get(name))]
  526. if not shared:
  527. continue
  528. key, server = shared[0]
  529. # Visibility for this profile: the owner keeps teardown, this scope sees the connection.
  530. with _core._lock:
  531. _core._server_tool_scopes.setdefault(key, set()).add(scope)
  532. _record_scope_trust(name, config, scope)
  533. if registry.get_tool_names_for_toolset(f"mcp-{name}"):
  534. continue
  535. candidates = _tool_candidates(name, server._tools, _make_tool_filter(name, config), server.tool_timeout)
  536. candidates += _utility_candidates(
  537. name, _select_utility_schemas(name, server, config), server.tool_timeout)
  538. names = _register_candidates(
  539. name, _resolve_name_collisions(name, candidates),
  540. check_fn=_make_check_fn(name), scope=lambda: scope, lazy=False, key=key,
  541. execution_timeout=config.get("timeout"))
  542. if names:
  543. registered_servers += 1
  544. with _core._lock:
  545. server._registered_tool_names = sorted(
  546. set(getattr(server, "_registered_tool_names", []) or ()) | set(names))
  547. return registered_servers
  548. def _register_from_cache_sync(name: str, config: dict, entry: dict) -> list[str]:
  549. """Lazy startup: register from a cached manifest with no child process (first real call goes
  550. through ``_ensure_lazy_server_connected``). Trust metadata is recorded first so the
  551. call-time gate is identical for live and cached registrations.
  552. Lazy startup (#56832, design by Vansh5632): tools appear in the registry immediately; the first real
  553. call routes through ``_get_connected_server_for_call`` → ``_ensure_lazy_server_connected``.
  554. """
  555. from tools.mcp_schema_cache import config_fingerprint, tools_from_cache_entry, utility_tools_from_cache_entry
  556. tool_timeout = _resolve_tool_timeout(config)
  557. cached_tools = _cached_tools(tools_from_cache_entry(entry))
  558. _record_tool_trust_metadata(name, config, cached_tools)
  559. candidates = _tool_candidates(name, cached_tools, _make_tool_filter(name, config), tool_timeout)
  560. candidates += _utility_candidates(name, utility_tools_from_cache_entry(entry), tool_timeout)
  561. registered = _register_candidates(
  562. name, candidates, check_fn=_make_check_fn(name), scope=_core._mcp_registry_scope, lazy=True,
  563. execution_timeout=config.get("timeout"))
  564. if registered:
  565. with _core._lock:
  566. key = _server_key(name)
  567. _core._lazy_server_configs[key] = dict(config)
  568. _core._lazy_server_fingerprints[key] = config_fingerprint(config)
  569. _core._lazy_server_tool_names[key] = list(registered)
  570. logger.info("MCP server '%s' (lazy): registered %d tool(s) from schema cache", name, len(registered))
  571. return registered