Add story-style examples suite (29 stories + harness + CI)

- examples/stories/: 29 narrative example scripts, each a self-contained
  client+server scenario that can be read top-to-bottom and run directly
- examples/pyproject.toml: workspace member so stories resolve against the
  in-tree SDK
- tests/examples/: pytest harness that imports and runs every story under
  the existing coverage gate (in-memory, no subprocesses)
- .github/workflows/shared.yml: wire the stories harness into the test job
- pyproject.toml / uv.lock: register examples workspace member

Author: maxisbey

.github/workflows/shared.yml

@@ -79,6 +79,10 @@ jobs:
 
       - name: Run pytest with coverage
         shell: bash
+        env:
+          # tests/examples/test_stories_smoke.py is gated on this var; it spawns real
+          # stdio + uvicorn subprocesses, so run it on exactly one matrix cell.
+          MCP_EXAMPLES_SMOKE: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' && matrix.dep-resolution.name == 'locked' && '1' || '' }}
         run: |
           uv run --frozen --no-sync coverage erase
           uv run --frozen --no-sync coverage run -m pytest -n auto

examples/README.md

@@ -1,5 +1,18 @@
-# Python SDK Examples
+# Python SDK examples
 
-This folders aims to provide simple examples of using the Python SDK. Please refer to the
-[servers repository](https://github.com/modelcontextprotocol/servers)
-for real-world servers.
+- [`stories/`](stories/) — **the canonical reference.** One self-verifying
+  example per protocol feature, each with its own README. Start with
+  [`stories/tools/`](stories/tools/); the [stories README](stories/README.md)
+  has the full table and how to run them.
+- [`snippets/`](snippets/) — short extracts embedded into `README.v2.md`. Kept
+  minimal and in sync with the top-level README; not intended to be run
+  standalone.
+- [`servers/everything-server/`](servers/everything-server/) — the conformance
+  target for the cross-SDK
+  [conformance suite](https://github.com/modelcontextprotocol/conformance).
+  Exercises every server capability in one process.
+- [`mcpserver/`](mcpserver/) — single-file v1-era examples retained for the
+  migration guide; superseded by `stories/` and slated for removal.
+
+For real-world servers see the
+[servers repository](https://github.com/modelcontextprotocol/servers).

examples/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "mcp-example-stories"
+version = "0.0.0"
+description = "Self-verifying example suite for the MCP Python SDK (dev-only, not published)"
+requires-python = ">=3.10"
+dependencies = ["mcp"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["stories"]

examples/stories/README.md

@@ -0,0 +1,89 @@
+# Story examples
+
+One feature per folder. Each story is a small, self-verifying program: a
+`server.py` (plus, where the wire contract is worth seeing by hand, a
+`server_lowlevel.py`) and a `client.py` whose `scenario(client)` makes
+assertions and exits non-zero on failure. The code you read here is the same
+code CI runs — there is no separate test double.
+
+## Running a story
+
+From the repository root:
+
+```bash
+# stdio (default — the client spawns the server as a subprocess)
+uv run python -m stories.tools.client
+
+# against a running HTTP server
+uv run python -m stories.tools.server --http --port 8000 &
+uv run python -m stories.tools.client --http http://127.0.0.1:8000/mcp
+```
+
+The full matrix (every story × transport × era × server-variant) runs under
+pytest:
+
+```bash
+uv run --frozen pytest tests/examples/          # everything
+uv run --frozen pytest tests/examples/ -k tools # one story
+```
+
+[`manifest.toml`](manifest.toml) declares each story's transports, era, and
+variants; `tests/examples/` expands it.
+
+## Layout
+
+`_harness.py` and `_hosting.py` are scaffolding that adapts a story's
+`build_server()` / `build_app()` to argv (stdio vs `--http`) and to the
+in-process test bridge. They isolate the parts of the SDK's hosting surface
+that are still moving — **don't copy them into your own project**; copy the
+`server.py` / `client.py` bodies instead. `_shared/` holds an in-process OAuth
+authorization server reused by the auth stories.
+
+## Stories
+
+| story | what it shows | status |
+|---|---|---|
+| **— start here —** | | |
+| [`tools`](tools/) | `@mcp.tool()`, schema inference, structured output, annotations | ready |
+| [`prompts`](prompts/) | `@mcp.prompt()`, list/get, argument completion | ready |
+| [`resources`](resources/) | `@mcp.resource()`, list/read, URI templates | ready |
+| [`lifespan`](lifespan/) | startup/shutdown lifespan, per-request state injection | ready |
+| [`dual_era`](dual_era/) | one server factory serving both protocol eras; era-neutral accessors | ready |
+| [`custom_version`](custom_version/) | restricting `supported_protocol_versions` | ready |
+| **— feature stories —** | | |
+| [`streaming`](streaming/) | progress notifications, in-flight logging, cancellation | ready |
+| [`elicitation`](elicitation/) | server pauses a tool to ask the user (form + url) | ready (legacy-era) |
+| [`sampling`](sampling/) | server asks the client's LLM mid-tool (push request) | ready (legacy-era) |
+| [`stickynotes`](stickynotes/) | capstone: tools mutate state → resources + `list_changed` + elicit guard | ready |
+| [`custom_methods`](custom_methods/) | vendor-prefixed JSON-RPC via `add_request_handler` / `send_request` | ready |
+| [`schema_validators`](schema_validators/) | tool input schema from pydantic / TypedDict / dataclass / dict | ready |
+| [`middleware`](middleware/) | server-side request/response middleware | ready |
+| [`parallel_calls`](parallel_calls/) | N×M concurrent calls; per-call notification attribution | ready |
+| [`roots`](roots/) | client-declared roots, server reads them via `ctx` | ready (legacy-era) |
+| [`pagination`](pagination/) | manual cursor loop over list endpoints | ready |
+| [`error_handling`](error_handling/) | `is_error` results vs `MCPError`; `ToolError` | ready |
+| [`client_session`](client_session/) | dropping to `client.session` / `ClientSession` mechanics | ready |
+| [`serve_one`](serve_one/) | building a `Connection` by hand and calling `serve_one` directly | ready |
+| **— HTTP hosting —** | | |
+| [`stateless_legacy`](stateless_legacy/) | `streamable_http_app()` default posture; the one-liner deploy | ready |
+| [`json_response`](json_response/) | `json_response=True` mode; raw 2026 POST envelope on the wire | ready |
+| [`legacy_routing`](legacy_routing/) | `is_legacy_request()` classifier in front of a sessionful 1.x deploy | ready |
+| [`starlette_mount`](starlette_mount/) | mounting `streamable_http_app()` under a Starlette/FastAPI sub-path | ready |
+| [`sse_polling`](sse_polling/) | SEP-1699 `closeSSE()` + `Last-Event-ID` resume via `EventStore` | ready |
+| [`standalone_get`](standalone_get/) | server-initiated `list_changed` over the sessionful GET stream | ready |
+| [`reconnect`](reconnect/) | explicit `discover()`, persist `DiscoverResult`, zero-RTT reconnect | ready |
+| [`bearer_auth`](bearer_auth/) | `requireBearerAuth`, PRM metadata, static-token verifier, `ctx.authInfo` | ready |
+| [`oauth`](oauth/) | full `authorization_code` grant against an in-process AS | ready |
+| [`oauth_client_credentials`](oauth_client_credentials/) | `client_credentials` grant; minimal in-process token endpoint | ready |
+| **— deferred (README only) —** | | |
+| [`caching`](caching/) | `CacheableResult` ttl/scope hints; client honouring | not yet implemented |
+| [`mrtr`](mrtr/) | `InputRequiredResult` round-trip with `requestState` HMAC | not yet implemented — [#2898](https://github.com/modelcontextprotocol/python-sdk/issues/2898) |
+| [`subscriptions`](subscriptions/) | `subscriptions/listen`, `ServerEventBus`, `Client.listen()` | not yet implemented — [#2901](https://github.com/modelcontextprotocol/python-sdk/issues/2901) |
+| [`tasks`](tasks/) | `io.modelcontextprotocol/tasks` extension | not yet implemented |
+| [`apps`](apps/) | MCP Apps: `ui://` resource + `_meta.ui` | not yet implemented — [#2896](https://github.com/modelcontextprotocol/python-sdk/issues/2896) |
+| [`skills`](skills/) | SEP-2640 skills extension | not yet implemented — [#2896](https://github.com/modelcontextprotocol/python-sdk/issues/2896) |
+| [`events`](events/) | `io.modelcontextprotocol/events` extension | not yet implemented |
+
+The TypeScript SDK's `repl`, `client-quickstart`, and `server-quickstart`
+examples are intentionally not ported (interactive / external network deps);
+its `hono` example maps to `starlette_mount/`.

examples/stories/__init__.py

@@ -0,0 +1,6 @@
+"""Self-verifying example suite for the MCP Python SDK.
+
+Each story directory holds a ``server.py`` (and usually ``server_lowlevel.py``)
+plus a ``client.py`` whose ``scenario(client)`` runs against both.
+``tests/examples/`` drives every story over an in-process matrix.
+"""

examples/stories/_harness.py

@@ -0,0 +1,117 @@
+"""Client-side scaffold for story examples.
+
+A story's ``client.py`` imports only from here. The ``Connect`` factory and
+``run_client`` ride the locked ``Client(transport, mode=...)`` surface; the one
+volatile line is the stdio wrap (marked inline).
+"""
+
+from __future__ import annotations
+
+import sys
+import traceback
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from pathlib import Path
+from typing import Any, Protocol
+
+import anyio
+import httpx
+
+from mcp import StdioServerParameters, stdio_client
+from mcp.client import Client
+from mcp.shared.version import LATEST_MODERN_VERSION
+
+Scenario = Callable[[Client], Awaitable[None]]
+ScenarioWithConnect = Callable[[Client, "Connect"], Awaitable[None]]
+AuthBuilder = Callable[[httpx.AsyncClient], httpx.Auth]
+"""Builds an ``httpx.Auth`` bound to the in-process HTTP client (auth-story harness seam)."""
+
+
+class Connect(Protocol):
+    """A factory yielding a connected ``Client``; accepts the same kwargs as ``Client``.
+
+    ``auth`` is the HTTP-only escape hatch for auth stories: when given, the factory
+    builds a fresh ``httpx.AsyncClient`` against the same app, applies ``auth(http)``
+    to it, and wraps the result in ``streamable_http_client`` before entering ``Client``.
+    """
+
+    def __call__(self, *, auth: AuthBuilder | None = None, **client_kw: Any) -> AbstractAsyncContextManager[Client]: ...
+
+
+def argv_after(flag: str, *, default: str | None = None) -> str:
+    """Return the argv token following ``flag``, or ``default`` when the flag is absent."""
+    try:
+        return sys.argv[sys.argv.index(flag) + 1]
+    except ValueError:
+        if default is None:
+            raise SystemExit(f"missing required {flag}") from None
+        return default
+
+
+def connect_from_args(file: str) -> Connect:
+    """Build a ``Connect`` targeting the sibling server over the argv-selected transport.
+
+    ``--http <url>`` connects over streamable HTTP; ``--stdio`` (the default) spawns the
+    sibling ``server.py`` as a subprocess. ``--server <stem>`` selects ``<stem>.py``
+    (e.g. ``server_lowlevel``). ``--legacy`` pins the handshake era; otherwise the
+    modern era is used. ``file`` is the caller's ``__file__``.
+    """
+    here = Path(file).parent
+    server_stem = argv_after("--server", default="server")
+    # Never rely on the SDK's mode= default — be explicit. stdio is legacy-only until
+    # the SDK's stdio entry can negotiate the era; the modern arm is --http only for now.
+    if "--http" in sys.argv:
+        mode = "legacy" if "--legacy" in sys.argv else LATEST_MODERN_VERSION
+    else:
+        mode = "legacy"  # stdio gains a modern arm once serve_stdio() lands
+
+    @asynccontextmanager
+    async def _connect(*, auth: AuthBuilder | None = None, **client_kw: Any) -> AsyncIterator[Client]:
+        assert auth is None, "auth= via connect_from_args is not wired; auth stories own their __main__"
+        client_kw.setdefault("mode", mode)
+        target: Any
+        if "--http" in sys.argv:
+            target = argv_after("--http")
+        else:
+            params = StdioServerParameters(command=sys.executable, args=[str(here / f"{server_stem}.py")])
+            target = stdio_client(params)  # becomes Client(params) once that overload lands
+        async with Client(target, **client_kw) as client:
+            yield client
+
+    return _connect
+
+
+def run_client(
+    scenario: Scenario | ScenarioWithConnect,
+    *,
+    connect: Connect,
+    needs_connect: bool = False,
+    **client_kw: Any,
+) -> None:
+    """Entry point for ``if __name__ == "__main__"`` in every ``client.py``.
+
+    Runs ``scenario`` inside a connected client; prints ``OK:``/``FAIL:`` to stderr and
+    exits 0/1. ``needs_connect=True`` passes ``connect`` as the second argument so the
+    scenario can open additional clients.
+    """
+    file = getattr(scenario, "__globals__", {}).get("__file__", "<unknown>")
+    name = Path(file).parent.name
+    transport = "http" if "--http" in sys.argv else "stdio"
+    era = "modern" if transport == "http" and "--legacy" not in sys.argv else "legacy"
+
+    async def _main() -> None:
+        with anyio.fail_after(30):
+            async with connect(**client_kw) as client:
+                if needs_connect:
+                    await scenario(client, connect)  # type: ignore[call-arg]
+                else:
+                    await scenario(client)  # type: ignore[call-arg]
+
+    try:
+        anyio.run(_main)
+    except Exception:
+        print(f"FAIL: {name} ({transport}/{era})", file=sys.stderr)
+        traceback.print_exc()
+        raise SystemExit(1) from None
+    print(f"OK: {name} ({transport}/{era})", file=sys.stderr)
+    raise SystemExit(0)

examples/stories/_hosting.py

@@ -0,0 +1,87 @@
+"""Server-side hosting scaffold for story examples.
+
+A story's ``server.py`` / ``server_lowlevel.py`` imports only from here. The
+marked lines touch entry-point APIs that a later release reshapes into
+free-function entries; isolating them here keeps story bodies stable.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from typing import Any, TypeAlias
+
+import anyio
+import uvicorn
+from starlette.applications import Starlette
+
+from mcp.server.lowlevel import Server
+from mcp.server.mcpserver import MCPServer
+from mcp.server.stdio import stdio_server
+from mcp.server.transport_security import TransportSecuritySettings
+
+AnyServer: TypeAlias = "MCPServer | Server[Any]"
+ServerFactory = Callable[[], AnyServer]
+AppFactory = Callable[[], Starlette]
+
+NO_DNS_REBIND = TransportSecuritySettings(enable_dns_rebinding_protection=False)
+"""Harness servers bind 127.0.0.1 and the in-process httpx client sends no Origin header."""
+
+
+def argv_after(flag: str, *, default: str | None = None) -> str:
+    """Return the argv token following ``flag``, or ``default`` when the flag is absent."""
+    try:
+        return sys.argv[sys.argv.index(flag) + 1]
+    except ValueError:
+        if default is None:
+            raise SystemExit(f"missing required {flag}") from None
+        return default
+
+
+def asgi_from(server: AnyServer, *, path: str = "/mcp") -> Starlette:
+    """Wrap a server instance in its streamable-HTTP ASGI app for in-process driving."""
+    return server.streamable_http_app(  # becomes free fn streamable_http(server, legacy=...)
+        streamable_http_path=path,
+        stateless_http=False,  # bool folds into a legacy= enum in a later release
+        transport_security=NO_DNS_REBIND,
+    )
+
+
+def run_server_from_args(build_server: ServerFactory) -> None:
+    """Entry point for ``if __name__ == "__main__"`` in every ``server*.py``.
+
+    Bare argv serves over stdio; ``--http --port N [--path /mcp]`` serves over
+    uvicorn on 127.0.0.1:N.
+    """
+    server = build_server()
+    if "--http" in sys.argv:
+        port = int(argv_after("--port", default="8000"))
+        path = argv_after("--path", default="/mcp")
+        anyio.run(_serve_http, server, port, path)
+    else:
+        anyio.run(_serve_stdio, server)
+
+
+async def _serve_stdio(server: AnyServer) -> None:
+    if isinstance(server, MCPServer):
+        await server.run_stdio_async()  # becomes await serve_stdio(server)
+    else:
+        async with stdio_server() as (read, write):  # becomes await serve_stdio(server)
+            await server.run(read, write, server.create_initialization_options())
+
+
+async def _serve_http(server: AnyServer, port: int, path: str) -> None:
+    app = asgi_from(server, path=path)
+    config = uvicorn.Config(app, host="127.0.0.1", port=port, log_level="error")
+    await uvicorn.Server(config).serve()
+
+
+def run_app_from_args(build_app: AppFactory) -> None:
+    """Entry point for ``if __name__ == "__main__"`` in app-exporting ``server*.py``.
+
+    App-exporting stories are HTTP-only; ``--port N`` serves the Starlette app over
+    uvicorn on 127.0.0.1:N (uvicorn drives the app's own lifespan). No stdio leg.
+    """
+    port = int(argv_after("--port", default="8000"))
+    config = uvicorn.Config(build_app(), host="127.0.0.1", port=port, log_level="error")
+    anyio.run(uvicorn.Server(config).serve)

examples/stories/_shared/__init__.py

@@ -0,0 +1 @@
+"""Shared scaffolding the auth/hosting stories import (not teaching surface)."""