Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
fix(mcp): fence discovery responses after tool list invalidation (#3889)
qkycir17517d3c56e5
diff --git a/src/agentscope/mcp/_mcp_client.py b/src/agentscope/mcp/_mcp_client.pyindex 849c5304c..f57a0f743 100644--- a/src/agentscope/mcp/_mcp_client.py+++ b/src/agentscope/mcp/_mcp_client.py@@ -137,6 +137,11 @@ class MCPClient(BaseModel):_close_requested: asyncio.Event | None = PrivateAttr(default=None)_is_connected: bool = PrivateAttr(default=False)_cached_tools: list[mcp.types.Tool] | None = PrivateAttr(default=None)+ _tool_list_generation: int = PrivateAttr(default=0)+ _discovery_task: asyncio.Task[list[mcp.types.Tool]] | None = PrivateAttr(+ default=None,+ )+ _discovery_waiters: int = PrivateAttr(default=0)_http_client: httpx2.AsyncClient | None = PrivateAttr(default=None)_static_headers: httpx2.Headers | None = PrivateAttr(default=None)_runtime_headers: dict[str, str] = PrivateAttr(default_factory=dict)@@ -239,6 +244,7 @@ class MCPClient(BaseModel):from a connection that no longer matches them."""if isinstance(message, mcp.types.ToolListChangedNotification):+ self._tool_list_generation += 1self._cached_tools = Nonedef _create_http_client(@@ -498,20 +504,10 @@ class MCPClient(BaseModel):Raw MCP tool descriptors after filtering.Raises:- RuntimeError: If not connected (for stateful connections).+ RuntimeError: If not connected (for stateful connections), or+ if tool-list notifications invalidate both discovery attempts."""- if not self.is_stateful:- # Stateless: create a temporary auto-negotiating client.- async with self._get_client_gen() as client:- res = await client.list_tools(cache_mode="refresh")- self._cached_tools = res.tools- else:- # Stateful: use the existing high-level client.- self._validate_connection()- res = await self._client.list_tools(cache_mode="refresh")- self._cached_tools = res.tools-- available_tools: list = self._cached_tools+ available_tools = await self._discover_tools()if self.enable_tools is not None:available_tools = [tool@@ -524,6 +520,51 @@ class MCPClient(BaseModel):]return available_tools+ async def _discover_tools(self) -> list[mcp.types.Tool]:+ """Share stateless discovery without sharing caller cancellation."""+ if self.is_stateful:+ return await self._fetch_tools()++ task = self._discovery_task+ if task is None or task.done():+ task = asyncio.create_task(self._fetch_tools())+ self._discovery_task = task+ self._discovery_waiters = 0+ self._discovery_waiters += 1+ try:+ return await asyncio.shield(task)+ finally:+ if self._discovery_task is task:+ self._discovery_waiters -= 1+ if self._discovery_waiters == 0:+ self._discovery_task = None+ if not task.done():+ # No callers remain to use the temporary connection.+ task.cancel()+ await asyncio.gather(task, return_exceptions=True)+ elif not task.cancelled():+ task.exception()++ async def _fetch_tools(self) -> list[mcp.types.Tool]:+ """Fetch and cache a catalog that survives the invalidation fence."""+ # Retry once if a notification invalidates the in-flight tool list.+ for _ in range(2):+ if not self.is_stateful:+ async with self._get_client_gen() as client:+ generation = self._tool_list_generation+ res = await client.list_tools(cache_mode="refresh")+ else:+ self._validate_connection()+ generation = self._tool_list_generation+ res = await self._client.list_tools(cache_mode="refresh")+ if generation == self._tool_list_generation:+ self._cached_tools = res.tools+ return res.tools+ raise RuntimeError(+ f"MCP {self.name!r} tool list changed during discovery; "+ "retry the lookup.",+ )+async def list_tools(self) -> list[ToolBase]:"""List available tools from the MCP server as wrapped:class:`ToolBase` instances. If `enable_tools` and `disable_tools`@@ -565,10 +606,11 @@ class MCPClient(BaseModel):# Avoid circular import by importing herefrom ..tool import MCPTool- if self._cached_tools is None:- await self.list_raw_tools()+ tools = self._cached_tools+ if tools is None:+ tools = await self._discover_tools()target_tool = next(- (tool for tool in self._cached_tools or [] if tool.name == name),+ (tool for tool in tools if tool.name == name),None,)if target_tool is None:diff --git a/tests/mcp_client_list_changed_test.py b/tests/mcp_client_list_changed_test.pyindex 0f68478d7..02ee03c60 100644--- a/tests/mcp_client_list_changed_test.py+++ b/tests/mcp_client_list_changed_test.py@@ -1,6 +1,7 @@# -*- coding: utf-8 -*-"""Tests for tool-cache invalidation on tools/list_changed notifications."""# pylint: disable=protected-access+import asynciofrom types import TracebackTypefrom typing import Anyfrom unittest.async_case import IsolatedAsyncioTestCase@@ -8,7 +9,7 @@ from unittest.mock import patchimport mcp.types-from agentscope.mcp import MCPClient, StdioMCPConfig+from agentscope.mcp import HttpMCPConfig, MCPClient, StdioMCPConfigclass _FakeTransport:@@ -144,3 +145,357 @@ class MCPClientListChangedTest(IsolatedAsyncioTestCase):("mcp__list_changed__echo", 1),)self.assertIs(client._cached_tools, cached)+++class MCPClientConcurrentDiscoveryTest(IsolatedAsyncioTestCase):+ """Coordinate concurrent discovery and connection cleanup with events."""++ def setUp(self) -> None:+ self.started = asyncio.Event()+ self.release = asyncio.Event()+ self.connections: list[_FakeClient] = []+ self.closed: list[_FakeClient] = []+ self.closing = asyncio.Event()+ self.close_gate: asyncio.Event | None = None+ self.notify_on_enter = True+ self.error: Exception | None = None+ self.catalog = [+ mcp.types.Tool(name=name, inputSchema={"type": "object"})+ for name in ("echo", "hidden")+ ]+ case = self++ class ControlledClient(_FakeClient):+ """Hold a snapshot until the test releases its response."""++ async def __aenter__(self) -> "ControlledClient":+ case.connections.append(self)+ if case.notify_on_enter:+ await self.message_handler(+ mcp.types.ToolListChangedNotification(+ method="notifications/tools/list_changed",+ ),+ )+ return self++ async def list_tools(+ self,+ **_kwargs: Any,+ ) -> mcp.types.ListToolsResult:+ snapshot = mcp.types.ListToolsResult(tools=case.catalog)+ case.started.set()+ await case.release.wait()+ if case.error is not None:+ raise case.error+ return snapshot++ async def __aexit__(self, *args: Any) -> bool:+ if case.close_gate is not None:+ case.closing.set()+ await case.close_gate.wait()+ case.closed.append(self)+ return False++ self.enterContext(+ patch("agentscope.mcp._mcp_client.SDKClient", ControlledClient),+ )+ self.client = MCPClient(+ name="concurrent",+ is_stateful=False,+ mcp_config=HttpMCPConfig(url="http://mcp.invalid/mcp"),+ )++ async def _start(+ self,+ entry: str = "list",+ name: str = "echo",+ ) -> asyncio.Task[Any]:+ """Wait until the caller has joined discovery before returning."""+ joined = asyncio.Event()++ async def lookup() -> Any:+ joined.set()+ if entry == "get":+ return await self.client.get_tool(name)+ return await self.client.list_raw_tools()++ task = asyncio.create_task(lookup())+ self.addAsyncCleanup(self._cancel, task)+ await joined.wait()+ return task++ async def _cancel(self, task: asyncio.Task[Any]) -> None:+ """Drain caller tasks even when an assertion fails."""+ if self.close_gate is not None:+ self.close_gate.set()+ task.cancel()+ await asyncio.gather(task, return_exceptions=True)++ async def test_concurrent_discovery_shares_one_connection(self) -> None:+ """Connection notifications must not multiply discovery attempts."""+ for notify in (False, True):+ for callers in (2, 8):+ with self.subTest(notify=notify, callers=callers):+ self.notify_on_enter = notify+ self.started.clear()+ self.release.clear()+ self.connections.clear()+ self.closed.clear()+ tasks = [await self._start() for _ in range(callers)]+ await self.started.wait()+ self.release.set()+ results = await asyncio.gather(*tasks)+ self.assertEqual(results, [self.catalog] * callers)+ self.assertEqual(len(self.connections), 1)+ self.assertEqual(self.closed, self.connections)+ self.assertIsNone(self.client._discovery_task)++ async def test_get_and_list_share_unfiltered_discovery(self) -> None:+ """Filtering must not hide tools from concurrent direct lookups."""+ self.client.enable_tools = ["echo"]+ listed = await self._start()+ hidden = await self._start("get", "hidden")+ await self.started.wait()+ self.release.set()+ raw, tool = await asyncio.gather(listed, hidden)+ self.assertEqual(raw, self.catalog[:1])+ self.assertEqual(tool.name, "mcp__concurrent__hidden")+ self.assertEqual(self.client._cached_tools, self.catalog)+ self.assertEqual(len(self.connections), 1)++ async def test_connection_notifications_do_not_cause_ping_pong(+ self,+ ) -> None:+ """Sibling connection notifications must not exhaust both attempts."""+ entered = [asyncio.Event() for _ in range(4)]+ case = self++ class PingPongClient(_FakeClient):+ """Release each old response after the next connection opens."""++ index: int = 0++ async def __aenter__(self) -> "PingPongClient":+ self.index = len(case.connections)+ case.connections.append(self)+ if self.index:+ await self.message_handler(+ mcp.types.ToolListChangedNotification(+ method="notifications/tools/list_changed",+ ),+ )+ entered[self.index].set()+ return self++ async def list_tools(+ self,+ **_kwargs: Any,+ ) -> mcp.types.ListToolsResult:+ if self.index == 0:+ await case.release.wait()+ elif self.index < 3:+ await entered[self.index + 1].wait()+ return mcp.types.ListToolsResult(tools=case.catalog)++ with patch("agentscope.mcp._mcp_client.SDKClient", PingPongClient):+ first = await self._start()+ await entered[0].wait()+ second = await self._start()+ self.release.set()+ results = await asyncio.wait_for(+ asyncio.gather(first, second, return_exceptions=True),+ timeout=5,+ )+ self.assertEqual(results, [self.catalog, self.catalog])+ self.assertEqual(self.client._cached_tools, self.catalog)+ self.assertEqual(len(self.connections), 1)++ async def test_other_session_notification_fences_shared_cache(+ self,+ ) -> None:+ """A notification outside discovery must still reject its snapshot."""+ callers = [await self._start() for _ in range(2)]+ await self.started.wait()+ self.catalog = [+ mcp.types.Tool(name="new", inputSchema={"type": "object"}),+ ]+ async with self.client._get_client_gen():+ self.release.set()+ results = await asyncio.gather(*callers)+ self.assertEqual(results, [self.catalog, self.catalog])+ self.assertEqual(self.client._cached_tools, self.catalog)+ self.assertEqual(len(self.connections), 3)++ async def test_cancelled_caller_does_not_cancel_other_waiters(+ self,+ ) -> None:+ """Either the first caller or a follower may cancel independently."""+ for cancelled in (0, 1):+ with self.subTest(cancelled=cancelled):+ self.started.clear()+ self.release.clear()+ self.connections.clear()+ self.closed.clear()+ callers = [await self._start() for _ in range(2)]+ await self.started.wait()+ await self._cancel(callers[cancelled])+ self.assertEqual(self.closed, [])+ self.release.set()+ result = await callers[1 - cancelled]+ self.assertEqual(result, self.catalog)+ self.assertEqual(self.closed, self.connections)+ self.assertEqual(len(self.connections), 1)+ self.assertIsNone(self.client._discovery_task)++ async def test_last_cancelled_caller_closes_connection(self) -> None:+ """Abandoned discovery must close and allow a subsequent request."""+ callers = [await self._start() for _ in range(2)]+ await self.started.wait()+ for caller in callers:+ await self._cancel(caller)+ self.assertEqual(self.closed, self.connections)+ self.assertEqual(len(self.connections), 1)+ self.assertIsNone(self.client._discovery_task)+ self.assertIsNone(self.client._cached_tools)+ self.release.set()+ self.assertEqual(await self.client.list_raw_tools(), self.catalog)+ self.assertEqual(len(self.connections), 2)++ async def test_failed_discovery_reaches_all_callers_and_can_retry(+ self,+ ) -> None:+ """A failed shared task must not poison later discovery."""+ self.error = RuntimeError("discovery failed")+ callers = [await self._start() for _ in range(2)]+ await self.started.wait()+ self.release.set()+ results = await asyncio.gather(*callers, return_exceptions=True)+ self.assertEqual(results, [self.error, self.error])+ self.assertEqual(self.closed, self.connections)+ self.assertEqual(len(self.connections), 1)+ self.assertIsNone(self.client._discovery_task)+ self.error = None+ self.assertEqual(await self.client.list_raw_tools(), self.catalog)+ self.assertEqual(len(self.connections), 2)++ async def test_cancelled_cleanup_does_not_clear_new_discovery(+ self,+ ) -> None:+ """A fresh caller may arrive while the abandoned connection closes."""+ self.close_gate = asyncio.Event()+ first = await self._start()+ await self.started.wait()+ first.cancel()+ await self.closing.wait()+ self.started.clear()+ second = await self._start()+ await self.started.wait()+ active = self.client._discovery_task+ self.close_gate.set()+ await asyncio.gather(first, return_exceptions=True)+ self.assertIs(self.client._discovery_task, active)+ self.assertFalse(second.done())+ self.release.set()+ self.assertEqual(await second, self.catalog)+ self.assertEqual(self.closed, self.connections)+ self.assertEqual(len(self.connections), 2)+ self.assertIsNone(self.client._discovery_task)+++class MCPClientListGenerationTest(IsolatedAsyncioTestCase):+ """Reject tool lists invalidated during discovery."""++ async def test_discovery_crossing_notification_uses_new_catalog(+ self,+ ) -> None:+ """Retry stale responses once in both connection modes."""+ for stateful in (False, True):+ for entry in ("list", "get"):+ for repeated in (False, True):+ with self.subTest(+ stateful=stateful,+ entry=entry,+ repeated=repeated,+ ):+ await self._check(stateful, entry, repeated)++ async def _check(+ self,+ stateful: bool,+ entry: str,+ repeated: bool,+ ) -> None:+ calls = 0++ class RacingClient(_FakeClient):+ """Notify after taking a tool-list snapshot."""++ async def __aenter__(self) -> "RacingClient":+ # Pre-request notifications must not invalidate the response.+ await self.message_handler(+ mcp.types.ToolListChangedNotification(+ method="notifications/tools/list_changed",+ ),+ )+ return self++ async def list_tools(+ self,+ **_kwargs: Any,+ ) -> mcp.types.ListToolsResult:+ nonlocal calls+ calls += 1+ if calls > 3:+ raise AssertionError("Discovery retried without a bound")+ name = "old" if calls == 1 else "new"+ snapshot = mcp.types.ListToolsResult(+ tools=[+ mcp.types.Tool(+ name=name,+ inputSchema={"type": "object"},+ ),+ ],+ )+ if calls == 1 or repeated:+ await self.message_handler(+ mcp.types.ToolListChangedNotification(+ method="notifications/tools/list_changed",+ ),+ )+ return snapshot++ with patch(+ "agentscope.mcp._mcp_client.stdio_client",+ return_value=_FakeTransport(),+ ), patch("agentscope.mcp._mcp_client.SDKClient", RacingClient):+ client = MCPClient(+ name="generation",+ is_stateful=stateful,+ mcp_config=StdioMCPConfig(command="unused")+ if stateful+ else HttpMCPConfig(url="http://mcp.invalid/mcp"),+ )+ if stateful:+ await client.connect()+ try:+ if repeated:+ with self.assertRaisesRegex(RuntimeError, "changed"):+ if entry == "get":+ await client.get_tool("new")+ else:+ await client.list_raw_tools()+ self.assertIsNone(client._cached_tools)+ else:+ if entry == "list":+ result = await client.list_raw_tools()+ self.assertEqual(+ [tool.name for tool in result],+ ["new"],+ )+ await client.get_tool("new")+ with self.assertRaises(ValueError):+ await client.get_tool("old")+ self.assertEqual(calls, 2)+ finally:+ if stateful:+ await client.close()