Skip to content

Commit 5e7afe4

Browse files
authored
fix(mcp): preserve cache invalidation during refresh (#4807)
1 parent 588826c commit 5e7afe4

3 files changed

Lines changed: 246 additions & 4 deletions

File tree

‎src/agents/mcp/server.py‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -997,6 +997,9 @@ def __init__(
997997

998998
# The cache is always dirty at startup, so that we fetch tools at least once
999999
self._cache_dirty = True
1000+
self._tools_cache_generation = 0
1001+
self._tools_refresh_sequence = 0
1002+
self._tools_last_published_refresh_sequence = 0
10001003
self._tools_list: list[MCPTool] | None = None
10011004

10021005
self.tool_filter = tool_filter
@@ -1133,6 +1136,7 @@ async def __aexit__(self, exc_type, exc_value, traceback):
11331136

11341137
def invalidate_tools_cache(self):
11351138
"""Invalidate the tools cache."""
1139+
self._tools_cache_generation += 1
11361140
self._cache_dirty = True
11371141

11381142
def _extract_http_errors_from_exception(self, e: BaseException) -> list[Exception]:
@@ -1482,6 +1486,9 @@ async def list_tools(
14821486
if self.cache_tools_list and not self._cache_dirty and self._tools_list:
14831487
tools = self._tools_list
14841488
else:
1489+
refresh_generation = self._tools_cache_generation
1490+
self._tools_refresh_sequence += 1
1491+
refresh_sequence = self._tools_refresh_sequence
14851492
tools = []
14861493
cursor: str | None = None
14871494
seen_cursors: set[str | None] = set()
@@ -1540,8 +1547,13 @@ async def fetch_pages() -> Literal["complete", "repeated_cursor", "page_limit"]:
15401547
cursor = None
15411548
seen_cursors.clear()
15421549
del fetch_pages
1543-
self._tools_list = tools
1544-
self._cache_dirty = False
1550+
if (
1551+
refresh_generation == self._tools_cache_generation
1552+
and refresh_sequence > self._tools_last_published_refresh_sequence
1553+
):
1554+
self._tools_list = tools
1555+
self._cache_dirty = False
1556+
self._tools_last_published_refresh_sequence = refresh_sequence
15451557

15461558
# Filter tools based on tool_filter
15471559
filtered_tools = tools
@@ -1641,7 +1653,7 @@ def _validate_required_parameters(
16411653
self, tool_name: str, arguments: dict[str, Any] | None
16421654
) -> None:
16431655
"""Validate required tool parameters from cached MCP tool schemas before invocation."""
1644-
if self._tools_list is None:
1656+
if self._cache_dirty or self._tools_list is None:
16451657
return
16461658

16471659
tool = next((item for item in self._tools_list if item.name == tool_name), None)

‎tests/mcp/test_caching.py‎

Lines changed: 225 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
1+
import asyncio
12
from unittest.mock import AsyncMock, call, patch
23

34
import pytest
4-
from mcp.types import PaginatedRequestParams
5+
from mcp.types import CallToolResult, PaginatedRequestParams, TextContent
56

67
from agents import Agent
8+
from agents.exceptions import UserError
79
from agents.mcp import MCPServerStdio
810
from agents.run_context import RunContextWrapper
911

@@ -64,6 +66,228 @@ async def test_server_caching_works(
6466
assert result_tools == tools
6567

6668

69+
@pytest.mark.asyncio
70+
@patch("mcp.client.stdio.stdio_client", return_value=DummyStreamsContextManager())
71+
@patch("mcp.client.session.ClientSession.initialize", new_callable=AsyncMock, return_value=None)
72+
@patch("mcp.client.session.ClientSession.call_tool", new_callable=AsyncMock)
73+
@patch("mcp.client.session.ClientSession.list_tools")
74+
async def test_cache_invalidation_during_refresh_is_preserved(
75+
mock_list_tools: AsyncMock,
76+
mock_call_tool: AsyncMock,
77+
mock_initialize: AsyncMock,
78+
mock_stdio_client,
79+
):
80+
refresh_started = asyncio.Event()
81+
release_refresh = asyncio.Event()
82+
request_count = 0
83+
responses = [
84+
ListToolsResult(
85+
tools=[
86+
MCPTool(
87+
name="tool1",
88+
description="initial",
89+
inputSchema={"required": ["q"]},
90+
),
91+
],
92+
),
93+
ListToolsResult(
94+
tools=[
95+
MCPTool(
96+
name="tool1",
97+
description="before-second-invalidation",
98+
inputSchema={},
99+
),
100+
],
101+
),
102+
ListToolsResult(
103+
tools=[
104+
MCPTool(
105+
name="tool1",
106+
description="after-second-invalidation",
107+
inputSchema={"required": ["latest"]},
108+
),
109+
],
110+
),
111+
]
112+
113+
async def list_tools():
114+
nonlocal request_count
115+
request_count += 1
116+
if request_count == 2:
117+
refresh_started.set()
118+
await release_refresh.wait()
119+
return responses[request_count - 1]
120+
121+
mock_list_tools.side_effect = list_tools
122+
mock_call_tool.return_value = CallToolResult(
123+
content=[TextContent(type="text", text="ok")],
124+
)
125+
server = MCPServerStdio(
126+
params={"command": tee},
127+
cache_tools_list=True,
128+
)
129+
130+
async with server:
131+
initial = await server.list_tools()
132+
assert initial[0].description == "initial"
133+
134+
server.invalidate_tools_cache()
135+
refresh_task = asyncio.create_task(server.list_tools())
136+
try:
137+
await asyncio.wait_for(refresh_started.wait(), timeout=1)
138+
139+
server.invalidate_tools_cache()
140+
release_refresh.set()
141+
refreshed = await asyncio.wait_for(refresh_task, timeout=1)
142+
finally:
143+
release_refresh.set()
144+
if not refresh_task.done():
145+
refresh_task.cancel()
146+
await asyncio.gather(refresh_task, return_exceptions=True)
147+
148+
assert refreshed[0].description == "before-second-invalidation"
149+
assert (server.cached_tools or [])[0].description == "initial"
150+
151+
await server.call_tool("tool1", {})
152+
assert mock_call_tool.call_count == 1
153+
154+
latest = await server.list_tools()
155+
assert latest[0].description == "after-second-invalidation"
156+
assert (server.cached_tools or [])[0].description == "after-second-invalidation"
157+
assert request_count == 3
158+
159+
with pytest.raises(UserError, match="missing required parameters: latest"):
160+
await server.call_tool("tool1", {})
161+
assert mock_call_tool.call_count == 1
162+
163+
164+
@pytest.mark.asyncio
165+
@patch("mcp.client.stdio.stdio_client", return_value=DummyStreamsContextManager())
166+
@patch("mcp.client.session.ClientSession.initialize", new_callable=AsyncMock, return_value=None)
167+
@patch("mcp.client.session.ClientSession.list_tools")
168+
async def test_older_concurrent_refresh_does_not_overwrite_newer_cache(
169+
mock_list_tools: AsyncMock,
170+
mock_initialize: AsyncMock,
171+
mock_stdio_client,
172+
):
173+
first_refresh_started = asyncio.Event()
174+
release_first_refresh = asyncio.Event()
175+
request_count = 0
176+
177+
async def list_tools():
178+
nonlocal request_count
179+
request_count += 1
180+
if request_count == 1:
181+
first_refresh_started.set()
182+
await release_first_refresh.wait()
183+
return ListToolsResult(
184+
tools=[
185+
MCPTool(
186+
name="tool1",
187+
description="first-started",
188+
inputSchema={"required": ["old"]},
189+
),
190+
],
191+
)
192+
return ListToolsResult(
193+
tools=[
194+
MCPTool(
195+
name="tool1",
196+
description="second-started",
197+
inputSchema={"required": ["latest"]},
198+
),
199+
],
200+
)
201+
202+
mock_list_tools.side_effect = list_tools
203+
server = MCPServerStdio(
204+
params={"command": tee},
205+
cache_tools_list=True,
206+
)
207+
208+
async with server:
209+
first_refresh = asyncio.create_task(server.list_tools())
210+
try:
211+
await asyncio.wait_for(first_refresh_started.wait(), timeout=1)
212+
second_result = await asyncio.wait_for(server.list_tools(), timeout=1)
213+
assert second_result[0].description == "second-started"
214+
assert (server.cached_tools or [])[0].description == "second-started"
215+
216+
release_first_refresh.set()
217+
first_result = await asyncio.wait_for(first_refresh, timeout=1)
218+
finally:
219+
release_first_refresh.set()
220+
if not first_refresh.done():
221+
first_refresh.cancel()
222+
await asyncio.gather(first_refresh, return_exceptions=True)
223+
224+
assert first_result[0].description == "first-started"
225+
assert (server.cached_tools or [])[0].description == "second-started"
226+
assert (server.cached_tools or [])[0].input_schema == {"required": ["latest"]}
227+
assert request_count == 2
228+
229+
230+
@pytest.mark.asyncio
231+
@patch("mcp.client.stdio.stdio_client", return_value=DummyStreamsContextManager())
232+
@patch("mcp.client.session.ClientSession.initialize", new_callable=AsyncMock, return_value=None)
233+
@patch("mcp.client.session.ClientSession.list_tools")
234+
async def test_older_refresh_publishes_when_newer_refresh_fails(
235+
mock_list_tools: AsyncMock,
236+
mock_initialize: AsyncMock,
237+
mock_stdio_client,
238+
):
239+
first_refresh_started = asyncio.Event()
240+
release_first_refresh = asyncio.Event()
241+
request_count = 0
242+
243+
async def list_tools():
244+
nonlocal request_count
245+
request_count += 1
246+
if request_count == 1:
247+
first_refresh_started.set()
248+
await release_first_refresh.wait()
249+
return ListToolsResult(
250+
tools=[
251+
MCPTool(
252+
name="tool1",
253+
description="first-started",
254+
inputSchema={"required": ["q"]},
255+
),
256+
],
257+
)
258+
raise RuntimeError("second refresh failed")
259+
260+
mock_list_tools.side_effect = list_tools
261+
server = MCPServerStdio(
262+
params={"command": tee},
263+
cache_tools_list=True,
264+
)
265+
266+
async with server:
267+
first_refresh = asyncio.create_task(server.list_tools())
268+
try:
269+
await asyncio.wait_for(first_refresh_started.wait(), timeout=1)
270+
with pytest.raises(RuntimeError, match="second refresh failed"):
271+
await asyncio.wait_for(server.list_tools(), timeout=1)
272+
273+
release_first_refresh.set()
274+
first_result = await asyncio.wait_for(first_refresh, timeout=1)
275+
finally:
276+
release_first_refresh.set()
277+
if not first_refresh.done():
278+
first_refresh.cancel()
279+
await asyncio.gather(first_refresh, return_exceptions=True)
280+
281+
assert first_result[0].description == "first-started"
282+
cached_tools = server.cached_tools
283+
assert cached_tools is not None
284+
assert cached_tools[0].description == "first-started"
285+
286+
cached_result = await server.list_tools()
287+
assert cached_result[0].description == "first-started"
288+
assert request_count == 2
289+
290+
67291
@pytest.mark.asyncio
68292
@patch("mcp.client.stdio.stdio_client", return_value=DummyStreamsContextManager())
69293
@patch("mcp.client.session.ClientSession.initialize", new_callable=AsyncMock, return_value=None)

‎tests/mcp/test_client_session_retries.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -225,6 +225,7 @@ async def test_call_tool_validates_required_parameters_before_remote_call():
225225
},
226226
)
227227
]
228+
server._cache_dirty = False # noqa: SLF001
228229

229230
with pytest.raises(UserError, match="missing required parameters: param_a"):
230231
await server.call_tool("tool", {})
@@ -246,6 +247,7 @@ async def test_call_tool_with_required_parameters_still_calls_remote_tool():
246247
},
247248
)
248249
]
250+
server._cache_dirty = False # noqa: SLF001
249251

250252
result = await server.call_tool("tool", {"param_a": "value"})
251253
assert isinstance(result, CallToolResult)
@@ -257,6 +259,7 @@ async def test_call_tool_skips_validation_when_tool_is_missing_from_cache():
257259
session = DummySession()
258260
server = DummyServer(session=session, retries=0)
259261
server._tools_list = [MCPTool(name="different_tool", inputSchema={"required": ["param_a"]})] # noqa: SLF001
262+
server._cache_dirty = False # noqa: SLF001
260263

261264
await server.call_tool("tool", {})
262265
assert session.call_tool_attempts == 1
@@ -267,6 +270,7 @@ async def test_call_tool_skips_validation_when_required_list_is_absent():
267270
session = DummySession()
268271
server = DummyServer(session=session, retries=0)
269272
server._tools_list = [MCPTool(name="tool", inputSchema={"type": "object"})] # noqa: SLF001
273+
server._cache_dirty = False # noqa: SLF001
270274

271275
await server.call_tool("tool", None)
272276
assert session.call_tool_attempts == 1
@@ -277,6 +281,7 @@ async def test_call_tool_validates_required_parameters_when_arguments_is_none():
277281
session = DummySession()
278282
server = DummyServer(session=session, retries=0)
279283
server._tools_list = [MCPTool(name="tool", inputSchema={"required": ["param_a"]})] # noqa: SLF001
284+
server._cache_dirty = False # noqa: SLF001
280285

281286
with pytest.raises(UserError, match="missing required parameters: param_a"):
282287
await server.call_tool("tool", None)
@@ -289,6 +294,7 @@ async def test_call_tool_rejects_non_object_arguments_before_remote_call():
289294
session = DummySession()
290295
server = DummyServer(session=session, retries=0)
291296
server._tools_list = [MCPTool(name="tool", inputSchema={"required": ["param_a"]})] # noqa: SLF001
297+
server._cache_dirty = False # noqa: SLF001
292298

293299
with pytest.raises(UserError, match="arguments must be an object"):
294300
await server.call_tool("tool", cast(dict[str, object] | None, ["bad"]))

0 commit comments

Comments
 (0)