chore: import upstream snapshot with attribution

examples/stories/stateless_legacy/README.md

@@ -0,0 +1,59 @@
+# stateless-legacy
+
+The one-liner HTTP deploy. `MCPServer.streamable_http_app(stateless_http=True)`
+returns a complete ASGI app that serves **both** protocol eras on `/mcp`: 2025
+clients get the `initialize` handshake answered statelessly (no `Mcp-Session-Id`,
+fresh transport per request, horizontally scalable), 2026 clients get the
+per-request envelope path. Hand it straight to uvicorn — no session-manager
+wiring, no era flag. The client connects once per era and asserts the same
+`greet` tool answers identically either way.
+
+## Run it
+
+```bash
+# HTTP — the client self-hosts the app on a free port, connects once as a
+# modern client and once as a legacy client, then tears it down
+uv run python -m stories.stateless_legacy.client --http
+# same, against the lowlevel-API server variant
+uv run python -m stories.stateless_legacy.client --http --server server_lowlevel
+
+# against a server you run yourself (real uvicorn on :8000)
+uv run python -m stories.stateless_legacy.server --port 8000 &
+SERVER_PID=$!
+uv run python -m stories.stateless_legacy.client --http http://127.0.0.1:8000/mcp
+kill "$SERVER_PID"
+```
+
+## What to look at
+
+- `client.py` — two visible `Client(targets(), mode=...)` constructions against
+  the same URL. The first connects at the caller's `mode` (the real-user
+  `"auto"` default routes to the 2026 envelope path); the second pins
+  `mode="legacy"` and runs the `initialize` handshake. `client.protocol_version`
+  is the era-neutral accessor: two negotiated versions, identical tool result.
+- `server.py` — `stateless_http=True` is the only knob; era routing is automatic
+  inside `StreamableHTTPSessionManager.handle_request`. The returned `Starlette`
+  already wires `lifespan=session_manager.run()`, so `uvicorn.run(app, ...)`
+  works with no parent-lifespan ceremony.
+- `server_lowlevel.py` — `lowlevel.Server.streamable_http_app()` is the same
+  call; `MCPServer` delegates to it.
+
+## Caveats
+
+- `transport_security=NO_DNS_REBIND` — DNS-rebinding protection is on by default
+  for localhost binds; the harness disables it because the in-process httpx
+  client sends no `Origin` header. Drop the kwarg for a real deployment.
+- `streamable_http_app()` reshapes in a later release; the call is isolated in
+  `build_app()` so the change touches one line per server file.
+
+## Spec
+
+[Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http)
+· [Versioning — backward compatibility](https://modelcontextprotocol.io/specification/draft/basic/versioning)
+
+## See also
+
+`dual_era/` (era branching inside a tool handler) · `legacy_routing/`
+(`classify_inbound_request()` for sessionful-2025 + modern on one mount) ·
+`starlette_mount/` (mounting under FastAPI/Starlette with parent lifespan) ·
+`json_response/` (`json_response=True` and what it drops).

examples/stories/stateless_legacy/client.py

@@ -0,0 +1,37 @@
+"""Connect at each era — two connections, so `main` takes `targets`; the same stateless app answers both."""
+
+from mcp_types import TextContent
+from mcp_types.version import LATEST_HANDSHAKE_VERSION, LATEST_MODERN_VERSION
+
+from mcp.client import Client
+from stories._harness import TargetFactory, run_client
+
+
+async def main(targets: TargetFactory, *, mode: str = "auto") -> None:
+    # ── modern era: the caller's mode (the real-user "auto" default) routes this connection
+    # through the 2026 envelope path. No initialize handshake, no session id.
+    async with Client(targets(), mode=mode) as client:
+        assert client.protocol_version == LATEST_MODERN_VERSION
+
+        listed = await client.list_tools()
+        assert [t.name for t in listed.tools] == ["greet"]
+
+        result = await client.call_tool("greet", {"name": "world"})
+        assert not result.is_error
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "Hello, world!", result
+
+    # ── legacy era: a fresh mode="legacy" client runs the initialize handshake against the
+    # SAME stateless app. It is answered statelessly (no Mcp-Session-Id) and the same tool
+    # gives the same answer — the era is invisible to the server body.
+    async with Client(targets(), mode="legacy") as legacy:
+        assert legacy.protocol_version == LATEST_HANDSHAKE_VERSION
+
+        result = await legacy.call_tool("greet", {"name": "world"})
+        assert not result.is_error
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "Hello, world!", result
+
+
+if __name__ == "__main__":
+    run_client(main)

examples/stories/stateless_legacy/server.py

@@ -0,0 +1,22 @@
+"""The one-liner HTTP deploy: one stateless ASGI app serves both protocol eras, so it exports `build_app()`."""
+
+from starlette.applications import Starlette
+
+from mcp.server.mcpserver import MCPServer
+from stories._hosting import NO_DNS_REBIND, run_app_from_args
+
+
+def build_app() -> Starlette:
+    mcp = MCPServer("stateless-legacy-example")
+
+    @mcp.tool(description="A simple greeting tool.")
+    def greet(name: str) -> str:
+        return f"Hello, {name}!"
+
+    # stateless_http=True: no Mcp-Session-Id, fresh transport per POST — horizontally
+    # scalable. The same app also answers 2026-era envelope requests with no extra config.
+    return mcp.streamable_http_app(stateless_http=True, transport_security=NO_DNS_REBIND)
+
+
+if __name__ == "__main__":
+    run_app_from_args(build_app)

examples/stories/stateless_legacy/server_lowlevel.py

@@ -0,0 +1,38 @@
+"""The one-liner HTTP deploy (lowlevel API): Server.streamable_http_app(stateless_http=True)."""
+
+from typing import Any
+
+import mcp_types as types
+from starlette.applications import Starlette
+
+from mcp.server.context import ServerRequestContext
+from mcp.server.lowlevel import Server
+from stories._hosting import NO_DNS_REBIND, run_app_from_args
+
+GREET_INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {"name": {"type": "string"}},
+    "required": ["name"],
+}
+
+
+def build_app() -> Starlette:
+    async def list_tools(
+        ctx: ServerRequestContext[Any], params: types.PaginatedRequestParams | None
+    ) -> types.ListToolsResult:
+        return types.ListToolsResult(
+            tools=[
+                types.Tool(name="greet", description="A simple greeting tool.", input_schema=GREET_INPUT_SCHEMA),
+            ]
+        )
+
+    async def call_tool(ctx: ServerRequestContext[Any], params: types.CallToolRequestParams) -> types.CallToolResult:
+        assert params.name == "greet" and params.arguments is not None
+        return types.CallToolResult(content=[types.TextContent(text=f"Hello, {params.arguments['name']}!")])
+
+    server = Server("stateless-legacy-example", on_list_tools=list_tools, on_call_tool=call_tool)
+    return server.streamable_http_app(stateless_http=True, transport_security=NO_DNS_REBIND)
+
+
+if __name__ == "__main__":
+    run_app_from_args(build_app)