|
1 | 1 | #!/usr/bin/env python3 |
2 | | -"""Regression coverage for the docs MCP server's HTTP transport (CUS-1340). |
| 2 | +"""Regression coverage for the docs MCP server's HTTP transport. |
3 | 3 |
|
4 | | -The hosted server runs several Cloud Run instances behind a global load |
5 | | -balancer with no session affinity. A stateful streamable-HTTP transport keys |
6 | | -each session to the instance that handled `initialize`, so a follow-up request |
7 | | -(for example `notifications/initialized`) landing on another instance was |
8 | | -rejected with 404 "Session not found". Running the transport with |
9 | | -`stateless_http=True` makes every request self-contained, which is safe here |
10 | | -because the docs tools are read-only and the server sends no server-initiated |
11 | | -notifications. |
| 4 | +These tests send real HTTP requests to the app that production serves, built |
| 5 | +by build_http_app() in mcp-server.py, and guard three settings: |
12 | 6 |
|
13 | | -This asserts the production invocation keeps that flag. It reads the source |
14 | | -rather than importing, because the `server.run(...)` call lives under |
15 | | -`if __name__ == "__main__"` and would block on uvicorn if executed. |
| 7 | +- Stateless (CUS-1340). The hosted server runs several Cloud Run instances |
| 8 | + behind a global load balancer with no session affinity. A stateful transport |
| 9 | + keys each session to the instance that handled `initialize`, so a follow-up |
| 10 | + request landing on another instance was rejected with 404 "Session not |
| 11 | + found". A stateless server mints no Mcp-Session-Id. |
| 12 | +- JSON responses. Each POST reply is a single application/json body, not a |
| 13 | + one-shot text/event-stream. |
| 14 | +- No SSE stream (EXP-577). In stateless mode the SDK accepts GET /mcp and |
| 15 | + holds an empty stream open until Cloud Run's 300-second request timeout, |
| 16 | + holding one of the service's request slots the whole time. Enough of those |
| 17 | + filled every slot, and Cloud Run returned 429 to all callers. The server |
| 18 | + must answer GET with 405 instead. |
| 19 | +
|
| 20 | +TestClient is used as a context manager so it runs the app's lifespan, which |
| 21 | +starts the SDK's session manager; without it every POST fails with 500. |
16 | 22 |
|
17 | 23 | Run with: |
18 | 24 | pytest scripts/test_mcp_transport.py -v |
19 | 25 | """ |
20 | 26 |
|
21 | | -import ast |
| 27 | +import importlib.util |
| 28 | +import os |
22 | 29 | from pathlib import Path |
23 | 30 |
|
24 | | -SERVER = Path(__file__).parent / "mcp-server.py" |
25 | | - |
26 | | - |
27 | | -def streamable_http_run_calls(tree): |
28 | | - """Every `.run(transport="streamable-http", ...)` call in the module.""" |
29 | | - calls = [] |
30 | | - for node in ast.walk(tree): |
31 | | - if not isinstance(node, ast.Call): |
32 | | - continue |
33 | | - transport = next( |
34 | | - (kw.value for kw in node.keywords if kw.arg == "transport"), None |
35 | | - ) |
36 | | - if isinstance(transport, ast.Constant) and transport.value == "streamable-http": |
37 | | - calls.append(node) |
38 | | - return calls |
39 | | - |
40 | | - |
41 | | -def test_http_transport_runs_stateless(): |
42 | | - """The streamable-HTTP server must run stateless, or CUS-1340 regresses.""" |
43 | | - tree = ast.parse(SERVER.read_text(encoding="utf-8")) |
44 | | - calls = streamable_http_run_calls(tree) |
45 | | - assert calls, "expected a streamable-http server.run() call" |
46 | | - for call in calls: |
47 | | - flag = next( |
48 | | - (kw.value for kw in call.keywords if kw.arg == "stateless_http"), None |
49 | | - ) |
50 | | - assert flag is not None, ( |
51 | | - "stateless_http kwarg missing from the streamable-http run() call " |
52 | | - "(CUS-1340): stateful sessions break across unaffinitized Cloud " |
53 | | - "Run instances" |
54 | | - ) |
55 | | - # `is True` is deliberate: it rejects truthy-but-not-True literals such |
56 | | - # as stateless_http=1, which the SDK would not treat as the boolean flag. |
57 | | - assert isinstance(flag, ast.Constant) and flag.value is True, ( |
58 | | - "stateless_http must be the literal True, not a falsy or non-True " |
59 | | - "value (CUS-1340)" |
60 | | - ) |
| 31 | +import pytest |
| 32 | +from starlette.testclient import TestClient |
| 33 | + |
| 34 | + |
| 35 | +def load_server_module(): |
| 36 | + """Import scripts/mcp-server.py, whose filename is not a valid module name. |
| 37 | +
|
| 38 | + The module indexes DOCS_PATH at import time. Point it at paths that do not |
| 39 | + exist so the import stays cheap; these tests need no documentation content. |
| 40 | + """ |
| 41 | + os.environ["DOCS_PATH"] = "/nonexistent/docs.md" |
| 42 | + os.environ["CATALOG_PATH"] = "/nonexistent/catalog.json" |
| 43 | + |
| 44 | + spec = importlib.util.spec_from_file_location( |
| 45 | + "mcp_server_transport_under_test", Path(__file__).parent / "mcp-server.py" |
| 46 | + ) |
| 47 | + module = importlib.util.module_from_spec(spec) |
| 48 | + spec.loader.exec_module(module) |
| 49 | + return module |
| 50 | + |
| 51 | + |
| 52 | +mcp_server = load_server_module() |
| 53 | + |
| 54 | +# The Envoy AI Gateway sends this protocol version, and clients on any 2025 |
| 55 | +# version reach the SDK path that opened the stream. |
| 56 | +PROTOCOL_VERSION = "2025-06-18" |
| 57 | + |
| 58 | +POST_HEADERS = { |
| 59 | + "Accept": "application/json, text/event-stream", |
| 60 | + "Content-Type": "application/json", |
| 61 | +} |
| 62 | + |
| 63 | +INITIALIZE = { |
| 64 | + "jsonrpc": "2.0", |
| 65 | + "id": 1, |
| 66 | + "method": "initialize", |
| 67 | + "params": { |
| 68 | + "protocolVersion": PROTOCOL_VERSION, |
| 69 | + "capabilities": {}, |
| 70 | + "clientInfo": {"name": "transport-test", "version": "0"}, |
| 71 | + }, |
| 72 | +} |
| 73 | + |
| 74 | + |
| 75 | +@pytest.fixture(scope="module") |
| 76 | +def client(): |
| 77 | + # Nothing binds here. The test passes production's host so the SDK picks |
| 78 | + # the same transport-security settings; a localhost host would turn on DNS |
| 79 | + # rebinding protection, which production doesn't run with. |
| 80 | + with TestClient(mcp_server.build_http_app("0.0.0.0")) as test_client: # nosec B104 |
| 81 | + yield test_client |
| 82 | + |
| 83 | + |
| 84 | +@pytest.mark.parametrize( |
| 85 | + "headers", |
| 86 | + [ |
| 87 | + {"Accept": "text/event-stream", "MCP-Protocol-Version": PROTOCOL_VERSION}, |
| 88 | + {"Accept": "text/event-stream"}, |
| 89 | + ], |
| 90 | + ids=["with-protocol-version", "without-protocol-version"], |
| 91 | +) |
| 92 | +# If the 405 route regresses, the GET opens a stream that never ends and |
| 93 | +# TestClient waits forever for its body. The timeout (pytest-timeout) turns |
| 94 | +# that hang into a failure. |
| 95 | +@pytest.mark.timeout(10) |
| 96 | +def test_get_is_refused_with_405(client, headers): |
| 97 | + """GET /mcp must not open an SSE stream (EXP-577).""" |
| 98 | + response = client.get("/mcp", headers=headers) |
| 99 | + assert response.status_code == 405 |
| 100 | + assert response.headers["allow"] == "POST" |
| 101 | + |
| 102 | + |
| 103 | +def test_initialize_is_stateless_and_json(client): |
| 104 | + """POST initialize still works, mints no session, and replies in JSON.""" |
| 105 | + response = client.post("/mcp", headers=POST_HEADERS, json=INITIALIZE) |
| 106 | + assert response.status_code == 200 |
| 107 | + assert response.headers["content-type"].startswith("application/json") |
| 108 | + # A JSON-RPC error also comes back as HTTP 200, so check for a result |
| 109 | + # before trusting the absent session id. |
| 110 | + assert "result" in response.json() |
| 111 | + assert "mcp-session-id" not in response.headers, ( |
| 112 | + "stateless mode expected but the server minted an Mcp-Session-Id " |
| 113 | + "(CUS-1340): stateful sessions break across unaffinitized Cloud Run " |
| 114 | + "instances" |
| 115 | + ) |
| 116 | + |
| 117 | + |
| 118 | +def test_tools_list_works_without_a_session(client): |
| 119 | + """A follow-up request needs no session, so any instance can serve it.""" |
| 120 | + response = client.post( |
| 121 | + "/mcp", |
| 122 | + headers={**POST_HEADERS, "MCP-Protocol-Version": PROTOCOL_VERSION}, |
| 123 | + json={"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, |
| 124 | + ) |
| 125 | + assert response.status_code == 200 |
| 126 | + assert response.json()["result"]["tools"] |
0 commit comments