diff --git a/src/google/adk/tools/mcp_tool/mcp_toolset.py b/src/google/adk/tools/mcp_tool/mcp_toolset.py index 8459d05e1ec..03fab702d14 100644 --- a/src/google/adk/tools/mcp_tool/mcp_toolset.py +++ b/src/google/adk/tools/mcp_tool/mcp_toolset.py @@ -16,12 +16,14 @@ import asyncio import collections +import contextlib import dataclasses import inspect import logging import sys import time from typing import Any +from typing import AsyncGenerator from typing import Awaitable from typing import Callable from typing import Dict @@ -49,6 +51,7 @@ from ...dependencies._mcp import SamplingFnT from ...dependencies._mcp import StdioServerParameters from ...dependencies._mcp import Tool as McpBaseTool +from ...dependencies._mcp import types as mcp_types from ...utils.env_utils import is_env_enabled from ..base_tool import BaseTool from ..base_toolset import BaseToolset @@ -66,6 +69,7 @@ # MCPTool stays imported so existing mcp_toolset.MCPTool callers still resolve. from .mcp_tool import _dump_mcp_model from .mcp_tool import _merge_auth_and_provider_headers +from .mcp_tool import _read_field from .mcp_tool import _RESERVED_TOOL_NAMES from .mcp_tool import MCPTool # pylint: disable=unused-import # noqa: F401 from .mcp_tool import McpTool @@ -118,6 +122,57 @@ class _CachedToolList: expires_at: float +# Hard ceiling on resources/list pages, so a server that keeps returning new +# cursors cannot keep a listing going forever. +_MAX_RESOURCE_LIST_PAGES = 100 + + +async def _iter_resources( + session: _ClientSession, +) -> AsyncGenerator[mcp_types.Resource, None]: + """Yields the resources of each resources/list page, a page at a time. + + The listing ends at the first page without `nextCursor`. Any cursor the + server sends, `""` or one it sent before included, is sent back as is: the + specification treats cursors as opaque. + """ + result: ListResourcesResult = await session.list_resources() + pages = 1 + while True: + for resource in result.resources: + yield resource + cursor = _read_field(result, "nextCursor", "next_cursor") + if cursor is None: + return + if pages == _MAX_RESOURCE_LIST_PAGES: + raise ValueError( + "MCP server paginated resources/list past" + f" {_MAX_RESOURCE_LIST_PAGES} pages." + ) + result = await session.list_resources( + params=mcp_types.PaginatedRequestParams(cursor=cursor) + ) + pages += 1 + + +async def _list_all_resources( + session: _ClientSession, +) -> list[mcp_types.Resource]: + """Returns the resources from every resources/list page.""" + return [resource async for resource in _iter_resources(session)] + + +async def _find_resource( + session: _ClientSession, name: str +) -> Optional[mcp_types.Resource]: + """Returns the first resource named `name`, reading no page past it.""" + async with contextlib.aclosing(_iter_resources(session)) as resources: + async for resource in resources: + if resource.name == name: + return resource + return None + + class McpToolset(BaseToolset): """Connects to a MCP Server, and retrieves MCP Tools into ADK Tools. @@ -601,29 +656,28 @@ async def list_resources( self, readonly_context: Optional[ReadonlyContext] = None ) -> list[str]: """Returns a list of resource names available on the MCP server.""" - result: ListResourcesResult = await self._execute_with_session( - lambda session: session.list_resources(), + resources = await self._execute_with_session( + _list_all_resources, "Failed to list resources from MCP server", readonly_context, ) - return [resource.name for resource in result.resources] + return [resource.name for resource in resources] async def get_resource_info( self, name: str, readonly_context: Optional[ReadonlyContext] = None ) -> dict[str, Any]: """Returns metadata about a specific resource (name, MIME type, etc.).""" - result: ListResourcesResult = await self._execute_with_session( - lambda session: session.list_resources(), + resource = await self._execute_with_session( + lambda session: _find_resource(session, name), "Failed to list resources from MCP server", readonly_context, ) - for resource in result.resources: - if resource.name == name: - # `Resource` carries `mimeType`, which 2.x renames. A plain dump would - # hand the caller a different key on each major, the way the tool - # result did. - return _dump_mcp_model(resource) - raise ValueError(f"Resource with name '{name}' not found.") + if resource is None: + raise ValueError(f"Resource with name '{name}' not found.") + # `Resource` carries `mimeType`, which 2.x renames. A plain dump would + # hand the caller a different key on each major, the way the tool result + # did. + return _dump_mcp_model(resource) async def close(self) -> None: """Performs cleanup and releases resources held by the toolset. diff --git a/tests/unittests/tools/mcp_tool/test_mcp_toolset.py b/tests/unittests/tools/mcp_tool/test_mcp_toolset.py index 5d61cddf632..7a85ce5b24c 100644 --- a/tests/unittests/tools/mcp_tool/test_mcp_toolset.py +++ b/tests/unittests/tools/mcp_tool/test_mcp_toolset.py @@ -61,6 +61,7 @@ from mcp.shared.memory import create_client_server_memory_streams from mcp.types import BlobResourceContents from mcp.types import ListResourcesResult +from mcp.types import PaginatedRequestParams from mcp.types import ReadResourceResult from mcp.types import Resource from mcp.types import TextResourceContents @@ -89,6 +90,18 @@ def __init__(self, tools): self.tools = tools +def _list_resources_page( + name: str, *, next_cursor: str | None = None +) -> ListResourcesResult: + """Returns a resources/list page holding one text resource.""" + return ListResourcesResult( + resources=[ + Resource(name=name, mimeType="text/plain", uri=f"file:///{name}") + ], + nextCursor=next_cursor, + ) + + class TestMcpToolset: """Test suite for McpToolset class.""" @@ -888,7 +901,101 @@ async def test_list_resources(self): result = await toolset.list_resources() assert result == ["file1.txt", "data.json"] - self.mock_session.list_resources.assert_called_once() + self.mock_session.list_resources.assert_called_once_with() + + @pytest.mark.parametrize("next_cursor", ["page-2", ""]) + @pytest.mark.asyncio + async def test_list_resources_reads_every_page( + self, next_cursor: str + ) -> None: + """Resources on every resources/list page are listed, on one session.""" + self.mock_session.list_resources = AsyncMock( + side_effect=[ + _list_resources_page("file1.txt", next_cursor=next_cursor), + _list_resources_page("file2.txt"), + ] + ) + + toolset = McpToolset(connection_params=self.mock_stdio_params) + toolset._mcp_session_manager = self.mock_session_manager + + result = await toolset.list_resources() + + assert result == ["file1.txt", "file2.txt"] + second_call = self.mock_session.list_resources.await_args_list[1] + assert second_call.kwargs["params"].cursor == next_cursor + self.mock_session_manager.create_session.assert_awaited_once() + + @pytest.mark.asyncio + async def test_list_resources_follows_a_repeated_cursor(self) -> None: + """A server that sends the same cursor on each page has every page read.""" + self.mock_session.list_resources = AsyncMock( + side_effect=[ + _list_resources_page("file1.txt", next_cursor=""), + _list_resources_page("file2.txt", next_cursor=""), + _list_resources_page("file3.txt"), + ] + ) + + toolset = McpToolset(connection_params=self.mock_stdio_params) + toolset._mcp_session_manager = self.mock_session_manager + + result = await toolset.list_resources() + + assert result == ["file1.txt", "file2.txt", "file3.txt"] + later_calls = self.mock_session.list_resources.await_args_list[1:] + assert [call.kwargs["params"].cursor for call in later_calls] == ["", ""] + + @pytest.mark.asyncio + async def test_list_resources_on_a_server_whose_last_cursor_is_empty( + self, + ) -> None: + """A server that sends `""` on its last page hits the page limit. + + The server reads `int(cursor or 0)`, so the `""` cursor brings back the + first page. Lookups that end on an earlier page still succeed. + """ + + async def list_resources( + params: PaginatedRequestParams | None = None, + ) -> ListResourcesResult: + page = int(params.cursor or 0) if params else 0 + return _list_resources_page( + f"file{page + 1}.txt", next_cursor="" if page == 1 else str(page + 1) + ) + + self.mock_session.list_resources = AsyncMock(side_effect=list_resources) + + toolset = McpToolset(connection_params=self.mock_stdio_params) + toolset._mcp_session_manager = self.mock_session_manager + + with pytest.raises(ConnectionError, match="past 100 pages"): + await toolset.list_resources() + assert self.mock_session.list_resources.await_count == 100 + + self.mock_session.list_resources.reset_mock() + result = await toolset.get_resource_info("file2.txt") + assert result["name"] == "file2.txt" + assert self.mock_session.list_resources.await_count == 2 + + @pytest.mark.asyncio + async def test_list_resources_fails_past_the_page_limit(self) -> None: + """A server that keeps paginating gets an error after 100 pages.""" + + async def list_resources( + params: PaginatedRequestParams | None = None, + ) -> ListResourcesResult: + page = 1 if params is None else int(params.cursor) + return _list_resources_page(f"file{page}.txt", next_cursor=str(page + 1)) + + self.mock_session.list_resources = AsyncMock(side_effect=list_resources) + + toolset = McpToolset(connection_params=self.mock_stdio_params) + toolset._mcp_session_manager = self.mock_session_manager + + with pytest.raises(ConnectionError, match="past 100 pages"): + await toolset.list_resources() + assert self.mock_session.list_resources.await_count == 100 @pytest.mark.asyncio async def test_get_resource_info_success(self): @@ -951,6 +1058,54 @@ async def test_get_resource_info_keeps_the_1x_key_names(self): assert result["meta"] == {"trace": "t"} assert "_meta" not in result + @pytest.mark.asyncio + async def test_get_resource_info_finds_a_resource_on_a_later_page( + self, + ) -> None: + """A resource on a later resources/list page is found.""" + self.mock_session.list_resources = AsyncMock( + side_effect=[ + _list_resources_page("file1.txt", next_cursor="page-2"), + _list_resources_page("file2.txt"), + ] + ) + + toolset = McpToolset(connection_params=self.mock_stdio_params) + toolset._mcp_session_manager = self.mock_session_manager + + result = await toolset.get_resource_info("file2.txt") + + assert result == { + "name": "file2.txt", + "mimeType": "text/plain", + "uri": "file:///file2.txt", + } + + @pytest.mark.parametrize( + ("name", "pages_read"), [("file1.txt", 1), ("file2.txt", 2)] + ) + @pytest.mark.asyncio + async def test_get_resource_info_reads_no_page_past_the_match( + self, name: str, pages_read: int + ) -> None: + """A lookup stops at the page that lists the name, below the page limit.""" + + async def list_resources( + params: PaginatedRequestParams | None = None, + ) -> ListResourcesResult: + page = 1 if params is None else int(params.cursor) + return _list_resources_page(f"file{page}.txt", next_cursor=str(page + 1)) + + self.mock_session.list_resources = AsyncMock(side_effect=list_resources) + + toolset = McpToolset(connection_params=self.mock_stdio_params) + toolset._mcp_session_manager = self.mock_session_manager + + result = await toolset.get_resource_info(name) + + assert result["name"] == name + assert self.mock_session.list_resources.await_count == pages_read + @pytest.mark.asyncio async def test_get_resource_info_not_found(self): """Test getting resource info for a non-existent resource."""