fix(mcp): the endpoint is the exact path, and nothing redirects
`Starlette(routes=[Mount("/mcp", app=handle)])` serves `/mcp/` and
answers `/mcp` with a **307** -- or a 404 with `redirect_slashes` off.
Measured both ways. Every MCP client configuration spells the URL
without the trailing slash, and a redirected POST has to be re-sent with
its body: `urllib` will not do that at all, and some clients get it
wrong.
So the routing is three lines of its own (`http.Endpoint`) instead: both
spellings are the endpoint, neither is a redirect to the other, and
anything else is a 404. Starlette's router is gone from the request
path; the lifespan protocol is handled directly, which `manager.run()`
needs anyway because its task group must be exited by the task that
entered it.
This got through the unit suite once, and that is the more useful half of
this commit. `starlette.testclient` follows redirects by default, so
every assertion in `test_mcp_http.py` passed against a server a real
client could not talk to -- the 307 only surfaced in
`checks/vm-mcp-http.nix`, from a `urllib` client over a real socket.
`post()` now passes `follow_redirects=False`, and
`test_the_exact_path_does_not_redirect` asserts both spellings answer
200 directly. A test client that papers over a redirect is a test client
that cannot see one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
This commit is contained in:
1 parent
c2ff8fadbd
commit
b2a683a560
2 files changed
+132
-38
No files matched your search
+87
-35
@@ -55,7 +55,6 @@ The deliberate choices in the request path
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import contextlib
|
||||
import logging
|
||||
from collections.abc import Callable, Sequence
|
||||
from typing import Any
|
||||
@@ -219,17 +218,13 @@ class BearerAuth:
|
||||
allowed = self.limiter.allow(client)
|
||||
status = 401 if allowed else 429
|
||||
log.warning("%s from %s: %s", status, client, reason if allowed else "rate limited")
|
||||
headers = [
|
||||
(b"content-length", b"0"),
|
||||
(b"cache-control", b"no-store"),
|
||||
(b"x-content-type-options", b"nosniff"),
|
||||
]
|
||||
headers: list[tuple[bytes, bytes]] = []
|
||||
if status == 401:
|
||||
# RFC 9110's challenge. A realm and nothing else: there is no
|
||||
# `as_uri` to point at, because there is no authorization server.
|
||||
# metadata document to point at, because there is no authorization
|
||||
# server -- see `docs/TODO/mcp-http-auth-is-not-oauth.md`.
|
||||
headers.append((b"www-authenticate", f'Bearer realm="{SERVER_NAME}"'.encode()))
|
||||
await send({"type": "http.response.start", "status": status, "headers": headers})
|
||||
await send({"type": "http.response.body", "body": b""})
|
||||
await _empty(send, status, headers)
|
||||
|
||||
|
||||
def _header(scope: dict[str, Any], name: bytes) -> str:
|
||||
@@ -297,6 +292,85 @@ def offered_for(server: Any, base: tuple[tools.Tool, ...]) -> Callable[[], tuple
|
||||
return chooser
|
||||
|
||||
|
||||
class Endpoint:
|
||||
"""The ASGI app under :class:`BearerAuth`: one path, and the lifespan.
|
||||
|
||||
Hand-rolled rather than ``Starlette(routes=[Mount(path, app=…)])``, and
|
||||
the reason is a 307 that costs real clients their request. A Starlette
|
||||
``Mount`` at ``/mcp`` serves ``/mcp/`` and answers ``/mcp`` with a redirect
|
||||
(or a 404 with ``redirect_slashes`` off) -- measured, both ways. Every MCP
|
||||
client configuration spells the URL without the trailing slash, and a
|
||||
redirected **POST** has to be re-sent with its body, which ``urllib`` will
|
||||
not do at all and some clients get wrong. So the path is matched here,
|
||||
exactly, with and without the slash, and nothing redirects.
|
||||
|
||||
It also means the only routing in this server is three lines long and in
|
||||
one place, which is the whole of what a single-endpoint server needs.
|
||||
"""
|
||||
|
||||
def __init__(self, manager: StreamableHTTPSessionManager, path: str) -> None:
|
||||
self.manager = manager
|
||||
# Both spellings are the endpoint; neither is a redirect to the other.
|
||||
self.paths = {path, path.rstrip("/") + "/"} if path != "/" else {"/"}
|
||||
|
||||
async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None:
|
||||
if scope["type"] == "lifespan":
|
||||
await self._lifespan(receive, send)
|
||||
return
|
||||
if scope.get("path") in self.paths:
|
||||
await self.manager.handle_request(scope, receive, send)
|
||||
return
|
||||
await _empty(send, 404)
|
||||
|
||||
async def _lifespan(self, receive: Any, send: Any) -> None:
|
||||
"""The startup/shutdown protocol, by hand.
|
||||
|
||||
``manager.run()`` has to stay open for the life of the process: it owns
|
||||
the task group the per-session server tasks live in. Entered on
|
||||
``startup`` and exited on ``shutdown``, both of which arrive in this
|
||||
one coroutine -- which matters, because an anyio task group must be
|
||||
exited by the task that entered it.
|
||||
"""
|
||||
|
||||
running: Any = None
|
||||
while True:
|
||||
message = await receive()
|
||||
kind = message["type"]
|
||||
if kind == "lifespan.startup":
|
||||
try:
|
||||
running = self.manager.run()
|
||||
await running.__aenter__()
|
||||
except BaseException as exc: # noqa: BLE001 -- reported, not swallowed
|
||||
log.exception("http transport failed to start")
|
||||
await send({"type": "lifespan.startup.failed", "message": repr(exc)})
|
||||
return
|
||||
log.info("http transport ready on %s", ", ".join(sorted(self.paths)))
|
||||
await send({"type": "lifespan.startup.complete"})
|
||||
elif kind == "lifespan.shutdown":
|
||||
if running is not None:
|
||||
await running.__aexit__(None, None, None)
|
||||
await send({"type": "lifespan.shutdown.complete"})
|
||||
return
|
||||
|
||||
|
||||
async def _empty(send: Any, status: int, headers: list[tuple[bytes, bytes]] | None = None) -> None:
|
||||
"""A response with no body, which is every response this layer writes itself."""
|
||||
|
||||
await send(
|
||||
{
|
||||
"type": "http.response.start",
|
||||
"status": status,
|
||||
"headers": [
|
||||
(b"content-length", b"0"),
|
||||
(b"cache-control", b"no-store"),
|
||||
(b"x-content-type-options", b"nosniff"),
|
||||
*(headers or ()),
|
||||
],
|
||||
}
|
||||
)
|
||||
await send({"type": "http.response.body", "body": b""})
|
||||
|
||||
|
||||
def build_app(
|
||||
runner: Runner,
|
||||
store: Store,
|
||||
@@ -308,7 +382,7 @@ def build_app(
|
||||
stateless: bool = False,
|
||||
json_response: bool = False,
|
||||
) -> Any:
|
||||
"""The ASGI application: one route, behind :class:`BearerAuth`.
|
||||
"""The ASGI application: one endpoint, behind :class:`BearerAuth`.
|
||||
|
||||
``allowed_hosts`` must already be resolved -- :func:`default_allowed_hosts`
|
||||
is the caller's to apply, because the empty list has to stay meaningful
|
||||
@@ -322,12 +396,6 @@ def build_app(
|
||||
only honest answer.
|
||||
"""
|
||||
|
||||
# Imported here and not at module scope: `build_app` is the only thing in
|
||||
# this file that needs Starlette, and an import error should name the
|
||||
# feature being started rather than fire on `import hhstream_mcp.http`.
|
||||
from starlette.applications import Starlette
|
||||
from starlette.routing import Mount
|
||||
|
||||
from .server import build
|
||||
|
||||
security = TransportSecuritySettings(
|
||||
@@ -356,28 +424,11 @@ def build_app(
|
||||
json_response=json_response,
|
||||
security_settings=security,
|
||||
)
|
||||
|
||||
async def handle(scope: Any, receive: Any, send: Any) -> None:
|
||||
await manager.handle_request(scope, receive, send)
|
||||
|
||||
@contextlib.asynccontextmanager
|
||||
async def lifespan(_app: Any) -> Any:
|
||||
# The manager's task group has to be open for the whole life of the
|
||||
# process: it owns the per-session server tasks.
|
||||
async with manager.run():
|
||||
log.info("http transport ready on %s", path)
|
||||
yield
|
||||
|
||||
app = Starlette(
|
||||
debug=False,
|
||||
routes=[Mount(path, app=handle)],
|
||||
lifespan=lifespan,
|
||||
)
|
||||
# The token check wraps the *whole* app and not just the route, so a
|
||||
# The token check wraps the *whole* app and not just the endpoint, so a
|
||||
# request to any other path is a 401 rather than a 404. An unauthenticated
|
||||
# caller learns nothing about what this server has mounted, including
|
||||
# whether it is an hhstream server at all.
|
||||
return BearerAuth(app, store)
|
||||
return BearerAuth(Endpoint(manager, path), store)
|
||||
|
||||
|
||||
def serve(
|
||||
@@ -435,6 +486,7 @@ __all__ = [
|
||||
"DEFAULT_PORT",
|
||||
"SCOPE_KEY",
|
||||
"BearerAuth",
|
||||
"Endpoint",
|
||||
"bearer_token",
|
||||
"build_app",
|
||||
"current_grant",
|
||||
|
||||
@@ -72,12 +72,23 @@ def make_app(store, **kwargs):
|
||||
return http_transport.build_app(Runner(entry=lambda argv: 0), store, **kwargs)
|
||||
|
||||
|
||||
def post(client, body, token=None, headers=None):
|
||||
def post(client, body, token=None, headers=None, path="/mcp"):
|
||||
"""One POST, and **never** following a redirect.
|
||||
|
||||
`follow_redirects=False` is load-bearing, not tidiness. The test client
|
||||
follows redirects by default, which is how a `Mount`-shaped 307 on the
|
||||
exact path `/mcp` passed this whole file once while failing a real client:
|
||||
a redirected POST has to be re-sent with its body, and `urllib` will not do
|
||||
that at all. See `test_the_exact_path_does_not_redirect`.
|
||||
"""
|
||||
|
||||
sent = dict(HEADERS)
|
||||
if token is not None:
|
||||
sent["Authorization"] = f"Bearer {token}"
|
||||
sent.update(headers or {})
|
||||
return client.post("/mcp", content=json.dumps(body), headers=sent)
|
||||
return client.post(
|
||||
path, content=json.dumps(body), headers=sent, follow_redirects=False
|
||||
)
|
||||
|
||||
|
||||
def session(client, token):
|
||||
@@ -196,6 +207,33 @@ def test_the_refusal_does_not_say_which_kind_it_was(store):
|
||||
assert len(set(responses)) == 1
|
||||
|
||||
|
||||
@pytest.mark.parametrize("path", ["/mcp", "/mcp/"])
|
||||
def test_the_exact_path_does_not_redirect(store, path):
|
||||
"""Both spellings are the endpoint, and neither is a redirect to the other.
|
||||
|
||||
The regression this exists for: `Starlette(routes=[Mount("/mcp", ...)])`
|
||||
serves `/mcp/` and answers `/mcp` with a 307 — and every MCP client
|
||||
configuration spells the URL without the trailing slash. The redirect is
|
||||
invisible to a client that follows it on a POST and fatal to one that does
|
||||
not, which is why the endpoint matches the path itself instead.
|
||||
"""
|
||||
|
||||
_, token = store.mint()
|
||||
with TestClient(make_app(store)) as client:
|
||||
response = post(client, INITIALIZE, token=token, path=path)
|
||||
assert response.status_code == 200, (
|
||||
f"{path} answered {response.status_code} "
|
||||
f"(location: {response.headers.get('location')!r})"
|
||||
)
|
||||
|
||||
|
||||
def test_a_custom_path_is_honoured(store):
|
||||
_, token = store.mint()
|
||||
with TestClient(make_app(store, path="/agent/mcp")) as client:
|
||||
assert post(client, INITIALIZE, token=token, path="/agent/mcp").status_code == 200
|
||||
assert post(client, INITIALIZE, token=token, path="/mcp").status_code == 404
|
||||
|
||||
|
||||
def test_an_unknown_path_leaks_nothing_without_a_token(store):
|
||||
store.mint()
|
||||
with TestClient(make_app(store)) as client:
|
||||
@@ -207,7 +245,11 @@ def test_an_unknown_path_leaks_nothing_without_a_token(store):
|
||||
def test_an_unknown_path_is_a_404_once_authenticated(store):
|
||||
_, token = store.mint()
|
||||
with TestClient(make_app(store)) as client:
|
||||
response = client.get("/elsewhere", headers={"Authorization": f"Bearer {token}"})
|
||||
response = client.get(
|
||||
"/elsewhere",
|
||||
headers={"Authorization": f"Bearer {token}"},
|
||||
follow_redirects=False,
|
||||
)
|
||||
assert response.status_code == 404
|
||||
|
||||
|
||||
|
||||
Reference in new issue
Block a user