Skip to content

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

fix(mcp): clean up cancelled MCP connections (#2499)

林桉7c5c11436a6a
diff --git a/src/agentscope/mcp/_mcp_client.py b/src/agentscope/mcp/_mcp_client.py
index c3d448dbc..744e95b1f 100644
--- a/src/agentscope/mcp/_mcp_client.py
+++ b/src/agentscope/mcp/_mcp_client.py
@@ -1,5 +1,6 @@
# -*- coding: utf-8 -*-
"""Unified MCP client implementation for AgentScope."""
+import asyncio
import re
from contextlib import AsyncExitStack, _AsyncGeneratorContextManager
from typing import Any, TYPE_CHECKING
@@ -241,21 +242,31 @@ class MCPClient(BaseModel):
self._initialize_client()
assert self._client is not None
- self._stack = AsyncExitStack()
+ stack = AsyncExitStack()
+ self._stack = stack
try:
- context = await self._stack.enter_async_context(self._client)
+ context = await stack.enter_async_context(self._client)
read_stream, write_stream = context[0], context[1]
self._session = ClientSession(read_stream, write_stream)
- await self._stack.enter_async_context(self._session)
+ await stack.enter_async_context(self._session)
await self._session.initialize()
self._is_connected = True
logger.info("MCP connected: %s", self.name)
- except Exception:
- await self._stack.aclose()
- self._stack = None
- self._client = None
+ except BaseException:
+ # asyncio.CancelledError inherits BaseException, so a cancelled
+ # initialization must close every context entered so far. The
+ # close is shielded because an anyio cancel scope (a cancelled
+ # FastAPI request, for one) keeps cancelling every await inside
+ # it, which would otherwise abandon a live stdio subprocess.
+ try:
+ await asyncio.shield(stack.aclose())
+ finally:
+ self._client = None
+ self._stack = None
+ self._session = None
+ self._is_connected = False
raise
async def close(self, ignore_errors: bool = True) -> None:
diff --git a/tests/mcp_client_reconnect_test.py b/tests/mcp_client_reconnect_test.py
index cebe5d397..9977d5322 100644
--- a/tests/mcp_client_reconnect_test.py
+++ b/tests/mcp_client_reconnect_test.py
@@ -1,10 +1,13 @@
# -*- coding: utf-8 -*-
"""Tests for reconnecting stateful MCP clients."""
+import asyncio
from types import TracebackType
from typing import Any
from unittest.async_case import IsolatedAsyncioTestCase
from unittest.mock import patch
+import anyio
+
from agentscope.mcp import HttpMCPConfig, MCPClient, StdioMCPConfig
@@ -13,6 +16,7 @@ class _OneShotTransport:
def __init__(self) -> None:
self.enter_count = 0
+ self.exit_count = 0
async def __aenter__(self) -> tuple[object, object]:
self.enter_count += 1
@@ -26,6 +30,7 @@ class _OneShotTransport:
exc: BaseException | None,
traceback: TracebackType | None,
) -> bool:
+ self.exit_count += 1
return False
@@ -35,6 +40,7 @@ class _FakeSession:
def __init__(self, read_stream: object, write_stream: object) -> None:
self.read_stream = read_stream
self.write_stream = write_stream
+ self.exit_count = 0
async def __aenter__(self) -> "_FakeSession":
"""Enter the fake session context."""
@@ -47,6 +53,7 @@ class _FakeSession:
traceback: TracebackType | None,
) -> bool:
"""Leave the fake session context."""
+ self.exit_count += 1
return False
async def initialize(self) -> None:
@@ -129,6 +136,127 @@ class MCPClientReconnectTest(IsolatedAsyncioTestCase):
self.assertEqual(len(transports), 2)
self.assertTrue(all(_.enter_count == 1 for _ in transports))
+ async def test_cancelled_connect_closes_partial_connection(self) -> None:
+ """Cancellation during initialization must clean up and allow retry."""
+ initialize_started = asyncio.Event()
+ never_finish = asyncio.Event()
+ transports: list[_OneShotTransport] = []
+
+ def create_transport(_parameters: Any) -> _OneShotTransport:
+ """Create and retain one-shot transports for assertions."""
+ transport = _OneShotTransport()
+ transports.append(transport)
+ return transport
+
+ class _BlockingSession(_FakeSession):
+ """Block initialization until the test cancels the connection."""
+
+ instance: "_BlockingSession | None" = None
+ attempts = 0
+
+ def __init__(
+ self,
+ read_stream: object,
+ write_stream: object,
+ ) -> None:
+ super().__init__(read_stream, write_stream)
+ _BlockingSession.instance = self
+
+ async def initialize(self) -> None:
+ _BlockingSession.attempts += 1
+ initialize_started.set()
+ if _BlockingSession.attempts == 1:
+ await never_finish.wait()
+
+ with patch(
+ "agentscope.mcp._mcp_client.stdio_client",
+ side_effect=create_transport,
+ ), patch(
+ "agentscope.mcp._mcp_client.ClientSession",
+ _BlockingSession,
+ ):
+ client = MCPClient(
+ name="cancelled_connect",
+ is_stateful=True,
+ mcp_config=StdioMCPConfig(command="unused"),
+ )
+
+ task = asyncio.create_task(client.connect())
+ await initialize_started.wait()
+ task.cancel()
+ with self.assertRaises(asyncio.CancelledError):
+ await task
+
+ session = _BlockingSession.instance
+ assert session is not None
+ self.assertFalse(client.is_connected)
+ self.assertEqual(transports[0].exit_count, 1)
+ self.assertEqual(session.exit_count, 1)
+
+ await client.connect()
+ await client.close()
+
+ self.assertEqual(len(transports), 2)
+ self.assertTrue(all(_.enter_count == 1 for _ in transports))
+ self.assertTrue(all(_.exit_count == 1 for _ in transports))
+
+ async def test_cancel_scope_does_not_abandon_the_transport(self) -> None:
+ """A cancel scope must not cut the cleanup short."""
+ initialize_started = asyncio.Event()
+ transport_closed = asyncio.Event()
+
+ class _SlowTransport(_OneShotTransport):
+ """Await while closing, the way a real stdio transport does."""
+
+ async def __aexit__(
+ self,
+ exc_type: type[BaseException] | None,
+ exc: BaseException | None,
+ traceback: TracebackType | None,
+ ) -> bool:
+ await asyncio.sleep(0)
+ await super().__aexit__(exc_type, exc, traceback)
+ transport_closed.set()
+ return False
+
+ class _BlockingSession(_FakeSession):
+ """Never finish initializing, so the scope cancels mid-connect."""
+
+ async def initialize(self) -> None:
+ initialize_started.set()
+ await asyncio.Event().wait()
+
+ transport = _SlowTransport()
+ with patch(
+ "agentscope.mcp._mcp_client.stdio_client",
+ return_value=transport,
+ ), patch(
+ "agentscope.mcp._mcp_client.ClientSession",
+ _BlockingSession,
+ ):
+ client = MCPClient(
+ name="cancel_scope",
+ is_stateful=True,
+ mcp_config=StdioMCPConfig(command="unused"),
+ )
+
+ with anyio.CancelScope() as scope:
+
+ async def _cancel_once_started() -> None:
+ """Cancel the scope once the connect is blocked."""
+ await initialize_started.wait()
+ scope.cancel()
+
+ canceller = asyncio.create_task(_cancel_once_started())
+ await client.connect()
+ await canceller
+
+ self.assertTrue(scope.cancelled_caught)
+ # Cleanup runs to completion even though the scope keeps cancelling.
+ await asyncio.wait_for(transport_closed.wait(), 1)
+ self.assertEqual(transport.exit_count, 1)
+ self.assertFalse(client.is_connected)
+
async def test_http_client_can_reconnect_after_close(self) -> None:
"""An HTTP client must get a new transport after close()."""
transports: list[_OneShotTransport] = []