Skip to content

Build and run agents you can see, understand and trust.

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.py
index 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 += 1
self._cached_tools = None
def _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 here
from ..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.py
index 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 asyncio
from types import TracebackType
from typing import Any
from unittest.async_case import IsolatedAsyncioTestCase
@@ -8,7 +9,7 @@ from unittest.mock import patch
import mcp.types
-from agentscope.mcp import MCPClient, StdioMCPConfig
+from agentscope.mcp import HttpMCPConfig, MCPClient, StdioMCPConfig
class _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()