mcp_tool_sampling.py 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323
  1. """MCP client-side handlers for server-initiated requests: sampling
  2. (sampling/createMessage, text and tool-use results) and elicitation."""
  3. import asyncio
  4. import functools
  5. import json
  6. import logging
  7. import time
  8. from contextvars import Context
  9. from typing import TYPE_CHECKING, Callable, List, Optional
  10. from utils import is_truthy_value
  11. from tools.mcp_tool_common import _MISSING, _exc_str, _safe_numeric, _sanitize_error, mcp_field, _core
  12. from tools.mcp_tool_schema import _normalize_mcp_input_schema
  13. logger = logging.getLogger("tools.mcp_tool")
  14. def _tool_use_id(block):
  15. """Tool-use id (marks a tool *result* block) under both SDK spellings — on mcp 2.x a bare
  16. ``hasattr(b, "toolUseId")`` is False and would silently drop tool results."""
  17. return mcp_field(block, "tool_use_id", "toolUseId", _MISSING)
  18. def _tool_result_text(block) -> str:
  19. """Text of a ToolResultContent block ("" when it carries no content)."""
  20. content = getattr(block, "content", None)
  21. if content is None:
  22. return ""
  23. items = content if isinstance(content, list) else [content]
  24. return "\n".join(item.text for item in items if hasattr(item, "text"))
  25. def _content_part(block) -> Optional[dict]:
  26. """One OpenAI content part for a text/image block; None when unsupported."""
  27. if hasattr(block, "text"):
  28. return {"type": "text", "text": block.text}
  29. mime = mcp_field(block, "mime_type", "mimeType", _MISSING)
  30. if hasattr(block, "data") and mime is not _MISSING:
  31. return {"type": "image_url", "image_url": {"url": f"data:{mime};base64,{block.data}"}}
  32. logger.warning("Unsupported sampling content block type: %s (skipped)", type(block).__name__)
  33. return None
  34. def _tool_call_dict(tu, index: int) -> dict:
  35. args = tu.input
  36. return {"id": getattr(tu, "id", f"call_{index}"), "type": "function", "function": {
  37. "name": tu.name, "arguments": json.dumps(args, ensure_ascii=False) if isinstance(args, dict) else str(args)}}
  38. def _convert_sampling_message(msg) -> list[dict]:
  39. """One MCP SamplingMessage -> OpenAI messages: tool results first, then either an assistant
  40. tool_calls message or plain content."""
  41. blocks = msg.content_as_list if hasattr(msg, "content_as_list") else (
  42. msg.content if isinstance(msg.content, list) else [msg.content])
  43. tool_results = [b for b in blocks if _tool_use_id(b) is not _MISSING]
  44. others = [b for b in blocks if _tool_use_id(b) is _MISSING]
  45. tool_uses = [b for b in others if hasattr(b, "name") and hasattr(b, "input")]
  46. content_blocks = [b for b in others if not (hasattr(b, "name") and hasattr(b, "input"))]
  47. out = [{"role": "tool", "tool_call_id": _tool_use_id(tr), "content": _tool_result_text(tr)} for tr in tool_results]
  48. if tool_uses:
  49. msg_dict: dict = {"role": msg.role, "tool_calls": [_tool_call_dict(tu, i) for i, tu in enumerate(tool_uses)]}
  50. text_parts = [b.text for b in content_blocks if hasattr(b, "text")]
  51. if text_parts:
  52. msg_dict["content"] = "\n".join(text_parts)
  53. out.append(msg_dict)
  54. elif len(content_blocks) == 1 and hasattr(content_blocks[0], "text"):
  55. out.append({"role": msg.role, "content": content_blocks[0].text})
  56. elif content_blocks:
  57. parts = [p for p in map(_content_part, content_blocks) if p is not None]
  58. if parts:
  59. out.append({"role": msg.role, "content": parts})
  60. return out
  61. def _parse_tool_call_arguments(server_name: str, args) -> dict:
  62. """LLM tool_calls arguments -> dict; malformed JSON / non-dicts become ``{"_raw": ...}``, not dropped."""
  63. if isinstance(args, str):
  64. try:
  65. return json.loads(args)
  66. except (json.JSONDecodeError, ValueError):
  67. logger.warning("MCP server '%s': malformed tool_calls arguments from LLM (wrapping as raw): %.100s",
  68. server_name, args)
  69. return {"_raw": args}
  70. return args if isinstance(args, dict) else {"_raw": str(args)}
  71. class SamplingHandler:
  72. """``sampling_callback`` for one MCP server (per-instance rate-limit, metrics, tool-loop state).
  73. Runs on the MCP loop; the sync LLM call is offloaded via ``asyncio.to_thread``. Deprecated
  74. upstream (MCP 2026-07-28, SEP-2577): stays functional for handshake-era servers, but do NOT grow
  75. new capability here — modern servers use MRTR, handled by the SDK session layer."""
  76. _STOP_REASON_MAP = {"stop": "endTurn", "length": "maxTokens", "tool_calls": "toolUse"}
  77. _LOG_LEVELS = {"debug": logging.DEBUG, "info": logging.INFO, "warning": logging.WARNING}
  78. def __init__(self, server_name: str, config: dict):
  79. self.server_name = server_name
  80. self.max_rpm = _safe_numeric(config.get("max_rpm", 10), 10, int)
  81. self.timeout = _safe_numeric(config.get("timeout", 30), 30, float)
  82. self.max_tokens_cap = _safe_numeric(config.get("max_tokens_cap", 4096), 4096, int)
  83. self.max_tool_rounds = _safe_numeric(config.get("max_tool_rounds", 5), 5, int, minimum=0)
  84. # Strict MCP servers reject the unknown sampling.tools sub-capability during
  85. # initialization, so it is opt-in per server (default: plain sampling). (#5468)
  86. self.expose_client_tools = is_truthy_value(config.get("expose_client_tools"), default=False)
  87. self.model_override = config.get("model")
  88. self.allowed_models = config.get("allowed_models", [])
  89. self.audit_level = self._LOG_LEVELS.get(str(config.get("log_level", "info")).lower(), logging.INFO)
  90. self._rate_timestamps: list[float] = []
  91. self._tool_loop_count = 0
  92. self.metrics = {"requests": 0, "errors": 0, "tokens_used": 0, "tool_use_count": 0}
  93. def _check_rate_limit(self) -> bool:
  94. """Sliding-window (60s) limiter; True if the request is allowed."""
  95. now = time.time()
  96. self._rate_timestamps[:] = [t for t in self._rate_timestamps if t > now - 60]
  97. if len(self._rate_timestamps) >= self.max_rpm:
  98. return False
  99. self._rate_timestamps.append(now)
  100. return True
  101. def _resolve_model(self, preferences) -> Optional[str]:
  102. """Config override > server hint > None (use default)."""
  103. if self.model_override:
  104. return self.model_override
  105. hints = getattr(preferences, "hints", None) or []
  106. return next((hint.name for hint in hints if getattr(hint, "name", None)), None)
  107. def _convert_messages(self, params) -> list[dict]:
  108. """MCP SamplingMessages -> OpenAI format (per-block duck-typed dispatch)."""
  109. return [m for msg in params.messages for m in _convert_sampling_message(msg)]
  110. @staticmethod
  111. def _error(message: str, code: int = -1):
  112. """Return ErrorData (MCP spec) or raise as fallback."""
  113. if not _core._MCP_SAMPLING_TYPES:
  114. raise Exception(message)
  115. return _core.ErrorData(code=code, message=message)
  116. def _fail(self, message: str):
  117. """Count an error and return the ErrorData for it."""
  118. self.metrics["errors"] += 1
  119. return self._error(message)
  120. def _log_response(self, response, suffix: str = "", *args) -> None:
  121. logger.log(self.audit_level, "MCP server '%s' sampling response: model=%s, tokens=%s" + suffix,
  122. self.server_name, response.model, getattr(getattr(response, "usage", None), "total_tokens", "?"), *args)
  123. def _build_tool_use_result(self, choice, response):
  124. """CreateMessageResultWithTools from a tool_calls response, under ``max_tool_rounds`` (0 disables)."""
  125. self.metrics["tool_use_count"] += 1
  126. self._tool_loop_count += 1
  127. if self.max_tool_rounds == 0 or self._tool_loop_count > self.max_tool_rounds:
  128. self._tool_loop_count = 0
  129. return self._error(
  130. f"Tool loops disabled for server '{self.server_name}' (max_tool_rounds=0)" if self.max_tool_rounds == 0
  131. else f"Tool loop limit exceeded for server '{self.server_name}' (max {self.max_tool_rounds} rounds)")
  132. content_blocks = [_core.ToolUseContent(type="tool_use", id=tc.id, name=tc.function.name,
  133. input=_parse_tool_call_arguments(self.server_name, tc.function.arguments))
  134. for tc in choice.message.tool_calls]
  135. self._log_response(response, ", tool_calls=%d", len(content_blocks))
  136. return _core.CreateMessageResultWithTools(
  137. role="assistant", content=content_blocks, model=response.model, stopReason="toolUse")
  138. def _build_text_result(self, choice, response):
  139. """CreateMessageResult from a normal text response (resets the tool loop)."""
  140. self._tool_loop_count = 0
  141. self._log_response(response)
  142. return _core.CreateMessageResult(
  143. role="assistant", model=response.model,
  144. content=_core.TextContent(type="text", text=_sanitize_error(choice.message.content or "")),
  145. stopReason=self._STOP_REASON_MAP.get(choice.finish_reason, "endTurn"))
  146. def session_kwargs(self) -> dict:
  147. """Kwargs to pass to ClientSession for sampling support."""
  148. sampling_capabilities = (
  149. _core.SamplingCapability(tools=_core.SamplingToolsCapability())
  150. if self.expose_client_tools
  151. else _core.SamplingCapability()
  152. )
  153. return {"sampling_callback": self,
  154. "sampling_capabilities": sampling_capabilities}
  155. def _admit(self, params):
  156. """Rate-limit + allowed_models gate. Returns ``(resolved_model, None)`` or ``(None, ErrorData)``."""
  157. if not self._check_rate_limit():
  158. logger.warning("MCP server '%s' sampling rate limit exceeded (%d/min)", self.server_name, self.max_rpm)
  159. return None, self._fail(
  160. f"Sampling rate limit exceeded for server '{self.server_name}' ({self.max_rpm} requests/minute)")
  161. resolved_model = self._resolve_model(mcp_field(params, "model_preferences", "modelPreferences")) or ""
  162. if self.allowed_models and resolved_model and resolved_model not in self.allowed_models:
  163. logger.warning("MCP server '%s' requested model '%s' not in allowed_models",
  164. self.server_name, resolved_model)
  165. return None, self._fail(f"Model '{resolved_model}' not allowed for server "
  166. f"'{self.server_name}'. Allowed: {', '.join(self.allowed_models)}")
  167. return resolved_model, None
  168. def _build_llm_call(self, params, resolved_model: str) -> Callable[[], object]:
  169. """Sampling params -> zero-arg sync ``call_llm`` thunk (run off-loop); server tools are forwarded."""
  170. from agent.auxiliary_client import call_llm
  171. messages = self._convert_messages(params)
  172. system_prompt = mcp_field(params, "system_prompt", "systemPrompt")
  173. if system_prompt:
  174. messages.insert(0, {"role": "system", "content": system_prompt})
  175. max_tokens = min(mcp_field(params, "max_tokens", "maxTokens", self.max_tokens_cap), self.max_tokens_cap)
  176. server_tools = getattr(params, "tools", None)
  177. tools = [{"type": "function", "function": {
  178. "name": getattr(t, "name", ""), "description": getattr(t, "description", "") or "",
  179. "parameters": _normalize_mcp_input_schema(mcp_field(t, "input_schema", "inputSchema"))}}
  180. for t in server_tools] if server_tools else None
  181. logger.log(self.audit_level, "MCP server '%s' sampling request: model=%s, max_tokens=%d, messages=%d",
  182. self.server_name, resolved_model, max_tokens, len(messages))
  183. return lambda: call_llm(task="mcp", model=resolved_model or None, messages=messages, max_tokens=max_tokens,
  184. temperature=getattr(params, "temperature", None), tools=tools, timeout=self.timeout)
  185. async def __call__(self, context, params):
  186. """SDK ``SamplingFnT``: CreateMessageResult, CreateMessageResultWithTools, or ErrorData."""
  187. resolved_model, err = self._admit(params)
  188. if err is not None:
  189. return err
  190. sync_call = self._build_llm_call(params, resolved_model) # outside the try: its errors propagate, not _fail
  191. try:
  192. response = await asyncio.wait_for(asyncio.to_thread(sync_call), timeout=self.timeout)
  193. except TimeoutError:
  194. return self._fail(f"Sampling LLM call timed out after {self.timeout}s for server '{self.server_name}'")
  195. except Exception as exc:
  196. return self._fail(f"Sampling LLM call failed: {_sanitize_error(_exc_str(exc))}")
  197. # Empty choices happen on content filtering / provider errors.
  198. if not getattr(response, "choices", None):
  199. return self._fail(f"LLM returned empty response (no choices) for server '{self.server_name}'")
  200. choice = response.choices[0]
  201. self.metrics["requests"] += 1
  202. total_tokens = getattr(getattr(response, "usage", None), "total_tokens", 0)
  203. self.metrics["tokens_used"] += total_tokens if isinstance(total_tokens, int) else 0
  204. if choice.finish_reason == "tool_calls" and getattr(choice.message, "tool_calls", None):
  205. return self._build_tool_use_result(choice, response)
  206. return self._build_text_result(choice, response)
  207. def _format_elicitation_schema_summary(schema: dict, server_name: str) -> str:
  208. """Flat-object requested_schema -> readable field list so the user knows what they're approving."""
  209. props = schema.get("properties") if isinstance(schema, dict) else None
  210. if not isinstance(props, dict) or not props:
  211. return f"Approval requested by MCP server '{server_name}'."
  212. lines = [f"Fields requested by MCP server '{server_name}':"]
  213. for field_name, field_spec in props.items():
  214. spec = field_spec if isinstance(field_spec, dict) else {}
  215. field_type, field_desc = str(spec.get("type", "") or ""), str(spec.get("description", "") or "")
  216. lines.append(f" - {field_name}" + (f" ({field_type})" if field_type else "") + (f": {field_desc}" if field_desc else ""))
  217. return "\n".join(lines)
  218. class ElicitationHandler:
  219. """``elicitation_callback`` for one MCP server. Form-mode routes through Hermes' approval system
  220. (CLI, TUI, Telegram, ...); URL-mode is declined. Fail-closed: any timeout, exception or unexpected
  221. state returns decline/cancel, never a silent accept."""
  222. # asyncio-side safety net over the approval's own input() timeout so the MCP loop never blocks
  223. # indefinitely if the inner timeout is bypassed.
  224. _OUTER_TIMEOUT_GRACE_SECONDS = 5
  225. # consent answer -> (ElicitResult action, metric); anything else declines.
  226. _ANSWER_RESULTS = {"accept": ("accept", "accepted"), "cancel": ("cancel", "errors")}
  227. def __init__(self, server_name: str, config: dict,
  228. call_context: Callable[[], Optional[Context]] = lambda: None):
  229. self.server_name = server_name
  230. # 5 min mirrors the gateway approval default so async surfaces (Telegram, Slack) can respond.
  231. self.timeout = _safe_numeric(config.get("timeout", 300), 300, float)
  232. # Returns the owning MCPServerTask's contextvars snapshot for the in-flight tool call (None
  233. # between calls). A thunk, not the task: mcp_tool_server_run imports this module, so
  234. # MCPServerTask cannot be named here.
  235. self._call_context = call_context
  236. self.metrics = {"requests": 0, "accepted": 0, "declined": 0, "errors": 0}
  237. def session_kwargs(self) -> dict:
  238. """Kwargs to pass to ClientSession for elicitation support."""
  239. return {"elicitation_callback": self}
  240. def _result(self, action: str, metric: str):
  241. """Count *metric* and return ``ElicitResult(action)`` (accept carries empty content)."""
  242. self.metrics[metric] += 1
  243. return _core.ElicitResult(action=action, **({"content": {}} if action == "accept" else {}))
  244. def _consent_thunk(self, message: str, description: str) -> Callable[[], str]:
  245. """Sync consent call replaying the agent's contextvars snapshot when the owning task captured one
  246. (the recv-loop task does NOT inherit them; gateway-platform detection needs them).
  247. ``Context.run`` runs a context once, so it is copied per elicitation."""
  248. from tools.approval_prompt import request_elicitation_consent
  249. consent = functools.partial(request_elicitation_consent, message, description,
  250. timeout_seconds=int(self.timeout), surface=f"mcp-elicitation/{self.server_name}")
  251. captured = self._call_context()
  252. return consent if captured is None else (lambda: captured.copy().run(consent))
  253. async def __call__(self, context, params):
  254. """SDK elicitation callback (``ElicitationFnT``). Returns ElicitResult or ErrorData."""
  255. self.metrics["requests"] += 1
  256. if getattr(params, "mode", "form") == "url": # OAuth/payment: needs a browser + elicitation/complete; unsupported
  257. logger.info("MCP server '%s' requested URL-mode elicitation; declining "
  258. "(URL-mode elicitation not implemented)", self.server_name)
  259. return self._result("decline", "declined")
  260. message = getattr(params, "message", "") or f"MCP server '{self.server_name}' is requesting your approval"
  261. # ``requestedSchema`` on mcp 1.x, ``requested_schema`` on 2.0 (aliases don't apply to attribute
  262. # access) — read both or the user approves without seeing the fields.
  263. schema = getattr(params, "requestedSchema", None) or getattr(params, "requested_schema", None) or {}
  264. logger.info("MCP server '%s' elicitation request: %s", self.server_name, _sanitize_error(message)[:200])
  265. try: # lazy import inside avoids import-order coupling with early-bootstrap tools.approval
  266. invoke_consent = self._consent_thunk(message, _format_elicitation_schema_summary(schema, self.server_name))
  267. except Exception as exc: # pragma: no cover -- defensive
  268. logger.error("MCP server '%s' elicitation: approval system unavailable: %s", self.server_name, exc)
  269. return self._result("decline", "errors")
  270. try: # off-thread: inline, the sync consent flow would freeze the MCP loop and every RPC on it
  271. answer = await asyncio.wait_for(
  272. asyncio.to_thread(invoke_consent), timeout=self.timeout + self._OUTER_TIMEOUT_GRACE_SECONDS)
  273. except TimeoutError:
  274. logger.warning("MCP server '%s' elicitation timed out after %ds", self.server_name, int(self.timeout))
  275. return self._result("cancel", "errors")
  276. except Exception as exc:
  277. logger.error("MCP server '%s' elicitation failed: %s", self.server_name, exc, exc_info=True)
  278. return self._result("decline", "errors")
  279. return self._result(*self._ANSWER_RESULTS.get(answer, ("decline", "declined")))