diff --git a/docs/decisions/0045-python-mcp-v2-client-lifecycle.md b/docs/decisions/0045-python-mcp-v2-client-lifecycle.md index 57d389fc760..6e51ab6266f 100644 --- a/docs/decisions/0045-python-mcp-v2-client-lifecycle.md +++ b/docs/decisions/0045-python-mcp-v2-client-lifecycle.md @@ -68,10 +68,12 @@ Agent Framework owns: - transport and Client construction, Client entry, and resource cleanup for framework-created connections; - the lifecycle-owner task, locks, connection publication, reset coordination, and cancellation cleanup; +- the default request read timeout for framework-created Clients, with an explicit `None` opt-out; +- configurable page/item bounds for Agent Framework-driven tool and prompt catalog discovery; - request-scoped HTTP header identity and reconnects caused by identity changes; - tool argument filtering and trusted request metadata merging; - result parsing, Agent Framework content conversion, tracing, and error translation; -- atomic catalog publication and rollback after a failed complete fetch; +- atomic catalog publication, including retained server annotations, and rollback after a failed complete fetch; - the background catalog-subscription task for any high-level Client, including refresh scheduling, retry/backoff, cancellation, and recovery after a subscription ends or is lost; - security and approval policy. @@ -80,7 +82,9 @@ For **caller-supplied** connections, the caller owns: - entering and closing a **supplied** high-level `Client`; - constructing and closing a **supplied** low-level `ClientSession`; -- the transport, authentication, callbacks, and other configuration already captured by either supplied object. +- the transport, authentication, callbacks, request timeout, and other configuration already captured by either + supplied object. Agent Framework does not overwrite that request policy, while its own catalog-materialization + page and item bounds still apply. Transport-specific tool constructors enforce the same ownership boundary. A URL or command selects framework-owned Client construction; a supplied high-level `mcp.Client` selects caller-owned construction and @@ -88,6 +92,10 @@ lifecycle. Constructor combinations that mix those ownership modes or configure owns raise `ValueError` instead of silently ignoring parameters. Temporarily retained legacy constructor and `ClientSession` combinations remain compatible and will be removed in vNext. +Catalog page and item limits apply after the MCP SDK parses each response. They do not establish a universal +transport response-size bound; applications must connect to MCP servers trusted to return reasonably sized responses +and configure transport-specific limits where the selected transport exposes them. + The SDK `Client` owns: - modern negotiation and legacy initialization fallback; @@ -153,6 +161,7 @@ A caller-supplied `Client` is the preferred way to provide an existing connectio - The Client must already be entered before the MCP tool connects. - Agent Framework does not enter, close, replace, or recreate it. +- Agent Framework does not replace its request timeout or transport-level resource policy. - Standard operations continue through the high-level Client and retain SDK MRTR and response-cache behavior. - Agent Framework manages its own catalog-subscription task around `Client.listen()` while the wrapper is connected. - `MCPTool.session` remains `None`. diff --git a/python/packages/core/AGENTS.md b/python/packages/core/AGENTS.md index 3acfc513d51..b66484a40ec 100644 --- a/python/packages/core/AGENTS.md +++ b/python/packages/core/AGENTS.md @@ -251,6 +251,17 @@ The vector store API is experimental under the shared `VECTOR_STORES` feature ID caller responsible for transport configuration and Client lifecycle. Constructors reject mixed ownership modes and framework-owned transport options with `mcp_client` rather than ignoring them. Deprecated caller-owned `ClientSession` combinations remain compatible until their vNext removal. +- **MCP request and discovery bounds** - Framework-created high-level Clients use the configured + `request_timeout`, which defaults to a 30-second read timeout; `None` explicitly disables the timeout. + Caller-supplied Clients and + `ClientSession`s retain their caller-owned request policy. Agent Framework tool and prompt discovery follows at + most `max_discovery_pages` pages (default 100) and accepts at most `max_discovery_items` entries (default 1,000) + per complete catalog fetch; `None` explicitly disables the corresponding limit for a trusted server. + Continuation cursors remain opaque, and every non-`None` cursor, including an empty string, is forwarded + unchanged. These limits apply after the MCP SDK parses each page and do not bound the encoded response size; + applications remain responsible for connecting to servers trusted to return reasonably sized responses and for + configuring transport-specific size limits where the selected transport exposes them. + `SecureMCPToolProxy(url=...)` forwards both discovery limits to its internal HTTP tool. - **Argument allowlist (`_prepare_call_kwargs`)** - Before each `tools/call`, kwargs are filtered to an **allowlist** built from the tool's declared parameters (`inputSchema.properties`) plus any user-configured extras. **The declared half comes from the server's advertised schema**, and runtime kwargs (`FunctionInvocationContext.kwargs`, seeded from `function_invocation_kwargs`) are merged with the model-supplied arguments upstream in `_call_tool_with_runtime_kwargs`, so provenance is gone by the time the filter runs. A runtime kwarg is therefore forwarded whenever the server declares a property of that name, without the model mentioning it — the server, not the caller, decides which runtime kwarg names it receives. A tool that declares no usable `properties` (including schemas with `additionalProperties: true`) forwards only the configured extras. `_MCP_FRAMEWORK_DENYLIST` is a narrow safety net covering only non-serializable framework objects a server *declares* in its schema (those are dropped); it does not generalize to arbitrary caller-chosen names, and explicit extras always win. The reserved `_meta` key is never forwarded as an argument; trusted caller/runtime `_meta` is validated as MCP request metadata, model-supplied `_meta` is discarded in generated MCP functions, and metadata precedence is caller/runtime < OpenTelemetry < tools/list metadata. - **`allowed_tools`** (constructor arg on all `MCPTool` subclasses) - Restricts exposed MCP tools by raw remote MCP tool identity. Prefixed local names remain accepted only when the raw remote name already matches its normalized form; normalized/local aliases do not authorize a different raw remote name. Configured allow/approval names must identify at most one raw remote name across loaded tools and prompts: a raw name that overlaps another tool's prefixed alias raises `ToolExecutionException`. Discovery validates all pages before publishing new functions; a failed reload retains the previous functions and metadata. The allowlist is also revalidated when exposing functions so runtime changes cannot select an ambiguous name. If multiple raw remote tool names map to the same local function name, tool loading raises `ToolExecutionException` instead of first-one-wins shadowing. - **`approval_mode`** (constructor arg on all `MCPTool` subclasses) - Accepts `"always_require"`, `"never_require"`, @@ -263,7 +274,14 @@ The vector store API is experimental under the shared `VECTOR_STORES` feature ID prompts discovered later (for example after `tools/list_changed`) use the policy at discovery time; retained functions keep their resolved mode. - **Progressive MCP disclosure** (`use_progressive_disclosure`, `always_load`) - When enabled on any `MCPTool` subclass, the initial model-facing surface is loader tools (`list_mcp_tools` / `load_tool` / `unload_tool`, prefixed by `tool_name_prefix` when configured) plus allowed tools selected by `always_load` and tools loaded earlier on the same `MCPTool` instance. `list_mcp_tools` only reports tools that pass `allowed_tools`; filtered tools are not listed or loadable. Loader tool names are reserved in progressive mode: remote MCP tools whose local generated name collides with a loader name are omitted from the initial/listed surface, and explicit `load_tool` calls return a model-visible message pointing callers to `tool_name_prefix` or excluding the colliding tool. `load_tool` accepts one tool name or a list of tool names and uses `FunctionInvocationContext.add_tools(...)` so the selected generated MCP `FunctionTool`s become available on the next function-calling iteration while keeping existing approval mode, argument filtering, header-provider runtime kwargs, result parsing, and OTel. `unload_tool` accepts one dynamically loaded tool name or a list of names and removes them from the live tool list and persisted progressive surface, but it does not remove tools configured in `always_load`. Invalid `always_load` entries are ignored like unmatched `allowed_tools` entries. -- **Tool discovery refresh** - Validate the complete current tool snapshot alongside retained non-tool functions, not stale tool wrappers. Successful refreshes atomically replace the previous tool set and metadata, including empty snapshots, while preserving prompts, custom functions, and unchanged tool wrappers (including caller customizations). Removed or replaced tool identities lose their persisted progressive-loaded state; failed refreshes preserve the previous state. +- **Tool discovery refresh** - Validate the complete current tool snapshot alongside retained non-tool functions, + not stale tool wrappers. Successful refreshes atomically replace the previous tool set and metadata, including + call metadata, declared parameter names, and server annotations, while preserving prompts, custom functions, and + unchanged tool wrappers (including caller customizations). Empty snapshots clear all session-derived tool + metadata. Removed or replaced tool identities lose their persisted progressive-loaded state; failed refreshes + preserve the previous complete state. MCP security labeling reads the retained annotation snapshot instead of + independently listing tools; `SecureMCPToolProxy.refresh_labels()` explicitly performs a bounded tool refresh + before reapplying local policy. - **`additional_tool_argument_names`** (constructor arg on all `MCPTool` subclasses) - Opt extra argument names back into the allowlist. Accepts a `Sequence[str]` (applied to every tool) or a `Mapping[str, Sequence[str]]` keyed by **remote tool name**, where the reserved key `"*"` denotes global extras. It is configured only in user code at construction; there is **no per-call/runtime override**, so a model-issued tool call cannot change which names pass through — but note this constrains the *model*, not the *server*, which still widens the effective allowlist through its schema. To use a server that accepts `additionalProperties: true`, list the extra names here and then either (1) manually extend that tool's `inputSchema` (via the `.functions` list after connecting) so the model is prompted to supply them, or (2) supply the values yourself via `function_invocation_kwargs`. If a normal forwarded argument name is supplied by both the model and `function_invocation_kwargs`, the model-supplied value wins; `_meta` is the exception and only trusted runtime/caller metadata is used. - **MCP HTTP header request scoping** - `static_headers` supplies fixed, origin-scoped headers without serializing concurrent calls. Generated tool and prompt calls give `header_provider` only host runtime kwargs, separately from model arguments; direct `call_tool` calls give it caller kwargs. Model-over-runtime precedence is confined to outbound tool arguments. Fixed and dynamic headers form the session's complete effective identity (case-insensitive names, case-sensitive values), with dynamic values overriding fixed values of the same name. Agent runs reconcile a connected tool before copying its functions; generated tool and prompt calls perform the same check at invocation. Connected run preparation defers when a provider needs runtime values supplied by invocation middleware; invocation-time resolution remains strict. A different identity waits for in-flight discovery, reconnects framework-created sessions without loading, then refreshes session-derived discovery under the same lock. Because a caller-supplied session's established identity is unknown and the wrapper cannot reconnect it, dynamic header resolution on that wrapper is rejected even while disconnected. Ambient requests retain the bound set. With a shared `http_client`, processing stays scoped to the originating `MCPStreamableHTTPTool`, and every injected header is stripped from cross-origin redirects. The session exit stack removes its request hook after transport shutdown, including failed initialization or discovery, and closes framework-created HTTP clients. Failed discovery resets the connection and discovery flags and rolls back partial function/metadata additions. Framework-created sessions are discarded; constructor-supplied sessions remain caller-owned and reusable across cleanup, close, and reset. - **MCP lifecycle caller cancellation** - The lifecycle owner skips cancelled queued connect requests and waits for the caller to acknowledge successful setup. If the caller cancels before accepting a newly established connection, the owner tears it down before processing the next request. Cancelling a close waiter does not interrupt teardown, and cancelling a redundant connect does not discard a previously established session. diff --git a/python/packages/core/agent_framework/_mcp.py b/python/packages/core/agent_framework/_mcp.py index cb614d4e610..4a80154f55b 100644 --- a/python/packages/core/agent_framework/_mcp.py +++ b/python/packages/core/agent_framework/_mcp.py @@ -10,7 +10,7 @@ import sys import warnings from abc import abstractmethod -from collections.abc import Callable, Collection, Coroutine, Mapping, Sequence +from collections.abc import Awaitable, Callable, Collection, Coroutine, Mapping, Sequence from contextlib import AsyncExitStack, _AsyncGeneratorContextManager # type: ignore from contextvars import ContextVar from copy import copy @@ -18,7 +18,7 @@ from datetime import date, datetime from http.cookiejar import CookieJar, DefaultCookiePolicy from inspect import currentframe, isawaitable -from typing import TYPE_CHECKING, Any, Literal, Protocol, Self, TypeAlias, TypedDict, cast +from typing import TYPE_CHECKING, Any, Literal, Protocol, Self, TypeAlias, TypedDict, TypeVar, cast if sys.version_info >= (3, 13): from warnings import deprecated # pragma: no cover @@ -71,6 +71,12 @@ logger = logging.getLogger(__name__) +_MCPListResultT = TypeVar( + "_MCPListResultT", + "types.ListToolsResult", + "types.ListPromptsResult", +) + def _mcp_exception_log_level() -> Literal[10] | None: """Return the automatic exception log level allowed by observability settings.""" @@ -242,10 +248,13 @@ class MCPSpecificApproval(TypedDict, total=False): _MCP_HEADER_OWNER_EXTENSION = "agent_framework.mcp_header_owner" _MCP_INJECTED_HEADER_KEYS_EXTENSION = "agent_framework.mcp_injected_header_keys" _MCPHeaderIdentity: TypeAlias = tuple[tuple[str, str], ...] -MCP_DEFAULT_TIMEOUT = 30 +_MCP_DEFAULT_READ_TIMEOUT_SECONDS = 30 MCP_DEFAULT_SSE_READ_TIMEOUT = 60 * 5 _MCP_SUBSCRIPTION_RETRY_INITIAL_DELAY = 0.1 _MCP_SUBSCRIPTION_RETRY_MAX_DELAY = 2.0 + +_DEFAULT_MCP_DISCOVERY_MAX_PAGES = 100 +_DEFAULT_MCP_DISCOVERY_MAX_ITEMS = 1_000 _DEFAULT_MCP_HOST_PAYLOAD_SIZE_BYTES = 1024 * 1024 @@ -1163,7 +1172,7 @@ def __init__( parse_prompt_results: Callable[[types.GetPromptResult], str] | None = None, mcp_client: Client | None = None, session: ClientSession | None = None, - request_timeout: int | None = None, + request_timeout: int | None = _MCP_DEFAULT_READ_TIMEOUT_SECONDS, client: SupportsChatGetResponse | None = None, sampling_approval_callback: SamplingApprovalCallback | None = None, sampling_max_tokens: int | None = _DEFAULT_SAMPLING_MAX_TOKENS, @@ -1174,6 +1183,8 @@ def __init__( use_progressive_disclosure: bool = False, always_load: Collection[str] | None = None, *, + max_discovery_pages: int | None = _DEFAULT_MCP_DISCOVERY_MAX_PAGES, + max_discovery_items: int | None = _DEFAULT_MCP_DISCOVERY_MAX_ITEMS, max_host_payload_size_bytes: int | None = _DEFAULT_MCP_HOST_PAYLOAD_SIZE_BYTES, tool_result_content: MCPToolResultContentMode = "structured_first", ) -> None: @@ -1198,6 +1209,10 @@ def __init__( object_name="MCP progressive disclosure", category=ExperimentalWarning, ) + if max_discovery_pages is not None and max_discovery_pages <= 0: + raise ValueError("max_discovery_pages must be positive or None.") + if max_discovery_items is not None and max_discovery_items <= 0: + raise ValueError("max_discovery_items must be positive or None.") if max_host_payload_size_bytes is not None and max_host_payload_size_bytes <= 0: raise ValueError("max_host_payload_size_bytes must be positive or None.") if request_timeout is not None and request_timeout <= 0: @@ -1226,6 +1241,8 @@ def __init__( self.tool_result_content = tool_result_content self.load_prompts_flag = load_prompts self.parse_prompt_results = parse_prompt_results + self.max_discovery_pages = max_discovery_pages + self.max_discovery_items = max_discovery_items self.max_host_payload_size_bytes = max_host_payload_size_bytes self._exit_stack = AsyncExitStack() self._lifecycle_lock = asyncio.Lock() @@ -1274,6 +1291,7 @@ def __init__( self._progressive_loaded_tool_names: set[str] = set() self._tool_call_meta_by_name: dict[str, dict[str, Any]] = {} self._tool_param_names_by_name: dict[str, set[str]] = {} + self._tool_annotations_by_name: dict[str, Any] = {} self._global_extra_arg_names, self._tool_extra_arg_names = _normalize_additional_tool_argument_names( additional_tool_argument_names ) @@ -2321,6 +2339,7 @@ def _reset_session_discovery_state(self) -> None: ] self._tool_call_meta_by_name.clear() self._tool_param_names_by_name.clear() + self._tool_annotations_by_name.clear() self._progressive_loaded_tool_names.clear() def _reset_session_state(self) -> None: @@ -2554,6 +2573,7 @@ async def _connect_on_owner( functions_before_discovery = self._functions.copy() call_meta_before_discovery = self._tool_call_meta_by_name param_names_before_discovery = self._tool_param_names_by_name + annotations_before_discovery = self._tool_annotations_by_name try: connection = self._require_connection() logger.debug("Connected to MCP server: %s", connection.client or connection.session) @@ -2589,6 +2609,7 @@ async def _connect_on_owner( self._functions[:] = functions_before_discovery self._tool_call_meta_by_name = call_meta_before_discovery self._tool_param_names_by_name = param_names_before_discovery + self._tool_annotations_by_name = annotations_before_discovery raise async def _prepare_for_run(self, kwargs: Mapping[str, Any]) -> None: @@ -2964,7 +2985,6 @@ async def load_prompts(self) -> None: await self._load_prompts_locked() async def _load_prompts_locked(self) -> None: - from anyio import ClosedResourceError from mcp import types if not self._supports_prompts: @@ -2983,52 +3003,17 @@ async def _load_prompts_locked(self) -> None: prompt_functions: list[FunctionTool] = [] retained_prompt_names: set[str] = set() new_functions: list[FunctionTool] = [] + items_loaded = 0 - params: types.PaginatedRequestParams | None = None - while True: - prompt_list: types.ListPromptsResult | None = None - for attempt in range(2): - try: - # Ensure connection is still valid before each page request - await self._ensure_connected() - if not self._supports_prompts: - logger.debug( - "Skipping MCP prompt loading because the server did not advertise prompts support." - ) - return - with create_mcp_client_span( - "prompts/list", - attributes=self._mcp_base_span_attributes(), - capture_unhandled_exceptions=False, - ) as list_span: - try: - prompt_list = await self._require_connection().list_prompts_page(params) - except Exception as list_ex: - set_mcp_span_error(list_span, type(list_ex).__name__, str(list_ex)) - raise - break - except ClosedResourceError as cl_ex: - if attempt == 0: - await self._recover_connection_after_loss( - operation="prompt discovery", - inner_exception=cl_ex, - load_configured=False, - ) - continue - _log_mcp_exception( - logging.ERROR, - cl_ex, - "MCP connection closed unexpectedly after reconnection: %s", - cl_ex, - redacted_message="MCP prompt discovery connection closed after reconnection", - ) - raise _mcp_tool_execution_exception( - "Failed to load prompts - connection lost.", - inner_exception=cl_ex, - ) from cl_ex - - if prompt_list is None: - raise _mcp_tool_execution_exception("Failed to load prompts.") + def stage_prompt_page(prompt_list: types.ListPromptsResult) -> None: + nonlocal items_loaded + items_loaded += len(prompt_list.prompts) + if self.max_discovery_items is not None and items_loaded > self.max_discovery_items: + raise _mcp_tool_execution_exception( + f"MCP prompt discovery exceeded max_discovery_items={self.max_discovery_items}; " + f"the server returned {items_loaded} prompts. Increase max_discovery_items, " + "or set it to None only for a trusted MCP server." + ) for prompt in prompt_list.prompts: normalized_name = _normalize_mcp_name(prompt.name) @@ -3075,10 +3060,35 @@ async def _load_prompts_locked(self) -> None: prompt_functions.append(func) new_functions.append(func) - # Check if there are more pages - if not prompt_list.next_cursor: - break - params = types.PaginatedRequestParams(cursor=prompt_list.next_cursor) + prompt_list = await self._try_list_page_with_recovery( + None, + kind="prompt", + request_page=lambda page_params: self._require_connection().list_prompts_page(page_params), + ) + if prompt_list is None: + return + pages_loaded = 1 + stage_prompt_page(prompt_list) + cursor = prompt_list.next_cursor + + while cursor is not None: + if self.max_discovery_pages is not None and pages_loaded >= self.max_discovery_pages: + raise _mcp_tool_execution_exception( + f"MCP prompt discovery exceeded max_discovery_pages={self.max_discovery_pages}; " + f"the server returned a continuation cursor after page {pages_loaded}. " + "Increase max_discovery_pages, or set it to None only for a trusted MCP server." + ) + + prompt_list = await self._try_list_page_with_recovery( + types.PaginatedRequestParams(cursor=cursor), + kind="prompt", + request_page=lambda page_params: self._require_connection().list_prompts_page(page_params), + ) + if prompt_list is None: + return + pages_loaded += 1 + stage_prompt_page(prompt_list) + cursor = prompt_list.next_cursor current_functions = [func for func in self._functions if not _is_mcp_prompt_function(func)] current_functions.extend(prompt_functions) @@ -3091,6 +3101,78 @@ async def _load_prompts_locked(self) -> None: # different remote prompt that normalizes to the same local name must start unloaded. self._progressive_loaded_tool_names.difference_update(existing_prompts.keys() - retained_prompt_names) + async def _try_list_page_with_recovery( + self, + params: types.PaginatedRequestParams | None, + *, + kind: Literal["tool", "prompt"], + request_page: Callable[[types.PaginatedRequestParams | None], Awaitable[_MCPListResultT]], + ) -> _MCPListResultT | None: + """Fetch one catalog page, retrying after connection loss.""" + from anyio import ClosedResourceError + from tenacity import RetryCallState, retry, retry_if_exception_type, stop_after_attempt + + catalog_name = f"{kind}s" + operation = f"{kind} discovery" + + async def recover_connection(retry_state: RetryCallState) -> None: + outcome = retry_state.outcome + exception = outcome.exception() if outcome else None + + if not isinstance(exception, ClosedResourceError): + return + + await self._recover_connection_after_loss( + operation=operation, + inner_exception=exception, + load_configured=False, + ) + + @retry( + retry=retry_if_exception_type(ClosedResourceError), + stop=stop_after_attempt(2), + before_sleep=recover_connection, + reraise=True, + ) + async def request_page_with_retry() -> _MCPListResultT | None: + await self._ensure_connected() + + # on reconnect we may have different capabilities. + is_supported = self._supports_tools if kind == "tool" else self._supports_prompts + if not is_supported: + logger.debug( + "Skipping MCP %s loading because the server did not advertise %s support.", + kind, + catalog_name, + ) + return None + + with create_mcp_client_span( + f"{catalog_name}/list", + attributes=self._mcp_base_span_attributes(), + capture_unhandled_exceptions=False, + ) as list_span: + try: + return await request_page(params) + except Exception as exc: + set_mcp_span_error(list_span, type(exc).__name__, str(exc)) + raise + + try: + return await request_page_with_retry() + except ClosedResourceError as exc: + _log_mcp_exception( + logging.ERROR, + exc, + "MCP connection closed unexpectedly after reconnection: %s", + exc, + redacted_message=f"MCP {operation} connection closed after reconnection", + ) + raise _mcp_tool_execution_exception( + f"Failed to load {catalog_name} - connection lost.", + inner_exception=exc, + ) from exc + async def load_tools(self) -> None: """Load tools from the MCP server. @@ -3106,7 +3188,6 @@ async def load_tools(self) -> None: await self._load_tools_locked() async def _load_tools_locked(self) -> None: - from anyio import ClosedResourceError from mcp import types if not self._supports_tools: @@ -3128,50 +3209,17 @@ async def _load_tools_locked(self) -> None: tool_call_meta_by_name: dict[str, dict[str, Any]] = {} tool_param_names_by_name: dict[str, set[str]] = {} tool_annotations_by_name: dict[str, Any] = {} + items_loaded = 0 - params: types.PaginatedRequestParams | None = None - while True: - tool_list: types.ListToolsResult | None = None - for attempt in range(2): - try: - # Ensure connection is still valid before each page request - await self._ensure_connected() - if not self._supports_tools: - logger.debug("Skipping MCP tool loading because the server did not advertise tools support.") - return - with create_mcp_client_span( - "tools/list", - attributes=self._mcp_base_span_attributes(), - capture_unhandled_exceptions=False, - ) as list_span: - try: - tool_list = await self._require_connection().list_tools_page(params) - except Exception as list_ex: - set_mcp_span_error(list_span, type(list_ex).__name__, str(list_ex)) - raise - break - except ClosedResourceError as cl_ex: - if attempt == 0: - await self._recover_connection_after_loss( - operation="tool discovery", - inner_exception=cl_ex, - load_configured=False, - ) - continue - _log_mcp_exception( - logging.ERROR, - cl_ex, - "MCP connection closed unexpectedly after reconnection: %s", - cl_ex, - redacted_message="MCP tool discovery connection closed after reconnection", - ) - raise _mcp_tool_execution_exception( - "Failed to load tools - connection lost.", - inner_exception=cl_ex, - ) from cl_ex - - if tool_list is None: - raise _mcp_tool_execution_exception("Failed to load tools.") + def stage_tool_page(tool_list: types.ListToolsResult) -> None: + nonlocal items_loaded + items_loaded += len(tool_list.tools) + if self.max_discovery_items is not None and items_loaded > self.max_discovery_items: + raise _mcp_tool_execution_exception( + f"MCP tool discovery exceeded max_discovery_items={self.max_discovery_items}; " + f"the server returned {items_loaded} tools. Increase max_discovery_items, " + "or set it to None only for a trusted MCP server." + ) for tool in tool_list.tools: task_support = getattr(getattr(tool, "execution", None), "task_support", None) @@ -3250,10 +3298,35 @@ async def _load_tools_locked(self) -> None: ) new_functions.append(func) - # Check if there are more pages - if not tool_list.next_cursor: - break - params = types.PaginatedRequestParams(cursor=tool_list.next_cursor) + tool_list = await self._try_list_page_with_recovery( + None, + kind="tool", + request_page=lambda page_params: self._require_connection().list_tools_page(page_params), + ) + if tool_list is None: + return + pages_loaded = 1 + stage_tool_page(tool_list) + cursor = tool_list.next_cursor + + while cursor is not None: + if self.max_discovery_pages is not None and pages_loaded >= self.max_discovery_pages: + raise _mcp_tool_execution_exception( + f"MCP tool discovery exceeded max_discovery_pages={self.max_discovery_pages}; " + f"the server returned a continuation cursor after page {pages_loaded}. " + "Increase max_discovery_pages, or set it to None only for a trusted MCP server." + ) + + tool_list = await self._try_list_page_with_recovery( + types.PaginatedRequestParams(cursor=cursor), + kind="tool", + request_page=lambda page_params: self._require_connection().list_tools_page(page_params), + ) + if tool_list is None: + return + pages_loaded += 1 + stage_tool_page(tool_list) + cursor = tool_list.next_cursor current_functions = [ func @@ -3276,6 +3349,7 @@ async def _load_tools_locked(self) -> None: self._functions[:] = current_functions self._tool_call_meta_by_name = tool_call_meta_by_name self._tool_param_names_by_name = tool_param_names_by_name + self._tool_annotations_by_name = tool_annotations_by_name self._progressive_loaded_tool_names.difference_update(existing_tools.keys() - reused_tool_names) async def _cancel_pending_reload_tasks(self) -> None: @@ -3730,7 +3804,7 @@ def __init__( parse_tool_results: Callable[[types.CallToolResult], str | list[Content]] | None = None, load_prompts: bool = True, parse_prompt_results: Callable[[types.GetPromptResult], str] | None = None, - request_timeout: int | None = None, + request_timeout: int | None = _MCP_DEFAULT_READ_TIMEOUT_SECONDS, mcp_client: Client | None = None, session: ClientSession | None = None, description: str | None = None, @@ -3748,6 +3822,8 @@ def __init__( additional_properties: dict[str, Any] | None = None, task_options: Any | None = None, additional_tool_argument_names: Sequence[str] | Mapping[str, Sequence[str]] | None = None, + max_discovery_pages: int | None = _DEFAULT_MCP_DISCOVERY_MAX_PAGES, + max_discovery_items: int | None = _DEFAULT_MCP_DISCOVERY_MAX_ITEMS, max_host_payload_size_bytes: int | None = _DEFAULT_MCP_HOST_PAYLOAD_SIZE_BYTES, tool_result_content: MCPToolResultContentMode = "structured_first", **kwargs: Any, @@ -3784,7 +3860,8 @@ def __init__( MCP prompt results to a string. If you need per-function result parsing, access the ``.functions`` list after connecting and set ``result_parser`` on individual ``FunctionTool`` instances. - request_timeout: The default timeout in seconds for all requests. + request_timeout: The timeout in seconds for all requests. Framework-owned clients default to 30 seconds; + ``None`` disables the timeout. Caller-owned clients retain their own timeout policy. mcp_client: An already-entered high-level MCP ``Client`` to use. The caller retains ownership; closing or resetting this wrapper does not close or replace that client. Mutually exclusive with ``command`` and ``session``. ``request_timeout``, ``args``, ``env``, ``encoding``, and @@ -3856,6 +3933,12 @@ def __init__( ``function_invocation_kwargs`` - for example through ``env`` - for servers whose process you do not control. task_options: Deprecated compatibility parameter. Non-``None`` values are ignored with a warning. + max_discovery_pages: Maximum pages accepted independently for each tool or prompt catalog fetch. + ``None`` disables the limit. + max_discovery_items: Maximum entries accepted independently for each tool or prompt catalog fetch. + Defaults to 1,000. ``None`` disables the limit. Discovery limits apply after the MCP SDK parses + each page and do not bound the encoded response size; connect only to servers trusted to return + reasonably sized responses and configure transport-specific size limits where available. max_host_payload_size_bytes: Maximum encoded MCP result size retained for Host transports. ``None`` disables the limit. tool_result_content: How to choose model-visible text when both ``content`` and @@ -3874,7 +3957,10 @@ def __init__( conflicting_options = [ option for option, is_configured in ( - ("request_timeout", request_timeout is not None), + ( + "request_timeout", + request_timeout not in (None, _MCP_DEFAULT_READ_TIMEOUT_SECONDS), + ), ("args", args is not None), ("env", env is not None), ("encoding", encoding is not None), @@ -3911,6 +3997,8 @@ def __init__( sampling_max_tokens=sampling_max_tokens, sampling_max_requests=sampling_max_requests, task_options=task_options, + max_discovery_pages=max_discovery_pages, + max_discovery_items=max_discovery_items, max_host_payload_size_bytes=max_host_payload_size_bytes, tool_result_content=tool_result_content, ) @@ -3987,7 +4075,7 @@ def __init__( parse_tool_results: Callable[[types.CallToolResult], str | list[Content]] | None = None, load_prompts: bool = True, parse_prompt_results: Callable[[types.GetPromptResult], str] | None = None, - request_timeout: int | None = None, + request_timeout: int | None = _MCP_DEFAULT_READ_TIMEOUT_SECONDS, mcp_client: Client | None = None, session: ClientSession | None = None, description: str | None = None, @@ -4006,6 +4094,8 @@ def __init__( header_provider: Callable[[dict[str, Any]], dict[str, str]] | None = None, additional_tool_argument_names: Sequence[str] | Mapping[str, Sequence[str]] | None = None, task_options: Any = None, + max_discovery_pages: int | None = _DEFAULT_MCP_DISCOVERY_MAX_PAGES, + max_discovery_items: int | None = _DEFAULT_MCP_DISCOVERY_MAX_ITEMS, max_host_payload_size_bytes: int | None = _DEFAULT_MCP_HOST_PAYLOAD_SIZE_BYTES, tool_result_content: MCPToolResultContentMode = "structured_first", **kwargs: Any, @@ -4044,7 +4134,8 @@ def __init__( MCP prompt results to a string. If you need per-function result parsing, access the ``.functions`` list after connecting and set ``result_parser`` on individual ``FunctionTool`` instances. - request_timeout: The default timeout in seconds for all requests. + request_timeout: The timeout in seconds for all requests. Framework-owned clients default to 30 seconds; + ``None`` disables the timeout. Caller-owned clients retain their own timeout policy. mcp_client: An already-entered high-level MCP ``Client`` to use. The caller retains ownership; closing or resetting this wrapper does not close or replace that client. Mutually exclusive with ``url`` and ``session``. ``request_timeout``, ``terminate_on_close``, ``http_client``, @@ -4185,6 +4276,12 @@ def __init__( still allows a different value per request), or configure a custom ``http_client``. task_options: Deprecated compatibility parameter. Non-``None`` values are ignored with a warning. + max_discovery_pages: Maximum pages accepted independently for each tool or prompt catalog fetch. + ``None`` disables the limit. + max_discovery_items: Maximum entries accepted independently for each tool or prompt catalog fetch. + Defaults to 1,000. ``None`` disables the limit. Discovery limits apply after the MCP SDK parses + each page and do not bound the encoded response size; connect only to servers trusted to return + reasonably sized responses and configure transport-specific size limits where available. max_host_payload_size_bytes: Maximum encoded MCP result size retained for Host transports. ``None`` disables the limit. tool_result_content: How to choose model-visible text when both ``content`` and @@ -4203,7 +4300,10 @@ def __init__( conflicting_options = [ option for option, is_configured in ( - ("request_timeout", request_timeout is not None), + ( + "request_timeout", + request_timeout not in (None, _MCP_DEFAULT_READ_TIMEOUT_SECONDS), + ), ("terminate_on_close", terminate_on_close is not None), ("http_client", http_client is not None), ("static_headers", static_headers is not None), @@ -4240,6 +4340,8 @@ def __init__( sampling_max_tokens=sampling_max_tokens, sampling_max_requests=sampling_max_requests, task_options=task_options, + max_discovery_pages=max_discovery_pages, + max_discovery_items=max_discovery_items, max_host_payload_size_bytes=max_host_payload_size_bytes, tool_result_content=tool_result_content, ) @@ -4318,7 +4420,7 @@ def get_mcp_client(self) -> _AsyncGeneratorContextManager[Any, None]: if http_client is None: http_client = AsyncClient( follow_redirects=True, - timeout=Timeout(MCP_DEFAULT_TIMEOUT, read=MCP_DEFAULT_SSE_READ_TIMEOUT), + timeout=Timeout(_MCP_DEFAULT_READ_TIMEOUT_SECONDS, read=MCP_DEFAULT_SSE_READ_TIMEOUT), cookies=CookieJar(policy=DefaultCookiePolicy(allowed_domains=[])), ) self._httpx_client = http_client @@ -4657,7 +4759,7 @@ def __init__( parse_tool_results: Callable[[types.CallToolResult], str | list[Content]] | None = None, load_prompts: bool = True, parse_prompt_results: Callable[[types.GetPromptResult], str] | None = None, - request_timeout: int | None = None, + request_timeout: int | None = _MCP_DEFAULT_READ_TIMEOUT_SECONDS, session: ClientSession | None = None, description: str | None = None, approval_mode: (Literal["always_require", "never_require"] | MCPSpecificApproval | None) = None, @@ -4671,6 +4773,8 @@ def __init__( additional_properties: dict[str, Any] | None = None, additional_tool_argument_names: Sequence[str] | Mapping[str, Sequence[str]] | None = None, task_options: Any = None, + max_discovery_pages: int | None = _DEFAULT_MCP_DISCOVERY_MAX_PAGES, + max_discovery_items: int | None = _DEFAULT_MCP_DISCOVERY_MAX_ITEMS, max_host_payload_size_bytes: int | None = _DEFAULT_MCP_HOST_PAYLOAD_SIZE_BYTES, tool_result_content: MCPToolResultContentMode = "structured_first", **kwargs: Any, @@ -4702,7 +4806,8 @@ def __init__( MCP prompt results to a string. If you need per-function result parsing, access the ``.functions`` list after connecting and set ``result_parser`` on individual ``FunctionTool`` instances. - request_timeout: The default timeout in seconds for all requests. + request_timeout: The timeout in seconds for all requests. Framework-owned clients default to 30 seconds; + ``None`` disables the timeout. Caller-owned sessions retain their own timeout policy. session: An existing MCP client session to use. The caller retains ownership; closing or resetting this wrapper does not close or replace that session. description: The description of the tool. @@ -4764,6 +4869,12 @@ def __init__( transport has no header hook, so source credentials outside ``function_invocation_kwargs`` for servers you do not control. task_options: Deprecated compatibility parameter. Non-``None`` values are ignored with a warning. + max_discovery_pages: Maximum pages accepted independently for each tool or prompt catalog fetch. + ``None`` disables the limit. + max_discovery_items: Maximum entries accepted independently for each tool or prompt catalog fetch. + Defaults to 1,000. ``None`` disables the limit. Discovery limits apply after the MCP SDK parses + each page and do not bound the encoded response size; connect only to servers trusted to return + reasonably sized responses and configure transport-specific size limits where available. max_host_payload_size_bytes: Maximum encoded MCP result size retained for Host transports. ``None`` disables the limit. tool_result_content: How to choose model-visible text when both ``content`` and @@ -4791,6 +4902,8 @@ def __init__( sampling_max_tokens=sampling_max_tokens, sampling_max_requests=sampling_max_requests, task_options=task_options, + max_discovery_pages=max_discovery_pages, + max_discovery_items=max_discovery_items, max_host_payload_size_bytes=max_host_payload_size_bytes, tool_result_content=tool_result_content, ) diff --git a/python/packages/core/agent_framework/security.py b/python/packages/core/agent_framework/security.py index 0ae5b5e77de..954b7ce3043 100644 --- a/python/packages/core/agent_framework/security.py +++ b/python/packages/core/agent_framework/security.py @@ -4412,7 +4412,8 @@ def _apply_mcp_security_label_to_function( @experimental(feature_id=ExperimentalFeature.FIDES) -async def apply_mcp_security_labels( +# Keep this async for public API compatibility now that annotations come from the retained catalog snapshot. +async def apply_mcp_security_labels( # ruff: ignore[unused-async] mcp_tool: Any, *, default_integrity: IntegrityLabel = IntegrityLabel.UNTRUSTED, @@ -4478,19 +4479,7 @@ async def apply_mcp_security_labels( "MCPTool is not connected. Call connect() or use 'async with' before applying security labels." ) - connection = mcp_tool._require_connection() - - from mcp import types as mcp_types - - annotation_map: dict[str, Any] = {} - params: mcp_types.PaginatedRequestParams | None = None - while True: - tool_list = await connection.list_tools_page(params) - for remote_tool in tool_list.tools: - annotation_map[remote_tool.name] = remote_tool.annotations - if not tool_list.next_cursor: - break - params = mcp_types.PaginatedRequestParams(cursor=tool_list.next_cursor) + annotation_map = dict(mcp_tool._tool_annotations_by_name) loaded_functions = getattr(mcp_tool, "_functions", None) if not isinstance(loaded_functions, list): @@ -4681,6 +4670,10 @@ class SecureMCPToolProxy: name: Tool name used when creating the internal ``MCPStreamableHTTPTool`` (defaults to ``"mcp"``). description: Tool description for the internal tool. + max_discovery_pages: Maximum pages accepted independently for each tool or prompt catalog fetch in + *url* mode. Defaults to 100; ``None`` disables the limit. + max_discovery_items: Maximum entries accepted independently for each tool or prompt catalog fetch in + *url* mode. Defaults to 1,000; ``None`` disables the limit. default_integrity: Default integrity for tools without annotations. annotation_overrides: Per-tool-name label overrides (keyed by remote MCP tool name), applied only to this proxy's MCP connection. @@ -4702,6 +4695,8 @@ def __init__( headers: dict[str, str] | None = None, name: str | None = None, description: str | None = None, + max_discovery_pages: int | None = 100, + max_discovery_items: int | None = 1_000, default_integrity: IntegrityLabel = IntegrityLabel.UNTRUSTED, annotation_overrides: dict[str, tuple[IntegrityLabel, ConfidentialityLabel | None]] | None = None, mark_write_tools_as_sinks: bool = True, @@ -4722,6 +4717,10 @@ def __init__( name: Tool name used when creating the internal ``MCPStreamableHTTPTool`` (defaults to ``"mcp"``). description: Tool description for the internal tool. + max_discovery_pages: Maximum pages accepted independently for each tool or prompt catalog fetch in + ``url`` mode. Defaults to 100; ``None`` disables the limit. + max_discovery_items: Maximum entries accepted independently for each tool or prompt catalog fetch in + ``url`` mode. Defaults to 1,000; ``None`` disables the limit. default_integrity: Default integrity for tools without annotations. Defaults to ``IntegrityLabel.UNTRUSTED``. annotation_overrides: Per-tool-name label overrides keyed by remote MCP tool name, @@ -4752,6 +4751,8 @@ def __init__( url=url, description=description, static_headers=static_headers, + max_discovery_pages=max_discovery_pages, + max_discovery_items=max_discovery_items, ) # The validation above guarantees a tool is set (passed directly or built @@ -4819,15 +4820,17 @@ async def disconnect(self) -> None: self._unbind_function_load_callback() async def refresh_labels(self) -> None: - """Re-apply labels and wrappers to all currently discovered functions. + """Refresh enabled tool discovery, then re-apply labels to discovered functions. - Later-discovered functions are labeled automatically while the proxy - is active. + When tool loading is disabled, this only reapplies labels to the existing catalog snapshot. + Later-discovered functions are labeled automatically while the proxy is active. """ if not self.is_connected: raise RuntimeError("MCPTool is not connected. Connect before refreshing labels.") callback_bound = self._bind_function_load_callback() try: + if self._mcp_tool.load_tools_flag: + await self._mcp_tool.load_tools() await self._apply_labels() except BaseException: if callback_bound: diff --git a/python/packages/core/tests/core/test_mcp.py b/python/packages/core/tests/core/test_mcp.py index 30a44ec87c4..23ee4ea01a1 100644 --- a/python/packages/core/tests/core/test_mcp.py +++ b/python/packages/core/tests/core/test_mcp.py @@ -319,6 +319,60 @@ def test_mcp_transport_subclasses_accept_tool_name_prefix() -> None: ) +def test_mcp_transport_subclasses_default_discovery_page_limit() -> None: + with warnings.catch_warnings(): + warnings.simplefilter("ignore", DeprecationWarning) + tools = [ + MCPStdioTool(name="stdio", command="python"), + MCPStreamableHTTPTool(name="http", url="https://example.com/mcp"), + MCPWebsocketTool(name="websocket", url="wss://example.com/mcp"), # ty: ignore[deprecated] + ] + + assert all(tool.max_discovery_pages == 100 for tool in tools) + assert all(tool.max_discovery_items == 1_000 for tool in tools) + + +def test_mcp_transport_subclasses_forward_discovery_page_limit() -> None: + with warnings.catch_warnings(): + warnings.simplefilter("ignore", DeprecationWarning) + tools = [ + MCPStdioTool(name="stdio", command="python", max_discovery_pages=101, max_discovery_items=1_001), + MCPStreamableHTTPTool( + name="http", + url="https://example.com/mcp", + max_discovery_pages=102, + max_discovery_items=1_002, + ), + MCPWebsocketTool( # ty: ignore[deprecated] + name="websocket", + url="wss://example.com/mcp", + max_discovery_pages=103, + max_discovery_items=1_003, + ), + ] + + assert [tool.max_discovery_pages for tool in tools] == [101, 102, 103] + assert [tool.max_discovery_items for tool in tools] == [1_001, 1_002, 1_003] + + +@pytest.mark.parametrize("max_discovery_pages", [0, -1]) +def test_mcp_tool_rejects_non_positive_discovery_page_limit(max_discovery_pages: int) -> None: + with pytest.raises(ValueError, match="max_discovery_pages must be positive or None"): + MCPTool( # type: ignore[abstract] # ty: ignore[call-non-callable] + name="test_tool", + max_discovery_pages=max_discovery_pages, + ) + + +@pytest.mark.parametrize("max_discovery_items", [0, -1]) +def test_mcp_tool_rejects_non_positive_discovery_item_limit(max_discovery_items: int) -> None: + with pytest.raises(ValueError, match="max_discovery_items must be positive or None"): + MCPTool( # type: ignore[abstract] # ty: ignore[call-non-callable] + name="test_tool", + max_discovery_items=max_discovery_items, + ) + + @pytest.mark.parametrize("configured_name", ["search_docs", "docs_search_docs"]) async def test_load_tools_with_tool_name_prefix_preserves_matching_configuration(configured_name: str): """Prefixed MCP tool names should still honor unprefixed allow/approval configuration.""" @@ -511,9 +565,12 @@ async def test_tool_refresh_replaces_snapshot_and_preserves_other_functions(empt tool = MCPTool(name="docs", tool_name_prefix="docs") # type: ignore[abstract] # ty: ignore[call-non-callable] mock_session = AsyncMock() tool.session = mock_session + initial_annotations = types.ToolAnnotations(read_only_hint=True, open_world_hint=False) + refreshed_annotations = types.ToolAnnotations(read_only_hint=True, open_world_hint=True) keep = types.Tool( name="keep", input_schema={"type": "object", "properties": {"query": {"type": "string"}}}, + annotations=initial_annotations, _meta={"version": 1}, ) removed = types.Tool( @@ -536,6 +593,7 @@ async def test_tool_refresh_replaces_snapshot_and_preserves_other_functions(empt original_functions = list(original_list) original_meta = dict(tool._tool_call_meta_by_name) keep.meta = {"version": 2} + keep.annotations = refreshed_annotations async def list_tools(params: types.PaginatedRequestParams | None = None) -> types.ListToolsResult: assert tool._functions == original_functions @@ -559,6 +617,39 @@ async def list_tools(params: types.PaginatedRequestParams | None = None) -> type assert kept_function.result_parser is parser assert tool._tool_call_meta_by_name == ({} if empty_snapshot else {"keep": {"version": 2}}) assert tool._tool_param_names_by_name == ({} if empty_snapshot else {"keep": {"query"}}) + assert tool._tool_annotations_by_name == ({} if empty_snapshot else {"keep": refreshed_annotations}) + + +async def test_failed_tool_refresh_preserves_previous_annotation_snapshot() -> None: + tool = MCPTool(name="docs") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = AsyncMock() + tool.session = mock_session + original_annotations = types.ToolAnnotations(read_only_hint=True, open_world_hint=False) + replacement_annotations = types.ToolAnnotations(read_only_hint=True, open_world_hint=True) + original = types.Tool( + name="search", + input_schema={"type": "object", "properties": {}}, + annotations=original_annotations, + ) + mock_session.list_tools = AsyncMock(return_value=types.ListToolsResult(tools=[original])) + await tool.load_tools() + + replacement = types.Tool( + name="search", + input_schema={"type": "object", "properties": {}}, + annotations=replacement_annotations, + ) + mock_session.list_tools = AsyncMock( + side_effect=[ + types.ListToolsResult(tools=[replacement], next_cursor="second"), + RuntimeError("refresh failed"), + ] + ) + + with pytest.raises(RuntimeError, match="refresh failed"): + await tool.load_tools() + + assert tool._tool_annotations_by_name == {"search": original_annotations} async def test_load_tools_skips_only_task_required_tools(caplog: pytest.LogCaptureFixture) -> None: @@ -5721,6 +5812,39 @@ async def test_connect_preserves_request_timeout_over_24_hours() -> None: assert mock_client_class.call_args.kwargs["read_timeout_seconds"] == 90_000 +async def test_connect_uses_default_read_timeout_when_request_timeout_is_omitted() -> None: + from agent_framework._mcp import _MCP_DEFAULT_READ_TIMEOUT_SECONDS + + tool = MCPStdioTool( + name="test", + command="test-command", + load_tools=False, + load_prompts=False, + ) + + with patch("mcp.Client") as mock_client_class: + mock_client_class.return_value = _mock_sdk_client(protocol_version="2026-07-28") + + async with tool: + assert mock_client_class.call_args.kwargs["read_timeout_seconds"] == _MCP_DEFAULT_READ_TIMEOUT_SECONDS + + +async def test_connect_allows_disabling_request_timeout() -> None: + tool = MCPStdioTool( + name="test", + command="test-command", + load_tools=False, + load_prompts=False, + request_timeout=None, + ) + + with patch("mcp.Client") as mock_client_class: + mock_client_class.return_value = _mock_sdk_client(protocol_version="2026-07-28") + + async with tool: + assert mock_client_class.call_args.kwargs["read_timeout_seconds"] is None + + async def test_connect_revalidates_request_timeout_cleared_after_construction() -> None: tool = MCPStdioTool( name="test", @@ -6587,7 +6711,7 @@ def test_mcp_stdio_tool_get_mcp_client_with_env_and_kwargs(): async def test_mcp_streamable_http_tool_get_mcp_client_all_params(): """Test MCPStreamableHTTPTool.get_mcp_client() with all parameters.""" - from agent_framework._mcp import MCP_DEFAULT_SSE_READ_TIMEOUT, MCP_DEFAULT_TIMEOUT + from agent_framework._mcp import _MCP_DEFAULT_READ_TIMEOUT_SECONDS, MCP_DEFAULT_SSE_READ_TIMEOUT tool = MCPStreamableHTTPTool( name="test", @@ -6601,7 +6725,7 @@ async def test_mcp_streamable_http_tool_get_mcp_client_all_params(): http_client = tool._httpx_client assert http_client is not None assert http_client.follow_redirects is True - assert http_client.timeout.connect == MCP_DEFAULT_TIMEOUT + assert http_client.timeout.connect == _MCP_DEFAULT_READ_TIMEOUT_SECONDS assert http_client.timeout.read == MCP_DEFAULT_SSE_READ_TIMEOUT assert not http_client.event_hooks["request"] assert mock_http_client.call_args.kwargs["http_client"]._client is http_client @@ -6868,6 +6992,150 @@ async def mock_list_tools(params=None): assert [f.name for f in tool._functions] == ["tool_1", "tool_2", "tool_3", "tool_4"] +async def test_load_tools_rejects_catalog_exceeding_page_limit() -> None: + tool = MCPTool( # type: ignore[abstract] # ty: ignore[call-non-callable] + name="test_tool", + max_discovery_pages=2, + ) + mock_session = AsyncMock() + tool.session = mock_session + + async def list_tools(params: types.PaginatedRequestParams | None = None) -> types.ListToolsResult: + cursor = params.cursor if params is not None else None + if cursor is None: + return types.ListToolsResult( + tools=[types.Tool(name="first", input_schema={"type": "object", "properties": {}})], + next_cursor="second", + ) + if cursor == "second": + return types.ListToolsResult( + tools=[types.Tool(name="second", input_schema={"type": "object", "properties": {}})], + next_cursor="third", + ) + raise AssertionError(f"Unexpected tools/list cursor: {cursor!r}") + + mock_session.list_tools = AsyncMock(side_effect=list_tools) + + with pytest.raises(ToolExecutionException, match="max_discovery_pages=2"): + await tool.load_tools() + + assert mock_session.list_tools.await_count == 2 + assert tool.functions == [] + + +async def test_load_tools_accepts_catalog_completing_at_page_limit() -> None: + tool = MCPTool( # type: ignore[abstract] # ty: ignore[call-non-callable] + name="test_tool", + max_discovery_pages=2, + ) + mock_session = AsyncMock() + tool.session = mock_session + mock_session.list_tools = AsyncMock( + side_effect=[ + types.ListToolsResult( + tools=[types.Tool(name="first", input_schema={"type": "object", "properties": {}})], + next_cursor="second", + ), + types.ListToolsResult(tools=[types.Tool(name="second", input_schema={"type": "object", "properties": {}})]), + ] + ) + + await tool.load_tools() + + assert mock_session.list_tools.await_count == 2 + assert [function.name for function in tool.functions] == ["first", "second"] + + +async def test_load_tools_allows_unbounded_pagination_when_limit_is_none() -> None: + tool = MCPTool( # type: ignore[abstract] # ty: ignore[call-non-callable] + name="test_tool", + max_discovery_pages=None, + ) + mock_session = AsyncMock() + tool.session = mock_session + pages_served = 0 + + async def list_tools(params: types.PaginatedRequestParams | None = None) -> types.ListToolsResult: + nonlocal pages_served + if pages_served == 0: + assert params is None + else: + assert params is not None + assert params.cursor == str(pages_served) + + pages_served += 1 + next_cursor = str(pages_served) if pages_served < 101 else None + return types.ListToolsResult(tools=[], next_cursor=next_cursor) + + mock_session.list_tools = AsyncMock(side_effect=list_tools) + + await tool.load_tools() + + assert pages_served == 101 + assert mock_session.list_tools.await_count == 101 + + +@pytest.mark.parametrize("catalog_kind", ["tools", "prompts"]) +async def test_catalog_discovery_accepts_items_at_limit(catalog_kind: str) -> None: + tool = MCPTool( # type: ignore[abstract] # ty: ignore[call-non-callable] + name="test_tool", + max_discovery_items=2, + ) + mock_session = AsyncMock() + tool.session = mock_session + + if catalog_kind == "tools": + mock_session.list_tools = AsyncMock( + return_value=types.ListToolsResult( + tools=[ + types.Tool(name="first", input_schema={"type": "object", "properties": {}}), + types.Tool(name="second", input_schema={"type": "object", "properties": {}}), + ] + ) + ) + await tool.load_tools() + else: + mock_session.list_prompts = AsyncMock( + return_value=types.ListPromptsResult(prompts=[types.Prompt(name="first"), types.Prompt(name="second")]) + ) + await tool.load_prompts() + + assert [function.name for function in tool.functions] == ["first", "second"] + + +@pytest.mark.parametrize("catalog_kind", ["tools", "prompts"]) +async def test_catalog_discovery_rejects_items_exceeding_limit(catalog_kind: str) -> None: + tool = MCPTool( # type: ignore[abstract] # ty: ignore[call-non-callable] + name="test_tool", + max_discovery_items=2, + ) + mock_session = AsyncMock() + tool.session = mock_session + + if catalog_kind == "tools": + mock_session.list_tools = AsyncMock( + return_value=types.ListToolsResult( + tools=[ + types.Tool(name=name, input_schema={"type": "object", "properties": {}}) + for name in ("first", "second", "third") + ] + ) + ) + load_catalog = tool.load_tools + else: + mock_session.list_prompts = AsyncMock( + return_value=types.ListPromptsResult( + prompts=[types.Prompt(name=name) for name in ("first", "second", "third")] + ) + ) + load_catalog = tool.load_prompts + + with pytest.raises(ToolExecutionException, match="max_discovery_items=2"): + await load_catalog() + + assert tool.functions == [] + + async def test_load_tools_adds_properties_to_zero_arg_tool_schema(): """Test that load_tools normalizes inputSchema for zero-argument MCP tools. @@ -7021,6 +7289,88 @@ async def mock_list_prompts(params=None): assert [f.name for f in tool._functions] == ["prompt_1", "prompt_2", "prompt_3"] +async def test_load_prompts_rejects_catalog_exceeding_page_limit() -> None: + tool = MCPTool( # type: ignore[abstract] # ty: ignore[call-non-callable] + name="test_tool", + max_discovery_pages=2, + ) + mock_session = AsyncMock() + tool.session = mock_session + + async def list_prompts(params: types.PaginatedRequestParams | None = None) -> types.ListPromptsResult: + cursor = params.cursor if params is not None else None + if cursor is None: + return types.ListPromptsResult(prompts=[types.Prompt(name="first")], next_cursor="second") + if cursor == "second": + return types.ListPromptsResult(prompts=[types.Prompt(name="second")], next_cursor="third") + raise AssertionError(f"Unexpected prompts/list cursor: {cursor!r}") + + mock_session.list_prompts = AsyncMock(side_effect=list_prompts) + + with pytest.raises(ToolExecutionException, match="max_discovery_pages=2"): + await tool.load_prompts() + + assert mock_session.list_prompts.await_count == 2 + assert tool.functions == [] + + +async def test_load_prompts_accepts_catalog_completing_at_page_limit() -> None: + tool = MCPTool( # type: ignore[abstract] # ty: ignore[call-non-callable] + name="test_tool", + max_discovery_pages=2, + ) + mock_session = AsyncMock() + tool.session = mock_session + mock_session.list_prompts = AsyncMock( + side_effect=[ + types.ListPromptsResult(prompts=[types.Prompt(name="first")], next_cursor="second"), + types.ListPromptsResult(prompts=[types.Prompt(name="second")]), + ] + ) + + await tool.load_prompts() + + assert mock_session.list_prompts.await_count == 2 + assert [function.name for function in tool.functions] == ["first", "second"] + + +@pytest.mark.parametrize("catalog_kind", ["tools", "prompts"]) +async def test_catalog_discovery_follows_empty_string_cursor(catalog_kind: str) -> None: + tool = MCPTool(name="test_tool") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = AsyncMock() + tool.session = mock_session + + if catalog_kind == "tools": + + async def list_tools(params: types.PaginatedRequestParams | None = None) -> types.ListToolsResult: + if params is None: + return types.ListToolsResult( + tools=[types.Tool(name="first", input_schema={"type": "object", "properties": {}})], + next_cursor="", + ) + assert params.cursor == "" + return types.ListToolsResult( + tools=[types.Tool(name="second", input_schema={"type": "object", "properties": {}})] + ) + + mock_session.list_tools = AsyncMock(side_effect=list_tools) + await tool.load_tools() + assert mock_session.list_tools.await_count == 2 + else: + + async def list_prompts(params: types.PaginatedRequestParams | None = None) -> types.ListPromptsResult: + if params is None: + return types.ListPromptsResult(prompts=[types.Prompt(name="first")], next_cursor="") + assert params.cursor == "" + return types.ListPromptsResult(prompts=[types.Prompt(name="second")]) + + mock_session.list_prompts = AsyncMock(side_effect=list_prompts) + await tool.load_prompts() + assert mock_session.list_prompts.await_count == 2 + + assert [function.name for function in tool.functions] == ["first", "second"] + + async def test_load_tools_pagination_with_duplicates(): """Test that load_tools prevents duplicates across paginated results.""" from unittest.mock import AsyncMock, MagicMock @@ -8580,7 +8930,7 @@ def test_mcp_streamable_http_rejects_header_provider_with_supplied_client() -> N @pytest.mark.parametrize( ("option_name", "option_value"), [ - ("request_timeout", 30), + ("request_timeout", 31), ("terminate_on_close", False), ("http_client", Mock(spec=AsyncClient)), ("static_headers", {}), @@ -8609,7 +8959,7 @@ def test_mcp_streamable_http_lists_all_framework_owned_http_options_with_supplie MCPStreamableHTTPTool( name="test", mcp_client=Mock(), - request_timeout=30, + request_timeout=31, terminate_on_close=False, http_client=Mock(spec=AsyncClient), static_headers={}, @@ -8677,7 +9027,7 @@ def test_mcp_streamable_http_get_mcp_client_requires_framework_owned_url() -> No @pytest.mark.parametrize( ("option_name", "option_value"), [ - ("request_timeout", 30), + ("request_timeout", 31), ("args", []), ("env", {}), ("encoding", ""), @@ -8709,7 +9059,7 @@ def test_mcp_stdio_lists_all_framework_owned_options_with_supplied_client() -> N MCPStdioTool( name="test", mcp_client=Mock(), - request_timeout=30, + request_timeout=31, args=[], env={}, encoding="", @@ -9274,6 +9624,78 @@ async def reconnect() -> None: second_session.list_tools.assert_awaited_once() +async def test_load_tools_retries_continuation_page_after_closed_resource() -> None: + from anyio import ClosedResourceError + + tool = MCPTool(name="test_tool", load_tools=True) # type: ignore[abstract] # ty: ignore[call-non-callable] + tool._ping_available = False + + first_page = types.ListToolsResult( + tools=[types.Tool(name="first", input_schema={"type": "object", "properties": {}})], + next_cursor="second", + ) + + async def list_tools(params: types.PaginatedRequestParams | None = None) -> types.ListToolsResult: + if params is None: + return first_page + assert params.cursor == "second" + raise ClosedResourceError + + first_session = Mock() + first_session.list_tools = AsyncMock(side_effect=list_tools) + _set_framework_owned_session(tool, first_session) + + second_page = types.ListToolsResult( + tools=[types.Tool(name="second", input_schema={"type": "object", "properties": {}})] + ) + second_session = Mock() + second_session.list_tools = AsyncMock(return_value=second_page) + + async def reconnect() -> None: + tool.session = second_session + tool._supports_tools = True + + with patch.object(tool, "_reconnect_without_loading", AsyncMock(side_effect=reconnect)) as mock_reconnect: + await tool.load_tools() + + assert [function.name for function in tool.functions] == ["first", "second"] + assert first_session.list_tools.await_count == 2 + mock_reconnect.assert_awaited_once_with() + continuation_call = second_session.list_tools.await_args + assert continuation_call is not None + continuation_params = continuation_call.kwargs["params"] + assert continuation_params.cursor == "second" + + +async def test_load_tools_fails_after_closed_resource_retry_is_exhausted() -> None: + from anyio import ClosedResourceError + + tool = MCPTool(name="test_tool", load_tools=True) # type: ignore[abstract] # ty: ignore[call-non-callable] + tool._ping_available = False + + first_session = Mock() + first_session.list_tools = AsyncMock(side_effect=ClosedResourceError()) + _set_framework_owned_session(tool, first_session) + + second_session = Mock() + second_session.list_tools = AsyncMock(side_effect=ClosedResourceError()) + + async def reconnect() -> None: + tool.session = second_session + tool._supports_tools = True + + with ( + patch.object(tool, "_reconnect_without_loading", AsyncMock(side_effect=reconnect)) as mock_reconnect, + pytest.raises(ToolExecutionException, match="Failed to load tools - connection lost"), + ): + await tool.load_tools() + + first_session.list_tools.assert_awaited_once() + mock_reconnect.assert_awaited_once_with() + second_session.list_tools.assert_awaited_once() + assert tool.functions == [] + + async def test_load_prompts_reconnects_on_closed_resource_when_ping_is_unavailable() -> None: from anyio import ClosedResourceError @@ -9303,6 +9725,72 @@ async def reconnect() -> None: second_session.list_prompts.assert_awaited_once() +async def test_load_prompts_retries_continuation_page_after_closed_resource() -> None: + from anyio import ClosedResourceError + + tool = MCPTool(name="test_tool", load_prompts=True) # type: ignore[abstract] # ty: ignore[call-non-callable] + tool._ping_available = False + + first_page = types.ListPromptsResult(prompts=[types.Prompt(name="first")], next_cursor="second") + + async def list_prompts(params: types.PaginatedRequestParams | None = None) -> types.ListPromptsResult: + if params is None: + return first_page + assert params.cursor == "second" + raise ClosedResourceError + + first_session = Mock() + first_session.list_prompts = AsyncMock(side_effect=list_prompts) + _set_framework_owned_session(tool, first_session) + + second_session = Mock() + second_session.list_prompts = AsyncMock(return_value=types.ListPromptsResult(prompts=[types.Prompt(name="second")])) + + async def reconnect() -> None: + tool.session = second_session + tool._supports_prompts = True + + with patch.object(tool, "_reconnect_without_loading", AsyncMock(side_effect=reconnect)) as mock_reconnect: + await tool.load_prompts() + + assert [function.name for function in tool.functions] == ["first", "second"] + assert first_session.list_prompts.await_count == 2 + mock_reconnect.assert_awaited_once_with() + continuation_call = second_session.list_prompts.await_args + assert continuation_call is not None + continuation_params = continuation_call.kwargs["params"] + assert continuation_params.cursor == "second" + + +async def test_load_prompts_fails_after_closed_resource_retry_is_exhausted() -> None: + from anyio import ClosedResourceError + + tool = MCPTool(name="test_tool", load_prompts=True) # type: ignore[abstract] # ty: ignore[call-non-callable] + tool._ping_available = False + + first_session = Mock() + first_session.list_prompts = AsyncMock(side_effect=ClosedResourceError()) + _set_framework_owned_session(tool, first_session) + + second_session = Mock() + second_session.list_prompts = AsyncMock(side_effect=ClosedResourceError()) + + async def reconnect() -> None: + tool.session = second_session + tool._supports_prompts = True + + with ( + patch.object(tool, "_reconnect_without_loading", AsyncMock(side_effect=reconnect)) as mock_reconnect, + pytest.raises(ToolExecutionException, match="Failed to load prompts - connection lost"), + ): + await tool.load_prompts() + + first_session.list_prompts.assert_awaited_once() + mock_reconnect.assert_awaited_once_with() + second_session.list_prompts.assert_awaited_once() + assert tool.functions == [] + + async def test_mcp_tool_filters_framework_kwargs(): """Test that call_tool filters out framework-specific kwargs before calling MCP session. @@ -9918,7 +10406,11 @@ def get_mcp_client(self): # pyrefly: ignore[bad-override] async def test_mcp_streamable_http_tool_header_provider_with_httpx_event_hook(): """Test that the httpx event hook injects headers from the contextvar.""" - from agent_framework._mcp import MCP_DEFAULT_SSE_READ_TIMEOUT, MCP_DEFAULT_TIMEOUT, _mcp_call_headers + from agent_framework._mcp import ( + _MCP_DEFAULT_READ_TIMEOUT_SECONDS, + MCP_DEFAULT_SSE_READ_TIMEOUT, + _mcp_call_headers, + ) tool = MCPStreamableHTTPTool( name="test", @@ -9934,7 +10426,7 @@ async def test_mcp_streamable_http_tool_header_provider_with_httpx_event_hook(): # The tool should have created an httpx client with the event hook assert tool._httpx_client is not None assert tool._httpx_client.follow_redirects is True - assert tool._httpx_client.timeout.connect == MCP_DEFAULT_TIMEOUT + assert tool._httpx_client.timeout.connect == _MCP_DEFAULT_READ_TIMEOUT_SECONDS assert tool._httpx_client.timeout.read == MCP_DEFAULT_SSE_READ_TIMEOUT hooks = tool._httpx_client.event_hooks.get("request", []) assert len(hooks) == 1, "Expected one request event hook" diff --git a/python/packages/core/tests/test_security.py b/python/packages/core/tests/test_security.py index 46de415b2e9..32a128775ed 100644 --- a/python/packages/core/tests/test_security.py +++ b/python/packages/core/tests/test_security.py @@ -10,7 +10,7 @@ from datetime import datetime, timedelta, timezone from types import MappingProxyType, SimpleNamespace from typing import Annotated, Any, cast -from unittest.mock import AsyncMock, call +from unittest.mock import AsyncMock import pytest from pydantic import AfterValidator, BaseModel, field_validator @@ -6109,6 +6109,18 @@ def test_user_identity_requires_matching_principals( class TestSecureMCPToolProxyURLMode: """Tests for origin-scoped headers in the proxy's URL mode.""" + def test_forwards_discovery_limits(self) -> None: + from agent_framework.security import SecureMCPToolProxy + + proxy = SecureMCPToolProxy( + url="https://mcp.example/mcp", + max_discovery_pages=12, + max_discovery_items=345, + ) + + assert proxy.mcp_tool.max_discovery_pages == 12 + assert proxy.mcp_tool.max_discovery_items == 345 + async def test_static_headers_do_not_serialize_tool_calls(self) -> None: from unittest.mock import patch @@ -6348,12 +6360,7 @@ async def fake_call(**kwargs: Any) -> list[Content]: mcp_tool.is_connected = True mock_session = AsyncMock() mcp_tool.session = mock_session - mock_session.list_tools = AsyncMock( # type: ignore[method-assign] - return_value=SimpleNamespace( - tools=[SimpleNamespace(name="remote_tool", annotations=annotations)], - next_cursor=None, - ) - ) + mcp_tool._tool_annotations_by_name = {"remote_tool": annotations} mcp_tool.functions.append(function) return mcp_tool, function @@ -6786,22 +6793,17 @@ async def test_wrap_mcp_function_reads_refreshed_local_policy_at_invocation(self server_meta=server_meta, confidentiality=ConfidentialityLabel.PUBLIC, ) - mcp_tool.session.list_tools.side_effect = [ - SimpleNamespace( - tools=[SimpleNamespace(name="remote_tool", annotations=trusted_annotations)], next_cursor=None - ), - SimpleNamespace( - tools=[SimpleNamespace(name="remote_tool", annotations=untrusted_annotations)], next_cursor=None - ), - ] + mcp_tool.load_tools = AsyncMock() # type: ignore[method-assign] proxy = SecureMCPToolProxy(mcp_tool, default_integrity=IntegrityLabel.TRUSTED) await proxy.refresh_labels() props = function.additional_properties assert props is not None assert props["source_integrity"] == "trusted" + mcp_tool._tool_annotations_by_name["remote_tool"] = untrusted_annotations await proxy.refresh_labels() assert props["source_integrity"] == "untrusted" + assert mcp_tool.load_tools.await_count == 2 # type: ignore[union-attr] assert function.func is not None result = await function.func() @@ -6918,7 +6920,7 @@ async def test_apply_mcp_security_labels_configures_result_authority(self, trust ) assert result[0].additional_properties["security_label"] == expected_label - async def test_apply_mcp_security_labels_uses_high_level_client_connection(self) -> None: + async def test_apply_mcp_security_labels_uses_loaded_annotation_snapshot(self) -> None: from agent_framework._mcp import _ClientMCPConnection from agent_framework.security import apply_mcp_security_labels @@ -6927,21 +6929,11 @@ async def test_apply_mcp_security_labels_uses_high_level_client_connection(self) sdk_client = AsyncMock() mock_session = AsyncMock() sdk_client.session = mock_session - sdk_client.list_tools.side_effect = [ - SimpleNamespace( - tools=[SimpleNamespace(name="remote_tool", annotations=annotations)], - next_cursor="next-page", - ), - SimpleNamespace(tools=[], next_cursor=None), - ] mcp_tool._connection = _ClientMCPConnection(sdk_client, is_framework_owned=True) await apply_mcp_security_labels(mcp_tool) - assert sdk_client.list_tools.await_args_list == [ - call(cursor=None), - call(cursor="next-page"), - ] + sdk_client.list_tools.assert_not_awaited() mock_session.list_tools.assert_not_awaited() async def test_framework_stamped_mcp_label_remains_authoritative_through_tracking(self) -> None: @@ -6999,6 +6991,7 @@ async def test_secure_mcp_proxy_configures_result_authority(self, trust_server_i annotations = SimpleNamespace(read_only_hint=True, open_world_hint=False) server_meta = {"ifc": {"integrity": "trusted", "confidentiality": "public"}} mcp_tool, function = _make_connected_mcp_tool_for_ifc(annotations=annotations, server_meta=server_meta) + mcp_tool.load_tools = AsyncMock() # type: ignore[method-assign] proxy = ( SecureMCPToolProxy(mcp_tool, trust_server_ifc=True) if trust_server_ifc else SecureMCPToolProxy(mcp_tool) ) @@ -7020,6 +7013,21 @@ async def test_secure_mcp_proxy_configures_result_authority(self, trust_server_i ) assert result[0].additional_properties["security_label"] == expected_label + async def test_secure_mcp_proxy_refresh_respects_disabled_tool_loading(self) -> None: + from agent_framework.security import SecureMCPToolProxy + + annotations = SimpleNamespace(read_only_hint=True, open_world_hint=False) + mcp_tool, function = _make_connected_mcp_tool_for_ifc(annotations=annotations, server_meta={}) + mcp_tool.load_tools_flag = False + mcp_tool.load_tools = AsyncMock() # type: ignore[method-assign] + proxy = SecureMCPToolProxy(mcp_tool) + + await proxy.refresh_labels() + + mcp_tool.load_tools.assert_not_awaited() # type: ignore[union-attr] + assert function.additional_properties is not None + assert function.additional_properties["source_integrity"] == "untrusted" + async def test_secure_mcp_proxy_labels_notification_reload_before_publication(self): from mcp import types as mcp_types @@ -7227,6 +7235,7 @@ async def test_secure_mcp_proxy_refresh_failure_only_removes_new_binding( mcp_tool = _make_connected_mcp_discovery_tool() proxy = SecureMCPToolProxy(mcp_tool) + mcp_tool.load_tools = AsyncMock() # type: ignore[method-assign] if already_bound: mcp_tool._function_load_callback = proxy._function_load_callback proxy._apply_labels = AsyncMock(side_effect=failure_type("label refresh failed")) # type: ignore[method-assign] diff --git a/python/packages/declarative/AGENTS.md b/python/packages/declarative/AGENTS.md index 059c1c605d7..1c725aff316 100644 --- a/python/packages/declarative/AGENTS.md +++ b/python/packages/declarative/AGENTS.md @@ -27,6 +27,8 @@ series because response caching and default-header integration use its internals With a provider, every invocation (including `tools/list`) gets a fresh tool/session, even if the provider returns `None` or a shared HTTP client. Invocation cleanup closes the session and any internally owned fallback client, never caller-owned HTTP clients. +The handler forwards its configurable `max_discovery_pages` and `max_discovery_items` +limits to every internally created `MCPStreamableHTTPTool`. Shutdown waits for active provider-backed invocations to clean up. Calling `aclose()` from an active invocation's context (including inherited child tasks and cleanup) raises `RuntimeError` before changing handler state; shutdown must run outside that diff --git a/python/packages/declarative/agent_framework_declarative/_workflows/_mcp_handler.py b/python/packages/declarative/agent_framework_declarative/_workflows/_mcp_handler.py index 3dee698de35..f7ec768a6a9 100644 --- a/python/packages/declarative/agent_framework_declarative/_workflows/_mcp_handler.py +++ b/python/packages/declarative/agent_framework_declarative/_workflows/_mcp_handler.py @@ -202,6 +202,10 @@ class DefaultMCPToolHandler: When exceeded, the least-recently-used entry is evicted and its owned client closed. Defaults to ``32``. Does not enable session caching when a provider is configured. + max_discovery_pages: Maximum pages accepted independently for each tool catalog fetch. + Defaults to 100; ``None`` disables the limit. + max_discovery_items: Maximum tools accepted across each tool catalog fetch. + Defaults to 1,000; ``None`` disables the limit. """ LIST_TOOLS_TOOL_NAME: ClassVar[str] = "tools/list" @@ -224,11 +228,19 @@ def __init__( *, client_provider: ClientProvider | None = None, cache_max_size: int = _DEFAULT_CACHE_MAX_SIZE, + max_discovery_pages: int | None = 100, + max_discovery_items: int | None = 1_000, ) -> None: if cache_max_size <= 0: raise ValueError(f"cache_max_size must be positive, got {cache_max_size}") + if max_discovery_pages is not None and max_discovery_pages <= 0: + raise ValueError("max_discovery_pages must be positive or None.") + if max_discovery_items is not None and max_discovery_items <= 0: + raise ValueError("max_discovery_items must be positive or None.") self._client_provider = client_provider self._cache_max_size = cache_max_size + self._max_discovery_pages = max_discovery_pages + self._max_discovery_items = max_discovery_items self._cache: OrderedDict[tuple[str, str, str, str], _CacheEntry] = OrderedDict() # Outer lock guards the cache + in-flight-future map only — never # held across network I/O. @@ -603,6 +615,8 @@ def _header_provider(_kwargs: dict[str, Any]) -> dict[str, str]: load_prompts=False, http_client=provided_client, header_provider=_header_provider if captured_headers else None, + max_discovery_pages=self._max_discovery_pages, + max_discovery_items=self._max_discovery_items, ) try: await tool.connect() diff --git a/python/packages/declarative/tests/test_default_mcp_tool_handler.py b/python/packages/declarative/tests/test_default_mcp_tool_handler.py index 1c5f4476749..03a1f880465 100644 --- a/python/packages/declarative/tests/test_default_mcp_tool_handler.py +++ b/python/packages/declarative/tests/test_default_mcp_tool_handler.py @@ -828,11 +828,26 @@ def test_invalid_cache_size_raises(self) -> None: with pytest.raises(ValueError): DefaultMCPToolHandler(cache_max_size=-3) + def test_invalid_discovery_limit_raises(self) -> None: + with pytest.raises(ValueError, match="max_discovery_pages must be positive or None"): + DefaultMCPToolHandler(max_discovery_pages=0) + with pytest.raises(ValueError, match="max_discovery_items must be positive or None"): + DefaultMCPToolHandler(max_discovery_items=-1) + # ---------- Tool kwargs ---------------------------------------------------- class TestToolKwargs: + @pytest.mark.asyncio + async def test_discovery_limits_passed_to_tool(self) -> None: + handler = DefaultMCPToolHandler(max_discovery_pages=12, max_discovery_items=345) + with _patch_tool(): + await handler.invoke_tool(_invocation()) + + assert FakeTool.instances[0].kwargs["max_discovery_pages"] == 12 + assert FakeTool.instances[0].kwargs["max_discovery_items"] == 345 + @pytest.mark.asyncio async def test_load_prompts_false_passed_to_tool(self) -> None: handler = DefaultMCPToolHandler()