456 lines
19 KiB
Python
456 lines
19 KiB
Python
"""MCP connection/transport error classification: URL validation, TLS client certs, identity headers, redirect header stripping, exception-group unwrapping, auth/session-expired/method-not-found detection and connect-error formatting. Split from tools/mcp_tool.py."""
|
|
|
|
import asyncio
|
|
import errno
|
|
import importlib
|
|
import logging
|
|
import os
|
|
import re
|
|
from typing import Any, List, Optional
|
|
from urllib.parse import urlparse
|
|
from tools.mcp_tool_common import _sanitize_error, _core
|
|
|
|
logger = logging.getLogger("tools.mcp_tool")
|
|
|
|
|
|
# Stateless (2026-07-28) servers reject a legacy ``initialize`` with
|
|
# UnsupportedProtocolVersion (-32022) or plain method-not-found.
|
|
_JSONRPC_UNSUPPORTED_PROTOCOL_VERSION = -32022
|
|
|
|
|
|
def _jsonrpc_code(exc: BaseException):
|
|
"""Structural ``MCPError.error.code`` (None when absent)."""
|
|
return getattr(getattr(exc, "error", None), "code", None)
|
|
|
|
|
|
def _handshake_rejected_as_modern(exc: BaseException) -> bool:
|
|
"""True when a failed ``initialize`` signals a stateless-only (2026-07-28) server.
|
|
|
|
Structural code check first, then substring fallback — never ``isinstance`` on
|
|
SDK exception types (they arrive wrapped in ExceptionGroups and drift across generations).
|
|
"""
|
|
code = _jsonrpc_code(exc) or getattr(exc, "code", None)
|
|
if code in (_JSONRPC_UNSUPPORTED_PROTOCOL_VERSION, _core._JSONRPC_METHOD_NOT_FOUND):
|
|
return True
|
|
msg = str(exc).lower()
|
|
return bool(msg) and (
|
|
"unsupported protocol version" in msg
|
|
or str(_JSONRPC_UNSUPPORTED_PROTOCOL_VERSION) in msg
|
|
or _is_method_not_found_error(exc)
|
|
)
|
|
|
|
|
|
def _is_method_not_found_error(exc: BaseException) -> bool:
|
|
"""True if *exc* is a JSON-RPC ``method not found`` (-32601).
|
|
|
|
``ping`` is optional in MCP; servers lacking it answer -32601. Structural
|
|
code check first, then substring fallback — including "Unknown method: <name>",
|
|
which some servers use; without it the ping→list_tools keepalive fallback
|
|
never latches and reconnect-loops.
|
|
"""
|
|
if _jsonrpc_code(exc) == _core._JSONRPC_METHOD_NOT_FOUND:
|
|
return True
|
|
msg = str(exc).lower()
|
|
return bool(msg) and (
|
|
str(_core._JSONRPC_METHOD_NOT_FOUND) in msg
|
|
or "method not found" in msg
|
|
or "unknown method" in msg
|
|
or "not found: ping" in msg
|
|
)
|
|
|
|
|
|
class InvalidMcpUrlError(ValueError):
|
|
"""A remote MCP server's ``url`` is not parseable http(s)://.
|
|
|
|
Validated once at startup so we fail fast instead of burning the
|
|
reconnect-backoff loop on every attempt.
|
|
"""
|
|
|
|
|
|
class NonMcpEndpointError(ConnectionError):
|
|
"""An HTTP MCP URL served a non-MCP 2xx response (e.g. ``text/html``).
|
|
|
|
Real Streamable-HTTP endpoints answer ``application/json`` or
|
|
``text/event-stream``. Non-retryable: every attempt gets the same page, so
|
|
the backoff loop is skipped and the server is failed immediately.
|
|
Subclasses ConnectionError so broad catches still see a connection problem.
|
|
"""
|
|
|
|
|
|
def _unwrap_exception_group(exc: BaseException) -> BaseException:
|
|
"""Extract the root-cause leaf from anyio ``(Base)ExceptionGroup`` wrappers.
|
|
|
|
Group ``str()`` is opaque ("unhandled errors in a TaskGroup"), so log sites
|
|
must unwrap. Two rules: a ``KeyboardInterrupt``/``SystemExit`` leaf anywhere
|
|
is re-raised (never flattened into a loggable error); a non-cancellation
|
|
leaf is preferred over the ``CancelledError`` noise anyio sprays on siblings.
|
|
"""
|
|
while isinstance(exc, BaseExceptionGroup) and exc.exceptions:
|
|
fatal, _rest = exc.split((KeyboardInterrupt, SystemExit))
|
|
if fatal is not None:
|
|
leaf: BaseException = fatal
|
|
while isinstance(leaf, BaseExceptionGroup) and leaf.exceptions:
|
|
leaf = leaf.exceptions[0]
|
|
raise leaf
|
|
exc = next((sub for sub in exc.exceptions if not _contains_only_cancellation(sub)), exc.exceptions[0])
|
|
return exc
|
|
|
|
|
|
def _contains_only_cancellation(exc: BaseException) -> bool:
|
|
"""True if ``exc`` is (or a group containing only) CancelledError."""
|
|
if isinstance(exc, BaseExceptionGroup):
|
|
return all(_contains_only_cancellation(sub) for sub in exc.exceptions)
|
|
return isinstance(exc, asyncio.CancelledError)
|
|
|
|
|
|
def _classify_mcp_failure(exc: BaseException) -> str:
|
|
"""Classify a connection failure as ``'permanent'`` or ``'transient'``.
|
|
|
|
Permanent (deterministic — ``run()`` parks immediately instead of burning the
|
|
retry ladder): auth 401/403, NonMcpEndpointError, InvalidMcpUrlError, missing
|
|
stdio command (FileNotFoundError / ENOENT). Everything else keeps backoff retry.
|
|
"""
|
|
root = _unwrap_exception_group(exc)
|
|
permanent = (
|
|
_core._is_auth_error(root)
|
|
or isinstance(root, (NonMcpEndpointError, InvalidMcpUrlError, FileNotFoundError))
|
|
or (isinstance(root, OSError) and getattr(root, "errno", None) == errno.ENOENT)
|
|
# 401/403 HTTPStatusError that _is_auth_error's type-gate missed
|
|
# (auth types not importable in this environment).
|
|
or _response_status(root) in (401, 403)
|
|
)
|
|
return "permanent" if permanent else "transient"
|
|
|
|
|
|
def _response_status(exc: BaseException):
|
|
"""``exc.response.status_code`` for httpx-shaped errors, else None."""
|
|
return getattr(getattr(exc, "response", None), "status_code", None)
|
|
|
|
|
|
def _validate_remote_mcp_url(server_name: str, url: Any) -> str:
|
|
"""Return the stripped URL if it is a valid http(s) remote MCP URL.
|
|
|
|
Raises InvalidMcpUrlError naming the server for non-strings, missing/other
|
|
schemes (stdio servers use ``command``, not ``url``), and empty hosts.
|
|
"""
|
|
def _bad(detail: str) -> InvalidMcpUrlError:
|
|
return InvalidMcpUrlError(f"Invalid MCP URL for '{server_name}': {detail}")
|
|
|
|
if not isinstance(url, str):
|
|
raise _bad(f"expected a string, got {type(url).__name__}")
|
|
stripped = url.strip()
|
|
if not stripped:
|
|
raise _bad("empty url")
|
|
try:
|
|
parsed = urlparse(stripped)
|
|
except Exception as exc: # urlparse is very permissive — belt and braces
|
|
raise _bad(f"{stripped!r} ({exc})") from exc
|
|
if parsed.scheme.lower() not in {"http", "https"}:
|
|
raise _bad(f"scheme must be http or https, got {parsed.scheme!r} ({stripped!r})")
|
|
if not parsed.netloc:
|
|
raise _bad(f"missing host ({stripped!r})")
|
|
# ``urlparse`` accepts ``http://:8080`` (empty host, explicit port) — reject it.
|
|
if not parsed.hostname:
|
|
raise _bad(f"missing hostname ({stripped!r})")
|
|
return stripped
|
|
|
|
|
|
def _resolve_client_cert(server_name: str, config: dict):
|
|
"""Resolve ``client_cert`` / ``client_key`` into httpx's ``cert=`` shape.
|
|
|
|
None when neither is set; a single path for a combined PEM; ``(cert, key)``
|
|
or ``(cert, key, password)`` for the pair/list forms. ``~`` is expanded and
|
|
missing files raise a server-scoped FileNotFoundError instead of an opaque
|
|
TLS handshake error.
|
|
"""
|
|
raw_cert = config.get("client_cert")
|
|
raw_key = config.get("client_key")
|
|
if raw_cert is None and raw_key is None:
|
|
return None
|
|
prefix = f"MCP server '{server_name}': "
|
|
|
|
def _expand(path: Any, label: str) -> str:
|
|
if not isinstance(path, str) or not path.strip():
|
|
raise ValueError(f"{prefix}{label} must be a non-empty string path (got {type(path).__name__})")
|
|
expanded = os.path.expanduser(path.strip())
|
|
if not os.path.isfile(expanded):
|
|
raise FileNotFoundError(f"{prefix}{label} not found at {expanded!r}")
|
|
return expanded
|
|
|
|
if isinstance(raw_cert, (list, tuple)):
|
|
if raw_key is not None:
|
|
raise ValueError(
|
|
f"{prefix}specify either client_cert as a list [cert, key] OR "
|
|
f"client_cert + client_key, not both"
|
|
)
|
|
if len(raw_cert) not in (2, 3):
|
|
raise ValueError(f"{prefix}client_cert list form must have 2 or 3 elements (got {len(raw_cert)})")
|
|
pair = (_expand(raw_cert[0], "client_cert[0]"), _expand(raw_cert[1], "client_cert[1]"))
|
|
if len(raw_cert) == 2:
|
|
return pair
|
|
password = raw_cert[2]
|
|
if not isinstance(password, str):
|
|
raise ValueError(f"{prefix}client_cert[2] (key passphrase) must be a string")
|
|
return (*pair, password)
|
|
|
|
cert_path = _expand(raw_cert, "client_cert")
|
|
if raw_key is not None:
|
|
return (cert_path, _expand(raw_key, "client_key"))
|
|
return cert_path # single combined PEM (cert + key)
|
|
|
|
|
|
def _resolve_identity_header(server_name: str, config: dict):
|
|
"""Resolve the optional per-server ``identity_header`` config.
|
|
|
|
Shape: ``{name: "X-User-Id", value_from: "static"|"profile", value: "..."}``
|
|
(``value`` required for static). Returns ``(name, value)`` or None. Invalid
|
|
configs warn and are ignored — an identity header must never break the
|
|
connection. ``profile`` resolves once at connect time; no per-call mutation.
|
|
"""
|
|
raw = config.get("identity_header")
|
|
if raw is None:
|
|
return None
|
|
|
|
def _ignore(detail: str, *args):
|
|
logger.warning("MCP server '%s': identity_header " + detail + " — ignoring", server_name, *args)
|
|
return None
|
|
|
|
if not isinstance(raw, dict):
|
|
return _ignore("must be a mapping with 'name' and 'value'/'value_from' keys (got %s)", type(raw).__name__)
|
|
name = raw.get("name")
|
|
if not isinstance(name, str) or not name.strip():
|
|
return _ignore("requires a non-empty 'name'")
|
|
value_from = (raw.get("value_from") or "static").strip().lower()
|
|
if value_from == "static":
|
|
value = raw.get("value")
|
|
if not isinstance(value, str) or not value.strip():
|
|
return _ignore("with value_from: static requires a non-empty string 'value'")
|
|
return (name.strip(), value)
|
|
if value_from == "profile":
|
|
from hermes_cli.profiles import get_active_profile_name
|
|
return (name.strip(), get_active_profile_name())
|
|
return _ignore("value_from must be 'static' or 'profile' (got %r)", value_from)
|
|
|
|
|
|
def _apply_identity_header(server_name: str, config: dict, headers: dict) -> dict:
|
|
"""Merge the resolved identity header into ``headers`` in place.
|
|
|
|
An explicit per-server ``headers`` entry with the same name (any casing)
|
|
wins — the identity header never silently overrides user config.
|
|
"""
|
|
resolved = _resolve_identity_header(server_name, config)
|
|
if resolved is None:
|
|
return headers
|
|
name, value = resolved
|
|
if any(key.lower() == name.lower() for key in headers):
|
|
logger.debug(
|
|
"MCP server '%s': identity_header '%s' already set via explicit "
|
|
"headers config — keeping the explicit value", server_name, name,
|
|
)
|
|
return headers
|
|
headers[name] = value
|
|
return headers
|
|
|
|
|
|
def _make_redirect_header_stripper(
|
|
original_url,
|
|
*,
|
|
strict: bool = False,
|
|
configured_header_names: "set[str] | frozenset[str]" = frozenset(),
|
|
):
|
|
"""Build an httpx response hook that guards cross-origin redirects.
|
|
|
|
Always strips ``Authorization`` when a redirect leaves the original origin.
|
|
With *strict* (Agent Plugins v1 ``strict_redirect_headers``) every configured
|
|
header (lowercase names in *configured_header_names*) is stripped too — the
|
|
v1 spec forbids forwarding package-configured headers cross-origin.
|
|
"""
|
|
origin = (original_url.scheme, original_url.host, original_url.port)
|
|
|
|
async def _strip_on_cross_origin_redirect(response):
|
|
if not (response.is_redirect and response.next_request):
|
|
return
|
|
target = response.next_request.url
|
|
if (target.scheme, target.host, target.port) == origin:
|
|
return
|
|
headers = response.next_request.headers
|
|
headers.pop("authorization", None)
|
|
headers.pop("Authorization", None)
|
|
if strict:
|
|
for _name in configured_header_names:
|
|
while _name in headers:
|
|
del headers[_name]
|
|
|
|
return _strip_on_cross_origin_redirect
|
|
|
|
|
|
def _exc_causes(exc: BaseException) -> List[BaseException]:
|
|
"""``__cause__`` then ``__context__`` of *exc*, when they are exceptions."""
|
|
return [nested for nested in (exc.__cause__, exc.__context__) if isinstance(nested, BaseException)]
|
|
|
|
|
|
def _format_connect_error(exc: BaseException) -> str:
|
|
"""Render nested MCP connection errors into an actionable short message."""
|
|
|
|
def _find_missing(current: BaseException) -> Optional[str]:
|
|
nested = getattr(current, "exceptions", None)
|
|
if nested:
|
|
return next(filter(None, map(_find_missing, nested)), None)
|
|
if isinstance(current, FileNotFoundError):
|
|
if getattr(current, "filename", None):
|
|
return str(current.filename)
|
|
match = re.search(r"No such file or directory: '([^']+)'", str(current))
|
|
if match:
|
|
return match.group(1)
|
|
return next(filter(None, map(_find_missing, _exc_causes(current))), None)
|
|
|
|
def _flatten_messages(current: BaseException) -> List[str]:
|
|
nested = getattr(current, "exceptions", None)
|
|
if nested:
|
|
return [m for child in nested for m in _flatten_messages(child)]
|
|
text = str(current).strip()
|
|
messages = [text] if text else []
|
|
for nested_exc in _exc_causes(current):
|
|
messages.extend(_flatten_messages(nested_exc))
|
|
return messages or [current.__class__.__name__]
|
|
|
|
missing = _find_missing(exc)
|
|
if missing:
|
|
message = f"missing executable '{missing}'"
|
|
if os.path.basename(missing) in {"npx", "npm", "node"}:
|
|
message += (
|
|
" (ensure Node.js is installed and PATH includes its bin directory, "
|
|
"or set mcp_servers.<name>.command to an absolute path and include "
|
|
"that directory in mcp_servers.<name>.env.PATH)"
|
|
)
|
|
return _sanitize_error(message)
|
|
deduped = list(dict.fromkeys(_flatten_messages(exc)))
|
|
return _sanitize_error("; ".join(deduped[:3]))
|
|
|
|
|
|
# Lazily-built caches so this module imports even without the SDK OAuth module.
|
|
_AUTH_ERROR_TYPES: tuple = ()
|
|
_HTTP_STATUS_ERROR_TYPES: Optional[tuple] = None
|
|
|
|
|
|
def _optional_types(module: str, *names: str) -> list:
|
|
"""``[module.name, ...]`` or ``[]`` when the module/attribute is unavailable."""
|
|
try:
|
|
mod = importlib.import_module(module)
|
|
return [getattr(mod, name) for name in names]
|
|
except (ImportError, AttributeError):
|
|
return []
|
|
|
|
|
|
def _http_status_error_types() -> tuple:
|
|
"""``HTTPStatusError`` classes from both httpx flavours.
|
|
|
|
A 401 may come from the SDK's own stack (``httpx2`` on mcp >= 2.0) or from
|
|
Hermes' pinned ``httpx``; the classes are unrelated, so both go in the tuple.
|
|
"""
|
|
global _HTTP_STATUS_ERROR_TYPES
|
|
if _HTTP_STATUS_ERROR_TYPES is None:
|
|
found: list = []
|
|
sdk_mod = _core.sdk_httpx()
|
|
if sdk_mod is not None:
|
|
found.append(sdk_mod.HTTPStatusError)
|
|
for cls in _optional_types("httpx", "HTTPStatusError"):
|
|
if cls not in found:
|
|
found.append(cls)
|
|
_HTTP_STATUS_ERROR_TYPES = tuple(found)
|
|
return _HTTP_STATUS_ERROR_TYPES
|
|
|
|
|
|
def _get_auth_error_types() -> tuple:
|
|
"""Cached tuple of exception types indicating MCP OAuth failure.
|
|
|
|
SDK ``OAuthFlowError``/``OAuthTokenError`` (+ legacy ``UnauthorizedError``),
|
|
our ``OAuthNonInteractiveError``, and ``HTTPStatusError`` from both httpx
|
|
flavours — the latter needs the 401 status check in :func:`_is_auth_error`.
|
|
"""
|
|
global _AUTH_ERROR_TYPES
|
|
if not _AUTH_ERROR_TYPES:
|
|
_AUTH_ERROR_TYPES = tuple(
|
|
_optional_types("mcp.client.auth", "OAuthFlowError", "OAuthTokenError")
|
|
+ _optional_types("mcp.client.auth", "UnauthorizedError") # older SDKs
|
|
+ _optional_types("tools.mcp_oauth", "OAuthNonInteractiveError")
|
|
+ list(_http_status_error_types())
|
|
)
|
|
return _AUTH_ERROR_TYPES
|
|
|
|
|
|
def _is_auth_error(exc: BaseException) -> bool:
|
|
"""True if ``exc`` indicates an MCP OAuth failure.
|
|
|
|
``HTTPStatusError`` counts only with status 401; other HTTP errors fall
|
|
through to the generic error path.
|
|
"""
|
|
types = _get_auth_error_types()
|
|
if not types or not isinstance(exc, types):
|
|
return False
|
|
status_error_types = _http_status_error_types()
|
|
if status_error_types and isinstance(exc, status_error_types):
|
|
return getattr(exc.response, "status_code", None) == 401
|
|
return True
|
|
|
|
|
|
# Lower-cased substrings meaning the server-side transport session expired /
|
|
# was GC'd. The OAuth token is still valid — only the transport needs rebuilding.
|
|
_SESSION_EXPIRED_MARKERS: tuple = (
|
|
"invalid or expired session", "expired session", "session expired", "session not found",
|
|
"unknown session", "session terminated", "closedresourceerror", "closed resource",
|
|
"transport is closed", "connection closed", "broken pipe", "end of file",
|
|
)
|
|
|
|
|
|
# Node budget for ``_is_session_expired_error``. The visited set breaks cycles;
|
|
# the budget bounds pathological acyclic graphs. Kept well above
|
|
# ``sys.getrecursionlimit()`` so deep task-group nesting is still fully scanned.
|
|
_EXC_TRAVERSAL_MAX_NODES = 10_000
|
|
|
|
|
|
def _is_session_expired_error(exc: BaseException) -> bool:
|
|
"""True if ``exc`` looks like an MCP transport session expiry.
|
|
|
|
Streamable-HTTP servers GC session state (idle TTL, restart, pod rotation)
|
|
while the OAuth token stays valid, so unlike :func:`_is_auth_error` the fix
|
|
is a transport reconnect (``_reconnect_event``), not an OAuth refresh.
|
|
"""
|
|
# AnyIO stream exceptions are often message-less (``str(ClosedResourceError()) == ""``),
|
|
# so type checks are needed in addition to marker matching.
|
|
transport_error_types = tuple(
|
|
_optional_types("anyio", "BrokenResourceError", "ClosedResourceError", "EndOfStream")
|
|
)
|
|
|
|
# Iterative traversal over ``exceptions`` / ``__cause__`` / ``__context__``
|
|
# with an identity-visited set AND a node budget (graphs can be deep or
|
|
# cyclic). Every reachable node is inspected so an InterruptedError anywhere
|
|
# overrides transport markers; the chain walk matters because SDK wrappers
|
|
# often raise a generic RuntimeError *from* the message-less ClosedResourceError.
|
|
stack: "list[BaseException | None]" = [exc]
|
|
seen: set[int] = set()
|
|
transport_error_found = False
|
|
budget = _EXC_TRAVERSAL_MAX_NODES
|
|
while stack and budget > 0:
|
|
current = stack.pop()
|
|
if current is None or id(current) in seen:
|
|
continue
|
|
seen.add(id(current))
|
|
budget -= 1
|
|
|
|
if isinstance(current, InterruptedError):
|
|
return False
|
|
# Messages vary across SDK versions and servers: match a narrow
|
|
# allow-list of stable substrings, not exception type, to avoid false positives.
|
|
msg = str(current).lower()
|
|
if isinstance(current, transport_error_types) or (
|
|
msg and any(marker in msg for marker in _SESSION_EXPIRED_MARKERS)
|
|
):
|
|
transport_error_found = True
|
|
|
|
stack.extend(getattr(current, "exceptions", ()))
|
|
stack.append(getattr(current, "__cause__", None))
|
|
stack.append(getattr(current, "__context__", None))
|
|
|
|
return transport_error_found
|