Merge branch 'simp/r2a-mcp-reg' into simp/r2a-mcp

This commit is contained in:
Teknium
2026-09-02 16:15:20 -07:00
9 changed files with 1040 additions and 1541 deletions
+26 -40
View File
@@ -58,38 +58,29 @@ 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):
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(
@@ -101,17 +92,10 @@ 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`.
"""
entry = {
"fingerprint": fingerprint,
"tools": tools,
"utility_tools": utility_tools or [],
}
"""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
entry["written_at"] = time.time()
@@ -119,24 +103,26 @@ 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
_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")
+22 -39
View File
@@ -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 <original_parent_pid> -- <real_command> <arg1> <arg2> ...
@@ -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:
@@ -78,9 +75,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)
@@ -92,20 +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.
proc = subprocess.Popen(
real_argv,
stdin=sys.stdin,
stdout=sys.stdout,
stderr=sys.stderr,
start_new_session=True,
)
# 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)
@@ -113,12 +101,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()
+140 -160
View File
@@ -5,17 +5,84 @@ 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")
# 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.
_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 _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,
*,
@@ -25,120 +92,57 @@ 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
# 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
# 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 []
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_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 = list(getattr(agent, "tools", None) or [])
current = {t["function"]["name"] 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()
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)
@@ -163,38 +167,32 @@ 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)
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
fresh_defs = list(getattr(agent, "tools", None) or [])
fresh = {t["function"]["name"]: 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)
fresh_defs = _agent_tool_defs(agent)
fresh = {_def_name(t): t for t in fresh_defs}
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:
@@ -202,69 +200,60 @@ 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
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.
"""
fresh = {}
for entry in new_defs:
name = (entry.get("function") or {}).get("name", "")
if name:
fresh[name] = entry
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:
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:
"""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.
"""
def _add(schema: dict) -> bool:
name = schema.get("name", "")
``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:
return False
tools_list.append({"type": "function", "function": schema})
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(
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,19 +262,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:
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):
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)
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
+18 -23
View File
@@ -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,23 +28,18 @@ 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 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 +71,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 +136,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 +148,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 +170,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
+122 -169
View File
@@ -8,26 +8,20 @@ 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
logger = logging.getLogger("tools.mcp_tool")
_mcp_stderr_log_fh: Optional[Any] = None
_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:
@@ -36,10 +30,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 +57,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,47 +88,87 @@ 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:
"""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
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,82 +179,39 @@ 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):
"""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):
@@ -254,8 +219,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()}
@@ -271,12 +235,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:
@@ -301,8 +263,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 +271,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 +313,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 +328,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)
+101 -159
View File
@@ -10,21 +10,16 @@ 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] = {}
# 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
@@ -36,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/<pid>/task/<tid>/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.
@@ -53,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
@@ -77,49 +68,42 @@ _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:
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:
"""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.
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 —
@@ -127,38 +111,27 @@ 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
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,
)
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,137 +142,112 @@ 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:
"""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).
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
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: 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
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 = dict(_stdio_pids)
if server_name is not None:
active = {
pid: owner
for pid, owner in active.items()
if owner == server_name
}
active = _owned(_stdio_pids)
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)
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
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)."""
import signal as _signal
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:
"""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:
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()
@@ -312,29 +260,23 @@ async def _drain_mcp_loop_tasks(
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:
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:
"""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)
+265 -406
View File
@@ -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 ``_Candidate``
records and feed 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,47 +18,45 @@ 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
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 == _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,
"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):
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)
@@ -76,178 +77,247 @@ 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)
"""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 because
# ClientSession defines all four methods on the class.
advertised_caps = None
``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 {}
enabled = {f: _parse_boolish(tools_filter.get(f), default=True) for f in ("resources", "prompts")}
init_result = getattr(server, "initialize_result", None)
if init_result is not None:
advertised_caps = getattr(init_result, "capabilities", 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:
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}"
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)
reason = _skip_reason(entry["handler_key"])
if reason:
logger.debug("MCP server '%s': skipping utility '%s' (%s)", server_name, entry["handler_key"], reason)
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:
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,
)
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:
schema = _core._convert_mcp_schema(server.name, mcp_tool)
names.append(schema["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:
lazy_names = [
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)
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
)
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.
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")
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:
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
def _resolve_name_collisions(name: str, candidates: List[dict]):
class _CachedMCPTool:
"""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")
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 rows -> stand-ins; rows that are not dicts or lack a name are dropped."""
out = []
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"),
))
return out
@dataclass
class _Candidate:
"""One registration attempt: a native tool or a generated utility.
``origin`` is the provenance text 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)
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] = []
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, t.name, t.description or "")
schema = _core._convert_mcp_schema(name, t)
handler = _core._make_tool_handler(name, t.name, tool_timeout)
out.append(_Candidate(schema["name"], f"tool {t.name!r}", schema, handler))
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 dropped."""
out: List[_Candidate] = []
for raw in entries:
if not isinstance(raw, dict):
continue
schema, key = raw.get("schema"), raw.get("handler_key")
if isinstance(schema, dict) and key in _UTILITY_HANDLER_FACTORIES and schema.get("name"):
handler = _UTILITY_HANDLER_FACTORIES[key](name, tool_timeout)
out.append(_Candidate(schema["name"], f"{_UTILITY_ORIGIN_PREFIX}{key!r}", schema, handler))
return out
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 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).
"""
unique_candidates: List[dict] = []
seen_candidates: set[tuple[str, str]] = set()
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 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],
"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_names[registry_name] = sorted(origins)
for registry_name, origins in sorted(ambiguous_names.items()):
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",
name,
registry_name,
", ".join(origins),
"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 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 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,
)
return
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]:
"""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
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.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",
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,282 +326,71 @@ 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] = []
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),
},
})
tools_payload = []
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": entry["schema"], "handler_key": entry["handler_key"]}
for entry in _select_utility_schemas(name, server, config)
{"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. 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)
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.
one registry name; such collisions fail closed. Generated utilities share
the namespace and join the same preflight."""
should_register = _make_tool_filter(name, config)
_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=_make_check_fn(name), 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,
)
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
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=_make_check_fn(name), 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
+227 -345
View File
@@ -1,46 +1,129 @@
"""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.
"""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"}
_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}
@@ -48,8 +131,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)
@@ -59,100 +141,15 @@ 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"))
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,78 +158,49 @@ class SamplingHandler:
return _core.ErrorData(code=code, message=message)
raise Exception(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 _fail(self, message: str):
"""Count an error and return the ErrorData for it."""
self.metrics["errors"] += 1
return self._error(message)
# Tool-loop governance.
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,
)
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)"
)
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,
))
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),
)
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
]
self._log_response(response, ", tool_calls=%d", 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._log_response(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 +209,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,31 +304,26 @@ 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)
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.
_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
@@ -411,111 +333,71 @@ 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={})
if answer == "cancel":
self.metrics["errors"] += 1
return _core.ElicitResult(action="cancel")
self.metrics["declined"] += 1
return _core.ElicitResult(action="decline")
return self._result(*self._ANSWER_RESULTS.get(answer, ("decline", "declined")))
+119 -200
View File
@@ -11,148 +11,111 @@ 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 = [
(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) — 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):
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``.
"""
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 {"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,15 +129,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__<sanitizedServer>__<sanitizedTool>``."""
safe_server = sanitize_mcp_name_component(server_name)
safe_tool = 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}"
@@ -183,81 +143,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 +207,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