mcp_tool_errors.py 28 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536
  1. """MCP connection/transport error classification: URL validation, TLS client certs, identity
  2. headers, redirect header stripping, exception-group unwrapping, auth/session-expired/
  3. method-not-found detection and connect-error formatting. Split from tools/mcp_tool.py."""
  4. import asyncio
  5. import contextlib
  6. import errno
  7. import importlib
  8. import logging
  9. import os
  10. import re
  11. from typing import Any, List, Optional
  12. from urllib.parse import urlparse
  13. from tools.mcp_tool_common import _exc_str, _sanitize_error, _core
  14. from tools.mcp_tool_node_abi import NodeAbiMismatchError
  15. logger = logging.getLogger("tools.mcp_tool")
  16. # Stateless (2026-07-28) servers reject a legacy ``initialize`` with this or plain method-not-found.
  17. _JSONRPC_UNSUPPORTED_PROTOCOL_VERSION = -32022
  18. def _jsonrpc_matches(exc: BaseException, codes: tuple, markers: tuple, code=None) -> bool:
  19. """Structural ``MCPError.error.code`` (or *code*) in *codes*, else any *marker* in ``str(exc).lower()``. Never
  20. ``isinstance`` on SDK exception types: they arrive wrapped in ExceptionGroups and drift across generations."""
  21. code = getattr(getattr(exc, "error", None), "code", None) or code
  22. return code in codes or any(marker in str(exc).lower() for marker in markers)
  23. def _handshake_rejected_as_modern(exc: BaseException) -> bool:
  24. """True when a failed ``initialize`` signals a stateless-only (2026-07-28) server."""
  25. return _jsonrpc_matches(
  26. exc, (_JSONRPC_UNSUPPORTED_PROTOCOL_VERSION, _core._JSONRPC_METHOD_NOT_FOUND),
  27. ("unsupported protocol version", str(_JSONRPC_UNSUPPORTED_PROTOCOL_VERSION)),
  28. code=getattr(exc, "code", None)) or _is_method_not_found_error(exc)
  29. def _handshake_answered_with_unsupported_version(exc: BaseException) -> bool:
  30. """True when ``initialize`` SUCCEEDED on the wire (HTTP 200, a valid InitializeResult) but the SDK
  31. refused the ``protocolVersion`` the server named — its ``RuntimeError("Unsupported protocol version
  32. from the server: ...")``. Distinct from a JSON-RPC -32022 rejection, where the server refused us."""
  33. return "unsupported protocol version from the server" in str(_unwrap_exception_group(exc)).lower()
  34. def _is_method_not_found_error(exc: BaseException) -> bool:
  35. """True if *exc* is a JSON-RPC ``method not found`` (-32601; ``ping`` is optional in MCP). The
  36. substring fallback includes "Unknown method: <name>" — without it the ping→list_tools keepalive
  37. fallback never latches and reconnect-loops.
  38. The substring fallback matters when a server reports method-not-found without a structural ``-32601``
  39. code (e.g. surfaced as a plain exception string). Besides the canonical "method not found", many
  40. JSON-RPC implementations phrase it as "Unknown method: <name>" — agentmemory's MCP server is one such
  41. case (#50028).
  42. """
  43. return _jsonrpc_matches(
  44. exc, (_core._JSONRPC_METHOD_NOT_FOUND,),
  45. (str(_core._JSONRPC_METHOD_NOT_FOUND), "method not found", "unknown method", "not found: ping"))
  46. class InvalidMcpUrlError(ValueError):
  47. """A remote MCP server's ``url`` is not parseable http(s):// — validated once at startup to fail fast.
  48. Validated once at startup so we fail fast with a clear message instead of burning through the
  49. reconnect-backoff loop on every attempt. (Ported from anomalyco/opencode#25019.)
  50. """
  51. class NonMcpEndpointError(ConnectionError):
  52. """An HTTP MCP URL served a non-MCP 2xx (e.g. ``text/html``). Non-retryable: every attempt gets
  53. the same page, so backoff is skipped and the server fails immediately. Subclasses ConnectionError
  54. so broad catches still see a connection problem."""
  55. # Streamable-HTTP rejection statuses an SSE-only server (or its load balancer) produces for the
  56. # chunked ``initialize`` POST: Bad Request, Method Not Allowed, Not Acceptable, Length Required.
  57. _STREAMABLE_REJECT_STATUSES = (400, 405, 406, 411)
  58. def _is_streamable_http_rejection(exc: BaseException) -> bool:
  59. """True when a Streamable-HTTP connect failure looks like a transport mismatch rather than a
  60. broken server: a 400-family rejection of the initialize POST, or the SDK's opaque INTERNAL_ERROR
  61. (-32603 ``Server returned an error response``) it maps such rejections to on mcp >= 2.0 (error
  62. class per PR #104363, @RohithPariki). Timeouts and auth errors never qualify — neither carries
  63. these markers — so a slow or 401ing server is not retried on the wrong transport.
  64. """
  65. root = _unwrap_exception_group(exc)
  66. if getattr(getattr(root, "response", None), "status_code", None) in _STREAMABLE_REJECT_STATUSES:
  67. return True
  68. code = getattr(getattr(root, "error", None), "code", None)
  69. return code == -32603 and "server returned an error response" in str(root).lower()
  70. _HTTP_REJECTION_BODY_CHARS = 300
  71. def _make_http_rejection_recorder(sink: dict):
  72. """httpx response hook for the owned Streamable HTTP client: remembers the last 4xx/5xx the server
  73. sent (status, method, URL, head of the body). mcp >= 2.0 folds a non-2xx whose body it cannot
  74. parse as a JSON-RPC error into the opaque ``-32603 Server returned an error response`` — the
  75. status and the server's own words (e.g. ``400 {"code":-32020,"message":"Unsupported
  76. MCP-Protocol-Version"}``) never reach the exception, so this is the only place they can be
  77. observed. SSE bodies are never read (a stream would block the hook)."""
  78. async def _record(response):
  79. if response.status_code < 400:
  80. return
  81. body = ""
  82. if response.headers.get("content-type", "").split(";")[0].strip().lower() != "text/event-stream":
  83. try:
  84. raw = await response.aread() # buffered: the SDK's own aread() afterwards sees the same bytes
  85. body = " ".join(raw[:_HTTP_REJECTION_BODY_CHARS * 4].decode("utf-8", "replace").split())
  86. except Exception: # the failure itself is still reported, just without the body
  87. body = ""
  88. sink.update(status=response.status_code, method=response.request.method,
  89. url=str(response.request.url), body=body[:_HTTP_REJECTION_BODY_CHARS])
  90. return _record
  91. def _describe_http_failure(exc: BaseException, rejection: dict) -> str:
  92. """``str(root cause)`` of a Streamable HTTP connect failure; when that root is the SDK's opaque
  93. ``-32603 Server returned an error response`` and the recorder saw the rejection, the HTTP status,
  94. request URL and body head are appended so the message names what the server actually said."""
  95. root = _unwrap_exception_group(exc)
  96. text = str(root)
  97. opaque = (getattr(getattr(root, "error", None), "code", None) == -32603
  98. and "server returned an error response" in text.lower())
  99. if not (opaque and rejection):
  100. return text
  101. detail = f"HTTP {rejection['status']} from {rejection['method']} {rejection['url']}"
  102. if rejection["body"]:
  103. detail += f": {rejection['body']}"
  104. return f"{text} ({detail})"
  105. def _unwrap_exception_group(exc: BaseException) -> BaseException:
  106. """Root-cause leaf of anyio ``(Base)ExceptionGroup`` wrappers (group ``str()`` is opaque). A
  107. ``KeyboardInterrupt``/``SystemExit`` leaf anywhere is re-raised, never flattened into a loggable
  108. error; a non-cancellation leaf is preferred over the ``CancelledError`` noise anyio sprays on siblings."""
  109. while isinstance(exc, BaseExceptionGroup) and exc.exceptions:
  110. leaf: BaseException = exc.split((KeyboardInterrupt, SystemExit))[0]
  111. if leaf is not None:
  112. while isinstance(leaf, BaseExceptionGroup) and leaf.exceptions:
  113. leaf = leaf.exceptions[0]
  114. raise leaf
  115. exc = next((sub for sub in exc.exceptions if not _contains_only_cancellation(sub)), exc.exceptions[0])
  116. return exc
  117. def _contains_only_cancellation(exc: BaseException) -> bool:
  118. """True if ``exc`` is (or a group containing only) CancelledError."""
  119. if isinstance(exc, BaseExceptionGroup):
  120. return all(_contains_only_cancellation(sub) for sub in exc.exceptions)
  121. return isinstance(exc, asyncio.CancelledError)
  122. def _auth_error_detail(exc: BaseException) -> str:
  123. """`` <guidance>`` when *exc* (or its group root) is the SDK's ``OAuthRegistrationError``, else ``""``. The DCR
  124. guard in ``HermesMCPOAuthProvider`` raises one naming the next step (pre-register an OAuth client), and the
  125. generic needs-reauth text alone would hide it from the model (#78190)."""
  126. try:
  127. from mcp.client.auth import OAuthRegistrationError
  128. except ImportError: # pragma: no cover — SDK required in CI
  129. return ""
  130. root = _unwrap_exception_group(exc)
  131. text = str(root).strip() if isinstance(root, OAuthRegistrationError) else ""
  132. return f" {_sanitize_error(text)}" if text else ""
  133. def _mcp_call_failed_message(exc: BaseException) -> str:
  134. """Generic tool-error text naming the group root cause: the transport's TaskGroup wrapper ``str()`` is
  135. "unhandled errors in a TaskGroup (1 sub-exception)", which tells the model nothing."""
  136. root = _unwrap_exception_group(exc)
  137. return _sanitize_error(f"MCP call failed: {type(root).__name__}: {_exc_str(root)}")
  138. def _classify_mcp_failure(exc: BaseException) -> str:
  139. """``'permanent'`` (``run()`` parks instead of burning the retry ladder: auth 401/403,
  140. NonMcpEndpointError, InvalidMcpUrlError, missing stdio command, native addon built for another
  141. Node) or ``'transient'`` (backoff retry)."""
  142. root = _unwrap_exception_group(exc)
  143. permanent = (_is_auth_error(root)
  144. or isinstance(root, (NonMcpEndpointError, InvalidMcpUrlError, FileNotFoundError, NodeAbiMismatchError))
  145. or (isinstance(root, OSError) and getattr(root, "errno", None) == errno.ENOENT)
  146. # 401/403 HTTPStatusError that _is_auth_error's type-gate missed (auth types not importable here)
  147. or getattr(getattr(root, "response", None), "status_code", None) in (401, 403))
  148. return "permanent" if permanent else "transient"
  149. def _validate_remote_mcp_url(server_name: str, url: Any) -> str:
  150. """The stripped URL if valid http(s); else InvalidMcpUrlError naming the server (non-string, other scheme —
  151. stdio servers use ``command`` — or empty host)."""
  152. def _bad(detail: str) -> InvalidMcpUrlError:
  153. return InvalidMcpUrlError(f"Invalid MCP URL for '{server_name}': {detail}")
  154. if not isinstance(url, str):
  155. raise _bad(f"expected a string, got {type(url).__name__}")
  156. stripped = url.strip()
  157. if not stripped:
  158. raise _bad("empty url")
  159. try:
  160. parsed = urlparse(stripped)
  161. except Exception as exc: # urlparse is very permissive — belt and braces
  162. raise _bad(f"{stripped!r} ({exc})") from exc
  163. if parsed.scheme.lower() not in {"http", "https"}:
  164. raise _bad(f"scheme must be http or https, got {parsed.scheme!r} ({stripped!r})")
  165. if not parsed.netloc:
  166. raise _bad(f"missing host ({stripped!r})")
  167. if not parsed.hostname: # ``urlparse`` accepts ``http://:8080`` (empty host, explicit port)
  168. raise _bad(f"missing hostname ({stripped!r})")
  169. return stripped
  170. def _resolve_client_cert(server_name: str, config: dict):
  171. """``client_cert`` / ``client_key`` in httpx's ``cert=`` shape: None, a combined-PEM path,
  172. ``(cert, key)`` or ``(cert, key, password)``. ``~`` is expanded; missing files raise a
  173. server-scoped FileNotFoundError instead of an opaque TLS handshake error."""
  174. raw_cert = config.get("client_cert")
  175. raw_key = config.get("client_key")
  176. if raw_cert is None and raw_key is None:
  177. return None
  178. prefix = f"MCP server '{server_name}': "
  179. def _expand(path: Any, label: str) -> str:
  180. if not isinstance(path, str) or not path.strip():
  181. raise ValueError(f"{prefix}{label} must be a non-empty string path (got {type(path).__name__})")
  182. expanded = os.path.expanduser(path.strip())
  183. if not os.path.isfile(expanded):
  184. raise FileNotFoundError(f"{prefix}{label} not found at {expanded!r}")
  185. return expanded
  186. if not isinstance(raw_cert, (list, tuple)):
  187. cert_path = _expand(raw_cert, "client_cert")
  188. return (cert_path, _expand(raw_key, "client_key")) if raw_key is not None else cert_path # combined PEM
  189. if raw_key is not None:
  190. raise ValueError(f"{prefix}specify either client_cert as a list [cert, key] OR client_cert + client_key, not both")
  191. if len(raw_cert) not in (2, 3):
  192. raise ValueError(f"{prefix}client_cert list form must have 2 or 3 elements (got {len(raw_cert)})")
  193. pair = (_expand(raw_cert[0], "client_cert[0]"), _expand(raw_cert[1], "client_cert[1]"))
  194. if len(raw_cert) == 2:
  195. return pair
  196. if not isinstance(raw_cert[2], str):
  197. raise ValueError(f"{prefix}client_cert[2] (key passphrase) must be a string")
  198. return (*pair, raw_cert[2])
  199. def _resolve_identity_header(server_name: str, config: dict):
  200. """``identity_header`` ``{name, value_from: "static"|"profile", value}`` → ``(name, value)`` or
  201. None. Invalid configs warn and are ignored — an identity header must never break the connection.
  202. ``profile`` resolves once at connect time."""
  203. raw = config.get("identity_header")
  204. if raw is None:
  205. return None
  206. def _ignore(detail: str, *args):
  207. logger.warning("MCP server '%s': identity_header " + detail + " — ignoring", server_name, *args)
  208. if not isinstance(raw, dict):
  209. return _ignore("must be a mapping with 'name' and 'value'/'value_from' keys (got %s)", type(raw).__name__)
  210. name = raw.get("name")
  211. if not isinstance(name, str) or not name.strip():
  212. return _ignore("requires a non-empty 'name'")
  213. value_from = (raw.get("value_from") or "static").strip().lower()
  214. if value_from == "profile":
  215. from hermes_cli.profiles import get_active_profile_name
  216. return (name.strip(), get_active_profile_name())
  217. if value_from != "static":
  218. return _ignore("value_from must be 'static' or 'profile' (got %r)", value_from)
  219. value = raw.get("value")
  220. if not isinstance(value, str) or not value.strip():
  221. return _ignore("with value_from: static requires a non-empty string 'value'")
  222. return (name.strip(), value)
  223. def _apply_identity_header(server_name: str, config: dict, headers: dict) -> dict:
  224. """Merge the identity header into ``headers`` in place; an explicit entry of the same name (any
  225. casing) wins — never silently override user config."""
  226. name, value = _resolve_identity_header(server_name, config) or (None, None)
  227. if name is None:
  228. return headers
  229. if any(key.lower() == name.lower() for key in headers):
  230. logger.debug("MCP server '%s': identity_header '%s' already set via explicit "
  231. "headers config — keeping the explicit value", server_name, name)
  232. else:
  233. headers[name] = value
  234. return headers
  235. def _make_redirect_header_stripper(httpx_mod, original_url, *, strict: bool = False,
  236. configured_header_names: set[str] | frozenset[str] = frozenset()):
  237. """Client factory enforcing the redirect credential boundary: on a cross-origin redirect
  238. follow-up it strips ``Authorization``; with *strict* (Agent Plugins v1 ``strict_redirect_headers``)
  239. every configured header (lowercase names in *configured_header_names*) is stripped too — v1 forbids
  240. forwarding them cross-origin.
  241. The factory builds ``httpx_mod.AsyncClient(**kwargs)`` — resolved at call time, so the proxy
  242. ``mounts=`` / ``transport=`` the caller passes reach the SDK's real client class (and anything a
  243. caller swapped in for it) unchanged — and installs the boundary on that instance's
  244. ``_build_redirect_request``. This MUST live on ``_build_redirect_request``: ``response.next_request``
  245. is unset when response event hooks fire (httpx populates it later in the redirect loop), so a
  246. response hook can never mutate the follow-up; and a *request* hook would fire on non-redirect traffic
  247. too — the OAuth auth flow yields token/metadata/registration requests through the same client, often
  248. to a different-origin authorization server whose own credentials must NOT be stripped."""
  249. origin = (original_url.scheme, original_url.host, original_url.port)
  250. def _build_client(**kwargs):
  251. client = httpx_mod.AsyncClient(**kwargs)
  252. base_build = getattr(type(client), "_build_redirect_request", None)
  253. def _build_redirect_request(request, response):
  254. next_request = base_build(client, request, response)
  255. target = next_request.url
  256. if (target.scheme, target.host, target.port) != origin:
  257. headers = next_request.headers
  258. headers.pop("authorization", None)
  259. headers.pop("Authorization", None)
  260. for _name in configured_header_names if strict else ():
  261. while _name in headers:
  262. del headers[_name]
  263. return next_request
  264. client._build_redirect_request = _build_redirect_request
  265. return client
  266. return _build_client
  267. # Wire-body cap, applied at the httpx transport before the SDK buffers/JSON-parses a response. A
  268. # hostile or misbehaving remote MCP server can stream an unbounded catalog/tool-result body and none
  269. # of the post-parse limits (resource cap, tool-result truncation) run before the parse blows up.
  270. # Finite HTTP bodies are capped at this many bytes (a larger Content-Length is rejected up front);
  271. # each SSE *event* is capped, with the counter reset at completed event boundaries so a long-lived
  272. # stream and its keepalives have no cumulative limit. Violations raise the SDK httpx's ReadError and
  273. # flow through the ordinary transport teardown/reconnect path (#66092).
  274. _MCP_HTTP_MAX_BODY_BYTES = 10 * 1024 * 1024
  275. # An SSE event ends at a blank line: two consecutive line terminators. The spec allows CR,
  276. # LF, or CRLF terminators and permits mixing them, so the boundary is any of \n\n, \r\r,
  277. # \n\r, \r\n\r\n, \r\n\n, \r\n\r, \n\r\n, \r\r\n. "\r\n" alone is ONE terminator, not two:
  278. # the lookahead keeps a plain CRLF line ending from backtracking into a \r + \n boundary.
  279. _SSE_BOUNDARY_RE = re.compile(rb"(?:\r\n|\r(?!\n)|\n){2}")
  280. _SSE_BOUNDARY_CARRY = 3 # longest boundary ("\r\n\r\n") minus one byte
  281. def _make_mcp_body_cap_transport(httpx_mod, inner_transport, limit: int = _MCP_HTTP_MAX_BODY_BYTES):
  282. """Wrap ``inner_transport`` so every response body is size-capped. ``httpx_mod`` must be the SDK's
  283. own httpx module (``sdk_httpx()``): the transport is handed to that SDK's ``AsyncClient``."""
  284. class _CappedStream(httpx_mod.AsyncByteStream):
  285. def __init__(self, inner, is_sse: bool, url: str):
  286. self._inner, self._is_sse, self._url = inner, is_sse, url
  287. def _reject(self, kind: str):
  288. return httpx_mod.ReadError(f"MCP {kind} exceeds {limit} bytes (from {self._url})")
  289. async def __aiter__(self):
  290. counted = 0
  291. tail = b"" # last _SSE_BOUNDARY_CARRY stream bytes; a boundary can straddle chunks
  292. async for chunk in self._inner:
  293. if self._is_sse:
  294. # Charge each completed event once: the carried prefix plus bytes up to its
  295. # boundary must fit the cap, then the next event starts after it. Scan the
  296. # carried suffix plus this chunk so a boundary split across chunks is still
  297. # seen; bytes before len(tail) were already counted into `counted`.
  298. window = tail + chunk
  299. pos = 0
  300. for match in _SSE_BOUNDARY_RE.finditer(window):
  301. end = match.end()
  302. if end <= len(tail):
  303. continue # boundary completed inside the carried suffix: already counted
  304. if counted + end - max(pos, len(tail)) > limit:
  305. raise self._reject("SSE event")
  306. counted, pos = 0, end
  307. counted += len(window) - max(pos, len(tail))
  308. tail = window[-_SSE_BOUNDARY_CARRY:]
  309. else:
  310. counted += len(chunk)
  311. if counted > limit:
  312. raise self._reject("SSE event" if self._is_sse else "HTTP response")
  313. yield chunk
  314. async def aclose(self):
  315. await self._inner.aclose()
  316. class _BodyCapTransport(httpx_mod.AsyncBaseTransport):
  317. def __init__(self, inner):
  318. self._inner = inner
  319. async def handle_async_request(self, request):
  320. response = await self._inner.handle_async_request(request)
  321. declared = response.headers.get("content-length")
  322. with contextlib.suppress(ValueError): # malformed header: the streamed cap still applies
  323. if declared is not None and int(declared) > limit:
  324. await response.aclose()
  325. raise httpx_mod.ReadError(f"MCP HTTP response declares Content-Length {declared} > {limit} "
  326. f"bytes cap (from {request.url})")
  327. is_sse = "text/event-stream" in response.headers.get("content-type", "").lower()
  328. response.stream = _CappedStream(response.stream, is_sse, str(request.url))
  329. return response
  330. async def aclose(self):
  331. await self._inner.aclose()
  332. return _BodyCapTransport(inner_transport)
  333. # Node budget for ``_iter_exception_nodes`` (the visited set breaks cycles; this bounds acyclic blow-ups).
  334. # Well above ``sys.getrecursionlimit()`` so deep task-group nesting is fully scanned.
  335. _EXC_TRAVERSAL_MAX_NODES = 10_000
  336. def _exc_children(exc: BaseException) -> list[BaseException]:
  337. """A group's sub-exceptions (if any) followed by ``__cause__``/``__context__`` when they are exceptions — a
  338. group raised inside an ``except`` block carries the caught error as ``__context__``, so the chain is never
  339. skipped."""
  340. nested = getattr(exc, "exceptions", None) or ()
  341. return [*nested, *(c for c in (exc.__cause__, exc.__context__) if isinstance(c, BaseException))]
  342. def _iter_exception_nodes(exc: BaseException) -> list[BaseException]:
  343. """Pre-order, left-to-right walk of an exception tree/chain, each node once. ``__cause__``/``__context__``
  344. can point back at an ancestor (a raised-and-caught pair does this routinely, e.g. the same OAuth error
  345. raised on the Streamable-HTTP attempt and again on the SSE fallback), so a naive recursive walk dies with
  346. RecursionError and hides the real connect error; the visited set breaks cycles, the budget bounds acyclic
  347. blow-ups."""
  348. stack = [exc]
  349. seen: set[int] = set()
  350. ordered: list[BaseException] = []
  351. while stack and len(ordered) < _EXC_TRAVERSAL_MAX_NODES:
  352. current = stack.pop()
  353. if id(current) in seen:
  354. continue
  355. seen.add(id(current))
  356. ordered.append(current)
  357. stack.extend(reversed(_exc_children(current)))
  358. return ordered
  359. def _format_connect_error(exc: BaseException) -> str:
  360. """Render nested MCP connection errors into an actionable short message."""
  361. nodes = _iter_exception_nodes(exc)
  362. def _find_missing() -> Optional[str]:
  363. for current in nodes:
  364. if isinstance(current, FileNotFoundError):
  365. if getattr(current, "filename", None):
  366. return str(current.filename)
  367. match = re.search(r"No such file or directory: '([^']+)'", str(current))
  368. if match:
  369. return match.group(1)
  370. return None
  371. def _flatten_messages() -> list[str]:
  372. messages: list[str] = []
  373. for current in nodes:
  374. # A group's own str() is opaque — only its children speak; a message-less leaf still names its type.
  375. text = "" if getattr(current, "exceptions", None) else str(current).strip()
  376. if text:
  377. messages.append(text)
  378. elif not _exc_children(current):
  379. messages.append(current.__class__.__name__)
  380. return messages or [exc.__class__.__name__]
  381. abi = next((node for node in nodes if isinstance(node, NodeAbiMismatchError)), None)
  382. if abi is not None: # already the whole story, remedy included; the SDK's "Connection closed" adds nothing
  383. return _sanitize_error(str(abi))
  384. missing = _find_missing()
  385. if not missing:
  386. return _sanitize_error("; ".join(list(dict.fromkeys(_flatten_messages()))[:3]))
  387. message = f"missing executable '{missing}'"
  388. if os.path.basename(missing) in {"npx", "npm", "node"}:
  389. message += (" (ensure Node.js is installed and PATH includes its bin directory, "
  390. "or set mcp_servers.<name>.command to an absolute path and include "
  391. "that directory in mcp_servers.<name>.env.PATH)")
  392. return _sanitize_error(message)
  393. def _optional_types(module: str, *names: str) -> list:
  394. """``[module.name, ...]`` or ``[]`` when the module/attribute is unavailable."""
  395. try:
  396. mod = importlib.import_module(module)
  397. return [getattr(mod, name) for name in names]
  398. except (ImportError, AttributeError):
  399. return []
  400. # Lazily-built ``(auth_types, http_status_types)`` so this module imports without the SDK OAuth module.
  401. _AUTH_ERROR_TYPES: Optional[tuple] = None
  402. def _get_auth_error_types() -> tuple:
  403. """Cached ``(auth_types, http_status_types)``: SDK ``OAuthFlowError``/``OAuthTokenError`` (+ legacy
  404. ``UnauthorizedError``), our ``OAuthNonInteractiveError``, and ``HTTPStatusError`` from both httpx
  405. flavours — a 401 may come from the SDK's own stack (``httpx2`` on mcp >= 2.0) or Hermes' pinned
  406. ``httpx``; the classes are unrelated and still need the 401 check in :func:`_is_auth_error`."""
  407. global _AUTH_ERROR_TYPES
  408. if not (_AUTH_ERROR_TYPES and _AUTH_ERROR_TYPES[0]): # retry while empty (SDK may import later)
  409. sdk_mod = _core.sdk_httpx()
  410. http_types = tuple(dict.fromkeys(
  411. ([sdk_mod.HTTPStatusError] if sdk_mod is not None else []) + _optional_types("httpx", "HTTPStatusError")))
  412. auth_types = (*_optional_types("mcp.client.auth", "OAuthFlowError", "OAuthTokenError"),
  413. *_optional_types("mcp.client.auth", "UnauthorizedError"), # older SDKs
  414. *_optional_types("tools.mcp_oauth", "OAuthNonInteractiveError"), *http_types)
  415. _AUTH_ERROR_TYPES = (auth_types, http_types)
  416. return _AUTH_ERROR_TYPES
  417. def _is_auth_error(exc: BaseException) -> bool:
  418. """True if ``exc`` indicates an MCP OAuth failure; ``HTTPStatusError`` counts only with status 401."""
  419. auth_types, http_types = _get_auth_error_types()
  420. if not isinstance(exc, auth_types):
  421. return False
  422. return getattr(exc.response, "status_code", None) == 401 if isinstance(exc, http_types) else True
  423. # Lower-cased substrings meaning the transport session expired / was GC'd (OAuth token still valid).
  424. # Substrings (lower-cased match) that indicate the MCP server rejected the request because its server-side
  425. # transport session expired / was garbage-collected. See #13383.
  426. _SESSION_EXPIRED_MARKERS: tuple = (
  427. "invalid or expired session", "expired session", "session expired", "session not found",
  428. "unknown session", "session terminated", "closedresourceerror", "closed resource",
  429. "transport is closed", "connection closed", "broken pipe", "end of file")
  430. def _is_session_expired_error(exc: BaseException) -> bool:
  431. """True if ``exc`` looks like a transport session expiry (Streamable-HTTP servers GC session state on idle TTL /
  432. restart / pod rotation while the OAuth token stays valid) — the fix is a transport reconnect, not an OAuth
  433. refresh. Every node ``_iter_exception_nodes`` reaches is inspected so an InterruptedError anywhere overrides
  434. transport markers; the chain walk matters because SDK wrappers raise a generic RuntimeError *from* a
  435. message-less ClosedResourceError."""
  436. # AnyIO stream exceptions are often message-less, so type checks complement marker matching.
  437. transport_error_types = tuple(_optional_types("anyio", "BrokenResourceError", "ClosedResourceError", "EndOfStream"))
  438. found = False
  439. for current in _iter_exception_nodes(exc):
  440. if isinstance(current, InterruptedError):
  441. return False
  442. # Messages vary across SDK versions/servers: a narrow allow-list of stable substrings avoids false positives.
  443. msg = str(current).lower()
  444. found = found or isinstance(current, transport_error_types) or any(m in msg for m in _SESSION_EXPIRED_MARKERS)
  445. return found