Skip to content

Commit 8b1bf1b

Browse files
Merge pull request #311 from tina4stack/fix/mcp-await-async-handlers
fix(mcp): await async resource and tool handlers
2 parents d13b58a + 398c13f commit 8b1bf1b

3 files changed

Lines changed: 455 additions & 45 deletions

File tree

‎tests/test_mcp_async_handlers.py‎

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
# Copyright (c) 2026 Code Infinity
2+
# SPDX-License-Identifier: MPL-2.0
3+
# This Source Code Form is subject to the terms of the Mozilla Public
4+
# License, v. 2.0. If a copy of the MPL was not distributed with this
5+
# file, You can obtain one at https://mozilla.org/MPL/2.0/.
6+
7+
"""MCP awaits ``async def`` tool and resource handlers.
8+
9+
Before the fix, ``resources/read`` and ``tools/call`` called the handler and
10+
serialised whatever came back, so an async handler answered with the text
11+
``<coroutine object rows at 0x...>`` and the coroutine was never run. Python
12+
sibling of tina4-nodejs#193.
13+
14+
No mocks: a real McpServer, real JSON-RPC messages, and the real ASGI front
15+
controller (TestClient) for the async HTTP routes — both the routes
16+
``McpServer.register_routes`` mounts and the dev-admin ``/__dev/mcp`` endpoint.
17+
"""
18+
import asyncio
19+
import gc
20+
import json
21+
import os
22+
import warnings
23+
from contextlib import contextmanager
24+
25+
import pytest
26+
27+
from tina4_python.core import router
28+
from tina4_python.mcp import McpServer, _get_default_server
29+
from tina4_python.mcp.protocol import INTERNAL_ERROR, encode_response
30+
from tina4_python.test_client import TestClient
31+
32+
33+
async def rows():
34+
await asyncio.sleep(0)
35+
return {"rows": [1, 2, 3]}
36+
37+
38+
async def add(a: int, b: int):
39+
await asyncio.sleep(0)
40+
return a + b
41+
42+
43+
async def broken_resource():
44+
await asyncio.sleep(0)
45+
raise RuntimeError("db down")
46+
47+
48+
async def broken_tool(x: int):
49+
await asyncio.sleep(0)
50+
raise RuntimeError(f"tool failed on {x}")
51+
52+
53+
def sync_rows():
54+
return {"rows": [1, 2, 3]}
55+
56+
57+
def sync_add(a: int, b: int):
58+
return a + b
59+
60+
61+
def _server(path: str) -> McpServer:
62+
server = McpServer(path, name="async-handlers")
63+
server.register_resource("probe://rows", rows, "rows")
64+
server.register_resource("probe://boom", broken_resource, "fails")
65+
server.register_resource("probe://sync-rows", sync_rows, "sync rows")
66+
server.register_tool("add", add, "adds")
67+
server.register_tool("boom", broken_tool, "fails")
68+
server.register_tool("sync_add", sync_add, "adds synchronously")
69+
return server
70+
71+
72+
def _read(uri: str, rid: int = 1) -> dict:
73+
return {"jsonrpc": "2.0", "id": rid, "method": "resources/read", "params": {"uri": uri}}
74+
75+
76+
def _call(name: str, arguments: dict, rid: int = 2) -> dict:
77+
return {"jsonrpc": "2.0", "id": rid, "method": "tools/call",
78+
"params": {"name": name, "arguments": arguments}}
79+
80+
81+
# The exact replies a sync handler produced before this change; the async
82+
# handlers returning the same values must now produce the same bytes.
83+
ROWS_REPLY = encode_response(1, {"contents": [{
84+
"uri": "probe://rows", "mimeType": "application/json",
85+
"text": json.dumps({"rows": [1, 2, 3]}, indent=2),
86+
}]})
87+
ADD_REPLY = encode_response(2, {"content": [{"type": "text", "text": "5"}]})
88+
89+
90+
@contextmanager
91+
def no_unawaited_coroutines():
92+
"""Fail if any coroutine is garbage-collected without being awaited."""
93+
with warnings.catch_warnings(record=True) as caught:
94+
warnings.simplefilter("always")
95+
yield
96+
gc.collect()
97+
leaked = [str(w.message) for w in caught
98+
if issubclass(w.category, RuntimeWarning) and "never awaited" in str(w.message)]
99+
assert leaked == [], leaked
100+
101+
102+
def _assert_internal_error(raw: str, rid: int, message: str) -> None:
103+
reply = json.loads(raw)
104+
assert "result" not in reply, raw
105+
assert reply["id"] == rid
106+
assert reply["error"]["code"] == INTERNAL_ERROR == -32603
107+
assert reply["error"]["message"] == message
108+
109+
110+
# ── handle_message_async (the path the async routes take) ──────────────────
111+
112+
class TestHandleMessageAsync:
113+
async def test_async_resource_returns_its_value(self):
114+
server = _server("/__t-async-res")
115+
raw = await server.handle_message_async(_read("probe://rows"))
116+
assert "coroutine object" not in raw
117+
assert raw == ROWS_REPLY
118+
119+
async def test_async_tool_returns_its_value(self):
120+
server = _server("/__t-async-tool")
121+
raw = await server.handle_message_async(_call("add", {"a": 2, "b": 3}))
122+
assert "coroutine object" not in raw
123+
assert raw == ADD_REPLY
124+
125+
async def test_rejecting_async_resource_is_internal_error(self):
126+
server = _server("/__t-async-res-boom")
127+
with no_unawaited_coroutines():
128+
raw = await server.handle_message_async(_read("probe://boom", rid=7))
129+
_assert_internal_error(raw, 7, "db down")
130+
131+
async def test_rejecting_async_tool_is_internal_error(self):
132+
server = _server("/__t-async-tool-boom")
133+
with no_unawaited_coroutines():
134+
raw = await server.handle_message_async(_call("boom", {"x": 4}, rid=8))
135+
_assert_internal_error(raw, 8, "tool failed on 4")
136+
137+
async def test_sync_handlers_answer_byte_identically_on_both_paths(self):
138+
server = _server("/__t-sync-both")
139+
for message, expected in (
140+
(_read("probe://sync-rows"), encode_response(1, {"contents": [{
141+
"uri": "probe://sync-rows", "mimeType": "application/json",
142+
"text": json.dumps({"rows": [1, 2, 3]}, indent=2)}]})),
143+
(_call("sync_add", {"a": 2, "b": 3}), ADD_REPLY),
144+
):
145+
assert await server.handle_message_async(message) == expected
146+
# The sync entry point is still usable for sync handlers inside a
147+
# running loop — nothing about them changed.
148+
assert server.handle_message(message) == expected
149+
150+
async def test_async_notification_gets_no_reply(self):
151+
server = _server("/__t-async-notify")
152+
message = {"jsonrpc": "2.0", "method": "tools/call",
153+
"params": {"name": "add", "arguments": {"a": 1, "b": 1}}}
154+
assert await server.handle_message_async(message) == ""
155+
156+
157+
# ── handle_message (sync, public API) ──────────────────────────────────────
158+
159+
class TestHandleMessageSync:
160+
def test_async_resource_without_running_loop(self):
161+
server = _server("/__t-sync-res")
162+
with no_unawaited_coroutines():
163+
assert server.handle_message(_read("probe://rows")) == ROWS_REPLY
164+
165+
def test_async_tool_without_running_loop(self):
166+
server = _server("/__t-sync-tool")
167+
with no_unawaited_coroutines():
168+
assert server.handle_message(json.dumps(_call("add", {"a": 2, "b": 3}))) == ADD_REPLY
169+
170+
def test_rejecting_async_handlers_without_running_loop(self):
171+
server = _server("/__t-sync-boom")
172+
with no_unawaited_coroutines():
173+
_assert_internal_error(server.handle_message(_read("probe://boom", rid=3)), 3, "db down")
174+
_assert_internal_error(server.handle_message(_call("boom", {"x": 1}, rid=4)), 4,
175+
"tool failed on 1")
176+
177+
def test_leaves_the_threads_event_loop_setting_alone(self):
178+
# The private loop handle_message drives must not become (or clear)
179+
# this thread's current loop for code that runs afterwards.
180+
server = _server("/__t-sync-loop")
181+
own = asyncio.new_event_loop()
182+
asyncio.set_event_loop(own)
183+
try:
184+
assert server.handle_message(_read("probe://rows")) == ROWS_REPLY
185+
assert asyncio.get_event_loop() is own
186+
finally:
187+
asyncio.set_event_loop(None)
188+
own.close()
189+
190+
async def test_async_handler_inside_running_loop_is_clear_error(self):
191+
server = _server("/__t-sync-in-loop")
192+
message = ("async MCP handler cannot be awaited by the synchronous handle_message() "
193+
"inside a running event loop; await handle_message_async() instead")
194+
with no_unawaited_coroutines():
195+
_assert_internal_error(server.handle_message(_read("probe://rows", rid=5)), 5, message)
196+
_assert_internal_error(server.handle_message(_call("add", {"a": 1, "b": 2}, rid=6)), 6,
197+
message)
198+
199+
200+
# ── The real async HTTP routes ─────────────────────────────────────────────
201+
202+
@pytest.fixture(scope="module")
203+
def client():
204+
server = _server("/__t-async-route")
205+
server.register_routes(router)
206+
return TestClient()
207+
208+
209+
class TestRegisteredRoutes:
210+
"""POST through the real ASGI app to the routes register_routes mounts."""
211+
212+
def test_streamable_resource(self, client):
213+
res = client.post("/__t-async-route", json=_read("probe://rows"))
214+
assert res.status == 200
215+
assert res.json() == json.loads(ROWS_REPLY)
216+
217+
def test_streamable_tool(self, client):
218+
res = client.post("/__t-async-route", json=_call("add", {"a": 2, "b": 3}))
219+
assert res.status == 200
220+
assert res.json() == json.loads(ADD_REPLY)
221+
222+
def test_streamable_rejections(self, client):
223+
res = client.post("/__t-async-route", json=_read("probe://boom", rid=9))
224+
_assert_internal_error(json.dumps(res.json()), 9, "db down")
225+
res = client.post("/__t-async-route", json=_call("boom", {"x": 2}, rid=10))
226+
_assert_internal_error(json.dumps(res.json()), 10, "tool failed on 2")
227+
228+
def test_sync_handlers_unchanged_over_http(self, client):
229+
res = client.post("/__t-async-route", json=_call("sync_add", {"a": 2, "b": 3}))
230+
assert res.status == 200
231+
assert res.json() == json.loads(ADD_REPLY)
232+
233+
def test_legacy_message_path(self, client):
234+
res = client.post("/__t-async-route/message", json=_read("probe://rows"))
235+
assert res.status == 200
236+
assert res.json() == json.loads(ROWS_REPLY)
237+
res = client.post("/__t-async-route/message", json=_call("add", {"a": 2, "b": 3}))
238+
assert res.json() == json.loads(ADD_REPLY)
239+
240+
241+
@pytest.fixture
242+
def dev_mcp():
243+
"""Turn the dev MCP endpoint on for a loopback caller and put an async tool
244+
and resource on the real default server; restore everything after."""
245+
keys = ("TINA4_DEBUG", "TINA4_MCP", "TINA4_MCP_REMOTE", "TINA4_MCP_TOKEN", "TINA4_HOST")
246+
saved = {k: os.environ.get(k) for k in keys}
247+
for k in keys:
248+
os.environ.pop(k, None)
249+
os.environ["TINA4_DEBUG"] = "true"
250+
server = _get_default_server()
251+
server.register_tool("__t_async_add", add, "adds")
252+
server.register_resource("probe://dev-rows", rows, "rows")
253+
try:
254+
yield TestClient()
255+
finally:
256+
server._tools.pop("__t_async_add", None)
257+
server._resources.pop("probe://dev-rows", None)
258+
for k, v in saved.items():
259+
if v is None:
260+
os.environ.pop(k, None)
261+
else:
262+
os.environ[k] = v
263+
264+
265+
class TestDevAdminEndpoint:
266+
"""The dev-admin /__dev/mcp routes, through the real ASGI app."""
267+
268+
def test_async_tool_and_resource(self, dev_mcp):
269+
res = dev_mcp.post("/__dev/mcp", json=_call("__t_async_add", {"a": 2, "b": 3}))
270+
assert res.status == 200
271+
assert res.json() == json.loads(ADD_REPLY)
272+
res = dev_mcp.post("/__dev/mcp/message", json=_read("probe://dev-rows"))
273+
assert res.status == 200
274+
assert res.json()["result"]["contents"][0]["text"] == json.dumps({"rows": [1, 2, 3]}, indent=2)

‎tina4_python/dev_admin/__init__.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3236,7 +3236,7 @@ async def _api_mcp_endpoint(request, response):
32363236
method = (getattr(request, "method", "") or "GET").upper()
32373237

32383238
if method == "POST":
3239-
outcome = server.dispatch_http(request.body, _mcp_session_header(request))
3239+
outcome = await server.dispatch_http_async(request.body, _mcp_session_header(request))
32403240
return _mcp_apply(response, outcome)
32413241

32423242
if method == "DELETE":
@@ -3261,7 +3261,7 @@ async def _api_mcp_message(request, response):
32613261
server = _get_default_server()
32623262
params = getattr(request, "params", None) or {}
32633263
session_id = params.get("sessionId") or _mcp_session_header(request)
3264-
outcome = server.dispatch_sse_message(request.body, session_id)
3264+
outcome = await server.dispatch_sse_message_async(request.body, session_id)
32653265
return _mcp_apply(response, outcome)
32663266

32673267

0 commit comments

Comments
 (0)