Skip to content

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

fix(mcp): refresh cached tools on tools/list_changed notification (#3734)

DingNova444159e80ca6
diff --git a/src/agentscope/mcp/_mcp_client.py b/src/agentscope/mcp/_mcp_client.py
index d054fad3c..b6f1db8f2 100644
--- a/src/agentscope/mcp/_mcp_client.py
+++ b/src/agentscope/mcp/_mcp_client.py
@@ -43,7 +43,8 @@ class MCPClient(BaseModel):
- _lifecycle_task: Owns the stateful client context from enter to exit
- _close_requested: Signals the lifecycle task to exit the client context
- _is_connected: Connection state flag
- - _cached_tools: Cached list of tools
+ - _cached_tools: Cached list of tools, invalidated when the server
+ announces a tools/list_changed notification
- _http_client: The live HTTP client, while one is open
- _static_headers: Its headers before any runtime override
- _runtime_headers: See :meth:`set_runtime_headers`
@@ -221,8 +222,25 @@ class MCPClient(BaseModel):
return SDKClient(
transport,
mode="auto",
+ message_handler=self._handle_server_message,
)
+ async def _handle_server_message(self, message: Any) -> None:
+ """Watch server notifications for tool-list changes.
+
+ An MCP server may add, remove, or update tools while the
+ connection is alive, announcing each change with a
+ ``notifications/tools/list_changed`` notification. The MCP
+ SDK's response cache evicts the matching entry on its own, but
+ the tool descriptors cached in ``_cached_tools`` are a second
+ copy that only this class can invalidate. Dropping it here
+ makes the next :meth:`get_tool` / :meth:`list_tools` call
+ re-resolve against the live server instead of serving schemas
+ from a connection that no longer matches them.
+ """
+ if isinstance(message, mcp.types.ToolListChangedNotification):
+ self._cached_tools = None
+
def _create_http_client(
self,
) -> AbstractAsyncContextManager[Any]:
diff --git a/tests/mcp_client_list_changed_test.py b/tests/mcp_client_list_changed_test.py
new file mode 100644
index 000000000..0f68478d7
--- /dev/null
+++ b/tests/mcp_client_list_changed_test.py
@@ -0,0 +1,146 @@
+# -*- coding: utf-8 -*-
+"""Tests for tool-cache invalidation on tools/list_changed notifications."""
+# pylint: disable=protected-access
+from types import TracebackType
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import patch
+
+import mcp.types
+
+from agentscope.mcp import MCPClient, StdioMCPConfig
+
+
+class _FakeTransport:
+ """Minimal transport context manager for lifecycle-only tests."""
+
+ async def __aenter__(self) -> tuple[object, object]:
+ return object(), object()
+
+ async def __aexit__(
+ self,
+ exc_type: type[BaseException] | None,
+ exc: BaseException | None,
+ traceback: TracebackType | None,
+ ) -> bool:
+ return False
+
+
+class _FakeClient:
+ """MCP 2.x Client stand-in that records its message handler."""
+
+ instances: list["_FakeClient"] = []
+
+ def __init__(
+ self,
+ transport: Any,
+ *,
+ mode: str,
+ message_handler: Any = None,
+ ) -> None:
+ self.transport = transport
+ self.mode = mode
+ self.message_handler = message_handler
+ self.list_calls = 0
+ self.tool_names: list[str] = ["echo"]
+ _FakeClient.instances.append(self)
+
+ async def __aenter__(self) -> "_FakeClient":
+ return self
+
+ async def __aexit__(
+ self,
+ exc_type: type[BaseException] | None,
+ exc: BaseException | None,
+ traceback: TracebackType | None,
+ ) -> bool:
+ return False
+
+ async def list_tools(self, **_kwargs: Any) -> mcp.types.ListToolsResult:
+ """Serve the current tool names as raw tool descriptors."""
+ self.list_calls += 1
+ return mcp.types.ListToolsResult(
+ tools=[
+ mcp.types.Tool(name=name, inputSchema={"type": "object"})
+ for name in self.tool_names
+ ],
+ )
+
+
+class MCPClientListChangedTest(IsolatedAsyncioTestCase):
+ """Server-side tool changes must surface on the next tool lookup."""
+
+ def setUp(self) -> None:
+ _FakeClient.instances = []
+
+ async def _connect(self) -> tuple[MCPClient, _FakeClient]:
+ """Connect a stateful client against the fake SDK client."""
+ with patch(
+ "agentscope.mcp._mcp_client.stdio_client",
+ return_value=_FakeTransport(),
+ ), patch(
+ "agentscope.mcp._mcp_client.SDKClient",
+ _FakeClient,
+ ):
+ client = MCPClient(
+ name="list_changed",
+ is_stateful=True,
+ mcp_config=StdioMCPConfig(command="unused"),
+ )
+ await client.connect()
+ self.addAsyncCleanup(client.close)
+ self.assertEqual(len(_FakeClient.instances), 1)
+ fake = _FakeClient.instances[0]
+ self.assertIsNotNone(fake.message_handler)
+ return client, fake
+
+ async def test_get_tool_rediscovers_after_notification(self) -> None:
+ """A tool added after the notification must be discoverable."""
+ client, fake = await self._connect()
+
+ with self.assertRaises(ValueError):
+ await client.get_tool("echo_v2")
+ self.assertEqual(fake.list_calls, 1)
+
+ fake.tool_names = ["echo", "echo_v2"]
+ await fake.message_handler(
+ mcp.types.ToolListChangedNotification(
+ method="notifications/tools/list_changed",
+ ),
+ )
+ tool = await client.get_tool("echo_v2")
+ self.assertEqual(
+ (tool.name, fake.list_calls),
+ ("mcp__list_changed__echo_v2", 2),
+ )
+ self.assertEqual(
+ client._cached_tools,
+ [
+ mcp.types.Tool(name="echo", inputSchema={"type": "object"}),
+ mcp.types.Tool(name="echo_v2", inputSchema={"type": "object"}),
+ ],
+ )
+
+ async def test_unrelated_notifications_keep_cached_tools(self) -> None:
+ """Notifications other than tools/list_changed keep the cache."""
+ client, fake = await self._connect()
+
+ await client.get_tool("echo")
+ cached = client._cached_tools
+ fake.tool_names = ["echo_v2"]
+
+ await fake.message_handler(
+ mcp.types.LoggingMessageNotification(
+ method="notifications/message",
+ params=mcp.types.LoggingMessageNotificationParams(
+ level="info",
+ data="unrelated",
+ ),
+ ),
+ )
+ tool = await client.get_tool("echo")
+ self.assertEqual(
+ (tool.name, fake.list_calls),
+ ("mcp__list_changed__echo", 1),
+ )
+ self.assertIs(client._cached_tools, cached)
diff --git a/tests/mcp_client_reconnect_test.py b/tests/mcp_client_reconnect_test.py
index 3d2d7b605..a3fe41232 100644
--- a/tests/mcp_client_reconnect_test.py
+++ b/tests/mcp_client_reconnect_test.py
@@ -42,9 +42,11 @@ class _FakeClient:
transport: _OneShotTransport,
*,
mode: str,
+ message_handler: Any = None,
) -> None:
self.transport = transport
self.mode = mode
+ self.message_handler = message_handler
self.exit_count = 0
self._entered = False
@@ -88,8 +90,9 @@ class _TaskBoundClient(_FakeClient):
transport: _OneShotTransport,
*,
mode: str,
+ message_handler: Any = None,
) -> None:
- super().__init__(transport, mode=mode)
+ super().__init__(transport, mode=mode, message_handler=message_handler)
self.enter_task: asyncio.Task[Any] | None = None
self.exit_task: asyncio.Task[Any] | None = None
_TaskBoundClient.instance = self
@@ -252,8 +255,13 @@ class MCPClientReconnectTest(IsolatedAsyncioTestCase):
transport: _OneShotTransport,
*,
mode: str,
+ message_handler: Any = None,
) -> None:
- super().__init__(transport, mode=mode)
+ super().__init__(
+ transport,
+ mode=mode,
+ message_handler=message_handler,
+ )
_BlockingClient.instance = self
async def connect(self) -> None: