From d6ec8c3018673bfcdde2fab62e0899a90fb48f80 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 2 Sep 2026 15:38:42 -0700 Subject: [PATCH 1/9] refactor(mcp): unify live/cache registration into one candidate loop; phase-split sampling and elicitation handlers --- tools/mcp_tool_registration.py | 590 ++++++++++++++------------------- tools/mcp_tool_sampling.py | 524 ++++++++++++----------------- 2 files changed, 466 insertions(+), 648 deletions(-) diff --git a/tools/mcp_tool_registration.py b/tools/mcp_tool_registration.py index 542ea40d79..3201fc5e6b 100644 --- a/tools/mcp_tool_registration.py +++ b/tools/mcp_tool_registration.py @@ -1,13 +1,16 @@ """Registering a connected (or schema-cached) MCP server's tools into the tool registry: include/exclude filtering, trust-tier metadata capture, utility-tool -selection, name-collision resolution and the schema-cache write-through.""" +selection, name-collision resolution and the schema-cache write-through. + +Both entry points (``_register_server_tools`` for a live server, +``_register_from_cache_sync`` for a lazy cached manifest) build a list of +``_Candidate`` records and hand them to the single ``_register_candidates`` loop.""" import logging -from types import SimpleNamespace -from typing import TYPE_CHECKING, Any, Callable, Dict, List -from tools.mcp_tool_common import _parse_boolish, _core +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any, Callable, Dict, Iterable, List, Optional +from tools.mcp_tool_common import _parse_boolish, _core, _resolve_tool_timeout from tools.mcp_tool_handlers import _make_check_fn, _make_get_prompt_handler, _make_list_prompts_handler, _make_list_resources_handler, _make_read_resource_handler -from tools.mcp_tool_common import _resolve_tool_timeout from tools.mcp_tool_schema import _UTILITY_CAPABILITY_ATTRS, _UTILITY_CAPABILITY_METHODS, _build_utility_schemas, _normalize_name_filter, matches_name_filter if TYPE_CHECKING: # pragma: no cover @@ -15,6 +18,16 @@ if TYPE_CHECKING: # pragma: no cover logger = logging.getLogger("tools.mcp_tool") +_UTILITY_ORIGIN_PREFIX = "generated utility " + +# Utility tool key -> handler factory; each takes (server_name, tool_timeout). +_UTILITY_HANDLER_FACTORIES = { + "list_resources": _make_list_resources_handler, + "read_resource": _make_read_resource_handler, + "list_prompts": _make_list_prompts_handler, + "get_prompt": _make_get_prompt_handler, +} + def _normalize_server_trust(value: Any) -> str: """Normalize a config ``trust`` value: None -> ``full`` (backward-compatible @@ -23,10 +36,8 @@ def _normalize_server_trust(value: Any) -> str: if value is None: return _core._TRUST_FULL text = str(value).strip().lower() - if text == _core._TRUST_FULL: - return _core._TRUST_FULL - if text == _core._TRUST_UNTRUSTED: - return _core._TRUST_UNTRUSTED + if text in (_core._TRUST_FULL, _core._TRUST_UNTRUSTED): + return text logger.warning( "MCP trust: unrecognized trust value %r — treating as 'untrusted' " "(valid values: full, untrusted)", value, @@ -42,20 +53,16 @@ def _annotation_read_only_hint(mcp_tool: Any) -> bool: if annotations is None: return False if isinstance(annotations, dict): - hint = annotations.get("readOnlyHint") - else: - hint = getattr(annotations, "readOnlyHint", None) - return hint is True + return annotations.get("readOnlyHint") is True + return getattr(annotations, "readOnlyHint", None) is True -def _record_tool_trust_metadata( - server_name: str, config: dict, tools: List[Any] -) -> None: - """Capture per-server trust and per-tool readOnlyHint at discovery.""" +def _record_tool_trust_metadata(server_name: str, config: dict, tools: List[Any]) -> None: + """Capture per-server trust and per-tool readOnlyHint at discovery (the + security boundary: the call-time gate classifies from data we control, + never re-read server-supplied state).""" with _core._lock: - _core._server_trust_levels[server_name] = _normalize_server_trust( - (config or {}).get("trust") - ) + _core._server_trust_levels[server_name] = _normalize_server_trust((config or {}).get("trust")) hints = _core._tool_read_only_hints.setdefault(server_name, {}) for tool in tools: name = getattr(tool, "name", None) @@ -78,51 +85,39 @@ def _forget_mcp_tool_server(tool_name: str) -> None: def _select_utility_schemas(server_name: str, server: "MCPServerTask", config: dict) -> List[dict]: """Select utility schemas based on config and server capabilities.""" tools_filter = config.get("tools") or {} - resources_enabled = _parse_boolish(tools_filter.get("resources"), default=True) - prompts_enabled = _parse_boolish(tools_filter.get("prompts"), default=True) - + family_enabled = { + family: _parse_boolish(tools_filter.get(family), default=True) + for family in ("resources", "prompts") + } # ``initialize_result.capabilities`` is the source of truth: its sub-objects # are non-None iff the server advertises that request family. The old # ``hasattr(server.session, ...)`` gate never filtered anything because # ClientSession defines all four methods on the class. - advertised_caps = None init_result = getattr(server, "initialize_result", None) - if init_result is not None: - advertised_caps = getattr(init_result, "capabilities", None) + advertised_caps = getattr(init_result, "capabilities", None) if init_result is not None else None selected: List[dict] = [] for entry in _build_utility_schemas(server_name): handler_key = entry["handler_key"] - if handler_key in {"list_resources", "read_resource"} and not resources_enabled: - logger.debug("MCP server '%s': skipping utility '%s' (resources disabled)", server_name, handler_key) + family = _UTILITY_CAPABILITY_ATTRS[handler_key] + if not family_enabled[family]: + logger.debug("MCP server '%s': skipping utility '%s' (%s disabled)", server_name, handler_key, family) continue - if handler_key in {"list_prompts", "get_prompt"} and not prompts_enabled: - logger.debug("MCP server '%s': skipping utility '%s' (prompts disabled)", server_name, handler_key) - continue - if advertised_caps is not None: - cap_attr = _UTILITY_CAPABILITY_ATTRS[handler_key] - if getattr(advertised_caps, cap_attr, None) is None: + if getattr(advertised_caps, family, None) is None: logger.debug( - "MCP server '%s': skipping utility '%s' " - "(server does not advertise '%s' capability)", - server_name, - handler_key, - cap_attr, - ) - continue - else: - # Legacy fallback when initialize_result wasn't captured (test - # fixtures, older paths): register every stub, as before. - required_method = _UTILITY_CAPABILITY_METHODS[handler_key] - if not hasattr(server.session, required_method): - logger.debug( - "MCP server '%s': skipping utility '%s' (session lacks %s)", - server_name, - handler_key, - required_method, + "MCP server '%s': skipping utility '%s' (server does not advertise '%s' capability)", + server_name, handler_key, family, ) continue + # Legacy fallback when initialize_result wasn't captured (test + # fixtures, older paths): register every stub the session can serve. + elif not hasattr(server.session, _UTILITY_CAPABILITY_METHODS[handler_key]): + logger.debug( + "MCP server '%s': skipping utility '%s' (session lacks %s)", + server_name, handler_key, _UTILITY_CAPABILITY_METHODS[handler_key], + ) + continue selected.append(entry) return selected @@ -135,30 +130,19 @@ def _existing_tool_names() -> List[str]: names.extend(server._registered_tool_names) continue for mcp_tool in server._tools: - schema = _core._convert_mcp_schema(server.name, mcp_tool) - names.append(schema["name"]) + names.append(_core._convert_mcp_schema(server.name, mcp_tool)["name"]) # Lazy servers registered from the schema cache have no MCPServerTask yet — # their tools live only in the registry. with _core._lock: - lazy_names = [ + names.extend( n for sname, tool_names in _core._lazy_server_tool_names.items() if sname not in _core._servers for n in tool_names - ] - names.extend(lazy_names) + ) return names -# Utility tool key -> handler factory; each takes (server_name, tool_timeout). -_UTILITY_HANDLER_FACTORIES = { - "list_resources": _make_list_resources_handler, - "read_resource": _make_read_resource_handler, - "list_prompts": _make_list_prompts_handler, - "get_prompt": _make_get_prompt_handler, -} - - def _make_tool_filter(name: str, config: dict) -> Callable[[str], bool]: """Build the include/exclude predicate for a server's tool names. @@ -171,9 +155,7 @@ def _make_tool_filter(name: str, config: dict) -> Callable[[str], bool]: include_raw = tools_filter.get("include") include_set = _normalize_name_filter(include_raw, f"mcp_servers.{name}.tools.include") include_active = isinstance(include_raw, (str, list, tuple, set)) - exclude_set = _normalize_name_filter( - tools_filter.get("exclude"), f"mcp_servers.{name}.tools.exclude" - ) + exclude_set = _normalize_name_filter(tools_filter.get("exclude"), f"mcp_servers.{name}.tools.exclude") def _should_register(tool_name: str) -> bool: if include_active: @@ -185,69 +167,206 @@ def _make_tool_filter(name: str, config: dict) -> Callable[[str], bool]: return _should_register -def _resolve_name_collisions(name: str, candidates: List[dict]): +class _CachedMCPTool: + """Minimal stand-in for MCP Tool objects loaded from the schema cache. + Missing/non-dict ``annotations`` (older cache files) fail closed to + write-capable via ``_annotation_read_only_hint``.""" + + __slots__ = ("name", "description", "inputSchema", "annotations") + + def __init__(self, name: str, description: str, inputSchema: dict, annotations: Optional[dict] = None): + self.name = name + self.description = description + self.inputSchema = inputSchema or {} + self.annotations = annotations if isinstance(annotations, dict) else None + + @classmethod + def from_cache_dicts(cls, raws: Iterable[Any]) -> List["_CachedMCPTool"]: + """Cached tool rows -> stand-ins; rows that are not dicts or lack a name are dropped.""" + tools = [] + for raw in raws: + if not isinstance(raw, dict) or not raw.get("name"): + continue + schema = raw.get("inputSchema") + tools.append(cls( + raw["name"], + raw.get("description") or "", + schema if isinstance(schema, dict) else {}, + raw.get("annotations"), + )) + return tools + + +@dataclass +class _Candidate: + """One registry registration attempt for a server: a native tool or a + generated utility. ``origin`` is the human-readable provenance used in + collision diagnostics.""" + + registry_name: str + origin: str + schema: dict + handler: Callable + + @property + def is_utility(self) -> bool: + return self.origin.startswith(_UTILITY_ORIGIN_PREFIX) + + @property + def description(self) -> str: + return self.schema.get("description") or "" + + +def _tool_candidates(name: str, tools: Iterable[Any], should_register: Callable[[str], bool], tool_timeout) -> List[_Candidate]: + """Native tools (live SDK objects or ``_CachedMCPTool``) -> candidates. + The description scan runs on BOTH paths: the cache file is user-writable JSON.""" + candidates: List[_Candidate] = [] + for mcp_tool in tools: + if not should_register(mcp_tool.name): + logger.debug("MCP server '%s': skipping tool '%s' (filtered by config)", name, mcp_tool.name) + continue + _core._scan_mcp_description(name, mcp_tool.name, mcp_tool.description or "") + schema = _core._convert_mcp_schema(name, mcp_tool) + candidates.append(_Candidate( + schema["name"], f"tool {mcp_tool.name!r}", schema, + _core._make_tool_handler(name, mcp_tool.name, tool_timeout), + )) + return candidates + + +def _utility_candidates(name: str, entries: Iterable[Any], tool_timeout) -> List[_Candidate]: + """``{schema, handler_key}`` rows (live selection or cache) -> candidates; + malformed rows are dropped.""" + candidates: List[_Candidate] = [] + for raw in entries: + if not isinstance(raw, dict): + continue + schema, handler_key = raw.get("schema"), raw.get("handler_key") + if not isinstance(schema, dict) or handler_key not in _UTILITY_HANDLER_FACTORIES or not schema.get("name"): + continue + candidates.append(_Candidate( + schema["name"], f"{_UTILITY_ORIGIN_PREFIX}{handler_key!r}", schema, + _UTILITY_HANDLER_FACTORIES[handler_key](name, tool_timeout), + )) + return candidates + + +def _resolve_name_collisions(name: str, candidates: List[_Candidate]) -> List[_Candidate]: """Preflight registry-name collisions among one server's candidates. - Returns ``(unique_candidates, ambiguous_names, shadowed_utilities)``. Exact - duplicate rows (same name + origin) are dropped silently; a generated + Exact duplicate rows (same name + origin) are dropped silently; a generated utility that normalizes onto a server-native tool's name is shadowed (the native tool wins); any other multi-origin collision is ambiguous and every - colliding entry is skipped (fail closed). + colliding entry is skipped (fail closed). Returns the survivors in order. """ - unique_candidates: List[dict] = [] - seen_candidates: set[tuple[str, str]] = set() + unique: List[_Candidate] = [] + seen: set[tuple[str, str]] = set() origins_by_name: Dict[str, set[str]] = {} - for candidate in candidates: - key = (candidate["registry_name"], candidate["origin"]) - if key in seen_candidates: + for c in candidates: + if (c.registry_name, c.origin) in seen: logger.debug( - "MCP server '%s': duplicate registration candidate %s for '%s'; " - "keeping one", - name, - candidate["origin"], - candidate["registry_name"], + "MCP server '%s': duplicate registration candidate %s for '%s'; keeping one", + name, c.origin, c.registry_name, ) continue - seen_candidates.add(key) - unique_candidates.append(candidate) - origins_by_name.setdefault(candidate["registry_name"], set()).add( - candidate["origin"] - ) + seen.add((c.registry_name, c.origin)) + unique.append(c) + origins_by_name.setdefault(c.registry_name, set()).add(c.origin) - ambiguous_names: Dict[str, List[str]] = {} - shadowed_utilities: set[tuple[str, str]] = set() + ambiguous: Dict[str, List[str]] = {} + shadowed: set[tuple[str, str]] = set() for registry_name, origins in origins_by_name.items(): if len(origins) <= 1: continue - utility_origins = sorted( - o for o in origins if o.startswith("generated utility ") - ) + utility_origins = sorted(o for o in origins if o.startswith(_UTILITY_ORIGIN_PREFIX)) native_origins = sorted(origins - set(utility_origins)) if len(native_origins) == 1 and utility_origins: - for util_origin in utility_origins: - shadowed_utilities.add((registry_name, util_origin)) + shadowed.update((registry_name, o) for o in utility_origins) logger.info( "MCP server '%s': generated utility %s normalizes onto " "server-native %s — keeping the native tool and dropping the " "utility (the utility only applies when the server has no such " "tool of its own)", - name, - ", ".join(utility_origins), - native_origins[0], + name, ", ".join(utility_origins), native_origins[0], ) continue - ambiguous_names[registry_name] = sorted(origins) + ambiguous[registry_name] = sorted(origins) - for registry_name, origins in sorted(ambiguous_names.items()): + for registry_name, origins in sorted(ambiguous.items()): logger.error( "MCP server '%s': name normalization collision for '%s' from %s; " - "skipping every colliding entry instead of choosing an arbitrary " - "handler", - name, - registry_name, - ", ".join(origins), + "skipping every colliding entry instead of choosing an arbitrary handler", + name, registry_name, ", ".join(origins), ) - return unique_candidates, ambiguous_names, shadowed_utilities + return [ + c for c in unique + if c.registry_name not in ambiguous and (c.registry_name, c.origin) not in shadowed + ] + + +def _log_foreign_owner(name: str, c: _Candidate, existing_toolset: str, lazy: bool) -> None: + """Diagnostics for a candidate whose registry name is already owned by + another toolset (skipped to preserve the existing owner).""" + if lazy: + if not c.is_utility: + logger.warning( + "MCP server '%s' (lazy): cached tool '%s' collides with toolset '%s' — skipping", + name, c.registry_name, existing_toolset, + ) + elif existing_toolset.startswith("mcp-"): + logger.error( + "MCP server '%s': %s normalizes to '%s', already owned by MCP toolset '%s' " + "— skipping to preserve the existing owner", + name, c.origin, c.registry_name, existing_toolset, + ) + else: + logger.warning( + "MCP server '%s': %s (→ '%s') collides with built-in tool in toolset '%s' " + "— skipping to preserve built-in", + name, c.origin, c.registry_name, existing_toolset, + ) + + +def _register_candidates( + name: str, candidates: List[_Candidate], *, check_fn: Callable, scope: Callable[[], Optional[str]], lazy: bool, +) -> List[str]: + """Register candidates under toolset ``mcp-{name}``; returns the names that + actually landed. The ownership pre-check is advisory only — multiple + servers connect in parallel, so ``ToolRegistry.register()`` is the atomic + ownership gate and its verdict is re-read after every call.""" + from tools.registry import registry + + toolset_name = f"mcp-{name}" + registered: List[str] = [] + for c in candidates: + existing_toolset = registry.get_toolset_for_tool(c.registry_name) + if existing_toolset and existing_toolset != toolset_name: + _log_foreign_owner(name, c, existing_toolset, lazy) + continue + registry.register( + name=c.registry_name, + toolset=toolset_name, + schema=c.schema, + handler=c.handler, + check_fn=check_fn, + is_async=False, + description=c.description, + scope=scope(), + ) + if registry.get_toolset_for_tool(c.registry_name) != toolset_name: + if not lazy: + logger.error( + "MCP server '%s': registration of %s as '%s' was rejected by " + "the registry; skipping provenance/count updates", + name, c.origin, c.registry_name, + ) + continue + _core._track_mcp_tool_server(c.registry_name, name) + registered.append(c.registry_name) + + if registered: + registry.register_toolset_alias(name, toolset_name) + return registered def _write_schema_cache(name: str, server: "MCPServerTask", config: dict, should_register) -> None: @@ -256,7 +375,7 @@ def _write_schema_cache(name: str, server: "MCPServerTask", config: dict, should try: from tools.mcp_schema_cache import config_fingerprint, write_cache_entry - tools_payload: List[dict] = [] + tools_payload = [] for mcp_tool in server._tools: if not should_register(mcp_tool.name): continue @@ -266,9 +385,7 @@ def _write_schema_cache(name: str, server: "MCPServerTask", config: dict, should "description": mcp_tool.description or "", "inputSchema": schema_obj if isinstance(schema_obj, dict) else {}, # Persisted so the lazy path trust-gates identically next startup. - "annotations": { - "readOnlyHint": _annotation_read_only_hint(mcp_tool), - }, + "annotations": {"readOnlyHint": _annotation_read_only_hint(mcp_tool)}, }) utility_payload = [ {"schema": entry["schema"], "handler_key": entry["handler_key"]} @@ -295,243 +412,44 @@ def _register_server_tools(name: str, server: "MCPServerTask", config: dict) -> live registry rather than mutating ``toolsets.TOOLSETS``. Lossy name normalization can map distinct raw names (``read-file``/``read_file``) to one registry name; such collisions fail closed — every ambiguous entry is - skipped. Returns the registered prefixed names. + skipped. Generated utilities share the namespace and join the same + preflight. Returns the registered prefixed names. """ - from tools.registry import registry - - registered_names: List[str] = [] - toolset_name = f"mcp-{name}" - - _should_register = _make_tool_filter(name, config) + should_register = _make_tool_filter(name, config) check_fn = _make_check_fn(name) - candidates: List[dict] = [] - - # Security boundary: capture trust tier and readOnlyHint NOW, at discovery, - # so the call-time gate classifies from data we control, not re-read - # server-supplied state. _record_tool_trust_metadata(name, config, server._tools) - - for mcp_tool in server._tools: - if not _should_register(mcp_tool.name): - logger.debug( - "MCP server '%s': skipping tool '%s' (filtered by config)", - name, - mcp_tool.name, - ) - continue - - _core._scan_mcp_description(name, mcp_tool.name, mcp_tool.description or "") - schema = _core._convert_mcp_schema(name, mcp_tool) - candidates.append( - { - "registry_name": schema["name"], - "origin": f"tool {mcp_tool.name!r}", - "schema": schema, - "handler": _core._make_tool_handler( - name, mcp_tool.name, server.tool_timeout - ), - "check_fn": check_fn, - } - ) - - # Generated resource/prompt utility tools share the same namespace as raw - # MCP tools, so they must participate in the same collision preflight. - for entry in _select_utility_schemas(name, server, config): - schema = entry["schema"] - handler_key = entry["handler_key"] - candidates.append( - { - "registry_name": schema["name"], - "origin": f"generated utility {handler_key!r}", - "schema": schema, - "handler": _UTILITY_HANDLER_FACTORIES[handler_key]( - name, server.tool_timeout - ), - "check_fn": check_fn, - } - ) - - unique_candidates, ambiguous_names, shadowed_utilities = _resolve_name_collisions(name, candidates) - - for candidate in unique_candidates: - registry_name = candidate["registry_name"] - if registry_name in ambiguous_names: - continue - if (registry_name, candidate["origin"]) in shadowed_utilities: - continue - - existing_toolset = registry.get_toolset_for_tool(registry_name) - if existing_toolset and existing_toolset != toolset_name: - if existing_toolset.startswith("mcp-"): - logger.error( - "MCP server '%s': %s normalizes to '%s', already owned by " - "MCP toolset '%s' — skipping to preserve the existing owner", - name, - candidate["origin"], - registry_name, - existing_toolset, - ) - else: - logger.warning( - "MCP server '%s': %s (→ '%s') collides with built-in tool " - "in toolset '%s' — skipping to preserve built-in", - name, - candidate["origin"], - registry_name, - existing_toolset, - ) - continue - - registry.register( - name=registry_name, - toolset=toolset_name, - schema=candidate["schema"], - handler=candidate["handler"], - check_fn=candidate["check_fn"], - is_async=False, - description=candidate["schema"]["description"], - scope=_core._server_registry_scope(name), - ) - - # The pre-check above is advisory only. Multiple servers connect in - # parallel, so ToolRegistry.register() is the atomic ownership gate. - if registry.get_toolset_for_tool(registry_name) != toolset_name: - logger.error( - "MCP server '%s': registration of %s as '%s' was rejected by " - "the registry; skipping provenance/count updates", - name, - candidate["origin"], - registry_name, - ) - continue - - _core._track_mcp_tool_server(registry_name, name) - registered_names.append(registry_name) - - if registered_names: - registry.register_toolset_alias(name, toolset_name) - _write_schema_cache(name, server, config, _should_register) - - return registered_names - - -class _CachedMCPTool: - """Minimal stand-in for MCP Tool objects loaded from the schema cache.""" - - __slots__ = ("name", "description", "inputSchema") - - def __init__(self, name: str, description: str, inputSchema: dict): - self.name = name - self.description = description - self.inputSchema = inputSchema or {} + candidates = _tool_candidates(name, server._tools, should_register, server.tool_timeout) + candidates += _utility_candidates(name, _select_utility_schemas(name, server, config), server.tool_timeout) + registered = _register_candidates( + name, _resolve_name_collisions(name, candidates), + check_fn=check_fn, scope=lambda: _core._server_registry_scope(name), lazy=False, + ) + if registered: + _write_schema_cache(name, server, config, should_register) + return registered def _register_from_cache_sync(name: str, config: dict, entry: dict) -> List[str]: """Lazy startup: register a server's tools from a cached manifest with no child process. The first real call routes through - ``_get_connected_server_for_call`` -> ``_ensure_lazy_server_connected``.""" - from tools.registry import registry - from tools.mcp_schema_cache import ( - config_fingerprint, - tools_from_cache_entry, - utility_tools_from_cache_entry, - ) + ``_get_connected_server_for_call`` -> ``_ensure_lazy_server_connected``. + Trust metadata is recorded first so the call-time gate is identical whether + the server was spawned live or registered from cache.""" + from tools.mcp_schema_cache import config_fingerprint, tools_from_cache_entry, utility_tools_from_cache_entry - registered_names: List[str] = [] - toolset_name = f"mcp-{name}" - fingerprint = config_fingerprint(config) tool_timeout = _resolve_tool_timeout(config) - _should_register = _make_tool_filter(name, config) check_fn = _make_check_fn(name) - # Record trust metadata before registration so the call-time gate is - # identical whether the server was spawned live or registered from cache. - # Missing "annotations" in older cache files fails closed to write-capable. - cached_tool_objs = [ - SimpleNamespace( - name=raw.get("name"), - annotations=raw.get("annotations") - if isinstance(raw.get("annotations"), dict) else None, - ) - for raw in tools_from_cache_entry(entry) - if isinstance(raw, dict) and raw.get("name") - ] - _record_tool_trust_metadata(name, config, cached_tool_objs) - for raw in tools_from_cache_entry(entry): - if not isinstance(raw, dict): - continue - raw_name = raw.get("name") - if not raw_name or not _should_register(raw_name): - continue - raw_schema = raw.get("inputSchema") - mcp_tool = _CachedMCPTool( - raw_name, - raw.get("description") or "", - raw_schema if isinstance(raw_schema, dict) else {}, - ) - # Defense-in-depth: the cache file is user-writable JSON, so apply the - # same injection scan as eager discovery. - _core._scan_mcp_description(name, mcp_tool.name, mcp_tool.description or "") - schema = _core._convert_mcp_schema(name, mcp_tool) - registry_name = schema["name"] - existing_toolset = registry.get_toolset_for_tool(registry_name) - if existing_toolset and existing_toolset != toolset_name: - logger.warning( - "MCP server '%s' (lazy): cached tool '%s' collides with " - "toolset '%s' — skipping", - name, registry_name, existing_toolset, - ) - continue - registry.register( - name=registry_name, - toolset=toolset_name, - schema=schema, - handler=_core._make_tool_handler(name, raw_name, tool_timeout), - check_fn=check_fn, - is_async=False, - description=schema["description"], - scope=_core._mcp_registry_scope(), - ) - if registry.get_toolset_for_tool(registry_name) != toolset_name: - continue - _core._track_mcp_tool_server(registry_name, name) - registered_names.append(registry_name) - - for raw in utility_tools_from_cache_entry(entry): - if not isinstance(raw, dict): - continue - schema = raw.get("schema") - handler_key = raw.get("handler_key") - if not isinstance(schema, dict) or handler_key not in _UTILITY_HANDLER_FACTORIES: - continue - util_name = schema.get("name") or "" - if not util_name: - continue - existing_toolset = registry.get_toolset_for_tool(util_name) - if existing_toolset and existing_toolset != toolset_name: - continue - registry.register( - name=util_name, - toolset=toolset_name, - schema=schema, - handler=_UTILITY_HANDLER_FACTORIES[handler_key](name, tool_timeout), - check_fn=check_fn, - is_async=False, - description=schema.get("description") or "", - scope=_core._mcp_registry_scope(), - ) - if registry.get_toolset_for_tool(util_name) != toolset_name: - continue - _core._track_mcp_tool_server(util_name, name) - registered_names.append(util_name) - - if registered_names: - registry.register_toolset_alias(name, toolset_name) + cached_tools = _CachedMCPTool.from_cache_dicts(tools_from_cache_entry(entry)) + _record_tool_trust_metadata(name, config, cached_tools) + candidates = _tool_candidates(name, cached_tools, _make_tool_filter(name, config), tool_timeout) + candidates += _utility_candidates(name, utility_tools_from_cache_entry(entry), tool_timeout) + registered = _register_candidates( + name, candidates, check_fn=check_fn, scope=_core._mcp_registry_scope, lazy=True, + ) + if registered: with _core._lock: _core._lazy_server_configs[name] = dict(config) - _core._lazy_server_fingerprints[name] = fingerprint - _core._lazy_server_tool_names[name] = list(registered_names) - logger.info( - "MCP server '%s' (lazy): registered %d tool(s) from schema cache", - name, len(registered_names), - ) - return registered_names + _core._lazy_server_fingerprints[name] = config_fingerprint(config) + _core._lazy_server_tool_names[name] = list(registered) + logger.info("MCP server '%s' (lazy): registered %d tool(s) from schema cache", name, len(registered)) + return registered diff --git a/tools/mcp_tool_sampling.py b/tools/mcp_tool_sampling.py index 0ba22d55ca..48813e3968 100644 --- a/tools/mcp_tool_sampling.py +++ b/tools/mcp_tool_sampling.py @@ -1,16 +1,109 @@ -"""MCP client-side handlers for server-initiated requests: sampling (sampling/createMessage, text and tool-use results) and elicitation. Split from tools/mcp_tool.py.""" +"""MCP client-side handlers for server-initiated requests: sampling +(sampling/createMessage, text and tool-use results) and elicitation.""" import asyncio import json import logging import time -from typing import List, Optional +from typing import Callable, List, Optional from tools.mcp_tool_common import _MISSING, _exc_str, _safe_numeric, _sanitize_error, mcp_field, _core from tools.mcp_tool_schema import _normalize_mcp_input_schema logger = logging.getLogger("tools.mcp_tool") +def _tool_use_id(block): + """Tool-use id (the discriminator for a tool *result* block), read under both + SDK spellings — on mcp 2.x a bare ``hasattr(b, "toolUseId")`` is False and + would silently drop tool results.""" + return mcp_field(block, "tool_use_id", "toolUseId", _MISSING) + + +def _is_tool_use(block) -> bool: + return hasattr(block, "name") and hasattr(block, "input") + + +def _tool_result_text(block) -> str: + """Text of a ToolResultContent block ("" when it carries no content).""" + content = getattr(block, "content", None) + if content is None: + return "" + items = content if isinstance(content, list) else [content] + return "\n".join(item.text for item in items if hasattr(item, "text")) + + +def _content_part(block) -> Optional[dict]: + """One OpenAI content part for a text/image block; None when unsupported.""" + if hasattr(block, "text"): + return {"type": "text", "text": block.text} + mime = mcp_field(block, "mime_type", "mimeType", _MISSING) + if hasattr(block, "data") and mime is not _MISSING: + return {"type": "image_url", "image_url": {"url": f"data:{mime};base64,{block.data}"}} + logger.warning("Unsupported sampling content block type: %s (skipped)", type(block).__name__) + return None + + +def _tool_call_dict(tu, index: int) -> dict: + args = tu.input + return { + "id": getattr(tu, "id", f"call_{index}"), + "type": "function", + "function": { + "name": tu.name, + "arguments": json.dumps(args, ensure_ascii=False) if isinstance(args, dict) else str(args), + }, + } + + +def _convert_sampling_message(msg) -> List[dict]: + """One MCP SamplingMessage -> OpenAI-format messages (tool results first, + then either an assistant tool_calls message or plain content).""" + blocks = msg.content_as_list if hasattr(msg, "content_as_list") else ( + msg.content if isinstance(msg.content, list) else [msg.content] + ) + tool_results = [b for b in blocks if _tool_use_id(b) is not _MISSING] + tool_uses = [b for b in blocks if _is_tool_use(b) and _tool_use_id(b) is _MISSING] + content_blocks = [b for b in blocks if _tool_use_id(b) is _MISSING and not _is_tool_use(b)] + + out = [ + {"role": "tool", "tool_call_id": _tool_use_id(tr), "content": _tool_result_text(tr)} + for tr in tool_results + ] + if tool_uses: + msg_dict: dict = {"role": msg.role, "tool_calls": [_tool_call_dict(tu, i) for i, tu in enumerate(tool_uses)]} + text_parts = [b.text for b in content_blocks if hasattr(b, "text")] + if text_parts: + msg_dict["content"] = "\n".join(text_parts) + out.append(msg_dict) + elif content_blocks: + if len(content_blocks) == 1 and hasattr(content_blocks[0], "text"): + out.append({"role": msg.role, "content": content_blocks[0].text}) + else: + parts = [p for p in map(_content_part, content_blocks) if p is not None] + if parts: + out.append({"role": msg.role, "content": parts}) + return out + + +def _parse_tool_call_arguments(server_name: str, args) -> dict: + """LLM tool_calls arguments -> dict; malformed JSON / non-dict values are + wrapped as ``{"_raw": ...}`` rather than dropped.""" + if isinstance(args, str): + try: + return json.loads(args) + except (json.JSONDecodeError, ValueError): + logger.warning( + "MCP server '%s': malformed tool_calls arguments from LLM (wrapping as raw): %.100s", + server_name, args, + ) + return {"_raw": args} + return args if isinstance(args, dict) else {"_raw": str(args)} + + +def _response_total_tokens(response, default): + return getattr(getattr(response, "usage", None), "total_tokens", default) + + class SamplingHandler: """Handles sampling/createMessage requests for one MCP server. @@ -24,23 +117,17 @@ class SamplingHandler: """ _STOP_REASON_MAP = {"stop": "endTurn", "length": "maxTokens", "tool_calls": "toolUse"} + _LOG_LEVELS = {"debug": logging.DEBUG, "info": logging.INFO, "warning": logging.WARNING} def __init__(self, server_name: str, config: dict): self.server_name = server_name self.max_rpm = _safe_numeric(config.get("max_rpm", 10), 10, int) self.timeout = _safe_numeric(config.get("timeout", 30), 30, float) self.max_tokens_cap = _safe_numeric(config.get("max_tokens_cap", 4096), 4096, int) - self.max_tool_rounds = _safe_numeric( - config.get("max_tool_rounds", 5), 5, int, minimum=0, - ) + self.max_tool_rounds = _safe_numeric(config.get("max_tool_rounds", 5), 5, int, minimum=0) self.model_override = config.get("model") self.allowed_models = config.get("allowed_models", []) - - _log_levels = {"debug": logging.DEBUG, "info": logging.INFO, "warning": logging.WARNING} - self.audit_level = _log_levels.get( - str(config.get("log_level", "info")).lower(), logging.INFO, - ) - + self.audit_level = self._LOG_LEVELS.get(str(config.get("log_level", "info")).lower(), logging.INFO) self._rate_timestamps: List[float] = [] self._tool_loop_count = 0 self.metrics = {"requests": 0, "errors": 0, "tokens_used": 0, "tool_use_count": 0} @@ -59,100 +146,20 @@ class SamplingHandler: """Config override > server hint > None (use default).""" if self.model_override: return self.model_override - if preferences and hasattr(preferences, "hints") and preferences.hints: - for hint in preferences.hints: - if hasattr(hint, "name") and hint.name: - return hint.name + for hint in (getattr(preferences, "hints", None) or []): + if getattr(hint, "name", None): + return hint.name return None @staticmethod def _extract_tool_result_text(block) -> str: """Extract text from a ToolResultContent block.""" - if not hasattr(block, "content") or block.content is None: - return "" - items = block.content if isinstance(block.content, list) else [block.content] - return "\n".join(item.text for item in items if hasattr(item, "text")) + return _tool_result_text(block) def _convert_messages(self, params) -> List[dict]: - """Convert MCP SamplingMessages to OpenAI format. - - Uses ``msg.content_as_list`` when the SDK provides it; dispatches per - block by duck-typing. - """ - # A tool-use id is the discriminator for a tool *result* block; it must be - # read under both spellings (mcp_field) — on mcp 2.x a bare - # ``hasattr(b, "toolUseId")`` is False, silently dropping tool results. - def _tool_use_id(block): - return mcp_field(block, "tool_use_id", "toolUseId", _MISSING) - - def _is_tool_use(block): - return hasattr(block, "name") and hasattr(block, "input") - - messages: List[dict] = [] - for msg in params.messages: - blocks = msg.content_as_list if hasattr(msg, "content_as_list") else ( - msg.content if isinstance(msg.content, list) else [msg.content] - ) - - tool_results = [b for b in blocks if _tool_use_id(b) is not _MISSING] - tool_uses = [ - b for b in blocks - if _is_tool_use(b) and _tool_use_id(b) is _MISSING - ] - content_blocks = [ - b for b in blocks - if _tool_use_id(b) is _MISSING and not _is_tool_use(b) - ] - - for tr in tool_results: - messages.append({ - "role": "tool", - "tool_call_id": _tool_use_id(tr), - "content": self._extract_tool_result_text(tr), - }) - - if tool_uses: - tc_list = [] - for tu in tool_uses: - tc_list.append({ - "id": getattr(tu, "id", f"call_{len(tc_list)}"), - "type": "function", - "function": { - "name": tu.name, - "arguments": json.dumps(tu.input, ensure_ascii=False) if isinstance(tu.input, dict) else str(tu.input), - }, - }) - msg_dict: dict = {"role": msg.role, "tool_calls": tc_list} - text_parts = [b.text for b in content_blocks if hasattr(b, "text")] - if text_parts: - msg_dict["content"] = "\n".join(text_parts) - messages.append(msg_dict) - elif content_blocks: - # Pure text/image content. - if len(content_blocks) == 1 and hasattr(content_blocks[0], "text"): - messages.append({"role": msg.role, "content": content_blocks[0].text}) - else: - parts = [] - for block in content_blocks: - block_mime = mcp_field( - block, "mime_type", "mimeType", _MISSING - ) - if hasattr(block, "text"): - parts.append({"type": "text", "text": block.text}) - elif hasattr(block, "data") and block_mime is not _MISSING: - parts.append({ - "type": "image_url", - "image_url": {"url": f"data:{block_mime};base64,{block.data}"}, - }) - else: - logger.warning( - "Unsupported sampling content block type: %s (skipped)", - type(block).__name__, - ) - if parts: - messages.append({"role": msg.role, "content": parts}) - - return messages + """Convert MCP SamplingMessages to OpenAI format (``content_as_list`` + when the SDK provides it; per-block duck-typed dispatch).""" + return [m for msg in params.messages for m in _convert_sampling_message(msg)] @staticmethod def _error(message: str, code: int = -1): @@ -161,6 +168,11 @@ class SamplingHandler: return _core.ErrorData(code=code, message=message) raise Exception(message) + def _fail(self, message: str): + """Count an error and return the ErrorData for it.""" + self.metrics["errors"] += 1 + return self._error(message) + def _build_tool_use_result(self, choice, response): """Build a CreateMessageResultWithTools from an LLM tool_calls response.""" self.metrics["tool_use_count"] += 1 @@ -168,71 +180,41 @@ class SamplingHandler: # Tool-loop governance. if self.max_tool_rounds == 0: self._tool_loop_count = 0 - return self._error( - f"Tool loops disabled for server '{self.server_name}' (max_tool_rounds=0)" - ) - + return self._error(f"Tool loops disabled for server '{self.server_name}' (max_tool_rounds=0)") self._tool_loop_count += 1 if self._tool_loop_count > self.max_tool_rounds: self._tool_loop_count = 0 return self._error( - f"Tool loop limit exceeded for server '{self.server_name}' " - f"(max {self.max_tool_rounds} rounds)" + f"Tool loop limit exceeded for server '{self.server_name}' (max {self.max_tool_rounds} rounds)" ) - content_blocks = [] - for tc in choice.message.tool_calls: - args = tc.function.arguments - if isinstance(args, str): - try: - parsed = json.loads(args) - except (json.JSONDecodeError, ValueError): - logger.warning( - "MCP server '%s': malformed tool_calls arguments " - "from LLM (wrapping as raw): %.100s", - self.server_name, args, - ) - parsed = {"_raw": args} - else: - parsed = args if isinstance(args, dict) else {"_raw": str(args)} - - content_blocks.append(_core.ToolUseContent( - type="tool_use", - id=tc.id, - name=tc.function.name, - input=parsed, - )) - + content_blocks = [ + _core.ToolUseContent( + type="tool_use", id=tc.id, name=tc.function.name, + input=_parse_tool_call_arguments(self.server_name, tc.function.arguments), + ) + for tc in choice.message.tool_calls + ] logger.log( self.audit_level, "MCP server '%s' sampling response: model=%s, tokens=%s, tool_calls=%d", - self.server_name, response.model, - getattr(getattr(response, "usage", None), "total_tokens", "?"), - len(content_blocks), + self.server_name, response.model, _response_total_tokens(response, "?"), len(content_blocks), ) - return _core.CreateMessageResultWithTools( - role="assistant", - content=content_blocks, - model=response.model, - stopReason="toolUse", + role="assistant", content=content_blocks, model=response.model, stopReason="toolUse", ) def _build_text_result(self, choice, response): """Build a CreateMessageResult from a normal text response (resets the tool loop).""" self._tool_loop_count = 0 - response_text = choice.message.content or "" - logger.log( self.audit_level, "MCP server '%s' sampling response: model=%s, tokens=%s", - self.server_name, response.model, - getattr(getattr(response, "usage", None), "total_tokens", "?"), + self.server_name, response.model, _response_total_tokens(response, "?"), ) - return _core.CreateMessageResult( role="assistant", - content=_core.TextContent(type="text", text=_sanitize_error(response_text)), + content=_core.TextContent(type="text", text=_sanitize_error(choice.message.content or "")), model=response.model, stopReason=self._STOP_REASON_MAP.get(choice.finish_reason, "endTurn"), ) @@ -241,130 +223,89 @@ class SamplingHandler: """Kwargs to pass to ClientSession for sampling support.""" return { "sampling_callback": self, - "sampling_capabilities": _core.SamplingCapability( - tools=_core.SamplingToolsCapability(), - ), + "sampling_capabilities": _core.SamplingCapability(tools=_core.SamplingToolsCapability()), } - async def __call__(self, context, params): - """SDK sampling callback (``SamplingFnT``). Returns CreateMessageResult, - CreateMessageResultWithTools, or ErrorData.""" + def _admit(self, params): + """Rate-limit + allowed_models gate. Returns ``(resolved_model, None)`` + or ``(None, ErrorData)``.""" if not self._check_rate_limit(): - logger.warning( - "MCP server '%s' sampling rate limit exceeded (%d/min)", - self.server_name, self.max_rpm, + logger.warning("MCP server '%s' sampling rate limit exceeded (%d/min)", self.server_name, self.max_rpm) + return None, self._fail( + f"Sampling rate limit exceeded for server '{self.server_name}' ({self.max_rpm} requests/minute)" ) - self.metrics["errors"] += 1 - return self._error( - f"Sampling rate limit exceeded for server '{self.server_name}' " - f"({self.max_rpm} requests/minute)" - ) - - model = self._resolve_model( - mcp_field(params, "model_preferences", "modelPreferences") - ) - - from agent.auxiliary_client import call_llm - + model = self._resolve_model(mcp_field(params, "model_preferences", "modelPreferences")) resolved_model = model or self.model_override or "" - if self.allowed_models and resolved_model and resolved_model not in self.allowed_models: logger.warning( - "MCP server '%s' requested model '%s' not in allowed_models", - self.server_name, resolved_model, + "MCP server '%s' requested model '%s' not in allowed_models", self.server_name, resolved_model, ) - self.metrics["errors"] += 1 - return self._error( + return None, self._fail( f"Model '{resolved_model}' not allowed for server " f"'{self.server_name}'. Allowed: {', '.join(self.allowed_models)}" ) + return resolved_model, None + + def _build_llm_call(self, params, resolved_model: str) -> Callable[[], object]: + """Translate the sampling params into a zero-arg sync ``call_llm`` thunk + (run off-loop so the MCP loop is not blocked).""" + from agent.auxiliary_client import call_llm messages = self._convert_messages(params) system_prompt = mcp_field(params, "system_prompt", "systemPrompt") if system_prompt: messages.insert(0, {"role": "system", "content": system_prompt}) - - max_tokens = min( - mcp_field(params, "max_tokens", "maxTokens", self.max_tokens_cap), - self.max_tokens_cap, - ) - call_temperature = None - if hasattr(params, "temperature") and params.temperature is not None: - call_temperature = params.temperature - + max_tokens = min(mcp_field(params, "max_tokens", "maxTokens", self.max_tokens_cap), self.max_tokens_cap) + temperature = getattr(params, "temperature", None) # Forward server-provided tools. - call_tools = None server_tools = getattr(params, "tools", None) - if server_tools: - call_tools = [ - { - "type": "function", - "function": { - "name": getattr(t, "name", ""), - "description": getattr(t, "description", "") or "", - "parameters": _normalize_mcp_input_schema( - mcp_field(t, "input_schema", "inputSchema") - ), - }, - } - for t in server_tools - ] + tools = [ + { + "type": "function", + "function": { + "name": getattr(t, "name", ""), + "description": getattr(t, "description", "") or "", + "parameters": _normalize_mcp_input_schema(mcp_field(t, "input_schema", "inputSchema")), + }, + } + for t in server_tools + ] if server_tools else None logger.log( self.audit_level, "MCP server '%s' sampling request: model=%s, max_tokens=%d, messages=%d", self.server_name, resolved_model, max_tokens, len(messages), ) + return lambda: call_llm( + task="mcp", model=resolved_model or None, messages=messages, temperature=temperature, + max_tokens=max_tokens, tools=tools, timeout=self.timeout, + ) - # Offload the sync LLM call so the MCP loop is not blocked. - def _sync_call(): - return call_llm( - task="mcp", - model=resolved_model or None, - messages=messages, - temperature=call_temperature, - max_tokens=max_tokens, - tools=call_tools, - timeout=self.timeout, - ) - + async def __call__(self, context, params): + """SDK sampling callback (``SamplingFnT``). Returns CreateMessageResult, + CreateMessageResultWithTools, or ErrorData.""" + resolved_model, err = self._admit(params) + if err is not None: + return err + sync_call = self._build_llm_call(params, resolved_model) try: - response = await asyncio.wait_for( - asyncio.to_thread(_sync_call), timeout=self.timeout, - ) + response = await asyncio.wait_for(asyncio.to_thread(sync_call), timeout=self.timeout) except asyncio.TimeoutError: - self.metrics["errors"] += 1 - return self._error( - f"Sampling LLM call timed out after {self.timeout}s " - f"for server '{self.server_name}'" - ) + return self._fail(f"Sampling LLM call timed out after {self.timeout}s for server '{self.server_name}'") except Exception as exc: - self.metrics["errors"] += 1 - return self._error( - f"Sampling LLM call failed: {_sanitize_error(_exc_str(exc))}" - ) + return self._fail(f"Sampling LLM call failed: {_sanitize_error(_exc_str(exc))}") # Empty choices happen on content filtering / provider errors. if not getattr(response, "choices", None): - self.metrics["errors"] += 1 - return self._error( - f"LLM returned empty response (no choices) for server " - f"'{self.server_name}'" - ) + return self._fail(f"LLM returned empty response (no choices) for server '{self.server_name}'") choice = response.choices[0] self.metrics["requests"] += 1 - total_tokens = getattr(getattr(response, "usage", None), "total_tokens", 0) + total_tokens = _response_total_tokens(response, 0) if isinstance(total_tokens, int): self.metrics["tokens_used"] += total_tokens - - if ( - choice.finish_reason == "tool_calls" - and hasattr(choice.message, "tool_calls") - and choice.message.tool_calls - ): + if choice.finish_reason == "tool_calls" and getattr(choice.message, "tool_calls", None): return self._build_tool_use_result(choice, response) - return self._build_text_result(choice, response) @@ -377,16 +318,11 @@ def _format_elicitation_schema_summary(schema: dict, server_name: str) -> str: lines = [f"Fields requested by MCP server '{server_name}':"] for field_name, field_spec in props.items(): - field_type = "" - field_desc = "" - if isinstance(field_spec, dict): - field_type = str(field_spec.get("type", "") or "") - field_desc = str(field_spec.get("description", "") or "") + spec = field_spec if isinstance(field_spec, dict) else {} + field_type = str(spec.get("type", "") or "") + field_desc = str(spec.get("description", "") or "") suffix = f" ({field_type})" if field_type else "" - if field_desc: - lines.append(f" - {field_name}{suffix}: {field_desc}") - else: - lines.append(f" - {field_name}{suffix}") + lines.append(f" - {field_name}{suffix}: {field_desc}" if field_desc else f" - {field_name}{suffix}") return "\n".join(lines) @@ -411,111 +347,75 @@ class ElicitationHandler: # Back-reference for the agent's contextvars snapshot; optional so the # handler stays unit-testable in isolation. self.owner = owner - self.metrics = { - "requests": 0, - "accepted": 0, - "declined": 0, - "errors": 0, - } + self.metrics = {"requests": 0, "accepted": 0, "declined": 0, "errors": 0} def session_kwargs(self) -> dict: """Kwargs to pass to ClientSession for elicitation support.""" return {"elicitation_callback": self} + def _result(self, action: str, metric: str): + """Count *metric* and return ``ElicitResult(action)`` (accept carries empty content).""" + self.metrics[metric] += 1 + if action == "accept": + return _core.ElicitResult(action="accept", content={}) + return _core.ElicitResult(action=action) + + def _consent_thunk(self, message: str, description: str) -> Callable[[], str]: + """Sync consent call, replaying the agent's contextvars snapshot when the + owner captured one: the recv-loop task does NOT inherit them, and + gateway-platform detection needs them. ``Context.run`` executes a + context once, so it is copied per elicitation.""" + from tools.approval import request_elicitation_consent + + kwargs = {"timeout_seconds": int(self.timeout), "surface": f"mcp-elicitation/{self.server_name}"} + captured = getattr(self.owner, "_pending_call_context", None) if self.owner else None + if captured is None: + return lambda: request_elicitation_consent(message, description, **kwargs) + return lambda: captured.copy().run(request_elicitation_consent, message, description, **kwargs) + async def __call__(self, context, params): """SDK elicitation callback (``ElicitationFnT``). Returns ElicitResult or ErrorData.""" self.metrics["requests"] += 1 # URL-mode (OAuth, payment) would need a browser + waiting for # notifications/elicitation/complete — not implemented; decline cleanly. - mode = getattr(params, "mode", "form") - if mode == "url": + if getattr(params, "mode", "form") == "url": logger.info( - "MCP server '%s' requested URL-mode elicitation; " - "declining (URL-mode elicitation not implemented)", + "MCP server '%s' requested URL-mode elicitation; declining (URL-mode elicitation not implemented)", self.server_name, ) - self.metrics["declined"] += 1 - return _core.ElicitResult(action="decline") + return self._result("decline", "declined") - message = getattr(params, "message", "") or ( - f"MCP server '{self.server_name}' is requesting your approval" - ) + message = getattr(params, "message", "") or f"MCP server '{self.server_name}' is requesting your approval" # ``requestedSchema`` on mcp 1.x, ``requested_schema`` on 2.0 (pydantic # aliases don't apply to attribute access) — read both or the user is # asked to approve without seeing which fields the server wants. - schema = ( - getattr(params, "requestedSchema", None) - or getattr(params, "requested_schema", None) - or {} - ) + schema = getattr(params, "requestedSchema", None) or getattr(params, "requested_schema", None) or {} description = _format_elicitation_schema_summary(schema, self.server_name) - - logger.info( - "MCP server '%s' elicitation request: %s", - self.server_name, _sanitize_error(message)[:200], - ) + logger.info("MCP server '%s' elicitation request: %s", self.server_name, _sanitize_error(message)[:200]) # Lazy import avoids import-order coupling with early-bootstrap tools.approval. try: - from tools.approval import request_elicitation_consent + invoke_consent = self._consent_thunk(message, description) except Exception as exc: # pragma: no cover -- defensive - logger.error( - "MCP server '%s' elicitation: approval system unavailable: %s", - self.server_name, exc, - ) - self.metrics["errors"] += 1 - return _core.ElicitResult(action="decline") + logger.error("MCP server '%s' elicitation: approval system unavailable: %s", self.server_name, exc) + return self._result("decline", "errors") # Offload the sync consent flow to a thread — inline it would freeze the - # MCP loop and every other RPC on this session. The recv-loop task does - # NOT inherit the agent's contextvars, so replay the snapshot captured on - # owner._pending_call_context for gateway-platform detection. - captured = getattr(self.owner, "_pending_call_context", None) if self.owner else None - - def _invoke_consent() -> str: - if captured is None: - return request_elicitation_consent( - message, - description, - timeout_seconds=int(self.timeout), - surface=f"mcp-elicitation/{self.server_name}", - ) - # Context.run executes a context once — copy so multiple - # elicitations within one tool call work. - return captured.copy().run( - request_elicitation_consent, - message, - description, - timeout_seconds=int(self.timeout), - surface=f"mcp-elicitation/{self.server_name}", - ) - + # MCP loop and every other RPC on this session. try: answer = await asyncio.wait_for( - asyncio.to_thread(_invoke_consent), - timeout=self.timeout + self._OUTER_TIMEOUT_GRACE_SECONDS, + asyncio.to_thread(invoke_consent), timeout=self.timeout + self._OUTER_TIMEOUT_GRACE_SECONDS, ) except asyncio.TimeoutError: - logger.warning( - "MCP server '%s' elicitation timed out after %ds", - self.server_name, int(self.timeout), - ) - self.metrics["errors"] += 1 - return _core.ElicitResult(action="cancel") + logger.warning("MCP server '%s' elicitation timed out after %ds", self.server_name, int(self.timeout)) + return self._result("cancel", "errors") except Exception as exc: - logger.error( - "MCP server '%s' elicitation failed: %s", - self.server_name, exc, exc_info=True, - ) - self.metrics["errors"] += 1 - return _core.ElicitResult(action="decline") + logger.error("MCP server '%s' elicitation failed: %s", self.server_name, exc, exc_info=True) + return self._result("decline", "errors") if answer == "accept": - self.metrics["accepted"] += 1 - return _core.ElicitResult(action="accept", content={}) + return self._result("accept", "accepted") if answer == "cancel": - self.metrics["errors"] += 1 - return _core.ElicitResult(action="cancel") - self.metrics["declined"] += 1 - return _core.ElicitResult(action="decline") + return self._result("cancel", "errors") + return self._result("decline", "declined") From faceb453374043da2a38ed3c4981dd8190fdceac Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 2 Sep 2026 15:48:34 -0700 Subject: [PATCH 2/9] refactor(mcp): split orphan reaper/config/schema/agent-refresh helpers; table-build utility schemas and injection patterns --- tools/mcp_schema_cache.py | 29 ++-- tools/mcp_stdio_watchdog.py | 19 +-- tools/mcp_tool_agent.py | 140 +++++++--------- tools/mcp_tool_common.py | 23 +-- tools/mcp_tool_config.py | 253 ++++++++++++---------------- tools/mcp_tool_lifecycle.py | 188 +++++++++------------ tools/mcp_tool_schema.py | 318 ++++++++++++++---------------------- 7 files changed, 397 insertions(+), 573 deletions(-) diff --git a/tools/mcp_schema_cache.py b/tools/mcp_schema_cache.py index 0e3377bd9a..48ce08c12f 100644 --- a/tools/mcp_schema_cache.py +++ b/tools/mcp_schema_cache.py @@ -77,19 +77,16 @@ def get_cached_entry(server_name: str, fingerprint: str) -> Optional[dict]: """ with _cache_lock: entry = _load_all().get(server_name) - if not isinstance(entry, dict): - return None - if entry.get("fingerprint") != fingerprint: + if not isinstance(entry, dict) or entry.get("fingerprint") != fingerprint: return None ttl_ms = entry.get("ttl_ms") written_at = entry.get("written_at") - if ( + expired = ( isinstance(ttl_ms, (int, float)) and isinstance(written_at, (int, float)) and (time.time() - written_at) * 1000.0 >= float(ttl_ms) - ): - return None - return entry + ) + return None if expired else entry def write_cache_entry( @@ -107,11 +104,7 @@ def write_cache_entry( ``tools/list`` result (2026-07-28 servers). ``written_at`` anchors TTL expiry in :func:`get_cached_entry`. """ - entry = { - "fingerprint": fingerprint, - "tools": tools, - "utility_tools": utility_tools or [], - } + entry = {"fingerprint": fingerprint, "tools": tools, "utility_tools": utility_tools or []} if isinstance(ttl_ms, (int, float)): entry["ttl_ms"] = ttl_ms entry["written_at"] = time.time() @@ -131,12 +124,16 @@ def write_cache_entry( _save_all(data) +def _list_field(entry: dict, key: str) -> List[dict]: + value = entry.get(key) + return list(value) if isinstance(value, list) else [] + + def tools_from_cache_entry(entry: dict) -> List[dict]: """Return cached MCP tool dicts (name, description, inputSchema).""" - tools = entry.get("tools") - return list(tools) if isinstance(tools, list) else [] + return _list_field(entry, "tools") def utility_tools_from_cache_entry(entry: dict) -> List[dict]: - util = entry.get("utility_tools") - return list(util) if isinstance(util, list) else [] + """Return cached ``{schema, handler_key}`` utility rows.""" + return _list_field(entry, "utility_tools") diff --git a/tools/mcp_stdio_watchdog.py b/tools/mcp_stdio_watchdog.py index 7c4c1896b7..fa0570f9cd 100644 --- a/tools/mcp_stdio_watchdog.py +++ b/tools/mcp_stdio_watchdog.py @@ -78,9 +78,7 @@ def _watchdog_loop(proc: subprocess.Popen, original_ppid: int) -> None: def main(argv: list[str] | None = None) -> int: - parser = argparse.ArgumentParser( - description="Parent-death watchdog for a stdio MCP subprocess.", - ) + parser = argparse.ArgumentParser(description="Parent-death watchdog for a stdio MCP subprocess.") parser.add_argument("--ppid", type=int, required=True) parser.add_argument("command", nargs=argparse.REMAINDER) args = parser.parse_args(argv) @@ -94,13 +92,7 @@ def main(argv: list[str] | None = None) -> int: # New process group so we can killpg() the whole tree the real command may # spawn, without touching our own group or the original parent's. - proc = subprocess.Popen( - real_argv, - stdin=sys.stdin, - stdout=sys.stdout, - stderr=sys.stderr, - start_new_session=True, - ) + proc = subprocess.Popen(real_argv, stdin=sys.stdin, stdout=sys.stdout, stderr=sys.stderr, start_new_session=True) # The server lives in its OWN group, so the parent's shutdown killpg of # *our* group no longer reaches it. Forward SIGTERM/SIGINT to the child's @@ -113,12 +105,7 @@ def main(argv: list[str] | None = None) -> int: signal.signal(signal.SIGTERM, _forward_shutdown) signal.signal(signal.SIGINT, _forward_shutdown) - watchdog = threading.Thread( - target=_watchdog_loop, - args=(proc, args.ppid), - daemon=True, - ) - watchdog.start() + threading.Thread(target=_watchdog_loop, args=(proc, args.ppid), daemon=True).start() try: return proc.wait() diff --git a/tools/mcp_tool_agent.py b/tools/mcp_tool_agent.py index e7a509c7f3..2722d1b35b 100644 --- a/tools/mcp_tool_agent.py +++ b/tools/mcp_tool_agent.py @@ -16,6 +16,38 @@ logger = logging.getLogger("tools.mcp_tool") _agent_tools_lock = threading.Lock() +def _def_name(tool_def: dict) -> str: + return (tool_def.get("function") or {}).get("name", "") + + +def _agent_tool_defs(agent) -> list: + return list(getattr(agent, "tools", None) or []) + + +def _resolve_refresh_toolsets(agent, enabled_override, disabled_override): + """Explicit reloads pass freshly-resolved toolsets (so a server just ENABLED + in config is picked up) and the agent's selection is updated to match; + automatic paths pass nothing and reuse the build-time selection.""" + enabled = getattr(agent, "enabled_toolsets", None) + disabled = getattr(agent, "disabled_toolsets", None) + if enabled_override is not None or disabled_override is not None: + enabled = enabled_override if enabled_override is not None else enabled + disabled = disabled_override if disabled_override is not None else disabled + agent.enabled_toolsets = enabled + agent.disabled_toolsets = disabled + return enabled, disabled + + +def _tool_defs_content_changed(agent, new_defs: list) -> bool: + """Byte-level diff of the serialized tool arrays (dynamic schemas change + CONTENT under stable names); False if either side fails to serialize.""" + try: + dump = lambda defs: json.dumps(defs, sort_keys=True, separators=(",", ":"), default=str) # noqa: E731 + return dump(_agent_tool_defs(agent)) != dump(new_defs) + except Exception: # noqa: BLE001 + return False + + def refresh_agent_mcp_tools( agent, *, @@ -51,17 +83,7 @@ def refresh_agent_mcp_tools( from model_tools import get_tool_definitions from tools.registry import registry - # Explicit reloads pass freshly-resolved toolsets (so a server just ENABLED - # in config is picked up) and the agent's selection is updated to match; - # automatic paths pass nothing and reuse the build-time selection. - if enabled_override is not None or disabled_override is not None: - enabled = enabled_override if enabled_override is not None else getattr(agent, "enabled_toolsets", None) - disabled = disabled_override if disabled_override is not None else getattr(agent, "disabled_toolsets", None) - agent.enabled_toolsets = enabled - agent.disabled_toolsets = disabled - else: - enabled = getattr(agent, "enabled_toolsets", None) - disabled = getattr(agent, "disabled_toolsets", None) + enabled, disabled = _resolve_refresh_toolsets(agent, enabled_override, disabled_override) # Capture the registry generation BEFORE the slow get_tool_definitions call; # at publish time a slower caller holding an OLDER set must not clobber a @@ -70,15 +92,8 @@ def refresh_agent_mcp_tools( # Computed OUTSIDE the lock (can be slow); diff + publish happen together in # one critical section so concurrent callers can't torn-publish. - new_defs = list( - get_tool_definitions( - enabled_toolsets=enabled, - disabled_toolsets=disabled, - quiet_mode=quiet_mode, - ) - or [] - ) - new_names = {t["function"]["name"] for t in new_defs} + new_defs = list(get_tool_definitions(enabled_toolsets=enabled, disabled_toolsets=disabled, quiet_mode=quiet_mode) or []) + new_names = {_def_name(t) for t in new_defs} # Re-append the post-build families on LOCALS only; live agent attributes # are untouched until the single atomic publish below. @@ -102,34 +117,16 @@ def refresh_agent_mcp_tools( published_gen = published_gen_raw if isinstance(published_gen_raw, int) else -1 if snapshot_generation < published_gen: return set() # a newer snapshot already won - current_defs = list(getattr(agent, "tools", None) or []) - current = {t["function"]["name"] for t in current_defs} + current_defs = _agent_tool_defs(agent) + current = {_def_name(t) for t in current_defs} if preserve_prefix: - new_defs, new_names = _merge_preserving_prefix( - current_defs, new_defs, registered_names, - ) - if new_names == current: - # Same NAME set: no change for MCP-reload callers. Content-aware - # callers (compaction boundary) also diff serialized bytes, since - # dynamic schemas change CONTENT under stable names. - content_changed = False - if content_aware: - try: - _stable = json.dumps( - (getattr(agent, "tools", None) or []), - sort_keys=True, separators=(",", ":"), default=str, - ) - _new = json.dumps( - new_defs, sort_keys=True, separators=(",", ":"), - default=str, - ) - content_changed = _stable != _new - except Exception: # noqa: BLE001 - content_changed = False - if not content_changed: - # Record the generation so an in-flight older caller can't clobber. - agent._tool_snapshot_generation = max(published_gen, snapshot_generation) - return set() + new_defs, new_names = _merge_preserving_prefix(current_defs, new_defs, registered_names) + # Same NAME set: no change for MCP-reload callers. Content-aware callers + # (compaction boundary) also diff serialized bytes. + if new_names == current and not (content_aware and _tool_defs_content_changed(agent, new_defs)): + # Record the generation so an in-flight older caller can't clobber. + agent._tool_snapshot_generation = max(published_gen, snapshot_generation) + return set() agent.tools = new_defs agent.valid_tool_names = new_names # Publish context-engine routing names atomically with the snapshot. @@ -163,10 +160,7 @@ def persist_agent_tool_names(agent) -> None: if not db or not session_id: return try: - db.update_session_tool_names( - session_id, - [t["function"]["name"] for t in (getattr(agent, "tools", None) or [])], - ) + db.update_session_tool_names(session_id, [_def_name(t) for t in _agent_tool_defs(agent)]) except Exception: # noqa: BLE001 logger.debug("tool_names persist skipped", exc_info=True) @@ -184,8 +178,8 @@ def restore_agent_tool_prefix(agent, saved_names: list) -> bool: return False from tools.registry import registry - fresh_defs = list(getattr(agent, "tools", None) or []) - fresh = {t["function"]["name"]: t for t in fresh_defs} + fresh_defs = _agent_tool_defs(agent) + fresh = {_def_name(t): t for t in fresh_defs} saved_defs = [] for name in saved_names: entry_def = fresh.get(name) @@ -202,14 +196,12 @@ def restore_agent_tool_prefix(agent, saved_names: list) -> bool: return False agent.tools = merged agent.valid_tool_names = merged_names - if [t["function"]["name"] for t in merged] != list(saved_names): + if [_def_name(t) for t in merged] != list(saved_names): persist_agent_tool_names(agent) return True -def _merge_preserving_prefix( - current_defs: list, new_defs: list, registered_names: set, -) -> tuple[list, set]: +def _merge_preserving_prefix(current_defs: list, new_defs: list, registered_names: set) -> tuple[list, set]: """Fold a fresh tool snapshot into a live one without moving existing bytes. Ordered by ``current_defs`` (the cached request prefix): a name in both @@ -217,22 +209,17 @@ def _merge_preserving_prefix( kept if still registered (``check_fn`` flapped) and dropped if not; a name only in the fresh list is appended at the tail. """ - fresh = {} - for entry in new_defs: - name = (entry.get("function") or {}).get("name", "") - if name: - fresh[name] = entry - + fresh = {_def_name(entry): entry for entry in new_defs if _def_name(entry)} merged = [] for entry in current_defs: - name = (entry.get("function") or {}).get("name", "") + name = _def_name(entry) replacement = fresh.pop(name, None) if replacement is not None: merged.append(replacement) elif name and name in registered_names: merged.append(entry) merged.extend(fresh.values()) - return merged, {(t.get("function") or {}).get("name", "") for t in merged} + return merged, {_def_name(t) for t in merged} def _reinject_post_build_tools(agent, tools_list: list, name_set: set) -> set: @@ -243,14 +230,15 @@ def _reinject_post_build_tools(agent, tools_list: list, name_set: set) -> set: Returns the context-engine routing names THIS rebuild appended: a name already owned by a registry/plugin tool is not claimed, matching agent_init. """ - def _add(schema: dict) -> bool: - name = schema.get("name", "") + def _add(schema) -> bool: + name = schema.get("name", "") if isinstance(schema, dict) else "" if not name or name in name_set: return False tools_list.append({"type": "function", "function": schema}) name_set.add(name) return True + enabled = getattr(agent, "enabled_toolsets", None) try: memory_manager = getattr(agent, "_memory_manager", None) get_mem_schemas = getattr(memory_manager, "get_all_tool_schemas", None) if memory_manager else None @@ -258,13 +246,10 @@ def _reinject_post_build_tools(agent, tools_list: list, name_set: set) -> set: # Same toolset gate inject_memory_provider_tools uses. from agent.memory_manager import memory_provider_tools_enabled if memory_provider_tools_enabled( - getattr(agent, "enabled_toolsets", None), - getattr(agent, "disabled_toolsets", None), - memory_tool_present="memory" in name_set, + enabled, getattr(agent, "disabled_toolsets", None), memory_tool_present="memory" in name_set, ): for schema in get_mem_schemas(): - if isinstance(schema, dict): - _add(schema) + _add(schema) except Exception: logger.debug("Memory-provider tool re-injection skipped", exc_info=True) @@ -273,18 +258,13 @@ def _reinject_post_build_tools(agent, tools_list: list, name_set: set) -> set: # restricted-toolset platform would re-leak tools the build excluded. staged_engine_names: set = set() try: - enabled = getattr(agent, "enabled_toolsets", None) - context_engine_allowed = enabled is None or "context_engine" in enabled compressor = getattr(agent, "context_compressor", None) get_schemas = getattr(compressor, "get_tool_schemas", None) if compressor else None - if context_engine_allowed and callable(get_schemas): + if (enabled is None or "context_engine" in enabled) and callable(get_schemas): for schema in get_schemas(): - if not isinstance(schema, dict): - continue - name = schema.get("name", "") # Claim the routing name only when WE appended the schema. - if _add(schema) and name: - staged_engine_names.add(name) + if _add(schema): + staged_engine_names.add(schema["name"]) except Exception: logger.debug("Context-engine tool re-injection skipped", exc_info=True) diff --git a/tools/mcp_tool_common.py b/tools/mcp_tool_common.py index d0bc4f3438..e127e9154f 100644 --- a/tools/mcp_tool_common.py +++ b/tools/mcp_tool_common.py @@ -44,9 +44,8 @@ def mcp_field(obj, snake: str, camel: str, default=None): either SDK generation (``mcp`` is an optional extra at the user's version). """ value = getattr(obj, snake, _MISSING) - if value is not _MISSING: - return value - value = getattr(obj, camel, _MISSING) + if value is _MISSING: + value = getattr(obj, camel, _MISSING) return default if value is _MISSING else value @@ -78,8 +77,7 @@ _BACKOFF_JITTER = 0.2 # +/-20% def _jittered(seconds: float) -> float: """``seconds`` with +/-20% uniform jitter, floored at 0.""" - return max(0.0, seconds * random.uniform(1.0 - _BACKOFF_JITTER, - 1.0 + _BACKOFF_JITTER)) + return max(0.0, seconds * random.uniform(1.0 - _BACKOFF_JITTER, 1.0 + _BACKOFF_JITTER)) # Credential patterns to strip from error messages. @@ -144,6 +142,10 @@ def _safe_numeric(value, default, coerce=int, minimum=1): return default +_TRUE_WORDS = frozenset({"true", "1", "yes", "on"}) +_FALSE_WORDS = frozenset({"false", "0", "no", "off"}) + + def _parse_boolish(value: Any, default: bool = True) -> bool: """Parse a bool-like config value with safe fallback.""" if value is None: @@ -152,16 +154,17 @@ def _parse_boolish(value: Any, default: bool = True) -> bool: return value if isinstance(value, str): lowered = value.strip().lower() - if lowered in {"true", "1", "yes", "on"}: + if lowered in _TRUE_WORDS: return True - if lowered in {"false", "0", "no", "off"}: + if lowered in _FALSE_WORDS: return False logger.warning("MCP config expected a boolean-ish value, got %r; using default=%s", value, default) return default def _get_lifecycle_seconds(config: dict, key: str) -> Optional[float]: - """Return an optional positive lifecycle timeout from top-level/nested config.""" + """Return an optional positive lifecycle timeout from top-level/nested config + (``0`` disables; negatives and non-numbers are warned about and ignored).""" raw = config.get(key) lifecycle = config.get("lifecycle") if raw is None and isinstance(lifecycle, dict): @@ -173,9 +176,7 @@ def _get_lifecycle_seconds(config: dict, key: str) -> Optional[float]: except (TypeError, ValueError): logger.warning("MCP config %s must be a number of seconds; ignoring %r", key, raw) return None - if seconds == 0: - return None if seconds < 0: logger.warning("MCP config %s must be positive; ignoring %r", key, raw) return None - return seconds + return seconds or None diff --git a/tools/mcp_tool_config.py b/tools/mcp_tool_config.py index 80fd0dff2b..c3205ac1cb 100644 --- a/tools/mcp_tool_config.py +++ b/tools/mcp_tool_config.py @@ -8,7 +8,6 @@ import re import shutil import sys import threading -from typing import Callable from datetime import datetime from typing import Any, Dict, List, Optional, Set, Tuple from tools.mcp_tool_common import _env_ref_name, _prepend_path, _core @@ -17,8 +16,6 @@ logger = logging.getLogger("tools.mcp_tool") _mcp_stderr_log_fh: Optional[Any] = None - - _mcp_stderr_log_lock = threading.Lock() @@ -36,10 +33,9 @@ def _get_mcp_stderr_log() -> Any: from hermes_constants import get_hermes_home log_dir = get_hermes_home() / "logs" log_dir.mkdir(parents=True, exist_ok=True) - log_path = log_dir / "mcp-stderr.log" # Line-buffered so output lands promptly; errors="replace" tolerates # garbled binary from misbehaving servers. - fh = open(log_path, "a", encoding="utf-8", errors="replace", buffering=1) + fh = open(log_dir / "mcp-stderr.log", "a", encoding="utf-8", errors="replace", buffering=1) fh.fileno() # confirm a real fd before committing _mcp_stderr_log_fh = fh except Exception as exc: # pragma: no cover — best-effort fallback @@ -64,44 +60,19 @@ def _write_stderr_log_header(server_name: str) -> None: # Env vars safe to pass to stdio subprocesses (no secrets). -_SAFE_ENV_KEYS = frozenset({ - "PATH", "HOME", "USER", "LANG", "LC_ALL", "TERM", "SHELL", "TMPDIR", -}) - +_SAFE_ENV_KEYS = frozenset({"PATH", "HOME", "USER", "LANG", "LC_ALL", "TERM", "SHELL", "TMPDIR"}) +# Windows process/location vars needed by launcher-style tools (e.g. Docker +# Desktop's MCP plugin discovery); none carry secrets. _SAFE_ENV_KEYS_CASE_INSENSITIVE = frozenset({ - # Windows process/location vars needed by launcher-style tools (e.g. - # Docker Desktop's MCP plugin discovery); none carry secrets. - "ALLUSERSPROFILE", - "APPDATA", - "COMMONPROGRAMFILES", - "COMMONPROGRAMFILES(X86)", - "COMMONPROGRAMW6432", - "COMPUTERNAME", - "COMSPEC", - "HOMEDRIVE", - "HOMEPATH", - "LOCALAPPDATA", - "NUMBER_OF_PROCESSORS", - "OS", - "PATHEXT", - "PROCESSOR_ARCHITECTURE", - "PROGRAMDATA", - "PROGRAMFILES", - "PROGRAMFILES(X86)", - "PROGRAMW6432", - "PUBLIC", - "SYSTEMDRIVE", - "SYSTEMROOT", - "TEMP", - "TMP", - "USERDOMAIN", - "USERNAME", - "USERPROFILE", - "WINDIR", + "ALLUSERSPROFILE", "APPDATA", "COMMONPROGRAMFILES", "COMMONPROGRAMFILES(X86)", + "COMMONPROGRAMW6432", "COMPUTERNAME", "COMSPEC", "HOMEDRIVE", "HOMEPATH", + "LOCALAPPDATA", "NUMBER_OF_PROCESSORS", "OS", "PATHEXT", "PROCESSOR_ARCHITECTURE", + "PROGRAMDATA", "PROGRAMFILES", "PROGRAMFILES(X86)", "PROGRAMW6432", "PUBLIC", + "SYSTEMDRIVE", "SYSTEMROOT", "TEMP", "TMP", "USERDOMAIN", "USERNAME", + "USERPROFILE", "WINDIR", }) - # ${VAR_NAME} interpolation; any non-} chars allowed so MY-VAR / my.var work. _ENV_VAR_PATTERN = re.compile(r"\$\{([^}]+)\}") @@ -120,20 +91,26 @@ def _workspace_folder() -> str: return os.getcwd() +def _workspace_basename() -> str: + root = _core._workspace_folder() + return os.path.basename(root.rstrip("/\\")) or root + + +# Cursor's case-sensitive context vars -> resolver. +_CONTEXT_VAR_RESOLVERS = { + "userHome": lambda: os.path.expanduser("~"), + "workspaceFolder": lambda: _core._workspace_folder(), + "workspaceFolderBasename": _workspace_basename, + "pathSeparator": lambda: os.sep, + "/": lambda: os.sep, +} + + def _context_var_value(ref: str) -> Optional[str]: - """Resolve Cursor's case-sensitive context vars (``userHome``, - ``workspaceFolder``, ``workspaceFolderBasename``, ``pathSeparator``/``/``). - Returns None for anything else so it falls through to env-var lookup.""" - if ref == "userHome": - return os.path.expanduser("~") - if ref == "workspaceFolder": - return _core._workspace_folder() - if ref == "workspaceFolderBasename": - root = _core._workspace_folder() - return os.path.basename(root.rstrip("/\\")) or root - if ref in ("pathSeparator", "/"): - return os.sep - return None + """Resolve a Cursor context var; None for anything else so it falls through + to env-var lookup.""" + resolver = _CONTEXT_VAR_RESOLVERS.get(ref) + return resolver() if resolver else None def _build_safe_env(user_env: Optional[dict]) -> dict: @@ -147,20 +124,59 @@ def _build_safe_env(user_env: Optional[dict]) -> dict: from hermes_cli.env_loader import get_secret_source except Exception: # pragma: no cover — early bootstrap/import fallback get_secret_source = None - env = {} - for key, value in os.environ.items(): - if ( - key in _SAFE_ENV_KEYS - or key.upper() in _SAFE_ENV_KEYS_CASE_INSENSITIVE - or key.startswith("XDG_") - or (get_secret_source is not None and get_secret_source(key)) - ): - env[key] = value + env = { + key: value + for key, value in os.environ.items() + if key in _SAFE_ENV_KEYS + or key.upper() in _SAFE_ENV_KEYS_CASE_INSENSITIVE + or key.startswith("XDG_") + or (get_secret_source is not None and get_secret_source(key)) + } if user_env: env.update(user_env) return env +def _which_with_config_pathext(command: str, path_arg, env: dict): + """``shutil.which`` retried under the config env's PATHEXT (Windows only): + ``which(path=...)`` uses the PARENT's PATHEXT, not the config env's.""" + cfg_pathext = next( + (v for k, v in env.items() if k.upper() == "PATHEXT" and isinstance(v, str) and v.strip()), + None, + ) + if not cfg_pathext or cfg_pathext == os.environ.get("PATHEXT"): + return None + saved = os.environ.get("PATHEXT") + try: + os.environ["PATHEXT"] = cfg_pathext + return shutil.which(command, path=path_arg) + finally: + if saved is None: + os.environ.pop("PATHEXT", None) + else: + os.environ["PATHEXT"] = saved + + +def _node_fallback(command: str) -> str: + """Well-known Node install locations for bare ``npx``/``npm``/``node`` when + PATH lookup failed; returns *command* unchanged when none is executable.""" + home = os.path.expanduser("~") + hermes_home = os.path.expanduser(os.getenv("HERMES_HOME", os.path.join(home, ".hermes"))) + candidates = [ + os.path.join(hermes_home, "node", "bin", command), + os.path.join(home, ".local", "bin", command), + # Canonical Node location for from-source Linux builds, the Hermes Docker + # image and Intel Homebrew. Needed when a user's hand-authored env.PATH + # omits it: npx's shebang re-execs /usr/bin/env node, so a symlink + # workaround fails one layer deeper. + os.path.join(os.sep, "usr", "local", "bin", command), + ] + for candidate in candidates: + if os.path.isfile(candidate) and os.access(candidate, os.X_OK): + return candidate + return command + + def _resolve_stdio_command(command: str, env: dict) -> tuple[str, dict]: """Resolve a stdio command against the exact subprocess env, mainly so bare ``npx``/``npm``/``node`` work under a filtered PATH.""" @@ -171,72 +187,31 @@ def _resolve_stdio_command(command: str, env: dict) -> tuple[str, dict]: path_arg = resolved_env.get("PATH") which_hit = shutil.which(resolved_command, path=path_arg) if which_hit is None and sys.platform == "win32" and resolved_env: - # shutil.which(path=...) uses the PARENT's PATHEXT, not the config - # env's, so retry with the config's PATHEXT (any key casing) applied. - cfg_pathext = next( - (v for k, v in resolved_env.items() - if k.upper() == "PATHEXT" and isinstance(v, str) and v.strip()), - None, - ) - if cfg_pathext and cfg_pathext != os.environ.get("PATHEXT"): - _saved = os.environ.get("PATHEXT") - try: - os.environ["PATHEXT"] = cfg_pathext - which_hit = shutil.which(resolved_command, path=path_arg) - finally: - if _saved is None: - os.environ.pop("PATHEXT", None) - else: - os.environ["PATHEXT"] = _saved + which_hit = _which_with_config_pathext(resolved_command, path_arg, resolved_env) if which_hit: resolved_command = which_hit elif resolved_command in {"npx", "npm", "node"}: - hermes_home = os.path.expanduser( - os.getenv( - "HERMES_HOME", os.path.join(os.path.expanduser("~"), ".hermes") - ) - ) - candidates = [ - os.path.join(hermes_home, "node", "bin", resolved_command), - os.path.join(os.path.expanduser("~"), ".local", "bin", resolved_command), - # Canonical Node location for from-source Linux builds, the - # Hermes Docker image and Intel Homebrew. Needed when a user's - # hand-authored env.PATH omits it: npx's shebang re-execs - # /usr/bin/env node, so a symlink workaround fails one layer deeper. - os.path.join(os.sep, "usr", "local", "bin", resolved_command), - ] - for candidate in candidates: - if os.path.isfile(candidate) and os.access(candidate, os.X_OK): - resolved_command = candidate - break + resolved_command = _node_fallback(resolved_command) command_dir = os.path.dirname(resolved_command) if command_dir: resolved_env = _prepend_path(resolved_env, command_dir) - return resolved_command, resolved_env def _wrap_command_with_watchdog(command: str, args: list) -> tuple[str, list]: - """Wrap a stdio command in the parent-death watchdog (POSIX only; the - watchdog polls ``getppid()`` against our PID). Unchanged on non-POSIX or - if the PID cannot be read — watchdog bookkeeping must never block a connection.""" + """Wrap a stdio command in the parent-death watchdog (POSIX only — it relies + on process groups, same scope as the killpg-based orphan cleanup; the + watchdog polls ``getppid()`` against our PID). Unchanged on non-POSIX or if + the PID cannot be read — watchdog bookkeeping must never block a connection.""" if os.name != "posix": - # Relies on process groups (getpgid/killpg), same scope as the - # killpg-based orphan cleanup. return command, args try: my_pid = os.getpid() except Exception: return command, args - watchdog_args = [ - os.path.join(os.path.dirname(os.path.abspath(__file__)), "mcp_stdio_watchdog.py"), - "--ppid", str(my_pid), - "--", - command, - *args, - ] - return sys.executable, watchdog_args + watchdog = os.path.join(os.path.dirname(os.path.abspath(__file__)), "mcp_stdio_watchdog.py") + return sys.executable, [watchdog, "--ppid", str(my_pid), "--", command, *args] def _interpolate_env_vars(value): @@ -254,8 +229,7 @@ def _interpolate_env_vars(value): ctx = _context_var_value(m.group(1).strip()) if ctx is not None: return ctx - name = _env_ref_name(m.group(1)) - return _get_secret(name, m.group(0)) or m.group(0) + return _get_secret(_env_ref_name(m.group(1)), m.group(0)) or m.group(0) return _ENV_VAR_PATTERN.sub(_replace, value) if isinstance(value, dict): return {k: _interpolate_env_vars(v) for k, v in value.items()} @@ -301,8 +275,7 @@ def _warn_hidden_whitespace(server_name: str, config: dict) -> List[str]: "trailing whitespace — this often causes authentication or " "connection failures. Check for stray spaces/newlines in " "config.yaml (or the referenced env var).", - server_name, - key_path, + server_name, key_path, ) return flagged @@ -310,30 +283,37 @@ def _warn_hidden_whitespace(server_name: str, config: dict) -> List[str]: def _filter_suspicious_mcp_servers(servers: Dict[str, dict]) -> Dict[str, dict]: """Drop exfiltration-shaped MCP configs before any stdio spawn path.""" try: - from hermes_cli.mcp_security import validate_mcp_server_entry as _validate_mcp_server_entry + from hermes_cli.mcp_security import validate_mcp_server_entry except Exception: - _validate_mcp_server_entry: Callable[[str, dict[str, Any]], list[str]] | None = None - - if _validate_mcp_server_entry is None: return servers safe_servers = {} for name, cfg in servers.items(): - if not isinstance(cfg, dict): - safe_servers[name] = cfg - continue - issues = _validate_mcp_server_entry(name, cfg) + issues = validate_mcp_server_entry(name, cfg) if isinstance(cfg, dict) else None if issues: - logger.warning( - "Skipping suspicious MCP server '%s': %s", - name, - "; ".join(issues), - ) + logger.warning("Skipping suspicious MCP server '%s': %s", name, "; ".join(issues)) continue safe_servers[name] = cfg return safe_servers +def _portable_mcp_servers(safe_servers: Dict[str, dict]) -> None: + """Merge plugin-provided (portable) MCP servers into *safe_servers*; native + config wins on a name clash. Never raises.""" + try: + from hermes_cli.plugins import discover_plugins, get_plugin_manager + + discover_plugins() + portable = get_plugin_manager().get_portable_mcp_servers() + for name, cfg in _core._filter_suspicious_mcp_servers(portable).items(): + if name in safe_servers: + logger.warning("Portable MCP server '%s' conflicts with native config; skipping", name) + continue + safe_servers[name] = dict(cfg) + except Exception: + logger.debug("Failed to load portable MCP servers", exc_info=True) + + def _load_mcp_config() -> Dict[str, dict]: """Read ``mcp_servers`` from config.yaml as ``{name: config}`` (empty on error or in safe mode). Entries carry ``command``/``args``/``env`` (stdio) or @@ -345,8 +325,7 @@ def _load_mcp_config() -> Dict[str, dict]: if _env_enabled("HERMES_SAFE_MODE"): return {} - config = load_config() - servers = config.get("mcp_servers") + servers = load_config().get("mcp_servers") if not isinstance(servers, dict): servers = {} # Ensure .env vars are available for interpolation @@ -361,21 +340,7 @@ def _load_mcp_config() -> Dict[str, dict]: if isinstance(interpolated, dict): _warn_hidden_whitespace(name, interpolated) safe_servers[name] = interpolated - try: - from hermes_cli.plugins import discover_plugins, get_plugin_manager - - discover_plugins() - portable = get_plugin_manager().get_portable_mcp_servers() - for name, cfg in _core._filter_suspicious_mcp_servers(portable).items(): - if name in safe_servers: - logger.warning( - "Portable MCP server '%s' conflicts with native config; skipping", - name, - ) - continue - safe_servers[name] = dict(cfg) - except Exception: - logger.debug("Failed to load portable MCP servers", exc_info=True) + _portable_mcp_servers(safe_servers) return safe_servers except Exception as exc: logger.debug("Failed to load MCP config: %s", exc) diff --git a/tools/mcp_tool_lifecycle.py b/tools/mcp_tool_lifecycle.py index 6be36a732e..023179edc8 100644 --- a/tools/mcp_tool_lifecycle.py +++ b/tools/mcp_tool_lifecycle.py @@ -15,16 +15,12 @@ logger = logging.getLogger("tools.mcp_tool") # removed on normal shutdown, so they can be force-killed if SDK teardown fails. _stdio_pids: Dict[int, str] = {} - # PIDs that survived their session context exit (SDK teardown failed to kill # them); detected in _run_stdio's finally, reaped by _kill_orphaned_mcp_children(). # Kept separate from _stdio_pids so cleanup sweeps never race active sessions. _orphan_stdio_pids: set = set() - - _orphan_stdio_pid_servers: Dict[int, str] = {} - # pid -> pgid captured at spawn. The SDK spawns children with # start_new_session=True (PGID == PID); grandchildren inherit that PGID and # keep it after the direct child exits, so killpg still reaches them. Tracked @@ -96,16 +92,19 @@ def _filter_mcp_children(pids: set) -> set: except (psutil.NoSuchProcess, psutil.AccessDenied, OSError): # Raced away or zombie — cannot be our fresh server, unsafe to track. continue - if any( - marker in arg - for arg in argv[1:] - for marker in _NON_MCP_CHILD_CMDLINE_MARKERS - ): + if any(marker in arg for arg in argv[1:] for marker in _NON_MCP_CHILD_CMDLINE_MARKERS): continue filtered.add(pid) return filtered +def _clear_connect_cooldowns() -> None: + """Drop connect-retry cooldowns: a restart must re-attempt every server + immediately, not honour a stale per-server backoff. Caller holds ``_core._lock``.""" + _core._server_connect_retry_after.clear() + _core._server_connect_failures.clear() + + def shutdown_mcp_servers(*, scope: Optional[str] = None): """Close MCP server connections (in parallel) and stop the background loop. @@ -127,8 +126,7 @@ def shutdown_mcp_servers(*, scope: Optional[str] = None): # most likely state for stale backoff entries; a restart must retry at once. if not servers_snapshot: with _core._lock: - _core._server_connect_retry_after.clear() - _core._server_connect_failures.clear() + _clear_connect_cooldowns() _core._stop_mcp_loop(only_if_idle=scope is not None) return @@ -139,26 +137,19 @@ def shutdown_mcp_servers(*, scope: Optional[str] = None): ) for server, result in zip(servers_snapshot, results): if isinstance(result, Exception): - logger.debug( - "Error closing MCP server '%s': %s", server.name, result, - ) + logger.debug("Error closing MCP server '%s': %s", server.name, result) with _core._lock: for name in selected: _core._servers.pop(name, None) _core._server_scope_keys.pop(name, None) - # Drop connect-retry cooldowns too: a restart must re-attempt every - # server immediately, not honour a stale per-server backoff. - _core._server_connect_retry_after.clear() - _core._server_connect_failures.clear() + _clear_connect_cooldowns() with _core._lock: loop = _core._mcp_loop if loop is not None and loop.is_running(): from agent.async_utils import safe_schedule_threadsafe future = safe_schedule_threadsafe( - _shutdown(), loop, - logger=logger, - log_message="MCP shutdown: failed to schedule", + _shutdown(), loop, logger=logger, log_message="MCP shutdown: failed to schedule", ) if future is not None: try: @@ -169,16 +160,63 @@ def shutdown_mcp_servers(*, scope: Optional[str] = None): # Unconditional final sweep: whether ``_shutdown`` ran, timed out, or was # never scheduled, no stale connect-cooldown state may survive shutdown. with _core._lock: - _core._server_connect_retry_after.clear() - _core._server_connect_failures.clear() - + _clear_connect_cooldowns() _core._stop_mcp_loop(only_if_idle=scope is not None) -def _kill_orphaned_mcp_children( - include_active: bool = False, - server_name: Optional[str] = None, -) -> None: +def _take_reapable_pids(include_active: bool, server_name: Optional[str]) -> tuple[Dict[int, str], Dict[int, int]]: + """Pop the PIDs to reap (and their spawn-time pgids) out of the ledgers under + the lock, so a future spawn can't collide with stale state. + Returns ``(pid -> owner, pid -> pgid)``.""" + def _owned(entries: Dict[int, str]) -> Dict[int, str]: + return {pid: owner for pid, owner in entries.items() if server_name is None or owner == server_name} + + with _core._lock: + pids = _owned({opid: _orphan_stdio_pid_servers.get(opid, "orphan") for opid in _orphan_stdio_pids}) + for opid in pids: + _orphan_stdio_pids.discard(opid) + _orphan_stdio_pid_servers.pop(opid, None) + if include_active: + active = _owned(_stdio_pids) + pids.update(active) + for pid in active: + _stdio_pids.pop(pid, None) + pgids = {pid: _stdio_pgids.pop(pid) for pid in pids if pid in _stdio_pgids} + return pids, pgids + + +def _signal_mcp_process(pid: int, sig: int, server_name: str, pgid: Optional[int], my_pgid: Optional[int]) -> None: + """SIGTERM/SIGKILL via the spawn-time pgroup on POSIX (reaches reparented + grandchildren), falling back to a per-pid signal.""" + killpg = getattr(os, "killpg", None) + if pgid is not None and killpg is not None: + if my_pgid is not None and pgid == my_pgid: + # Child shares the gateway's pgroup: killpg would kill the gateway + # too, so use per-pid kill. Warn because per-pid kill can't reach + # grandchildren in this group (inherent trade-off). + logger.warning( + "MCP server '%s' pgid %d matches gateway pgid; skipping " + "killpg to avoid self-kill and using per-pid kill — any " + "grandchildren in this group may not be reaped", + server_name, pgid, + ) + else: + try: + killpg(pgid, sig) + return + except (ProcessLookupError, PermissionError, OSError) as exc: + # Pgroup gone or refused — still try the direct child. + logger.debug( + "killpg(%d, %d) failed for MCP server '%s': %s; falling back to kill(pid)", + pgid, sig, server_name, exc, + ) + try: + os.kill(pid, sig) + except (ProcessLookupError, PermissionError, OSError): + pass + + +def _kill_orphaned_mcp_children(include_active: bool = False, server_name: Optional[str] = None) -> None: """Best-effort reap of stdio MCP subprocesses: SIGTERM, wait 2s, SIGKILL survivors. By default only ``_orphan_stdio_pids`` (PIDs that outlived their session @@ -186,97 +224,35 @@ def _kill_orphaned_mcp_children( ``include_active=True`` also kills every ``_stdio_pids`` entry and is only for final shutdown after the MCP loop has stopped. ``server_name`` limits the sweep to one server (stdio reconnects cleaning up their old transport). - - On POSIX signals go via ``os.killpg`` to the spawn-time pgid when tracked, - so reparented grandchildren are reaped too; falls back to ``os.kill``. """ import signal as _signal - with _core._lock: - pids: Dict[int, str] = {} - for opid in _orphan_stdio_pids: - owner = _orphan_stdio_pid_servers.get(opid, "orphan") - if server_name is not None and owner != server_name: - continue - pids[opid] = owner - for opid in pids: - _orphan_stdio_pids.discard(opid) - _orphan_stdio_pid_servers.pop(opid, None) - if include_active: - active = dict(_stdio_pids) - if server_name is not None: - active = { - pid: owner - for pid, owner in active.items() - if owner == server_name - } - pids.update(active) - for pid in active: - _stdio_pids.pop(pid, None) - # Snapshot pgids for the pids we're about to kill, then drop them so a - # future spawn can't collide with stale state. - pgids: Dict[int, int] = {pid: _stdio_pgids[pid] for pid in pids if pid in _stdio_pgids} - for pid in pgids: - _stdio_pgids.pop(pid, None) - + pids, pgids = _take_reapable_pids(include_active, server_name) # Fast path: nothing to reap — skip the 2s sleep every MCP-free shutdown # would otherwise pay. if not pids: return - # Our own pgid, so _send_signal never killpg()s the gateway itself. + # Our own pgid, so we never killpg() the gateway itself. try: - _my_pgid = os.getpgrp() + my_pgid = os.getpgrp() except (AttributeError, OSError): - _my_pgid = None # Windows or restricted environment + my_pgid = None # Windows or restricted environment - def _send_signal(pid: int, sig: int, server_name: str) -> None: - """SIGTERM/SIGKILL via pgroup on POSIX, fall back to pid signal.""" - pgid = pgids.get(pid) - killpg = getattr(os, "killpg", None) - if pgid is not None and killpg is not None: - if _my_pgid is not None and pgid == _my_pgid: - # Child shares the gateway's pgroup: killpg would kill the - # gateway too, so use per-pid kill. Warn because per-pid kill - # can't reach grandchildren in this group (inherent trade-off). - logger.warning( - "MCP server '%s' pgid %d matches gateway pgid; skipping " - "killpg to avoid self-kill and using per-pid kill — any " - "grandchildren in this group may not be reaped", - server_name, pgid, - ) - else: - try: - killpg(pgid, sig) - return - except (ProcessLookupError, PermissionError, OSError) as exc: - # Pgroup gone or refused — still try the direct child. - logger.debug( - "killpg(%d, %d) failed for MCP server '%s': %s; falling back to kill(pid)", - pgid, sig, server_name, exc, - ) - try: - os.kill(pid, sig) - except (ProcessLookupError, PermissionError, OSError): - pass - - for pid, server_name in pids.items(): - _send_signal(pid, _signal.SIGTERM, server_name) - logger.debug("Sent SIGTERM to orphaned MCP process %d (%s)", pid, server_name) + for pid, owner in pids.items(): + _signal_mcp_process(pid, _signal.SIGTERM, owner, pgids.get(pid), my_pgid) + logger.debug("Sent SIGTERM to orphaned MCP process %d (%s)", pid, owner) time.sleep(2) - _sigkill = getattr(_signal, "SIGKILL", _signal.SIGTERM) + sigkill = getattr(_signal, "SIGKILL", _signal.SIGTERM) # ``os.kill(pid, 0)`` is NOT a no-op on Windows; use the portable check. from gateway.status import _pid_exists - for pid, server_name in pids.items(): + for pid, owner in pids.items(): if not _pid_exists(pid): continue # exited after SIGTERM - _send_signal(pid, _sigkill, server_name) - logger.warning( - "Force-killed MCP process %d (%s) after SIGTERM timeout", - pid, server_name, - ) + _signal_mcp_process(pid, sigkill, owner, pgids.get(pid), my_pgid) + logger.warning("Force-killed MCP process %d (%s) after SIGTERM timeout", pid, owner) def _stop_mcp_loop_if_idle() -> bool: @@ -290,10 +266,7 @@ def _stop_mcp_loop_if_idle() -> bool: return _core._stop_mcp_loop(only_if_idle=True) -async def _drain_mcp_loop_tasks( - *, - timeout: Optional[float] = None, -) -> None: +async def _drain_mcp_loop_tasks(*, timeout: Optional[float] = None) -> None: """Cancel every task still pending on the MCP loop and reap it. ``Task.cancel()`` only schedules the throw, so tasks need a cancellation @@ -322,10 +295,7 @@ async def _drain_mcp_loop_tasks( logger.debug("Pending MCP loop task ended during shutdown: %s", exc) if still_pending: - logger.warning( - "%d MCP loop task(s) still pending after %.1fs drain", - len(still_pending), timeout, - ) + logger.warning("%d MCP loop task(s) still pending after %.1fs drain", len(still_pending), timeout) async def _drain_and_stop_mcp_loop() -> None: diff --git a/tools/mcp_tool_schema.py b/tools/mcp_tool_schema.py index db8f43472b..9afe0ad953 100644 --- a/tools/mcp_tool_schema.py +++ b/tools/mcp_tool_schema.py @@ -15,144 +15,113 @@ logger = logging.getLogger("tools.mcp_tool") # Prompt-injection indicators in MCP tool descriptions. WARNING-level only: # log but never block, since false positives would break legitimate servers. _MCP_INJECTION_PATTERNS = [ - (re.compile(r"ignore\s+(all\s+)?previous\s+instructions", re.I), - "prompt override attempt ('ignore previous instructions')"), - (re.compile(r"you\s+are\s+now\s+a", re.I), - "identity override attempt ('you are now a...')"), - (re.compile(r"your\s+new\s+(task|role|instructions?)\s+(is|are)", re.I), - "task override attempt"), - (re.compile(r"system\s*:\s*", re.I), - "system prompt injection attempt"), - (re.compile(r"<\s*(system|human|assistant)\s*>", re.I), - "role tag injection attempt"), - (re.compile(r"do\s+not\s+(tell|inform|mention|reveal)", re.I), - "concealment instruction"), - (re.compile(r"(curl|wget|fetch)\s+https?://", re.I), - "network command in description"), - (re.compile(r"base64\.(b64decode|decodebytes)", re.I), - "base64 decode reference"), - (re.compile(r"exec\s*\(|eval\s*\(", re.I), - "code execution reference"), - (re.compile(r"import\s+(subprocess|os|shutil|socket)", re.I), - "dangerous import reference"), + (re.compile(pattern, re.I), reason) + for pattern, reason in ( + (r"ignore\s+(all\s+)?previous\s+instructions", "prompt override attempt ('ignore previous instructions')"), + (r"you\s+are\s+now\s+a", "identity override attempt ('you are now a...')"), + (r"your\s+new\s+(task|role|instructions?)\s+(is|are)", "task override attempt"), + (r"system\s*:\s*", "system prompt injection attempt"), + (r"<\s*(system|human|assistant)\s*>", "role tag injection attempt"), + (r"do\s+not\s+(tell|inform|mention|reveal)", "concealment instruction"), + (r"(curl|wget|fetch)\s+https?://", "network command in description"), + (r"base64\.(b64decode|decodebytes)", "base64 decode reference"), + (r"exec\s*\(|eval\s*\(", "code execution reference"), + (r"import\s+(subprocess|os|shutil|socket)", "dangerous import reference"), + ) ] def _scan_mcp_description(server_name: str, tool_name: str, description: str) -> List[str]: """Scan a tool description for injection patterns; returns finding strings (empty = clean) and logs a warning when any match.""" - findings = [] if not description: - return findings - for pattern, reason in _MCP_INJECTION_PATTERNS: - if pattern.search(description): - findings.append(reason) + return [] + findings = [reason for pattern, reason in _MCP_INJECTION_PATTERNS if pattern.search(description)] if findings: logger.warning( - "MCP server '%s' tool '%s': suspicious description content — %s. " - "Description: %.200s", - server_name, tool_name, "; ".join(findings), - description, + "MCP server '%s' tool '%s': suspicious description content — %s. Description: %.200s", + server_name, tool_name, "; ".join(findings), description, ) return findings +_EMPTY_OBJECT_SCHEMA = {"type": "object", "properties": {}} + + +def _rewrite_local_refs(node): + """Promote legacy ``definitions`` to ``$defs`` (Moonshot rejects the draft-07 + form) — but ONLY where it is a JSON Schema meta-keyword, never as a property + NAME inside ``properties``/``patternProperties``. A tool parameter + legitimately named ``definitions`` rewritten to ``$defs`` would 400 the whole + tool array (Anthropic/OpenAI forbid ``$`` in property names). Property names + are kept verbatim and recursion resumes ordinary semantics inside each + property's schema.""" + if isinstance(node, list): + return [_rewrite_local_refs(item) for item in node] + if not isinstance(node, dict): + return node + normalized = {} + for key, value in node.items(): + if key in ("properties", "patternProperties") and isinstance(value, dict): + normalized[key] = {name: _rewrite_local_refs(schema) for name, schema in value.items()} + else: + normalized["$defs" if key == "definitions" else key] = _rewrite_local_refs(value) + ref = normalized.get("$ref") + if isinstance(ref, str) and ref.startswith("#/definitions/"): + normalized["$ref"] = "#/$defs/" + ref[len("#/definitions/"):] + return normalized + + +def _repair_object_shape(node): + """Recursively fill a missing object ``type``, ensure ``properties`` (so + ``required`` can't dangle) and prune ``required`` to names present in + ``properties`` (Gemini 400s otherwise).""" + if isinstance(node, list): + return [_repair_object_shape(item) for item in node] + if not isinstance(node, dict): + return node + repaired = {k: _repair_object_shape(v) for k, v in node.items()} + if not repaired.get("type") and ("properties" in repaired or "required" in repaired): + repaired["type"] = "object" + if repaired.get("type") == "object": + if not isinstance(repaired.get("properties"), dict): + repaired["properties"] = {} + required = repaired.get("required") + if isinstance(required, list): + props = repaired.get("properties") or {} + valid = [r for r in required if isinstance(r, str) and r in props] + if len(valid) != len(required): + if valid: + repaired["required"] = valid + else: + repaired.pop("required", None) + return repaired + + def _normalize_mcp_input_schema(schema: dict | None) -> dict: """Normalize MCP input schemas so one form is valid on OpenAI, Anthropic, Gemini and Moonshot. - Repairs, applied recursively: ``definitions``/``#/definitions/`` refs -> - ``$defs`` (Moonshot rejects the draft-07 form); missing/null ``type`` on an - object-shaped node -> ``"object"``; an object without ``properties`` gets an - empty one so ``required`` can't dangle; ``required`` pruned to names present - in ``properties`` (Gemini 400s otherwise); nullable ``anyOf`` unions - collapsed to the non-null branch (Anthropic rejects nullable branches), - optionality living solely in the parent's ``required``. + Order matters: ``definitions`` -> ``$defs`` rewrite; nullable ``anyOf`` + unions collapsed to the non-null branch (Anthropic rejects nullable + branches; optionality lives solely in the parent's ``required``, the + ``nullable: true`` hint is kept so runtime coercion can still map a + model-emitted ``"null"`` string to ``None``); same-typed const unions -> + enum (must run AFTER the nullable strip); then object-shape repair. """ if not schema: - return {"type": "object", "properties": {}} - - def _rewrite_local_refs(node): - """Promote legacy ``definitions`` to ``$defs`` — but ONLY where it is a - JSON Schema meta-keyword, never as a property NAME inside ``properties``/ - ``patternProperties``. A tool parameter legitimately named ``definitions`` - rewritten to ``$defs`` would 400 the whole tool array (Anthropic/OpenAI - forbid ``$`` in property names). Property names are kept verbatim and - recursion resumes ordinary semantics inside each property's schema.""" - if isinstance(node, dict): - normalized = {} - for key, value in node.items(): - if key in ("properties", "patternProperties") and isinstance(value, dict): - normalized[key] = { - prop_name: _rewrite_local_refs(prop_schema) - for prop_name, prop_schema in value.items() - } - else: - out_key = "$defs" if key == "definitions" else key - normalized[out_key] = _rewrite_local_refs(value) - ref = normalized.get("$ref") - if isinstance(ref, str) and ref.startswith("#/definitions/"): - normalized["$ref"] = "#/$defs/" + ref[len("#/definitions/"):] - return normalized - if isinstance(node, list): - return [_rewrite_local_refs(item) for item in node] - return node - - def _strip_nullable_union(node): - """Shared implementation with the Anthropic guard and global sanitizer. - Keeps the ``nullable: true`` hint so runtime coercion can still map a - model-emitted ``"null"`` string to ``None``.""" - from tools.schema_sanitizer import strip_nullable_unions - - return strip_nullable_unions(node, keep_nullable_hint=True) - - def _collapse_const_unions(node): - """Collapse anyOf/oneOf unions of same-typed consts to enums. Must run - AFTER the nullable strip: consts -> enum, null branch -> ``nullable`` hint.""" - from tools.schema_sanitizer import collapse_const_unions - - return collapse_const_unions(node) - - def _repair_object_shape(node): - """Recursively fill missing object ``type``, ensure ``properties``, prune ``required``.""" - if isinstance(node, list): - return [_repair_object_shape(item) for item in node] - if not isinstance(node, dict): - return node - - repaired = {k: _repair_object_shape(v) for k, v in node.items()} - - if not repaired.get("type") and ( - "properties" in repaired or "required" in repaired - ): - repaired["type"] = "object" - - if repaired.get("type") == "object": - if not isinstance(repaired.get("properties"), dict): - repaired["properties"] = {} - - required = repaired.get("required") - if isinstance(required, list): - props = repaired.get("properties") or {} - valid = [r for r in required if isinstance(r, str) and r in props] - if len(valid) != len(required): - if valid: - repaired["required"] = valid - else: - repaired.pop("required", None) - - return repaired + return dict(_EMPTY_OBJECT_SCHEMA) + from tools.schema_sanitizer import collapse_const_unions, strip_nullable_unions normalized = _rewrite_local_refs(schema) - normalized = _strip_nullable_union(normalized) - normalized = _collapse_const_unions(normalized) + normalized = strip_nullable_unions(normalized, keep_nullable_hint=True) + normalized = collapse_const_unions(normalized) normalized = _repair_object_shape(normalized) if not isinstance(normalized, dict): - return {"type": "object", "properties": {}} + return dict(_EMPTY_OBJECT_SCHEMA) if normalized.get("type") == "object" and "properties" not in normalized: normalized = {**normalized, "properties": {}} - return normalized @@ -166,16 +135,12 @@ def sanitize_mcp_name_component(value: str) -> str: # OpenCode. The double underscore disambiguates the server/tool boundary even # when either contains underscores, and matches the Anthropic-OAuth wire form. MCP_TOOL_NAME_PREFIX = "mcp__" - - _MCP_NAME_DELIM = "__" def mcp_prefixed_tool_name(server_name: str, tool_name: str) -> str: """Registry/wire name: ``mcp____``.""" - safe_server = sanitize_mcp_name_component(server_name) - safe_tool = sanitize_mcp_name_component(tool_name) - return f"{MCP_TOOL_NAME_PREFIX}{safe_server}{_MCP_NAME_DELIM}{safe_tool}" + return f"{MCP_TOOL_NAME_PREFIX}{sanitize_mcp_name_component(server_name)}{_MCP_NAME_DELIM}{sanitize_mcp_name_component(tool_name)}" def _convert_mcp_schema(server_name: str, mcp_tool) -> dict: @@ -183,81 +148,48 @@ def _convert_mcp_schema(server_name: str, mcp_tool) -> dict: mcp 2.0) to a ``registry.register(schema=...)`` dict.""" return { "name": mcp_prefixed_tool_name(server_name, mcp_tool.name), - "description": strip_unicode_tags( - mcp_tool.description or f"MCP tool {mcp_tool.name} from {server_name}" - ), - "parameters": _normalize_mcp_input_schema( - mcp_field(mcp_tool, "input_schema", "inputSchema") - ), + "description": strip_unicode_tags(mcp_tool.description or f"MCP tool {mcp_tool.name} from {server_name}"), + "parameters": _normalize_mcp_input_schema(mcp_field(mcp_tool, "input_schema", "inputSchema")), } +# Utility tools generated per server: handler_key -> (description template, +# parameter properties, required names). Schemas are FROZEN wire bytes — the +# key order emitted by ``_build_utility_schemas`` must not change. +_UTILITY_TOOL_SPECS = ( + ("list_resources", "List available resources from MCP server '{server}'", {}, None), + ("read_resource", "Read a resource by URI from MCP server '{server}'", + {"uri": {"type": "string", "description": "URI of the resource to read"}}, ["uri"]), + ("list_prompts", "List available prompts from MCP server '{server}'", {}, None), + ("get_prompt", "Get a prompt by name from MCP server '{server}'", + { + "name": {"type": "string", "description": "Name of the prompt to retrieve"}, + "arguments": { + "type": "object", + "description": "Optional arguments to pass to the prompt", + "properties": {}, + "additionalProperties": True, + }, + }, ["name"]), +) + + def _build_utility_schemas(server_name: str) -> List[dict]: """Schemas for the resource/prompt utility tools as ``{schema, handler_key}`` dicts.""" - return [ - { + out = [] + for handler_key, description, properties, required in _UTILITY_TOOL_SPECS: + parameters = {"type": "object", "properties": {k: dict(v) for k, v in properties.items()}} + if required is not None: + parameters["required"] = list(required) + out.append({ "schema": { - "name": mcp_prefixed_tool_name(server_name, "list_resources"), - "description": f"List available resources from MCP server '{server_name}'", - "parameters": { - "type": "object", - "properties": {}, - }, + "name": mcp_prefixed_tool_name(server_name, handler_key), + "description": description.format(server=server_name), + "parameters": parameters, }, - "handler_key": "list_resources", - }, - { - "schema": { - "name": mcp_prefixed_tool_name(server_name, "read_resource"), - "description": f"Read a resource by URI from MCP server '{server_name}'", - "parameters": { - "type": "object", - "properties": { - "uri": { - "type": "string", - "description": "URI of the resource to read", - }, - }, - "required": ["uri"], - }, - }, - "handler_key": "read_resource", - }, - { - "schema": { - "name": mcp_prefixed_tool_name(server_name, "list_prompts"), - "description": f"List available prompts from MCP server '{server_name}'", - "parameters": { - "type": "object", - "properties": {}, - }, - }, - "handler_key": "list_prompts", - }, - { - "schema": { - "name": mcp_prefixed_tool_name(server_name, "get_prompt"), - "description": f"Get a prompt by name from MCP server '{server_name}'", - "parameters": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the prompt to retrieve", - }, - "arguments": { - "type": "object", - "description": "Optional arguments to pass to the prompt", - "properties": {}, - "additionalProperties": True, - }, - }, - "required": ["name"], - }, - }, - "handler_key": "get_prompt", - }, - ] + "handler_key": handler_key, + }) + return out def _normalize_name_filter(value: Any, label: str) -> set[str]: @@ -280,20 +212,12 @@ def matches_name_filter(tool_name: str, patterns: set[str]) -> bool: return False if tool_name in patterns: return True - return any( - fnmatch.fnmatchcase(tool_name, p) - for p in patterns - if "*" in p or "?" in p or "[" in p - ) + return any(fnmatch.fnmatchcase(tool_name, p) for p in patterns if "*" in p or "?" in p or "[" in p) -_UTILITY_CAPABILITY_METHODS = { - "list_resources": "list_resources", - "read_resource": "read_resource", - "list_prompts": "list_prompts", - "get_prompt": "get_prompt", -} - +# Utility handler -> ClientSession method it needs (legacy gate when no +# initialize_result was captured). +_UTILITY_CAPABILITY_METHODS = {key: key for key, *_ in _UTILITY_TOOL_SPECS} # Utility handler -> capability key that must be non-None on the server's # ``initialize`` response for the handler to be registered. Without this gate a From f59fb2e2922905ab046503fa15d6a3a61cf76311 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 2 Sep 2026 15:51:24 -0700 Subject: [PATCH 3/9] refactor(mcp): tighten registration candidates and sampling handler; drop dead _extract_tool_result_text --- tools/mcp_tool_registration.py | 294 ++++++++++++--------------------- tools/mcp_tool_sampling.py | 29 ++-- 2 files changed, 116 insertions(+), 207 deletions(-) diff --git a/tools/mcp_tool_registration.py b/tools/mcp_tool_registration.py index 3201fc5e6b..ecdfa24bb6 100644 --- a/tools/mcp_tool_registration.py +++ b/tools/mcp_tool_registration.py @@ -3,8 +3,8 @@ registry: include/exclude filtering, trust-tier metadata capture, utility-tool selection, name-collision resolution and the schema-cache write-through. Both entry points (``_register_server_tools`` for a live server, -``_register_from_cache_sync`` for a lazy cached manifest) build a list of -``_Candidate`` records and hand them to the single ``_register_candidates`` loop.""" +``_register_from_cache_sync`` for a lazy cached manifest) build ``_Candidate`` +records and feed the single ``_register_candidates`` loop.""" import logging from dataclasses import dataclass @@ -19,7 +19,6 @@ if TYPE_CHECKING: # pragma: no cover logger = logging.getLogger("tools.mcp_tool") _UTILITY_ORIGIN_PREFIX = "generated utility " - # Utility tool key -> handler factory; each takes (server_name, tool_timeout). _UTILITY_HANDLER_FACTORIES = { "list_resources": _make_list_resources_handler, @@ -30,37 +29,32 @@ _UTILITY_HANDLER_FACTORIES = { def _normalize_server_trust(value: Any) -> str: - """Normalize a config ``trust`` value: None -> ``full`` (backward-compatible - default); any unrecognized string -> ``untrusted``, so a misspelled tier - fails closed rather than silently disabling gating.""" + """Config ``trust`` -> tier. None -> ``full`` (backward-compatible default); + an unrecognized string -> ``untrusted`` so a misspelled tier fails closed.""" if value is None: return _core._TRUST_FULL text = str(value).strip().lower() if text in (_core._TRUST_FULL, _core._TRUST_UNTRUSTED): return text logger.warning( - "MCP trust: unrecognized trust value %r — treating as 'untrusted' " - "(valid values: full, untrusted)", value, + "MCP trust: unrecognized trust value %r — treating as 'untrusted' (valid values: full, untrusted)", value, ) return _core._TRUST_UNTRUSTED def _annotation_read_only_hint(mcp_tool: Any) -> bool: """True only when annotations (SDK object or schema-cache dict) carry - ``readOnlyHint is True``; anything else is False — unknown metadata means - the tool must be treated as write-capable.""" + ``readOnlyHint is True``; unknown metadata means write-capable.""" annotations = getattr(mcp_tool, "annotations", None) - if annotations is None: - return False if isinstance(annotations, dict): return annotations.get("readOnlyHint") is True return getattr(annotations, "readOnlyHint", None) is True def _record_tool_trust_metadata(server_name: str, config: dict, tools: List[Any]) -> None: - """Capture per-server trust and per-tool readOnlyHint at discovery (the + """Capture per-server trust and per-tool readOnlyHint at discovery — the security boundary: the call-time gate classifies from data we control, - never re-read server-supplied state).""" + never re-read server-supplied state.""" with _core._lock: _core._server_trust_levels[server_name] = _normalize_server_trust((config or {}).get("trust")) hints = _core._tool_read_only_hints.setdefault(server_name, {}) @@ -83,74 +77,59 @@ def _forget_mcp_tool_server(tool_name: str) -> None: def _select_utility_schemas(server_name: str, server: "MCPServerTask", config: dict) -> List[dict]: - """Select utility schemas based on config and server capabilities.""" + """Utility schemas allowed by config (``tools.resources``/``tools.prompts``) + and by the server's advertised capabilities. + + ``initialize_result.capabilities`` is the source of truth: its sub-objects are + non-None iff the server advertises that request family (the old + ``hasattr(server.session, ...)`` gate never filtered anything — ClientSession + defines all four methods). When no initialize_result was captured (test + fixtures, older paths) fall back to that legacy session-method check.""" tools_filter = config.get("tools") or {} - family_enabled = { - family: _parse_boolish(tools_filter.get(family), default=True) - for family in ("resources", "prompts") - } - # ``initialize_result.capabilities`` is the source of truth: its sub-objects - # are non-None iff the server advertises that request family. The old - # ``hasattr(server.session, ...)`` gate never filtered anything because - # ClientSession defines all four methods on the class. + enabled = {f: _parse_boolish(tools_filter.get(f), default=True) for f in ("resources", "prompts")} init_result = getattr(server, "initialize_result", None) - advertised_caps = getattr(init_result, "capabilities", None) if init_result is not None else None + advertised = getattr(init_result, "capabilities", None) if init_result is not None else None + + def _skip_reason(handler_key: str) -> Optional[str]: + family = _UTILITY_CAPABILITY_ATTRS[handler_key] + if not enabled[family]: + return f"{family} disabled" + if advertised is not None: + return None if getattr(advertised, family, None) is not None else f"server does not advertise '{family}' capability" + method = _UTILITY_CAPABILITY_METHODS[handler_key] + return None if hasattr(server.session, method) else f"session lacks {method}" selected: List[dict] = [] for entry in _build_utility_schemas(server_name): - handler_key = entry["handler_key"] - family = _UTILITY_CAPABILITY_ATTRS[handler_key] - if not family_enabled[family]: - logger.debug("MCP server '%s': skipping utility '%s' (%s disabled)", server_name, handler_key, family) - continue - if advertised_caps is not None: - if getattr(advertised_caps, family, None) is None: - logger.debug( - "MCP server '%s': skipping utility '%s' (server does not advertise '%s' capability)", - server_name, handler_key, family, - ) - continue - # Legacy fallback when initialize_result wasn't captured (test - # fixtures, older paths): register every stub the session can serve. - elif not hasattr(server.session, _UTILITY_CAPABILITY_METHODS[handler_key]): - logger.debug( - "MCP server '%s': skipping utility '%s' (session lacks %s)", - server_name, handler_key, _UTILITY_CAPABILITY_METHODS[handler_key], - ) + reason = _skip_reason(entry["handler_key"]) + if reason: + logger.debug("MCP server '%s': skipping utility '%s' (%s)", server_name, entry["handler_key"], reason) continue selected.append(entry) return selected def _existing_tool_names() -> List[str]: - """Return tool names for all currently connected servers.""" + """Tool names for all currently connected servers plus lazy (cache-registered) + servers, whose tools live only in the registry.""" names: List[str] = [] for _sname, server in _core._servers.items(): if hasattr(server, "_registered_tool_names"): names.extend(server._registered_tool_names) - continue - for mcp_tool in server._tools: - names.append(_core._convert_mcp_schema(server.name, mcp_tool)["name"]) - # Lazy servers registered from the schema cache have no MCPServerTask yet — - # their tools live only in the registry. + else: + names.extend(_core._convert_mcp_schema(server.name, t)["name"] for t in server._tools) with _core._lock: names.extend( - n - for sname, tool_names in _core._lazy_server_tool_names.items() - if sname not in _core._servers - for n in tool_names + n for sname, tool_names in _core._lazy_server_tool_names.items() + if sname not in _core._servers for n in tool_names ) return names def _make_tool_filter(name: str, config: dict) -> Callable[[str], bool]: - """Build the include/exclude predicate for a server's tool names. - - Rules: ``tools.include`` is a whitelist, ``tools.exclude`` a blacklist; - entries may be exact names or fnmatch globs; include wins over exclude; - ``include: []`` is an explicit empty whitelist (register nothing); neither - set registers everything. - """ + """Include/exclude predicate for a server's tool names: ``tools.include`` is a + whitelist (``[]`` = register nothing), ``tools.exclude`` a blacklist; entries + are exact names or fnmatch globs; include wins over exclude.""" tools_filter = config.get("tools") or {} include_raw = tools_filter.get("include") include_set = _normalize_name_filter(include_raw, f"mcp_servers.{name}.tools.include") @@ -160,17 +139,14 @@ def _make_tool_filter(name: str, config: dict) -> Callable[[str], bool]: def _should_register(tool_name: str) -> bool: if include_active: return matches_name_filter(tool_name, include_set) - if exclude_set: - return not matches_name_filter(tool_name, exclude_set) - return True + return not (exclude_set and matches_name_filter(tool_name, exclude_set)) return _should_register class _CachedMCPTool: - """Minimal stand-in for MCP Tool objects loaded from the schema cache. - Missing/non-dict ``annotations`` (older cache files) fail closed to - write-capable via ``_annotation_read_only_hint``.""" + """Stand-in for MCP Tool objects loaded from the schema cache. Missing or + non-dict ``annotations`` (older cache files) fail closed to write-capable.""" __slots__ = ("name", "description", "inputSchema", "annotations") @@ -182,26 +158,19 @@ class _CachedMCPTool: @classmethod def from_cache_dicts(cls, raws: Iterable[Any]) -> List["_CachedMCPTool"]: - """Cached tool rows -> stand-ins; rows that are not dicts or lack a name are dropped.""" - tools = [] + """Cached rows -> stand-ins; rows that are not dicts or lack a name are dropped.""" + out = [] for raw in raws: - if not isinstance(raw, dict) or not raw.get("name"): - continue - schema = raw.get("inputSchema") - tools.append(cls( - raw["name"], - raw.get("description") or "", - schema if isinstance(schema, dict) else {}, - raw.get("annotations"), - )) - return tools + if isinstance(raw, dict) and raw.get("name"): + schema = raw.get("inputSchema") + out.append(cls(raw["name"], raw.get("description") or "", schema if isinstance(schema, dict) else {}, raw.get("annotations"))) + return out @dataclass class _Candidate: - """One registry registration attempt for a server: a native tool or a - generated utility. ``origin`` is the human-readable provenance used in - collision diagnostics.""" + """One registration attempt: a native tool or a generated utility. + ``origin`` is the provenance text used in collision diagnostics.""" registry_name: str origin: str @@ -212,62 +181,46 @@ class _Candidate: def is_utility(self) -> bool: return self.origin.startswith(_UTILITY_ORIGIN_PREFIX) - @property - def description(self) -> str: - return self.schema.get("description") or "" - def _tool_candidates(name: str, tools: Iterable[Any], should_register: Callable[[str], bool], tool_timeout) -> List[_Candidate]: - """Native tools (live SDK objects or ``_CachedMCPTool``) -> candidates. - The description scan runs on BOTH paths: the cache file is user-writable JSON.""" - candidates: List[_Candidate] = [] - for mcp_tool in tools: - if not should_register(mcp_tool.name): - logger.debug("MCP server '%s': skipping tool '%s' (filtered by config)", name, mcp_tool.name) + """Native tools (live SDK objects or ``_CachedMCPTool``) -> candidates. The + injection scan runs on BOTH paths: the cache file is user-writable JSON.""" + out: List[_Candidate] = [] + for t in tools: + if not should_register(t.name): + logger.debug("MCP server '%s': skipping tool '%s' (filtered by config)", name, t.name) continue - _core._scan_mcp_description(name, mcp_tool.name, mcp_tool.description or "") - schema = _core._convert_mcp_schema(name, mcp_tool) - candidates.append(_Candidate( - schema["name"], f"tool {mcp_tool.name!r}", schema, - _core._make_tool_handler(name, mcp_tool.name, tool_timeout), - )) - return candidates + _core._scan_mcp_description(name, t.name, t.description or "") + schema = _core._convert_mcp_schema(name, t) + out.append(_Candidate(schema["name"], f"tool {t.name!r}", schema, _core._make_tool_handler(name, t.name, tool_timeout))) + return out def _utility_candidates(name: str, entries: Iterable[Any], tool_timeout) -> List[_Candidate]: - """``{schema, handler_key}`` rows (live selection or cache) -> candidates; - malformed rows are dropped.""" - candidates: List[_Candidate] = [] + """``{schema, handler_key}`` rows (live selection or cache) -> candidates; malformed rows dropped.""" + out: List[_Candidate] = [] for raw in entries: if not isinstance(raw, dict): continue - schema, handler_key = raw.get("schema"), raw.get("handler_key") - if not isinstance(schema, dict) or handler_key not in _UTILITY_HANDLER_FACTORIES or not schema.get("name"): - continue - candidates.append(_Candidate( - schema["name"], f"{_UTILITY_ORIGIN_PREFIX}{handler_key!r}", schema, - _UTILITY_HANDLER_FACTORIES[handler_key](name, tool_timeout), - )) - return candidates + schema, key = raw.get("schema"), raw.get("handler_key") + if isinstance(schema, dict) and key in _UTILITY_HANDLER_FACTORIES and schema.get("name"): + out.append(_Candidate(schema["name"], f"{_UTILITY_ORIGIN_PREFIX}{key!r}", schema, _UTILITY_HANDLER_FACTORIES[key](name, tool_timeout))) + return out def _resolve_name_collisions(name: str, candidates: List[_Candidate]) -> List[_Candidate]: """Preflight registry-name collisions among one server's candidates. - Exact duplicate rows (same name + origin) are dropped silently; a generated + Exact duplicates (same name + origin) are dropped silently; a generated utility that normalizes onto a server-native tool's name is shadowed (the native tool wins); any other multi-origin collision is ambiguous and every - colliding entry is skipped (fail closed). Returns the survivors in order. - """ + colliding entry is skipped (fail closed). Returns the survivors in order.""" unique: List[_Candidate] = [] seen: set[tuple[str, str]] = set() origins_by_name: Dict[str, set[str]] = {} for c in candidates: if (c.registry_name, c.origin) in seen: - logger.debug( - "MCP server '%s': duplicate registration candidate %s for '%s'; keeping one", - name, c.origin, c.registry_name, - ) + logger.debug("MCP server '%s': duplicate registration candidate %s for '%s'; keeping one", name, c.origin, c.registry_name) continue seen.add((c.registry_name, c.origin)) unique.append(c) @@ -283,57 +236,44 @@ def _resolve_name_collisions(name: str, candidates: List[_Candidate]) -> List[_C if len(native_origins) == 1 and utility_origins: shadowed.update((registry_name, o) for o in utility_origins) logger.info( - "MCP server '%s': generated utility %s normalizes onto " - "server-native %s — keeping the native tool and dropping the " - "utility (the utility only applies when the server has no such " - "tool of its own)", + "MCP server '%s': generated utility %s normalizes onto server-native %s — keeping the " + "native tool and dropping the utility (the utility only applies when the server has no " + "such tool of its own)", name, ", ".join(utility_origins), native_origins[0], ) continue ambiguous[registry_name] = sorted(origins) - for registry_name, origins in sorted(ambiguous.items()): logger.error( - "MCP server '%s': name normalization collision for '%s' from %s; " - "skipping every colliding entry instead of choosing an arbitrary handler", + "MCP server '%s': name normalization collision for '%s' from %s; skipping every colliding " + "entry instead of choosing an arbitrary handler", name, registry_name, ", ".join(origins), ) - return [ - c for c in unique - if c.registry_name not in ambiguous and (c.registry_name, c.origin) not in shadowed - ] + return [c for c in unique if c.registry_name not in ambiguous and (c.registry_name, c.origin) not in shadowed] def _log_foreign_owner(name: str, c: _Candidate, existing_toolset: str, lazy: bool) -> None: - """Diagnostics for a candidate whose registry name is already owned by - another toolset (skipped to preserve the existing owner).""" + """Diagnostics for a name already owned by another toolset (skipped to preserve the owner).""" if lazy: if not c.is_utility: - logger.warning( - "MCP server '%s' (lazy): cached tool '%s' collides with toolset '%s' — skipping", - name, c.registry_name, existing_toolset, - ) + logger.warning("MCP server '%s' (lazy): cached tool '%s' collides with toolset '%s' — skipping", name, c.registry_name, existing_toolset) elif existing_toolset.startswith("mcp-"): logger.error( - "MCP server '%s': %s normalizes to '%s', already owned by MCP toolset '%s' " - "— skipping to preserve the existing owner", + "MCP server '%s': %s normalizes to '%s', already owned by MCP toolset '%s' — skipping to preserve the existing owner", name, c.origin, c.registry_name, existing_toolset, ) else: logger.warning( - "MCP server '%s': %s (→ '%s') collides with built-in tool in toolset '%s' " - "— skipping to preserve built-in", + "MCP server '%s': %s (→ '%s') collides with built-in tool in toolset '%s' — skipping to preserve built-in", name, c.origin, c.registry_name, existing_toolset, ) -def _register_candidates( - name: str, candidates: List[_Candidate], *, check_fn: Callable, scope: Callable[[], Optional[str]], lazy: bool, -) -> List[str]: +def _register_candidates(name: str, candidates: List[_Candidate], *, check_fn: Callable, scope: Callable[[], Optional[str]], lazy: bool) -> List[str]: """Register candidates under toolset ``mcp-{name}``; returns the names that - actually landed. The ownership pre-check is advisory only — multiple - servers connect in parallel, so ``ToolRegistry.register()`` is the atomic - ownership gate and its verdict is re-read after every call.""" + landed. The ownership pre-check is advisory only — servers connect in + parallel, so ``ToolRegistry.register()`` is the atomic ownership gate and + its verdict is re-read after every call.""" from tools.registry import registry toolset_name = f"mcp-{name}" @@ -344,26 +284,18 @@ def _register_candidates( _log_foreign_owner(name, c, existing_toolset, lazy) continue registry.register( - name=c.registry_name, - toolset=toolset_name, - schema=c.schema, - handler=c.handler, - check_fn=check_fn, - is_async=False, - description=c.description, - scope=scope(), + name=c.registry_name, toolset=toolset_name, schema=c.schema, handler=c.handler, check_fn=check_fn, + is_async=False, description=c.schema.get("description") or "", scope=scope(), ) if registry.get_toolset_for_tool(c.registry_name) != toolset_name: if not lazy: logger.error( - "MCP server '%s': registration of %s as '%s' was rejected by " - "the registry; skipping provenance/count updates", + "MCP server '%s': registration of %s as '%s' was rejected by the registry; skipping provenance/count updates", name, c.origin, c.registry_name, ) continue _core._track_mcp_tool_server(c.registry_name, name) registered.append(c.registry_name) - if registered: registry.register_toolset_alias(name, toolset_name) return registered @@ -376,53 +308,42 @@ def _write_schema_cache(name: str, server: "MCPServerTask", config: dict, should from tools.mcp_schema_cache import config_fingerprint, write_cache_entry tools_payload = [] - for mcp_tool in server._tools: - if not should_register(mcp_tool.name): - continue - schema_obj = getattr(mcp_tool, "inputSchema", None) - tools_payload.append({ - "name": mcp_tool.name, - "description": mcp_tool.description or "", - "inputSchema": schema_obj if isinstance(schema_obj, dict) else {}, - # Persisted so the lazy path trust-gates identically next startup. - "annotations": {"readOnlyHint": _annotation_read_only_hint(mcp_tool)}, - }) - utility_payload = [ - {"schema": entry["schema"], "handler_key": entry["handler_key"]} - for entry in _select_utility_schemas(name, server, config) - ] + for t in server._tools: + if should_register(t.name): + schema_obj = getattr(t, "inputSchema", None) + tools_payload.append({ + "name": t.name, + "description": t.description or "", + "inputSchema": schema_obj if isinstance(schema_obj, dict) else {}, + # Persisted so the lazy path trust-gates identically next startup. + "annotations": {"readOnlyHint": _annotation_read_only_hint(t)}, + }) + utility_payload = [{"schema": e["schema"], "handler_key": e["handler_key"]} for e in _select_utility_schemas(name, server, config)] cache_meta = getattr(server, "_list_cache_meta", None) or {} write_cache_entry( - name, - config_fingerprint(config), - tools=tools_payload, - utility_tools=utility_payload, - ttl_ms=cache_meta.get("ttl_ms"), - cache_scope=cache_meta.get("cache_scope"), + name, config_fingerprint(config), tools=tools_payload, utility_tools=utility_payload, + ttl_ms=cache_meta.get("ttl_ms"), cache_scope=cache_meta.get("cache_scope"), ) except Exception as exc: logger.debug("MCP schema cache write failed for '%s': %s", name, exc) def _register_server_tools(name: str, server: "MCPServerTask", config: dict) -> List[str]: - """Register an already-connected server's tools (plus utility tools) into - the registry; used by initial discovery and list_changed refresh. + """Register an already-connected server's tools (plus utility tools); used by + initial discovery and list_changed refresh. Returns the registered names. Toolset resolution for ``mcp-{server}`` / raw-name aliases derives from the live registry rather than mutating ``toolsets.TOOLSETS``. Lossy name normalization can map distinct raw names (``read-file``/``read_file``) to - one registry name; such collisions fail closed — every ambiguous entry is - skipped. Generated utilities share the namespace and join the same - preflight. Returns the registered prefixed names. - """ + one registry name; such collisions fail closed. Generated utilities share + the namespace and join the same preflight.""" should_register = _make_tool_filter(name, config) - check_fn = _make_check_fn(name) _record_tool_trust_metadata(name, config, server._tools) candidates = _tool_candidates(name, server._tools, should_register, server.tool_timeout) candidates += _utility_candidates(name, _select_utility_schemas(name, server, config), server.tool_timeout) registered = _register_candidates( name, _resolve_name_collisions(name, candidates), - check_fn=check_fn, scope=lambda: _core._server_registry_scope(name), lazy=False, + check_fn=_make_check_fn(name), scope=lambda: _core._server_registry_scope(name), lazy=False, ) if registered: _write_schema_cache(name, server, config, should_register) @@ -431,21 +352,18 @@ def _register_server_tools(name: str, server: "MCPServerTask", config: dict) -> def _register_from_cache_sync(name: str, config: dict, entry: dict) -> List[str]: """Lazy startup: register a server's tools from a cached manifest with no - child process. The first real call routes through + child process; the first real call goes through ``_get_connected_server_for_call`` -> ``_ensure_lazy_server_connected``. Trust metadata is recorded first so the call-time gate is identical whether the server was spawned live or registered from cache.""" from tools.mcp_schema_cache import config_fingerprint, tools_from_cache_entry, utility_tools_from_cache_entry tool_timeout = _resolve_tool_timeout(config) - check_fn = _make_check_fn(name) cached_tools = _CachedMCPTool.from_cache_dicts(tools_from_cache_entry(entry)) _record_tool_trust_metadata(name, config, cached_tools) candidates = _tool_candidates(name, cached_tools, _make_tool_filter(name, config), tool_timeout) candidates += _utility_candidates(name, utility_tools_from_cache_entry(entry), tool_timeout) - registered = _register_candidates( - name, candidates, check_fn=check_fn, scope=_core._mcp_registry_scope, lazy=True, - ) + registered = _register_candidates(name, candidates, check_fn=_make_check_fn(name), scope=_core._mcp_registry_scope, lazy=True) if registered: with _core._lock: _core._lazy_server_configs[name] = dict(config) diff --git a/tools/mcp_tool_sampling.py b/tools/mcp_tool_sampling.py index 48813e3968..91c3492e22 100644 --- a/tools/mcp_tool_sampling.py +++ b/tools/mcp_tool_sampling.py @@ -105,15 +105,14 @@ def _response_total_tokens(response, default): class SamplingHandler: - """Handles sampling/createMessage requests for one MCP server. + """Handles sampling/createMessage requests for one MCP server; passed to + ``ClientSession`` as ``sampling_callback``. All state (rate-limit + timestamps, metrics, tool-loop counter) is per instance. Runs on the MCP + background loop; the sync LLM call is offloaded via ``asyncio.to_thread``. Deprecated upstream (MCP 2026-07-28, SEP-2577, 12-month window): stays fully functional because handshake-era servers still issue it, but do NOT grow new capability here — modern servers use MRTR, handled by the SDK session layer. - - Callable; passed to ``ClientSession`` as ``sampling_callback``. All state - (rate-limit timestamps, metrics, tool-loop counter) is per instance. Runs on - the MCP background loop; the sync LLM call is offloaded via ``asyncio.to_thread``. """ _STOP_REASON_MAP = {"stop": "endTurn", "length": "maxTokens", "tool_calls": "toolUse"} @@ -135,8 +134,7 @@ class SamplingHandler: def _check_rate_limit(self) -> bool: """Sliding-window (60s) limiter; True if the request is allowed.""" now = time.time() - window = now - 60 - self._rate_timestamps[:] = [t for t in self._rate_timestamps if t > window] + self._rate_timestamps[:] = [t for t in self._rate_timestamps if t > now - 60] if len(self._rate_timestamps) >= self.max_rpm: return False self._rate_timestamps.append(now) @@ -151,11 +149,6 @@ class SamplingHandler: return hint.name return None - @staticmethod - def _extract_tool_result_text(block) -> str: - """Extract text from a ToolResultContent block.""" - return _tool_result_text(block) - def _convert_messages(self, params) -> List[dict]: """Convert MCP SamplingMessages to OpenAI format (``content_as_list`` when the SDK provides it; per-block duck-typed dispatch).""" @@ -327,13 +320,11 @@ def _format_elicitation_schema_summary(schema: dict, server_name: str) -> str: class ElicitationHandler: - """Handles ``elicitation/create`` requests for one MCP server. - - Callable; passed to ``ClientSession`` as ``elicitation_callback``. Form-mode - requests route through Hermes' approval system (CLI, TUI, Telegram, ...); - URL-mode is declined as unsupported. Fail-closed: any timeout, exception, - or unexpected state returns decline/cancel, never a silent accept. - """ + """Handles ``elicitation/create`` requests for one MCP server; passed to + ``ClientSession`` as ``elicitation_callback``. Form-mode requests route + through Hermes' approval system (CLI, TUI, Telegram, ...); URL-mode is + declined as unsupported. Fail-closed: any timeout, exception or unexpected + state returns decline/cancel, never a silent accept.""" # asyncio-side safety net over the approval's own input() timeout so the # MCP loop never blocks indefinitely if the inner timeout is bypassed. From ade852f1d559a09bdd4c95ac355602a138c8450a Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 2 Sep 2026 15:55:38 -0700 Subject: [PATCH 4/9] refactor(mcp): extract atomic snapshot publish from refresh_agent_mcp_tools; compact docstrings by hand --- tools/mcp_schema_cache.py | 37 ++++----- tools/mcp_stdio_watchdog.py | 42 +++++------ tools/mcp_tool_agent.py | 144 ++++++++++++++++++------------------ tools/mcp_tool_common.py | 18 ++--- tools/mcp_tool_config.py | 45 +++++------ tools/mcp_tool_lifecycle.py | 61 +++++---------- tools/mcp_tool_sampling.py | 5 +- tools/mcp_tool_schema.py | 25 +++---- 8 files changed, 157 insertions(+), 220 deletions(-) diff --git a/tools/mcp_schema_cache.py b/tools/mcp_schema_cache.py index 48ce08c12f..1218a23593 100644 --- a/tools/mcp_schema_cache.py +++ b/tools/mcp_schema_cache.py @@ -58,23 +58,17 @@ def _load_all() -> Dict[str, Any]: def _save_all(data: Dict[str, Any]) -> None: from utils import atomic_json_write - # Cache dir + 0o600: sibling precedent in tools/registry.py - # _save_discovery_cache; the cache file is trusted input on the lazy - # registration path, so keep it user-only. + # 0o600 (as tools/registry.py _save_discovery_cache): the cache file is + # trusted input on the lazy registration path, so keep it user-only. atomic_json_write(_cache_path(), data, mode=0o600) def get_cached_entry(server_name: str, fingerprint: str) -> Optional[dict]: """Return cached entry when fingerprint matches (and TTL holds), else None. - - MCP 2026-07-28 (SEP-2549): ``tools/list`` results carry ``ttlMs`` as a - freshness hint. When the live discovery path recorded one, an entry - older than its TTL is treated as a miss so the next startup re-probes - the server instead of serving a stale manifest forever. Entries without - a recorded TTL (pre-2026 servers) keep the old never-expires behavior. - ``cacheScope`` is irrelevant here: this cache is per-user local disk, - which satisfies even ``private``. - """ + ``tools/list`` results may carry ``ttlMs`` (SEP-2549); an entry older than a + recorded TTL is a miss so the next startup re-probes instead of serving a + stale manifest forever. Entries without a TTL never expire. ``cacheScope`` + is irrelevant: this cache is per-user local disk, satisfying even ``private``.""" with _cache_lock: entry = _load_all().get(server_name) if not isinstance(entry, dict) or entry.get("fingerprint") != fingerprint: @@ -98,12 +92,9 @@ def write_cache_entry( ttl_ms: Optional[float] = None, cache_scope: Optional[str] = None, ) -> None: - """Persist tool schemas after a successful live connect. - - ``ttl_ms``/``cache_scope`` are the SEP-2549 hints from the server's - ``tools/list`` result (2026-07-28 servers). ``written_at`` anchors TTL - expiry in :func:`get_cached_entry`. - """ + """Persist tool schemas after a successful live connect. ``ttl_ms`` / + ``cache_scope`` are the server's ``tools/list`` SEP-2549 hints; + ``written_at`` anchors TTL expiry in :func:`get_cached_entry`.""" entry = {"fingerprint": fingerprint, "tools": tools, "utility_tools": utility_tools or []} if isinstance(ttl_ms, (int, float)): entry["ttl_ms"] = ttl_ms @@ -112,12 +103,10 @@ def write_cache_entry( entry["cache_scope"] = cache_scope with _cache_lock: data = _load_all() - # Write-through fires on every registration (reconnects, - # list_changed refreshes); skip the load-all+rewrite churn when the - # entry is byte-identical to what is already on disk. TTL'd entries - # always rewrite: written_at must advance or the entry would expire - # at its ORIGINAL write time no matter how many live reconnects - # confirmed it since. + # Write-through fires on every registration (reconnects, list_changed); + # skip the load-all+rewrite churn when the entry is byte-identical on + # disk. TTL'd entries always rewrite: written_at must advance or the + # entry would expire at its ORIGINAL write time regardless of reconnects. if "written_at" not in entry and data.get(server_name) == entry: return data[server_name] = entry diff --git a/tools/mcp_stdio_watchdog.py b/tools/mcp_stdio_watchdog.py index fa0570f9cd..e7b29a105b 100644 --- a/tools/mcp_stdio_watchdog.py +++ b/tools/mcp_stdio_watchdog.py @@ -1,21 +1,18 @@ #!/usr/bin/env python3 """Parent-death watchdog supervisor for stdio MCP subprocesses. -If Hermes dies hard (kill -9, crash, force-quit), its graceful teardown never -runs and the stdio child plus its descendants are orphaned; macOS has no -``PR_SET_PDEATHSIG`` equivalent. Piled-up orphans then race the legitimate new -connection for the same upstream session. So the MCP command is spawned via -this supervisor, which: - 1. runs the real command as its own child in a new process group (so the - whole tree can be killpg'd); - 2. passes stdin/stdout/stderr straight through — the MCP stdio protocol - talks over those pipes, so this must be a no-op relay, not a proxy; - 3. polls ``getppid()`` against the recorded parent PID and, when the parent - is gone, SIGTERMs the child's group, waits, then SIGKILLs. +If Hermes dies hard (kill -9, crash, force-quit) its graceful teardown never +runs and the stdio child plus its descendants are orphaned (macOS has no +``PR_SET_PDEATHSIG``); piled-up orphans then race the legitimate new connection +for the same upstream session. So the MCP command is spawned via this +supervisor, which (1) runs the real command as its own child in a new process +group so the whole tree can be killpg'd, (2) passes stdin/stdout/stderr straight +through — the MCP stdio protocol talks over those pipes, so this must be a +no-op relay, not a proxy — and (3) polls ``getppid()`` against the recorded +parent PID and, once the parent is gone, SIGTERMs the child's group, waits, +then SIGKILLs. Standard-library only so it starts fast and cannot itself leak. -Standard-library only so it starts fast and cannot itself leak. - -Usage (see ``tools/mcp_tool.py::_run_stdio``):: +Usage (see ``_wrap_command_with_watchdog``):: python3 -m tools.mcp_stdio_watchdog \\ --ppid -- ... @@ -41,9 +38,9 @@ def _is_orphaned(original_ppid: int, getppid=os.getppid) -> bool: def _terminate_process_group(proc: subprocess.Popen) -> None: - """Best-effort SIGTERM-then-SIGKILL of the child's process group. Only runs - on POSIX in practice, but guards the POSIX-only primitives so an accidental - Windows run degrades to a plain child kill instead of AttributeError.""" + """Best-effort SIGTERM-then-SIGKILL of the child's process group; guards the + POSIX-only primitives so an accidental Windows run degrades to a plain child + kill instead of AttributeError.""" killpg = getattr(os, "killpg", None) if killpg is None: # windows-footgun: ok — non-POSIX fallback try: @@ -90,14 +87,13 @@ def main(argv: list[str] | None = None) -> int: print("mcp_stdio_watchdog: no command given after '--'", file=sys.stderr) return 2 - # New process group so we can killpg() the whole tree the real command may - # spawn, without touching our own group or the original parent's. + # New process group: killpg() reaches the whole tree the real command may + # spawn without touching our own group or the original parent's. proc = subprocess.Popen(real_argv, stdin=sys.stdin, stdout=sys.stdout, stderr=sys.stderr, start_new_session=True) - # The server lives in its OWN group, so the parent's shutdown killpg of - # *our* group no longer reaches it. Forward SIGTERM/SIGINT to the child's - # group so graceful teardown still kills a wedged server that ignores stdin - # EOF — otherwise the wrap would invert the bug it fixes. + # The server lives in its OWN group, so the parent's shutdown killpg of *our* + # group no longer reaches it: forward SIGTERM/SIGINT to the child's group so + # graceful teardown still kills a wedged server that ignores stdin EOF. def _forward_shutdown(signum, frame): # noqa: ARG001 _terminate_process_group(proc) sys.exit(128 + signum) diff --git a/tools/mcp_tool_agent.py b/tools/mcp_tool_agent.py index 2722d1b35b..7e921ca573 100644 --- a/tools/mcp_tool_agent.py +++ b/tools/mcp_tool_agent.py @@ -5,6 +5,7 @@ and re-injecting post-build tools.""" import logging import json import threading +from typing import Optional from tools.mcp_tool_common import _core logger = logging.getLogger("tools.mcp_tool") @@ -48,6 +49,39 @@ def _tool_defs_content_changed(agent, new_defs: list) -> bool: return False +def _publish_tool_snapshot(agent, new_defs: list, new_names: set, *, snapshot_generation: int, + staged_engine_names: set, content_aware: bool, prefix_registered: Optional[set]) -> Optional[set]: + """Single atomic read-diff-publish under ``_agent_tools_lock`` so ``added`` + matches what was published and a stale (older-generation) rebuild can't + overwrite a newer one. Returns the added names, or None when nothing was + published (unchanged, or a newer snapshot already won).""" + with _agent_tools_lock: + # Tolerate an agent that never set the generation (or a non-int mock) + # rather than failing the whole refresh on the comparison. + published_gen = getattr(agent, "_tool_snapshot_generation", -1) + published_gen = published_gen if isinstance(published_gen, int) else -1 + if snapshot_generation < published_gen: + return None # a newer snapshot already won + current_defs = _agent_tool_defs(agent) + current = {_def_name(t) for t in current_defs} + if prefix_registered is not None: + new_defs, new_names = _merge_preserving_prefix(current_defs, new_defs, prefix_registered) + # Record the generation even when unchanged so an in-flight older caller can't clobber. + agent._tool_snapshot_generation = max(published_gen, snapshot_generation) + # Same NAME set: no change for MCP-reload callers. Content-aware callers + # (compaction boundary) also diff serialized bytes. + if new_names == current and not (content_aware and _tool_defs_content_changed(agent, new_defs)): + return None + agent.tools = new_defs + agent.valid_tool_names = new_names + # Publish context-engine routing names atomically with the snapshot. + engine_names = getattr(agent, "_context_engine_tool_names", None) + if isinstance(engine_names, set): + engine_names.clear() + engine_names.update(staged_engine_names) + return new_names - current + + def refresh_agent_mcp_tools( agent, *, @@ -57,85 +91,55 @@ def refresh_agent_mcp_tools( content_aware: bool = False, preserve_prefix: bool = False, ) -> set: - """Re-derive an already-built agent's tool snapshot from the live registry. + """Re-derive an already-built agent's tool snapshot from the live registry; + returns the newly-added tool names (empty when unchanged). - The agent snapshots ``agent.tools`` once at build time; servers that connect - later (slow OAuth server, ``/reload-mcp``) are invisible until rebuilt. This - is the single shared rebuild for the TUI RPC, gateway reload, late-binding - thread and between-turns refresh. It respects the agent's own toolset - filter, diffs by tool NAME (a count compare misses an equal-size swap), and - is additive-preserving: memory-provider and context-engine (``lcm_*``) tools - that ``agent_init`` appends after ``get_tool_definitions`` are re-injected, - since a naive rebuild would silently delete them. ``(tools, valid_tool_names)`` - are published together under ``_agent_tools_lock``. + The agent snapshots ``agent.tools`` once at build time, so servers that + connect later (slow OAuth server, ``/reload-mcp``) are invisible until + rebuilt. Single shared rebuild for the TUI RPC, gateway reload, late-binding + thread and between-turns refresh: respects the agent's toolset filter, diffs + by tool NAME (a count compare misses an equal-size swap), re-injects the + memory-provider / context-engine (``lcm_*``) tools ``agent_init`` appends + after ``get_tool_definitions`` (a naive rebuild would drop them), and + publishes ``(tools, valid_tool_names)`` together under ``_agent_tools_lock``. ``preserve_prefix`` is for rebuilds inside a live conversation, where the tool array is a cached request prefix and any moved byte re-prefills the whole history: existing tools keep their slot (schemas still refresh), a still-registered tool whose ``check_fn`` merely flapped is carried forward, - a tool that left the registry is dropped, and new tools append at the tail. - Carrying an unavailable tool forward is safe: ``check_fn`` gates exposure, - never invocation, and every handler owns its own unavailability error. - - Returns the newly-added tool names (empty when unchanged). The caller owns - the prompt-cache contract (turn-boundary policy differs per caller). - """ + a deregistered tool is dropped, new tools append at the tail. Carrying an + unavailable tool forward is safe: ``check_fn`` gates exposure, never + invocation. The caller owns the prompt-cache contract (turn-boundary policy + differs per caller).""" from model_tools import get_tool_definitions from tools.registry import registry enabled, disabled = _resolve_refresh_toolsets(agent, enabled_override, disabled_override) - # Capture the registry generation BEFORE the slow get_tool_definitions call; # at publish time a slower caller holding an OLDER set must not clobber a # newer set another caller already published. snapshot_generation = registry._generation - # Computed OUTSIDE the lock (can be slow); diff + publish happen together in # one critical section so concurrent callers can't torn-publish. new_defs = list(get_tool_definitions(enabled_toolsets=enabled, disabled_toolsets=disabled, quiet_mode=quiet_mode) or []) new_names = {_def_name(t) for t in new_defs} - # Re-append the post-build families on LOCALS only; live agent attributes - # are untouched until the single atomic publish below. + # are untouched until the single atomic publish. staged_engine_names = _core._reinject_post_build_tools(agent, new_defs, new_names) - # Registry membership is read OUTSIDE ``_agent_tools_lock``: taking # ``registry._lock`` under the tools lock would be the first nesting of the two. - registered_names: set = set() + prefix_registered: Optional[set] = None if preserve_prefix: try: - registered_names = {entry.name for entry in registry.get_all_entries()} + prefix_registered = {entry.name for entry in registry.get_all_entries()} except Exception: # noqa: BLE001 - preserve_prefix = False # fail open to the plain rebuild - - # Single atomic read-diff-publish so ``added`` matches what was published - # and a stale (older-generation) rebuild can't overwrite a newer one. - with _agent_tools_lock: - # Tolerate an agent that never set the generation (or a non-int mock) - # rather than failing the whole refresh on the comparison. - published_gen_raw = getattr(agent, "_tool_snapshot_generation", -1) - published_gen = published_gen_raw if isinstance(published_gen_raw, int) else -1 - if snapshot_generation < published_gen: - return set() # a newer snapshot already won - current_defs = _agent_tool_defs(agent) - current = {_def_name(t) for t in current_defs} - if preserve_prefix: - new_defs, new_names = _merge_preserving_prefix(current_defs, new_defs, registered_names) - # Same NAME set: no change for MCP-reload callers. Content-aware callers - # (compaction boundary) also diff serialized bytes. - if new_names == current and not (content_aware and _tool_defs_content_changed(agent, new_defs)): - # Record the generation so an in-flight older caller can't clobber. - agent._tool_snapshot_generation = max(published_gen, snapshot_generation) - return set() - agent.tools = new_defs - agent.valid_tool_names = new_names - # Publish context-engine routing names atomically with the snapshot. - engine_names = getattr(agent, "_context_engine_tool_names", None) - if isinstance(engine_names, set): - engine_names.clear() - engine_names.update(staged_engine_names) - agent._tool_snapshot_generation = max(published_gen, snapshot_generation) - added = new_names - current + pass # fail open to the plain rebuild + added = _publish_tool_snapshot( + agent, new_defs, new_names, snapshot_generation=snapshot_generation, + staged_engine_names=staged_engine_names, content_aware=content_aware, prefix_registered=prefix_registered, + ) + if added is None: + return set() # Re-pin the session's tool order so a rebuild-for-existing-session # (gateway agent-cache eviction) restores exactly these names. persist_agent_tool_names(agent) @@ -166,14 +170,12 @@ def persist_agent_tool_names(agent) -> None: def restore_agent_tool_prefix(agent, saved_names: list) -> bool: - """Fold a freshly built agent's ``tools`` onto the session's saved order. - - The gateway rebuilds a NEW AIAgent for an existing session after agent-cache - eviction, with no predecessor to preserve; the saved name list stands in: - a saved tool still registered but failing its probe is carried forward from - the registry schema, a deregistered one is dropped, new tools append at the - tail (same rule as ``_merge_preserving_prefix``). Returns True if changed. - """ + """Fold a freshly built agent's ``tools`` onto the session's saved order; + True if changed. The gateway rebuilds a NEW AIAgent for an existing session + after agent-cache eviction, with no predecessor to preserve, so the saved + name list stands in: a saved tool still registered but failing its probe is + carried forward from the registry schema, a deregistered one is dropped, new + tools append at the tail (same rule as ``_merge_preserving_prefix``).""" if not saved_names: return False from tools.registry import registry @@ -203,12 +205,10 @@ def restore_agent_tool_prefix(agent, saved_names: list) -> bool: def _merge_preserving_prefix(current_defs: list, new_defs: list, registered_names: set) -> tuple[list, set]: """Fold a fresh tool snapshot into a live one without moving existing bytes. - - Ordered by ``current_defs`` (the cached request prefix): a name in both - keeps its slot but takes the fresh schema; a name only in the live list is - kept if still registered (``check_fn`` flapped) and dropped if not; a name - only in the fresh list is appended at the tail. - """ + Ordered by ``current_defs`` (the cached request prefix): a name in both keeps + its slot but takes the fresh schema; a name only in the live list is kept if + still registered (``check_fn`` flapped), else dropped; a name only in the + fresh list is appended at the tail.""" fresh = {_def_name(entry): entry for entry in new_defs if _def_name(entry)} merged = [] for entry in current_defs: @@ -225,11 +225,9 @@ def _merge_preserving_prefix(current_defs: list, new_defs: list, registered_name def _reinject_post_build_tools(agent, tools_list: list, name_set: set) -> set: """Append memory-provider and context-engine tools onto the caller's staged ``tools_list`` / ``name_set`` (never the live agent attributes), mirroring - ``agent_init``'s post-build injection. Idempotent and fail-soft. - - Returns the context-engine routing names THIS rebuild appended: a name - already owned by a registry/plugin tool is not claimed, matching agent_init. - """ + ``agent_init``'s post-build injection. Idempotent and fail-soft. Returns the + context-engine routing names THIS rebuild appended: a name already owned by + a registry/plugin tool is not claimed, matching agent_init.""" def _add(schema) -> bool: name = schema.get("name", "") if isinstance(schema, dict) else "" if not name or name in name_set: diff --git a/tools/mcp_tool_common.py b/tools/mcp_tool_common.py index e127e9154f..0e96d04200 100644 --- a/tools/mcp_tool_common.py +++ b/tools/mcp_tool_common.py @@ -13,13 +13,11 @@ logger = logging.getLogger("tools.mcp_tool") class _OriginProxy: - """Attribute proxy for ``tools.mcp_tool`` resolved at access time. - - The split modules read origin state (``_servers``, ``_lock``, SDK symbols, - patchable helpers) through this so ``mock.patch("tools.mcp_tool.X")`` and - origin-side rebinds stay effective, and so no split module needs the origin - imported first (the origin imports them while it is still initialising). - """ + """Attribute proxy for ``tools.mcp_tool`` resolved at access time. The split + modules read origin state (``_servers``, ``_lock``, SDK symbols, patchable + helpers) through this so ``mock.patch("tools.mcp_tool.X")`` and origin-side + rebinds stay effective, and so no split module needs the origin imported + first (the origin imports them while it is still initialising).""" __slots__ = () @@ -30,19 +28,15 @@ class _OriginProxy: _core = _OriginProxy() - - _MISSING = object() def mcp_field(obj, snake: str, camel: str, default=None): """Read an MCP model field across the 1.x -> 2.x rename to snake_case. - Pydantic aliases don't apply to attribute access, so ``getattr(result, "isError", False)`` silently returns the default on 2.x — failed calls read as successful, schemas as empty. Trying both spellings stays correct on - either SDK generation (``mcp`` is an optional extra at the user's version). - """ + either SDK generation (``mcp`` is an optional extra at the user's version).""" value = getattr(obj, snake, _MISSING) if value is _MISSING: value = getattr(obj, camel, _MISSING) diff --git a/tools/mcp_tool_config.py b/tools/mcp_tool_config.py index c3205ac1cb..4bf532814c 100644 --- a/tools/mcp_tool_config.py +++ b/tools/mcp_tool_config.py @@ -20,11 +20,9 @@ _mcp_stderr_log_lock = threading.Lock() def _get_mcp_stderr_log() -> Any: - """Shared append-mode handle for MCP subprocess stderr, opened once per process. - - Must expose a real fd (``fileno()``) because asyncio wires the child's stderr - directly to it. Falls back to ``/dev/null``, then the real stderr. - """ + """Shared append-mode handle for MCP subprocess stderr, opened once per + process. Must expose a real fd (``fileno()``) because asyncio wires the + child's stderr directly to it. Falls back to ``/dev/null``, then real stderr.""" global _mcp_stderr_log_fh with _mcp_stderr_log_lock: if _mcp_stderr_log_fh is not None: @@ -114,12 +112,10 @@ def _context_var_value(ref: str) -> Optional[str]: def _build_safe_env(user_env: Optional[dict]) -> dict: - """Filtered env for stdio subprocesses so API keys/tokens don't leak. - - Passes only the safe baseline keys, ``XDG_*``, vars injected by an external - secret source (users configured that backend precisely so subprocesses can - consume them), plus the server config's own ``env``. - """ + """Filtered env for stdio subprocesses so API keys/tokens don't leak: only + the safe baseline keys, ``XDG_*``, vars injected by an external secret + source (users configured that backend precisely so subprocesses can consume + them), plus the server config's own ``env``.""" try: from hermes_cli.env_loader import get_secret_source except Exception: # pragma: no cover — early bootstrap/import fallback @@ -140,10 +136,7 @@ def _build_safe_env(user_env: Optional[dict]) -> dict: def _which_with_config_pathext(command: str, path_arg, env: dict): """``shutil.which`` retried under the config env's PATHEXT (Windows only): ``which(path=...)`` uses the PARENT's PATHEXT, not the config env's.""" - cfg_pathext = next( - (v for k, v in env.items() if k.upper() == "PATHEXT" and isinstance(v, str) and v.strip()), - None, - ) + cfg_pathext = next((v for k, v in env.items() if k.upper() == "PATHEXT" and isinstance(v, str) and v.strip()), None) if not cfg_pathext or cfg_pathext == os.environ.get("PATHEXT"): return None saved = os.environ.get("PATHEXT") @@ -215,13 +208,11 @@ def _wrap_command_with_watchdog(command: str, args: list) -> tuple[str, list]: def _interpolate_env_vars(value): - """Recursively resolve ``${VAR}`` / Cursor ``${env:VAR}`` placeholders plus the - Cursor context vars (see ``_context_var_value``). - - Env refs resolve from the active profile's secret scope when multiplexing - (so ``${API_KEY}`` picks up the routed profile's value, not another - profile's in ``os.environ``). Unset vars keep the literal placeholder. - """ + """Recursively resolve ``${VAR}`` / Cursor ``${env:VAR}`` placeholders plus + the Cursor context vars (``_context_var_value``). Env refs resolve from the + active profile's secret scope when multiplexing (so ``${API_KEY}`` picks up + the routed profile's value, not another profile's in ``os.environ``). Unset + vars keep the literal placeholder.""" from agent.secret_scope import get_secret as _get_secret if isinstance(value, str): @@ -245,12 +236,10 @@ _whitespace_warned: Set[Tuple[str, str]] = set() def _warn_hidden_whitespace(server_name: str, config: dict) -> List[str]: """Warn once per (server, key path) about string values with leading/trailing - whitespace — a pasted trailing newline or leading space causes opaque - auth/connect failures and is invisible in config.yaml. - - Advisory only: values are never mutated (whitespace could be intentional) - and never logged (often secrets). Returns the flagged key paths. - """ + whitespace — a pasted newline or leading space causes opaque auth/connect + failures and is invisible in config.yaml. Advisory only: values are never + mutated (whitespace could be intentional) and never logged (often secrets). + Returns the flagged key paths.""" flagged: List[str] = [] def _walk(value: Any, path: str) -> None: diff --git a/tools/mcp_tool_lifecycle.py b/tools/mcp_tool_lifecycle.py index 023179edc8..b8e799697a 100644 --- a/tools/mcp_tool_lifecycle.py +++ b/tools/mcp_tool_lifecycle.py @@ -73,12 +73,9 @@ _NON_MCP_CHILD_CMDLINE_MARKERS: tuple[str, ...] = ( def _filter_mcp_children(pids: set) -> set: - """Drop non-MCP children from a PID snapshot delta. - - Tracking a stray child in _stdio_pgids is catastrophic if it lacks - start_new_session: its pgid can be the TUI parent's, so the shutdown - killpg() would kill the TUI itself. - """ + """Drop non-MCP children from a PID snapshot delta. Tracking a stray child in + _stdio_pgids is catastrophic if it lacks start_new_session: its pgid can be + the TUI parent's, so the shutdown killpg() would kill the TUI itself.""" if not pids: return pids try: @@ -107,18 +104,13 @@ def _clear_connect_cooldowns() -> None: def shutdown_mcp_servers(*, scope: Optional[str] = None): """Close MCP server connections (in parallel) and stop the background loop. - Each server Task is signalled to exit its own ``async with`` so the anyio cancel-scope cleanup runs in the Task that opened it. ``scope`` restricts teardown to one multiplexed profile's servers (its ``/reload-mcp`` must not - kill other profiles') and leaves the shared loop running if anything else - is still connected. - """ + kill other profiles') and leaves the shared loop running if anything else is + still connected.""" with _core._lock: - selected = [ - name for name in _core._servers - if scope is None or _core._server_scope_keys.get(name) == scope - ] + selected = [name for name in _core._servers if scope is None or _core._server_scope_keys.get(name) == scope] servers_snapshot = [_core._servers[name] for name in selected] # Fast path: nothing to shut down. Still clear the connect-cooldown maps — @@ -131,10 +123,7 @@ def shutdown_mcp_servers(*, scope: Optional[str] = None): return async def _shutdown(): - results = await asyncio.gather( - *(server.shutdown() for server in servers_snapshot), - return_exceptions=True, - ) + results = await asyncio.gather(*(server.shutdown() for server in servers_snapshot), return_exceptions=True) for server, result in zip(servers_snapshot, results): if isinstance(result, Exception): logger.debug("Error closing MCP server '%s': %s", server.name, result) @@ -218,13 +207,11 @@ def _signal_mcp_process(pid: int, sig: int, server_name: str, pgid: Optional[int def _kill_orphaned_mcp_children(include_active: bool = False, server_name: Optional[str] = None) -> None: """Best-effort reap of stdio MCP subprocesses: SIGTERM, wait 2s, SIGKILL survivors. - By default only ``_orphan_stdio_pids`` (PIDs that outlived their session context) are reaped so concurrent cron jobs / live sessions are untouched; ``include_active=True`` also kills every ``_stdio_pids`` entry and is only - for final shutdown after the MCP loop has stopped. ``server_name`` limits - the sweep to one server (stdio reconnects cleaning up their old transport). - """ + for final shutdown after the MCP loop has stopped. ``server_name`` limits the + sweep to one server (stdio reconnects cleaning up their old transport).""" import signal as _signal pids, pgids = _take_reapable_pids(include_active, server_name) @@ -256,23 +243,18 @@ def _kill_orphaned_mcp_children(include_active: bool = False, server_name: Optio def _stop_mcp_loop_if_idle() -> bool: - """Stop the MCP loop only when no registered server still owns it. - - Probe paths create temporary MCPServerTasks not placed in ``_servers``; - they may clean up an idle loop but must not tear down the process-global - loop under live agent tools, or later calls fail with - ``MCP event loop is not running``. - """ + """Stop the MCP loop only when no registered server still owns it. Probe + paths create temporary MCPServerTasks not placed in ``_servers``; they may + clean up an idle loop but must not tear down the process-global loop under + live agent tools, or later calls fail with ``MCP event loop is not running``.""" return _core._stop_mcp_loop(only_if_idle=True) async def _drain_mcp_loop_tasks(*, timeout: Optional[float] = None) -> None: """Cancel every task still pending on the MCP loop and reap it. - ``Task.cancel()`` only schedules the throw, so tasks need a cancellation cycle before the loop goes away; wait for them here, on their owning loop, - bounded so a task that suppresses cancellation cannot hang process exit. - """ + bounded so a task that suppresses cancellation cannot hang process exit.""" if timeout is None: timeout = _core._MCP_LOOP_DRAIN_TIMEOUT current = asyncio.current_task() @@ -285,10 +267,9 @@ async def _drain_mcp_loop_tasks(*, timeout: Optional[float] = None) -> None: done, still_pending = await asyncio.wait(pending, timeout=timeout) for task in done: - if task.cancelled(): - continue try: - task.exception() + if not task.cancelled(): + task.exception() except asyncio.CancelledError: pass except Exception as exc: @@ -299,12 +280,10 @@ async def _drain_mcp_loop_tasks(*, timeout: Optional[float] = None) -> None: async def _drain_and_stop_mcp_loop() -> None: - """Drain pending tasks, then stop the loop from its owning thread. - - Both must run as one loop-owned sequence: a ``loop.stop`` queued separately - by a timed-out caller can overtake the scheduled drain, leaving the drain - coroutine itself pending when the loop is closed. - """ + """Drain pending tasks, then stop the loop from its owning thread. Both must + run as one loop-owned sequence: a ``loop.stop`` queued separately by a + timed-out caller can overtake the scheduled drain, leaving the drain + coroutine itself pending when the loop is closed.""" loop = asyncio.get_running_loop() try: await _drain_mcp_loop_tasks(timeout=_core._MCP_LOOP_DRAIN_TIMEOUT) diff --git a/tools/mcp_tool_sampling.py b/tools/mcp_tool_sampling.py index 91c3492e22..a1aa99c2c5 100644 --- a/tools/mcp_tool_sampling.py +++ b/tools/mcp_tool_sampling.py @@ -65,10 +65,7 @@ def _convert_sampling_message(msg) -> List[dict]: tool_uses = [b for b in blocks if _is_tool_use(b) and _tool_use_id(b) is _MISSING] content_blocks = [b for b in blocks if _tool_use_id(b) is _MISSING and not _is_tool_use(b)] - out = [ - {"role": "tool", "tool_call_id": _tool_use_id(tr), "content": _tool_result_text(tr)} - for tr in tool_results - ] + out = [{"role": "tool", "tool_call_id": _tool_use_id(tr), "content": _tool_result_text(tr)} for tr in tool_results] if tool_uses: msg_dict: dict = {"role": msg.role, "tool_calls": [_tool_call_dict(tu, i) for i, tu in enumerate(tool_uses)]} text_parts = [b.text for b in content_blocks if hasattr(b, "text")] diff --git a/tools/mcp_tool_schema.py b/tools/mcp_tool_schema.py index 9afe0ad953..ce3c62c188 100644 --- a/tools/mcp_tool_schema.py +++ b/tools/mcp_tool_schema.py @@ -50,12 +50,10 @@ _EMPTY_OBJECT_SCHEMA = {"type": "object", "properties": {}} def _rewrite_local_refs(node): """Promote legacy ``definitions`` to ``$defs`` (Moonshot rejects the draft-07 - form) — but ONLY where it is a JSON Schema meta-keyword, never as a property - NAME inside ``properties``/``patternProperties``. A tool parameter - legitimately named ``definitions`` rewritten to ``$defs`` would 400 the whole - tool array (Anthropic/OpenAI forbid ``$`` in property names). Property names - are kept verbatim and recursion resumes ordinary semantics inside each - property's schema.""" + form) — ONLY where it is a JSON Schema meta-keyword, never as a property NAME + inside ``properties``/``patternProperties``: a parameter legitimately named + ``definitions`` rewritten to ``$defs`` would 400 the whole tool array + (Anthropic/OpenAI forbid ``$`` in property names).""" if isinstance(node, list): return [_rewrite_local_refs(item) for item in node] if not isinstance(node, dict): @@ -100,15 +98,12 @@ def _repair_object_shape(node): def _normalize_mcp_input_schema(schema: dict | None) -> dict: """Normalize MCP input schemas so one form is valid on OpenAI, Anthropic, - Gemini and Moonshot. - - Order matters: ``definitions`` -> ``$defs`` rewrite; nullable ``anyOf`` - unions collapsed to the non-null branch (Anthropic rejects nullable - branches; optionality lives solely in the parent's ``required``, the - ``nullable: true`` hint is kept so runtime coercion can still map a - model-emitted ``"null"`` string to ``None``); same-typed const unions -> - enum (must run AFTER the nullable strip); then object-shape repair. - """ + Gemini and Moonshot. Order matters: ``definitions`` -> ``$defs``; nullable + ``anyOf`` unions collapsed to the non-null branch (Anthropic rejects nullable + branches; optionality lives in the parent's ``required``; the ``nullable: + true`` hint is kept so runtime coercion can map a model-emitted ``"null"`` + string to ``None``); same-typed const unions -> enum (AFTER the nullable + strip); then object-shape repair.""" if not schema: return dict(_EMPTY_OBJECT_SCHEMA) from tools.schema_sanitizer import collapse_const_unions, strip_nullable_unions From 97fbd7e232e601cdd8705b793c8aac983aa1fb31 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 2 Sep 2026 15:57:42 -0700 Subject: [PATCH 5/9] refactor(mcp): table-drive elicitation answers, unify sampling response log, tighten collision diagnostics --- tools/mcp_tool_agent.py | 1 - tools/mcp_tool_common.py | 5 ----- tools/mcp_tool_config.py | 4 ---- tools/mcp_tool_lifecycle.py | 2 -- tools/mcp_tool_registration.py | 17 +++++++-------- tools/mcp_tool_sampling.py | 38 ++++++++++++++-------------------- tools/mcp_tool_schema.py | 5 ----- 7 files changed, 22 insertions(+), 50 deletions(-) diff --git a/tools/mcp_tool_agent.py b/tools/mcp_tool_agent.py index 7e921ca573..963af71bda 100644 --- a/tools/mcp_tool_agent.py +++ b/tools/mcp_tool_agent.py @@ -10,7 +10,6 @@ from tools.mcp_tool_common import _core logger = logging.getLogger("tools.mcp_tool") - # Serializes in-place swaps of ``agent.tools`` / ``agent.valid_tool_names`` by # the reload RPC, gateway reload and late-binding refresh thread; the run loop # reads them during tool iteration and must never see a half-updated pair. diff --git a/tools/mcp_tool_common.py b/tools/mcp_tool_common.py index 0e96d04200..bdd91de8aa 100644 --- a/tools/mcp_tool_common.py +++ b/tools/mcp_tool_common.py @@ -26,7 +26,6 @@ class _OriginProxy: return getattr(mcp_tool, name) - _core = _OriginProxy() _MISSING = object() @@ -42,7 +41,6 @@ def mcp_field(obj, snake: str, camel: str, default=None): value = getattr(obj, camel, _MISSING) return default if value is _MISSING else value - _DEFAULT_TOOL_TIMEOUT = 300 # seconds for tool calls @@ -63,7 +61,6 @@ def _resolve_tool_timeout(config: dict) -> float: logger.debug("mcp.tool_call timeout resolution failed", exc_info=True) return _DEFAULT_TOOL_TIMEOUT - # Jitter on reconnect backoff so servers that lost the same backend don't # retry in lockstep (thundering herd, synchronized log bursts). _BACKOFF_JITTER = 0.2 # +/-20% @@ -73,7 +70,6 @@ def _jittered(seconds: float) -> float: """``seconds`` with +/-20% uniform jitter, floored at 0.""" return max(0.0, seconds * random.uniform(1.0 - _BACKOFF_JITTER, 1.0 + _BACKOFF_JITTER)) - # Credential patterns to strip from error messages. _CREDENTIAL_PATTERN = re.compile( r"(?:" @@ -135,7 +131,6 @@ def _safe_numeric(value, default, coerce=int, minimum=1): except (TypeError, ValueError, OverflowError): return default - _TRUE_WORDS = frozenset({"true", "1", "yes", "on"}) _FALSE_WORDS = frozenset({"false", "0", "no", "off"}) diff --git a/tools/mcp_tool_config.py b/tools/mcp_tool_config.py index 4bf532814c..940fdc0e9e 100644 --- a/tools/mcp_tool_config.py +++ b/tools/mcp_tool_config.py @@ -14,7 +14,6 @@ from tools.mcp_tool_common import _env_ref_name, _prepend_path, _core logger = logging.getLogger("tools.mcp_tool") - _mcp_stderr_log_fh: Optional[Any] = None _mcp_stderr_log_lock = threading.Lock() @@ -56,7 +55,6 @@ def _write_stderr_log_header(server_name: str) -> None: except Exception: pass - # Env vars safe to pass to stdio subprocesses (no secrets). _SAFE_ENV_KEYS = frozenset({"PATH", "HOME", "USER", "LANG", "LC_ALL", "TERM", "SHELL", "TMPDIR"}) @@ -93,7 +91,6 @@ def _workspace_basename() -> str: root = _core._workspace_folder() return os.path.basename(root.rstrip("/\\")) or root - # Cursor's case-sensitive context vars -> resolver. _CONTEXT_VAR_RESOLVERS = { "userHome": lambda: os.path.expanduser("~"), @@ -228,7 +225,6 @@ def _interpolate_env_vars(value): return [_interpolate_env_vars(v) for v in value] return value - # (server_name, dotted key path) pairs already warned about; config loads # happen on every discovery pass, so warn once per process. _whitespace_warned: Set[Tuple[str, str]] = set() diff --git a/tools/mcp_tool_lifecycle.py b/tools/mcp_tool_lifecycle.py index b8e799697a..45890dad4f 100644 --- a/tools/mcp_tool_lifecycle.py +++ b/tools/mcp_tool_lifecycle.py @@ -10,7 +10,6 @@ from tools.mcp_tool_common import _core logger = logging.getLogger("tools.mcp_tool") - # Live stdio MCP children (pid -> server_name), added after connection and # removed on normal shutdown, so they can be force-killed if SDK teardown fails. _stdio_pids: Dict[int, str] = {} @@ -58,7 +57,6 @@ def _snapshot_child_pids() -> set: return set() - # argv markers of non-MCP gateway children that can race into the snapshot # delta during an MCP spawn (defense-in-depth; LSP/slash_worker already use # start_new_session). Matched against argv[1:] because Python/Java children diff --git a/tools/mcp_tool_registration.py b/tools/mcp_tool_registration.py index ecdfa24bb6..061c0caa5c 100644 --- a/tools/mcp_tool_registration.py +++ b/tools/mcp_tool_registration.py @@ -257,16 +257,13 @@ def _log_foreign_owner(name: str, c: _Candidate, existing_toolset: str, lazy: bo if lazy: if not c.is_utility: logger.warning("MCP server '%s' (lazy): cached tool '%s' collides with toolset '%s' — skipping", name, c.registry_name, existing_toolset) - elif existing_toolset.startswith("mcp-"): - logger.error( - "MCP server '%s': %s normalizes to '%s', already owned by MCP toolset '%s' — skipping to preserve the existing owner", - name, c.origin, c.registry_name, existing_toolset, - ) - else: - logger.warning( - "MCP server '%s': %s (→ '%s') collides with built-in tool in toolset '%s' — skipping to preserve built-in", - name, c.origin, c.registry_name, existing_toolset, - ) + return + log, fmt = ( + (logger.error, "MCP server '%s': %s normalizes to '%s', already owned by MCP toolset '%s' — skipping to preserve the existing owner") + if existing_toolset.startswith("mcp-") else + (logger.warning, "MCP server '%s': %s (→ '%s') collides with built-in tool in toolset '%s' — skipping to preserve built-in") + ) + log(fmt, name, c.origin, c.registry_name, existing_toolset) def _register_candidates(name: str, candidates: List[_Candidate], *, check_fn: Callable, scope: Callable[[], Optional[str]], lazy: bool) -> List[str]: diff --git a/tools/mcp_tool_sampling.py b/tools/mcp_tool_sampling.py index a1aa99c2c5..9fef4414db 100644 --- a/tools/mcp_tool_sampling.py +++ b/tools/mcp_tool_sampling.py @@ -163,11 +163,16 @@ class SamplingHandler: self.metrics["errors"] += 1 return self._error(message) - def _build_tool_use_result(self, choice, response): - """Build a CreateMessageResultWithTools from an LLM tool_calls response.""" - self.metrics["tool_use_count"] += 1 + def _log_response(self, response, suffix: str = "", *args) -> None: + logger.log( + self.audit_level, "MCP server '%s' sampling response: model=%s, tokens=%s" + suffix, + self.server_name, response.model, _response_total_tokens(response, "?"), *args, + ) - # Tool-loop governance. + def _build_tool_use_result(self, choice, response): + """Build a CreateMessageResultWithTools from an LLM tool_calls response, + subject to tool-loop governance (``max_tool_rounds``; 0 disables).""" + self.metrics["tool_use_count"] += 1 if self.max_tool_rounds == 0: self._tool_loop_count = 0 return self._error(f"Tool loops disabled for server '{self.server_name}' (max_tool_rounds=0)") @@ -177,7 +182,6 @@ class SamplingHandler: return self._error( f"Tool loop limit exceeded for server '{self.server_name}' (max {self.max_tool_rounds} rounds)" ) - content_blocks = [ _core.ToolUseContent( type="tool_use", id=tc.id, name=tc.function.name, @@ -185,11 +189,7 @@ class SamplingHandler: ) for tc in choice.message.tool_calls ] - logger.log( - self.audit_level, - "MCP server '%s' sampling response: model=%s, tokens=%s, tool_calls=%d", - self.server_name, response.model, _response_total_tokens(response, "?"), len(content_blocks), - ) + self._log_response(response, ", tool_calls=%d", len(content_blocks)) return _core.CreateMessageResultWithTools( role="assistant", content=content_blocks, model=response.model, stopReason="toolUse", ) @@ -197,11 +197,7 @@ class SamplingHandler: def _build_text_result(self, choice, response): """Build a CreateMessageResult from a normal text response (resets the tool loop).""" self._tool_loop_count = 0 - logger.log( - self.audit_level, - "MCP server '%s' sampling response: model=%s, tokens=%s", - self.server_name, response.model, _response_total_tokens(response, "?"), - ) + self._log_response(response) return _core.CreateMessageResult( role="assistant", content=_core.TextContent(type="text", text=_sanitize_error(choice.message.content or "")), @@ -326,6 +322,8 @@ class ElicitationHandler: # asyncio-side safety net over the approval's own input() timeout so the # MCP loop never blocks indefinitely if the inner timeout is bypassed. _OUTER_TIMEOUT_GRACE_SECONDS = 5 + # consent answer -> (ElicitResult action, metric); anything else declines. + _ANSWER_RESULTS = {"accept": ("accept", "accepted"), "cancel": ("cancel", "errors")} def __init__(self, server_name: str, config: dict, owner: Optional["MCPServerTask"] = None): self.server_name = server_name @@ -344,9 +342,7 @@ class ElicitationHandler: def _result(self, action: str, metric: str): """Count *metric* and return ``ElicitResult(action)`` (accept carries empty content).""" self.metrics[metric] += 1 - if action == "accept": - return _core.ElicitResult(action="accept", content={}) - return _core.ElicitResult(action=action) + return _core.ElicitResult(action=action, content={}) if action == "accept" else _core.ElicitResult(action=action) def _consent_thunk(self, message: str, description: str) -> Callable[[], str]: """Sync consent call, replaying the agent's contextvars snapshot when the @@ -402,8 +398,4 @@ class ElicitationHandler: logger.error("MCP server '%s' elicitation failed: %s", self.server_name, exc, exc_info=True) return self._result("decline", "errors") - if answer == "accept": - return self._result("accept", "accepted") - if answer == "cancel": - return self._result("cancel", "errors") - return self._result("decline", "declined") + return self._result(*self._ANSWER_RESULTS.get(answer, ("decline", "declined"))) diff --git a/tools/mcp_tool_schema.py b/tools/mcp_tool_schema.py index ce3c62c188..a28c3ead51 100644 --- a/tools/mcp_tool_schema.py +++ b/tools/mcp_tool_schema.py @@ -11,7 +11,6 @@ from tools.mcp_tool_common import mcp_field logger = logging.getLogger("tools.mcp_tool") - # Prompt-injection indicators in MCP tool descriptions. WARNING-level only: # log but never block, since false positives would break legitimate servers. _MCP_INJECTION_PATTERNS = [ @@ -44,7 +43,6 @@ def _scan_mcp_description(server_name: str, tool_name: str, description: str) -> ) return findings - _EMPTY_OBJECT_SCHEMA = {"type": "object", "properties": {}} @@ -125,7 +123,6 @@ def sanitize_mcp_name_component(value: str) -> str: the historical behavior) so generated names pass provider validation.""" return re.sub(r"[^A-Za-z0-9_]", "_", str(value or "")) - # ``mcp____``: the convention shared by Claude Code, Codex and # OpenCode. The double underscore disambiguates the server/tool boundary even # when either contains underscores, and matches the Anthropic-OAuth wire form. @@ -147,7 +144,6 @@ def _convert_mcp_schema(server_name: str, mcp_tool) -> dict: "parameters": _normalize_mcp_input_schema(mcp_field(mcp_tool, "input_schema", "inputSchema")), } - # Utility tools generated per server: handler_key -> (description template, # parameter properties, required names). Schemas are FROZEN wire bytes — the # key order emitted by ``_build_utility_schemas`` must not change. @@ -209,7 +205,6 @@ def matches_name_filter(tool_name: str, patterns: set[str]) -> bool: return True return any(fnmatch.fnmatchcase(tool_name, p) for p in patterns if "*" in p or "?" in p or "[" in p) - # Utility handler -> ClientSession method it needs (legacy gate when no # initialize_result was captured). _UTILITY_CAPABILITY_METHODS = {key: key for key, *_ in _UTILITY_TOOL_SPECS} From a3a9cacf93d8fca4ef0282e8120b16c4f1b899b0 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 2 Sep 2026 16:00:08 -0700 Subject: [PATCH 6/9] refactor(mcp): collapse post-build re-injection getters and saved-prefix lookup --- tools/mcp_tool_agent.py | 39 +++++++++++++++++++-------------------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/tools/mcp_tool_agent.py b/tools/mcp_tool_agent.py index 963af71bda..7a2f75b81b 100644 --- a/tools/mcp_tool_agent.py +++ b/tools/mcp_tool_agent.py @@ -181,15 +181,14 @@ def restore_agent_tool_prefix(agent, saved_names: list) -> bool: fresh_defs = _agent_tool_defs(agent) fresh = {_def_name(t): t for t in fresh_defs} - saved_defs = [] - for name in saved_names: - entry_def = fresh.get(name) - if entry_def is None: - entry = registry.get_entry(name) - if entry is None: - continue - entry_def = {"type": "function", "function": {**entry.schema, "name": entry.name}} - saved_defs.append(entry_def) + + def _saved_def(name): + if name in fresh: + return fresh[name] + entry = registry.get_entry(name) + return None if entry is None else {"type": "function", "function": {**entry.schema, "name": entry.name}} + + saved_defs = [d for d in map(_saved_def, saved_names) if d is not None] registered_names = {entry.name for entry in registry.get_all_entries()} merged, merged_names = _merge_preserving_prefix(saved_defs, fresh_defs, registered_names) with _agent_tools_lock: @@ -235,11 +234,15 @@ def _reinject_post_build_tools(agent, tools_list: list, name_set: set) -> set: name_set.add(name) return True + def _schema_getter(attr: str, method: str): + owner = getattr(agent, attr, None) + getter = getattr(owner, method, None) if owner else None + return getter if callable(getter) else None + enabled = getattr(agent, "enabled_toolsets", None) try: - memory_manager = getattr(agent, "_memory_manager", None) - get_mem_schemas = getattr(memory_manager, "get_all_tool_schemas", None) if memory_manager else None - if callable(get_mem_schemas): + get_mem_schemas = _schema_getter("_memory_manager", "get_all_tool_schemas") + if get_mem_schemas is not None: # Same toolset gate inject_memory_provider_tools uses. from agent.memory_manager import memory_provider_tools_enabled if memory_provider_tools_enabled( @@ -255,14 +258,10 @@ def _reinject_post_build_tools(agent, tools_list: list, name_set: set) -> set: # restricted-toolset platform would re-leak tools the build excluded. staged_engine_names: set = set() try: - compressor = getattr(agent, "context_compressor", None) - get_schemas = getattr(compressor, "get_tool_schemas", None) if compressor else None - if (enabled is None or "context_engine" in enabled) and callable(get_schemas): - for schema in get_schemas(): - # Claim the routing name only when WE appended the schema. - if _add(schema): - staged_engine_names.add(schema["name"]) + get_schemas = _schema_getter("context_compressor", "get_tool_schemas") + if (enabled is None or "context_engine" in enabled) and get_schemas is not None: + # Claim the routing name only when WE appended the schema. + staged_engine_names.update(s["name"] for s in get_schemas() if _add(s)) except Exception: logger.debug("Context-engine tool re-injection skipped", exc_info=True) - return staged_engine_names From d9f6d9eda003a40ee41730a1aca0e6331d541a20 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 2 Sep 2026 16:01:24 -0700 Subject: [PATCH 7/9] refactor(mcp): wrap overlong lines in reg/sampling/schema/agent --- tools/mcp_tool_agent.py | 10 ++++-- tools/mcp_tool_registration.py | 58 ++++++++++++++++++++++++---------- tools/mcp_tool_sampling.py | 4 ++- tools/mcp_tool_schema.py | 3 +- 4 files changed, 54 insertions(+), 21 deletions(-) diff --git a/tools/mcp_tool_agent.py b/tools/mcp_tool_agent.py index 7a2f75b81b..697cd45118 100644 --- a/tools/mcp_tool_agent.py +++ b/tools/mcp_tool_agent.py @@ -48,8 +48,10 @@ def _tool_defs_content_changed(agent, new_defs: list) -> bool: return False -def _publish_tool_snapshot(agent, new_defs: list, new_names: set, *, snapshot_generation: int, - staged_engine_names: set, content_aware: bool, prefix_registered: Optional[set]) -> Optional[set]: +def _publish_tool_snapshot( + agent, new_defs: list, new_names: set, *, snapshot_generation: int, + staged_engine_names: set, content_aware: bool, prefix_registered: Optional[set], +) -> Optional[set]: """Single atomic read-diff-publish under ``_agent_tools_lock`` so ``added`` matches what was published and a stale (older-generation) rebuild can't overwrite a newer one. Returns the added names, or None when nothing was @@ -120,7 +122,9 @@ def refresh_agent_mcp_tools( snapshot_generation = registry._generation # Computed OUTSIDE the lock (can be slow); diff + publish happen together in # one critical section so concurrent callers can't torn-publish. - new_defs = list(get_tool_definitions(enabled_toolsets=enabled, disabled_toolsets=disabled, quiet_mode=quiet_mode) or []) + new_defs = list( + get_tool_definitions(enabled_toolsets=enabled, disabled_toolsets=disabled, quiet_mode=quiet_mode) or [] + ) new_names = {_def_name(t) for t in new_defs} # Re-append the post-build families on LOCALS only; live agent attributes # are untouched until the single atomic publish. diff --git a/tools/mcp_tool_registration.py b/tools/mcp_tool_registration.py index 061c0caa5c..06e7096a12 100644 --- a/tools/mcp_tool_registration.py +++ b/tools/mcp_tool_registration.py @@ -95,7 +95,9 @@ def _select_utility_schemas(server_name: str, server: "MCPServerTask", config: d if not enabled[family]: return f"{family} disabled" if advertised is not None: - return None if getattr(advertised, family, None) is not None else f"server does not advertise '{family}' capability" + if getattr(advertised, family, None) is None: + return f"server does not advertise '{family}' capability" + return None method = _UTILITY_CAPABILITY_METHODS[handler_key] return None if hasattr(server.session, method) else f"session lacks {method}" @@ -163,7 +165,10 @@ class _CachedMCPTool: for raw in raws: if isinstance(raw, dict) and raw.get("name"): schema = raw.get("inputSchema") - out.append(cls(raw["name"], raw.get("description") or "", schema if isinstance(schema, dict) else {}, raw.get("annotations"))) + out.append(cls( + raw["name"], raw.get("description") or "", + schema if isinstance(schema, dict) else {}, raw.get("annotations"), + )) return out @@ -182,7 +187,9 @@ class _Candidate: return self.origin.startswith(_UTILITY_ORIGIN_PREFIX) -def _tool_candidates(name: str, tools: Iterable[Any], should_register: Callable[[str], bool], tool_timeout) -> List[_Candidate]: +def _tool_candidates( + name: str, tools: Iterable[Any], should_register: Callable[[str], bool], tool_timeout, +) -> List[_Candidate]: """Native tools (live SDK objects or ``_CachedMCPTool``) -> candidates. The injection scan runs on BOTH paths: the cache file is user-writable JSON.""" out: List[_Candidate] = [] @@ -192,7 +199,8 @@ def _tool_candidates(name: str, tools: Iterable[Any], should_register: Callable[ continue _core._scan_mcp_description(name, t.name, t.description or "") schema = _core._convert_mcp_schema(name, t) - out.append(_Candidate(schema["name"], f"tool {t.name!r}", schema, _core._make_tool_handler(name, t.name, tool_timeout))) + handler = _core._make_tool_handler(name, t.name, tool_timeout) + out.append(_Candidate(schema["name"], f"tool {t.name!r}", schema, handler)) return out @@ -204,7 +212,8 @@ def _utility_candidates(name: str, entries: Iterable[Any], tool_timeout) -> List continue schema, key = raw.get("schema"), raw.get("handler_key") if isinstance(schema, dict) and key in _UTILITY_HANDLER_FACTORIES and schema.get("name"): - out.append(_Candidate(schema["name"], f"{_UTILITY_ORIGIN_PREFIX}{key!r}", schema, _UTILITY_HANDLER_FACTORIES[key](name, tool_timeout))) + handler = _UTILITY_HANDLER_FACTORIES[key](name, tool_timeout) + out.append(_Candidate(schema["name"], f"{_UTILITY_ORIGIN_PREFIX}{key!r}", schema, handler)) return out @@ -220,7 +229,10 @@ def _resolve_name_collisions(name: str, candidates: List[_Candidate]) -> List[_C origins_by_name: Dict[str, set[str]] = {} for c in candidates: if (c.registry_name, c.origin) in seen: - logger.debug("MCP server '%s': duplicate registration candidate %s for '%s'; keeping one", name, c.origin, c.registry_name) + logger.debug( + "MCP server '%s': duplicate registration candidate %s for '%s'; keeping one", + name, c.origin, c.registry_name, + ) continue seen.add((c.registry_name, c.origin)) unique.append(c) @@ -256,17 +268,26 @@ def _log_foreign_owner(name: str, c: _Candidate, existing_toolset: str, lazy: bo """Diagnostics for a name already owned by another toolset (skipped to preserve the owner).""" if lazy: if not c.is_utility: - logger.warning("MCP server '%s' (lazy): cached tool '%s' collides with toolset '%s' — skipping", name, c.registry_name, existing_toolset) + logger.warning( + "MCP server '%s' (lazy): cached tool '%s' collides with toolset '%s' — skipping", + name, c.registry_name, existing_toolset, + ) return - log, fmt = ( - (logger.error, "MCP server '%s': %s normalizes to '%s', already owned by MCP toolset '%s' — skipping to preserve the existing owner") - if existing_toolset.startswith("mcp-") else - (logger.warning, "MCP server '%s': %s (→ '%s') collides with built-in tool in toolset '%s' — skipping to preserve built-in") - ) + if existing_toolset.startswith("mcp-"): + log, fmt = logger.error, ( + "MCP server '%s': %s normalizes to '%s', already owned by MCP toolset '%s' " + "— skipping to preserve the existing owner" + ) + else: + log, fmt = logger.warning, ( + "MCP server '%s': %s (→ '%s') collides with built-in tool in toolset '%s' — skipping to preserve built-in" + ) log(fmt, name, c.origin, c.registry_name, existing_toolset) -def _register_candidates(name: str, candidates: List[_Candidate], *, check_fn: Callable, scope: Callable[[], Optional[str]], lazy: bool) -> List[str]: +def _register_candidates( + name: str, candidates: List[_Candidate], *, check_fn: Callable, scope: Callable[[], Optional[str]], lazy: bool, +) -> List[str]: """Register candidates under toolset ``mcp-{name}``; returns the names that landed. The ownership pre-check is advisory only — servers connect in parallel, so ``ToolRegistry.register()`` is the atomic ownership gate and @@ -287,7 +308,8 @@ def _register_candidates(name: str, candidates: List[_Candidate], *, check_fn: C if registry.get_toolset_for_tool(c.registry_name) != toolset_name: if not lazy: logger.error( - "MCP server '%s': registration of %s as '%s' was rejected by the registry; skipping provenance/count updates", + "MCP server '%s': registration of %s as '%s' was rejected by the registry; " + "skipping provenance/count updates", name, c.origin, c.registry_name, ) continue @@ -315,7 +337,9 @@ def _write_schema_cache(name: str, server: "MCPServerTask", config: dict, should # Persisted so the lazy path trust-gates identically next startup. "annotations": {"readOnlyHint": _annotation_read_only_hint(t)}, }) - utility_payload = [{"schema": e["schema"], "handler_key": e["handler_key"]} for e in _select_utility_schemas(name, server, config)] + utility_payload = [ + {"schema": e["schema"], "handler_key": e["handler_key"]} for e in _select_utility_schemas(name, server, config) + ] cache_meta = getattr(server, "_list_cache_meta", None) or {} write_cache_entry( name, config_fingerprint(config), tools=tools_payload, utility_tools=utility_payload, @@ -360,7 +384,9 @@ def _register_from_cache_sync(name: str, config: dict, entry: dict) -> List[str] _record_tool_trust_metadata(name, config, cached_tools) candidates = _tool_candidates(name, cached_tools, _make_tool_filter(name, config), tool_timeout) candidates += _utility_candidates(name, utility_tools_from_cache_entry(entry), tool_timeout) - registered = _register_candidates(name, candidates, check_fn=_make_check_fn(name), scope=_core._mcp_registry_scope, lazy=True) + registered = _register_candidates( + name, candidates, check_fn=_make_check_fn(name), scope=_core._mcp_registry_scope, lazy=True, + ) if registered: with _core._lock: _core._lazy_server_configs[name] = dict(config) diff --git a/tools/mcp_tool_sampling.py b/tools/mcp_tool_sampling.py index 9fef4414db..598a3bd6e0 100644 --- a/tools/mcp_tool_sampling.py +++ b/tools/mcp_tool_sampling.py @@ -342,7 +342,9 @@ class ElicitationHandler: def _result(self, action: str, metric: str): """Count *metric* and return ``ElicitResult(action)`` (accept carries empty content).""" self.metrics[metric] += 1 - return _core.ElicitResult(action=action, content={}) if action == "accept" else _core.ElicitResult(action=action) + if action == "accept": + return _core.ElicitResult(action="accept", content={}) + return _core.ElicitResult(action=action) def _consent_thunk(self, message: str, description: str) -> Callable[[], str]: """Sync consent call, replaying the agent's contextvars snapshot when the diff --git a/tools/mcp_tool_schema.py b/tools/mcp_tool_schema.py index a28c3ead51..01e620d3ba 100644 --- a/tools/mcp_tool_schema.py +++ b/tools/mcp_tool_schema.py @@ -132,7 +132,8 @@ _MCP_NAME_DELIM = "__" def mcp_prefixed_tool_name(server_name: str, tool_name: str) -> str: """Registry/wire name: ``mcp____``.""" - return f"{MCP_TOOL_NAME_PREFIX}{sanitize_mcp_name_component(server_name)}{_MCP_NAME_DELIM}{sanitize_mcp_name_component(tool_name)}" + safe_server, safe_tool = sanitize_mcp_name_component(server_name), sanitize_mcp_name_component(tool_name) + return f"{MCP_TOOL_NAME_PREFIX}{safe_server}{_MCP_NAME_DELIM}{safe_tool}" def _convert_mcp_schema(server_name: str, mcp_tool) -> dict: From 410e95e100342908239118db395e8ede4e374b74 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 2 Sep 2026 16:01:37 -0700 Subject: [PATCH 8/9] refactor(mcp): restore E305 spacing after squeeze --- tools/mcp_tool_common.py | 5 +++++ tools/mcp_tool_config.py | 3 +++ tools/mcp_tool_lifecycle.py | 1 + tools/mcp_tool_schema.py | 4 ++++ 4 files changed, 13 insertions(+) diff --git a/tools/mcp_tool_common.py b/tools/mcp_tool_common.py index bdd91de8aa..0e96d04200 100644 --- a/tools/mcp_tool_common.py +++ b/tools/mcp_tool_common.py @@ -26,6 +26,7 @@ class _OriginProxy: return getattr(mcp_tool, name) + _core = _OriginProxy() _MISSING = object() @@ -41,6 +42,7 @@ def mcp_field(obj, snake: str, camel: str, default=None): value = getattr(obj, camel, _MISSING) return default if value is _MISSING else value + _DEFAULT_TOOL_TIMEOUT = 300 # seconds for tool calls @@ -61,6 +63,7 @@ def _resolve_tool_timeout(config: dict) -> float: logger.debug("mcp.tool_call timeout resolution failed", exc_info=True) return _DEFAULT_TOOL_TIMEOUT + # Jitter on reconnect backoff so servers that lost the same backend don't # retry in lockstep (thundering herd, synchronized log bursts). _BACKOFF_JITTER = 0.2 # +/-20% @@ -70,6 +73,7 @@ def _jittered(seconds: float) -> float: """``seconds`` with +/-20% uniform jitter, floored at 0.""" return max(0.0, seconds * random.uniform(1.0 - _BACKOFF_JITTER, 1.0 + _BACKOFF_JITTER)) + # Credential patterns to strip from error messages. _CREDENTIAL_PATTERN = re.compile( r"(?:" @@ -131,6 +135,7 @@ def _safe_numeric(value, default, coerce=int, minimum=1): except (TypeError, ValueError, OverflowError): return default + _TRUE_WORDS = frozenset({"true", "1", "yes", "on"}) _FALSE_WORDS = frozenset({"false", "0", "no", "off"}) diff --git a/tools/mcp_tool_config.py b/tools/mcp_tool_config.py index 940fdc0e9e..feede5259d 100644 --- a/tools/mcp_tool_config.py +++ b/tools/mcp_tool_config.py @@ -55,6 +55,7 @@ def _write_stderr_log_header(server_name: str) -> None: except Exception: pass + # Env vars safe to pass to stdio subprocesses (no secrets). _SAFE_ENV_KEYS = frozenset({"PATH", "HOME", "USER", "LANG", "LC_ALL", "TERM", "SHELL", "TMPDIR"}) @@ -91,6 +92,7 @@ def _workspace_basename() -> str: root = _core._workspace_folder() return os.path.basename(root.rstrip("/\\")) or root + # Cursor's case-sensitive context vars -> resolver. _CONTEXT_VAR_RESOLVERS = { "userHome": lambda: os.path.expanduser("~"), @@ -225,6 +227,7 @@ def _interpolate_env_vars(value): return [_interpolate_env_vars(v) for v in value] return value + # (server_name, dotted key path) pairs already warned about; config loads # happen on every discovery pass, so warn once per process. _whitespace_warned: Set[Tuple[str, str]] = set() diff --git a/tools/mcp_tool_lifecycle.py b/tools/mcp_tool_lifecycle.py index 45890dad4f..3b3f730780 100644 --- a/tools/mcp_tool_lifecycle.py +++ b/tools/mcp_tool_lifecycle.py @@ -57,6 +57,7 @@ def _snapshot_child_pids() -> set: return set() + # argv markers of non-MCP gateway children that can race into the snapshot # delta during an MCP spawn (defense-in-depth; LSP/slash_worker already use # start_new_session). Matched against argv[1:] because Python/Java children diff --git a/tools/mcp_tool_schema.py b/tools/mcp_tool_schema.py index 01e620d3ba..c654861636 100644 --- a/tools/mcp_tool_schema.py +++ b/tools/mcp_tool_schema.py @@ -43,6 +43,7 @@ def _scan_mcp_description(server_name: str, tool_name: str, description: str) -> ) return findings + _EMPTY_OBJECT_SCHEMA = {"type": "object", "properties": {}} @@ -123,6 +124,7 @@ def sanitize_mcp_name_component(value: str) -> str: the historical behavior) so generated names pass provider validation.""" return re.sub(r"[^A-Za-z0-9_]", "_", str(value or "")) + # ``mcp____``: the convention shared by Claude Code, Codex and # OpenCode. The double underscore disambiguates the server/tool boundary even # when either contains underscores, and matches the Anthropic-OAuth wire form. @@ -145,6 +147,7 @@ def _convert_mcp_schema(server_name: str, mcp_tool) -> dict: "parameters": _normalize_mcp_input_schema(mcp_field(mcp_tool, "input_schema", "inputSchema")), } + # Utility tools generated per server: handler_key -> (description template, # parameter properties, required names). Schemas are FROZEN wire bytes — the # key order emitted by ``_build_utility_schemas`` must not change. @@ -206,6 +209,7 @@ def matches_name_filter(tool_name: str, patterns: set[str]) -> bool: return True return any(fnmatch.fnmatchcase(tool_name, p) for p in patterns if "*" in p or "?" in p or "[" in p) + # Utility handler -> ClientSession method it needs (legacy gate when no # initialize_result was captured). _UTILITY_CAPABILITY_METHODS = {key: key for key, *_ in _UTILITY_TOOL_SPECS} From 538b9eedaeb165006a7cd5e49568c2423682d54e Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 2 Sep 2026 16:05:08 -0700 Subject: [PATCH 9/9] refactor(mcp): flatten child-pid snapshot and MCP-child filter --- tools/mcp_tool_lifecycle.py | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/tools/mcp_tool_lifecycle.py b/tools/mcp_tool_lifecycle.py index 3b3f730780..71a338c443 100644 --- a/tools/mcp_tool_lifecycle.py +++ b/tools/mcp_tool_lifecycle.py @@ -31,7 +31,6 @@ _stdio_pgids: Dict[int, int] = {} def _snapshot_child_pids() -> set: """Current direct-child PIDs: /proc on Linux, else psutil, else empty set.""" my_pid = os.getpid() - # /proc//task//children is per-THREAD, and stdio_client() spawns # from the MCP loop thread, so union every task's children — reading only # the main thread's file returns an empty set on every Linux install. @@ -48,14 +47,11 @@ def _snapshot_child_pids() -> set: return found except (FileNotFoundError, OSError, ValueError): pass - try: import psutil return {c.pid for c in psutil.Process(my_pid).children()} except Exception: - pass - - return set() + return set() # argv markers of non-MCP gateway children that can race into the snapshot @@ -81,17 +77,15 @@ def _filter_mcp_children(pids: set) -> set: import psutil except ImportError: return pids # keep all PIDs (prior behavior) - filtered: set = set() - for pid in pids: + + def _is_mcp(pid: int) -> bool: try: argv = psutil.Process(pid).cmdline() except (psutil.NoSuchProcess, psutil.AccessDenied, OSError): - # Raced away or zombie — cannot be our fresh server, unsafe to track. - continue - if any(marker in arg for arg in argv[1:] for marker in _NON_MCP_CHILD_CMDLINE_MARKERS): - continue - filtered.add(pid) - return filtered + return False # raced away or zombie — cannot be our fresh server, unsafe to track + return not any(marker in arg for arg in argv[1:] for marker in _NON_MCP_CHILD_CMDLINE_MARKERS) + + return {pid for pid in pids if _is_mcp(pid)} def _clear_connect_cooldowns() -> None: