Add a story shape-check; document the canonical example shape

maxisbey · maxisbey · commit c439aebec2df · 2026-06-25T15:45:58.000Z
- tests/examples/test_story_shape.py: an AST check that every client.py
  constructs Client(...) inline in main's body, imports only the small
  harness allowlist, reaches no private mcp attributes, and that
  server_lowlevel.py never imports the high-level server module.
- stories/README.md gains a "Canonical shape" section with the pasteable
  skeleton and the import rules; non-canonical stories state why in their
  module docstring; server names normalised to "&lt;story&gt;-example".
- mrtr/ and subscriptions/ stubs note the lowlevel registration surface
  now exists upstream and they graduate once this branch's base has it.
diff --git a/examples/stories/README.md b/examples/stories/README.md
@@ -6,6 +6,45 @@ One feature per folder. Each story is a small, self-verifying program: a
 exits non-zero on failure. The code you read here is the same code CI runs —
 there is no separate test double.
 
+## Canonical shape
+
+Every `client.py` starts from this skeleton — copy it, then replace the body
+with the story's assertions:
+
+```python
+"""One line: what this client proves."""
+
+from mcp.client import Client
+from stories._harness import Target, run_client
+
+
+async def main(target: Target, *, mode: str = "auto") -> None:
+    async with Client(target, mode=mode) as client:
+        ...  # the story's assertions
+
+
+if __name__ == "__main__":
+    run_client(main)
+```
+
+There are exactly two `main` shapes. A story that opens **one** connection
+takes `main(target: Target, ...)`. A story that opens **more than one** sets
+`multi_connection = true` in [`manifest.toml`](manifest.toml), takes
+`main(targets: TargetFactory, ...)`, and calls `targets()` once per fresh
+connection — a `Client` cannot be re-entered after exit. Nothing else changes
+shape.
+
+Story files import from `stories._harness` only these names: `run_client`,
+`target_from_args`, `Target`, `TargetFactory` — plus `AuthBuilder` for the
+auth stories. Everything else a story uses comes from public `mcp.*` modules.
+
+The repetition this produces across stories is deliberate, not a refactor
+waiting to happen: each `client.py` is a standalone, compiled doc page, so
+when a public API changes, N red example files flag N doc pages. Don't pull
+the `Client(target, mode=mode)` line (or anything around it) into a shared
+helper. A story that can't be the canonical shape says why in its module
+docstring's first line.
+
 ## How to read a story
 
 Start with the story's README, then `server.py`, then `client.py`. Every
diff --git a/examples/stories/bearer_auth/client.py b/examples/stories/bearer_auth/client.py
@@ -1,4 +1,4 @@
-"""Call the bearer-gated server through an already-authed transport; assert the ``whoami`` principal."""
+"""Call the bearer-gated server through an already-authed (``build_auth``, HTTP-only) transport; assert ``whoami``."""
 
 from collections.abc import Generator
 
diff --git a/examples/stories/bearer_auth/server.py b/examples/stories/bearer_auth/server.py
@@ -1,4 +1,4 @@
-"""Resource-server-only bearer auth: ``TokenVerifier`` + ``AuthSettings`` → 401/PRM/principal."""
+"""Resource-server-only bearer auth: ``TokenVerifier``/``AuthSettings`` → 401/PRM/principal. Exports ``build_app()``."""
 
 import time
 
diff --git a/examples/stories/custom_methods/server.py b/examples/stories/custom_methods/server.py
@@ -24,7 +24,7 @@ class SearchResult(types.Result):
 
 
 def build_server() -> Server[Any]:
-    server = Server("acme-search")
+    server = Server("custom-methods-example")
 
     async def search(ctx: ServerRequestContext[Any], params: SearchParams) -> SearchResult:
         items = [f"{params.query}-{i}" for i in range(params.limit)]
diff --git a/examples/stories/dual_era/client.py b/examples/stories/dual_era/client.py
@@ -1,4 +1,4 @@
-"""Connect to the same server factory twice — once per era — and assert both are served."""
+"""Connect to the same server factory twice — once per era, so `main` takes `targets` — and assert both are served."""
 
 from mcp import types
 from mcp.client import Client
diff --git a/examples/stories/json_response/client.py b/examples/stories/json_response/client.py
@@ -1,4 +1,4 @@
-"""Regular ``Client`` against a JSON-only server; assert mid-call progress is dropped.
+"""Plain ``Client`` against a JSON-only server: mid-call progress drops. HTTP-only — ``main`` also takes ``http``.
 
 ``RAW_ENVELOPE_BODY`` / ``MODERN_HEADERS`` are the exact wire shape a 2026-era client
 sends — this is the only story that shows it. ``main`` posts that body by hand and
diff --git a/examples/stories/json_response/server.py b/examples/stories/json_response/server.py
@@ -1,4 +1,4 @@
-"""Serve over Streamable HTTP with JSON responses (no SSE stream).
+"""Serve over Streamable HTTP with JSON responses (no SSE stream); HTTP-only, so this exports ``build_app()``.
 
 The 2026-07-28 path is stateless and JSON-only by construction today; the
 ``json_response=True`` flag also forces JSON for the legacy (2025-era) branch on
diff --git a/examples/stories/legacy_elicitation/README.md b/examples/stories/legacy_elicitation/README.md
@@ -6,6 +6,8 @@
 > [`mrtr/`](../mrtr/) story. Elicitation itself is **not** deprecated.
 > TODO(maxisbey): unify once the MRTR runtime lands
 > ([#2898](https://github.com/modelcontextprotocol/python-sdk/issues/2898)).
+> The TypeScript SDK ships a single dual-era `elicitation/` story; this
+> directory re-merges back into `elicitation/` once MRTR lands.
 
 A tool pauses mid-call to ask the user for structured input. On the
 handshake-era protocol the server pushes an `elicitation/create` *request* to
diff --git a/examples/stories/legacy_elicitation/server.py b/examples/stories/legacy_elicitation/server.py
@@ -13,7 +13,7 @@ class Registration(BaseModel):
 
 
 def build_server() -> MCPServer:
-    mcp = MCPServer("elicitation-example")
+    mcp = MCPServer("legacy-elicitation-example")
 
     @mcp.tool(description="Register a new account by asking the user for their details.")
     async def register_user(ctx: Context) -> str:
diff --git a/examples/stories/legacy_elicitation/server_lowlevel.py b/examples/stories/legacy_elicitation/server_lowlevel.py
@@ -58,7 +58,7 @@ async def call_tool(ctx: ServerRequestContext[Any], params: types.CallToolReques
         await ctx.session.send_elicit_complete(elicitation_id, related_request_id=ctx.request_id)
         return types.CallToolResult(content=[types.TextContent(text=f"linked {provider}")])
 
-    return Server("elicitation-example", on_list_tools=list_tools, on_call_tool=call_tool)
+    return Server("legacy-elicitation-example", on_list_tools=list_tools, on_call_tool=call_tool)
 
 
 if __name__ == "__main__":
diff --git a/examples/stories/legacy_routing/client.py b/examples/stories/legacy_routing/client.py
@@ -1,4 +1,4 @@
-"""Connect at both eras to one app; assert the built-in router and the predicate agree."""
+"""Connect at both eras to one app — so `main` takes `targets` — and assert the built-in router and predicate agree."""
 
 from typing import Any
 
diff --git a/examples/stories/legacy_routing/server.py b/examples/stories/legacy_routing/server.py
@@ -1,4 +1,4 @@
-"""Exported era classifier: the body-primary predicate, the built-in dual-era app, and CORS."""
+"""Exported era classifier: the body-primary predicate, the built-in dual-era app, and CORS — exports `build_app()`."""
 
 from collections.abc import Mapping
 from typing import Any, Literal
diff --git a/examples/stories/mrtr/README.md b/examples/stories/mrtr/README.md
@@ -7,9 +7,11 @@ the server resumes from the carried state. The story will show both the
 auto-fulfil helper and a manual resubmit loop.
 
 **Status: not yet implemented** ([#2898](https://github.com/modelcontextprotocol/python-sdk/issues/2898)).
-The `InputRequiredResult` types exist, but `Client.call_tool` still validates
-the response as a plain `CallToolResult` and rejects `input_required`. There is
-no runnable round-trip until the runtime lands.
+The lowlevel registration surface exists on `main` as of
+[#2967](https://github.com/modelcontextprotocol/python-sdk/pull/2967)
+(`ae13ede`), which widened the tool/prompt/resource handler return types to
+include `InputRequiredResult`. This story graduates from a README stub to a
+runnable example once this branch's base includes that commit.
 
 ## Spec
 
@@ -23,4 +25,6 @@ The TypeScript SDK ships a runnable `mrtr` story:
 ## See also
 
 `legacy_elicitation/` and `sampling/` — the handshake-era push equivalents that
-this mechanism replaces on the 2026 protocol.
+this mechanism replaces on the 2026 protocol. The TypeScript SDK ships a single
+dual-era `elicitation/` story covering both eras in one place; we re-merge
+`legacy_elicitation/` back into `elicitation/` once MRTR lands.
diff --git a/examples/stories/oauth/client.py b/examples/stories/oauth/client.py
@@ -1,4 +1,4 @@
-"""OAuth authorization-code flow: 401 → PRM → AS metadata → DCR → PKCE authorize → token → retry."""
+"""HTTP-only OAuth authorization-code flow; `build_auth` supplies the provider, reconnecting needs `targets`."""
 
 import httpx
 from pydantic import AnyUrl
diff --git a/examples/stories/oauth/server.py b/examples/stories/oauth/server.py
@@ -1,4 +1,4 @@
-"""OAuth-protected MCP server: in-process AS + PRM + bearer-gated /mcp on one Starlette app."""
+"""OAuth-protected MCP server: in-process AS + PRM + bearer-gated /mcp on one Starlette app — exports `build_app()`."""
 
 from pydantic import BaseModel
 from starlette.applications import Starlette
diff --git a/examples/stories/oauth_client_credentials/client.py b/examples/stories/oauth_client_credentials/client.py
@@ -1,4 +1,4 @@
-"""Connect with ``ClientCredentialsOAuthProvider``; assert ``whoami`` round-trips client_id + scopes."""
+"""HTTP-only: ``build_auth`` returns a ``ClientCredentialsOAuthProvider``; ``whoami`` round-trips client_id + scopes."""
 
 import httpx
 
diff --git a/examples/stories/oauth_client_credentials/server.py b/examples/stories/oauth_client_credentials/server.py
@@ -1,4 +1,4 @@
-"""Bearer-gated MCP resource server + a minimal in-process ``client_credentials`` AS, one app."""
+"""Bearer-gated resource server + a minimal in-process ``client_credentials`` AS, one app; exports ``build_app()``."""
 
 import base64
 import secrets
diff --git a/examples/stories/parallel_calls/client.py b/examples/stories/parallel_calls/client.py
@@ -1,4 +1,4 @@
-"""Two concurrent `Client`s against one server; the rendezvous tool proves concurrent dispatch."""
+"""Two concurrent `Client`s, so `main` takes `targets`; their rendezvous in one tool proves concurrent dispatch."""
 
 import anyio
 
diff --git a/examples/stories/reconnect/client.py b/examples/stories/reconnect/client.py
@@ -1,4 +1,4 @@
-"""Probe server/discover once, persist the DiscoverResult, then reconnect with zero round-trips."""
+"""Probe server/discover once, persist the result, reconnect with zero round-trips — a fresh `Client` via `targets`."""
 
 from mcp.client import Client
 from mcp.shared.version import LATEST_MODERN_VERSION
diff --git a/examples/stories/sse_polling/client.py b/examples/stories/sse_polling/client.py
@@ -1,4 +1,4 @@
-"""Call a tool whose SSE stream the server closes mid-flight; assert the call still completes."""
+"""Call a tool whose SSE stream the server closes mid-flight; the call still completes. HTTP-only — no SSE on stdio."""
 
 import anyio
 
diff --git a/examples/stories/sse_polling/server.py b/examples/stories/sse_polling/server.py
@@ -1,4 +1,4 @@
-"""SEP-1699: a tool that closes its own SSE stream mid-call; the event store buffers the rest."""
+"""SEP-1699: a tool closes its own SSE stream mid-call; the event store buffers the rest. Exports `build_app()`."""
 
 from starlette.applications import Starlette
 
diff --git a/examples/stories/starlette_mount/client.py b/examples/stories/starlette_mount/client.py
@@ -1,4 +1,4 @@
-"""Connect to the sub-mounted MCP endpoint at /api/, list tools and call greet."""
+"""Connect to the sub-mounted MCP endpoint at /api/, list tools and call greet. HTTP-only: the mount is the story."""
 
 from mcp.client import Client
 from mcp.types import TextContent
diff --git a/examples/stories/starlette_mount/server.py b/examples/stories/starlette_mount/server.py
@@ -1,4 +1,4 @@
-"""Mount an MCPServer inside an existing Starlette app at a sub-path, alongside non-MCP routes."""
+"""Mount an MCPServer in an existing Starlette app at a sub-path, alongside non-MCP routes; exports `build_app()`."""
 
 import contextlib
 from collections.abc import AsyncIterator
diff --git a/examples/stories/stateless_legacy/client.py b/examples/stories/stateless_legacy/client.py
@@ -1,4 +1,4 @@
-"""Connect at each era; the same stateless app answers both with the same result."""
+"""Connect at each era — two connections, so `main` takes `targets`; the same stateless app answers both."""
 
 from mcp.client import Client
 from mcp.shared.version import LATEST_HANDSHAKE_VERSION, LATEST_MODERN_VERSION
diff --git a/examples/stories/stateless_legacy/server.py b/examples/stories/stateless_legacy/server.py
@@ -1,4 +1,4 @@
-"""The one-liner HTTP deploy: one stateless ASGI app serves both protocol eras."""
+"""The one-liner HTTP deploy: one stateless ASGI app serves both protocol eras, so it exports `build_app()`."""
 
 from starlette.applications import Starlette
 
diff --git a/examples/stories/subscriptions/README.md b/examples/stories/subscriptions/README.md
@@ -6,8 +6,12 @@ them. Replaces the handshake-era `resources/subscribe` + standalone-GET
 notification path.
 
 **Status: not yet implemented** ([#2901](https://github.com/modelcontextprotocol/python-sdk/issues/2901)).
-Types exist; there is no `Client.listen()`, no `ServerEventBus`, and no
-entry-handled `subscriptions/listen` route yet.
+The lowlevel registration surface exists on `main` as of
+[#2967](https://github.com/modelcontextprotocol/python-sdk/pull/2967)
+(`ae13ede`), which added the lowlevel `on_subscriptions_listen` handler slot.
+There is no `Client.listen()` or `ServerEventBus` yet; this story graduates
+from a README stub to a runnable example once this branch's base includes that
+commit.
 
 ## Spec
 
diff --git a/tests/examples/test_story_shape.py b/tests/examples/test_story_shape.py
@@ -0,0 +1,122 @@
+"""AST shape-check: stories keep the SDK construction visible and the harness contained.
+
+The python analogue of typescript-sdk's eslint import-allowlist over its examples,
+strictly stronger: it also asserts each ``main`` constructs ``Client(...)`` itself —
+the regression the harness inversion exists to prevent.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+import pytest
+
+from tests.examples.conftest import STORIES, STORIES_DIR, story_cfg
+
+_HARNESS_ALLOWLIST = frozenset({"run_client", "target_from_args", "Target", "TargetFactory"})
+"""The only ``stories._harness`` names a ``client.py`` may use. ``AuthBuilder`` is
+additionally allowed in a ``client.py`` that defines ``build_auth`` (the auth seam
+``run_client`` and the conftest both look up by name)."""
+
+_MCPSERVER_TIER = ("mcp.server.mcpserver", "mcp.server.MCPServer")
+"""Both spellings of the high-level tier: the ``mcpserver`` module and its ``mcp.server`` re-export."""
+
+_LOWLEVEL_STORIES = [name for name in sorted(STORIES) if story_cfg(name)["lowlevel"]]
+
+
+def _parse(path: Path) -> ast.Module:
+    """Parse ``path`` into an AST module."""
+    return ast.parse(path.read_text(), filename=str(path))
+
+
+def _resolve(node: ast.ImportFrom, package: str) -> str:
+    """The absolute module path ``node`` imports from, resolving a relative import against ``package``."""
+    parents = package.split(".")[: -(node.level - 1) or None] if node.level else []
+    return ".".join([*parents, *([node.module] if node.module else [])])
+
+
+def _module_paths(tree: ast.Module, package: str) -> set[str]:
+    """Every dotted module path the file (a module in ``package``) references — imports, with relative
+    ones resolved to absolute, plus attribute chains rooted at an import-bound name (``import mcp.shared``
+    + ``mcp.shared._memory.f()``), so a reach-in is caught however it is spelled."""
+    paths: set[str] = set()
+    bound: dict[str, str] = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                paths.add(alias.name)
+                local = alias.asname or alias.name.partition(".")[0]
+                bound[local] = alias.name if alias.asname else local
+        elif isinstance(node, ast.ImportFrom):
+            module = _resolve(node, package)
+            for alias in node.names:
+                paths.add(f"{module}.{alias.name}")
+                bound[alias.asname or alias.name] = f"{module}.{alias.name}"
+    for node in ast.walk(tree):
+        attrs: list[str] = []
+        expr: ast.AST = node
+        while isinstance(expr, ast.Attribute):
+            attrs.append(expr.attr)
+            expr = expr.value
+        if attrs and isinstance(expr, ast.Name) and expr.id in bound:
+            paths.add(".".join([bound[expr.id], *reversed(attrs)]))
+    return paths
+
+
+def _is_private_mcp(path: str) -> bool:
+    """True when ``path`` crosses a ``_``-private segment inside the ``mcp`` package."""
+    head, *rest = path.split(".")
+    return head == "mcp" and any(part.startswith("_") for part in rest)
+
+
+def _is_story_module(path: str) -> bool:
+    """True for ``stories.<story>...`` — a story package, not a ``stories._*`` scaffold."""
+    head, _, rest = path.partition(".")
+    return head == "stories" and bool(rest) and not rest.startswith("_")
+
+
+@pytest.mark.parametrize("name", sorted(STORIES))
+def test_main_constructs_client_inline(name: str) -> None:
+    """``main``'s body contains a literal ``Client(...)`` call; the construction is never hidden in a helper."""
+    tree = _parse(STORIES_DIR / name / "client.py")
+    mains = [n for n in tree.body if isinstance(n, ast.AsyncFunctionDef) and n.name == "main"]
+    assert mains, f"{name}/client.py defines no top-level async `main`"
+    calls = {n.func.id for n in ast.walk(mains[0]) if isinstance(n, ast.Call) and isinstance(n.func, ast.Name)}
+    assert "Client" in calls, f"{name}/client.py: main() never calls Client(...) itself"
+
+
+@pytest.mark.parametrize("name", sorted(STORIES))
+def test_client_harness_imports_within_allowlist(name: str) -> None:
+    """``client.py`` takes nothing from ``stories._harness`` beyond the allowlist, bounding the harness surface."""
+    tree = _parse(STORIES_DIR / name / "client.py")
+    defines_build_auth = any(isinstance(n, ast.FunctionDef) and n.name == "build_auth" for n in tree.body)
+    allowed = _HARNESS_ALLOWLIST | {"AuthBuilder"} if defines_build_auth else _HARNESS_ALLOWLIST
+    paths = _module_paths(tree, package=f"stories.{name}")
+    used = {p.removeprefix("stories._harness.").partition(".")[0] for p in paths if p.startswith("stories._harness.")}
+    assert used <= allowed, f"{name}/client.py uses {sorted(used - allowed)} from stories._harness"
+
+
+@pytest.mark.parametrize("name", sorted(STORIES))
+def test_story_files_import_no_private_mcp_module(name: str) -> None:
+    """No file in a story directory references a ``_``-private ``mcp.*`` module."""
+    for path in sorted((STORIES_DIR / name).glob("*.py")):
+        private = sorted(p for p in _module_paths(_parse(path), package=f"stories.{name}") if _is_private_mcp(p))
+        assert not private, f"{path.relative_to(STORIES_DIR)} reaches into private mcp module(s): {private}"
+
+
+@pytest.mark.parametrize("name", _LOWLEVEL_STORIES)
+def test_server_lowlevel_imports_no_mcpserver_tier(name: str) -> None:
+    """``server_lowlevel.py`` stays on the lowlevel tier; it never references ``MCPServer`` or its module."""
+    paths = _module_paths(_parse(STORIES_DIR / name / "server_lowlevel.py"), package=f"stories.{name}")
+    high = sorted(p for p in paths if any(f"{p}.".startswith(f"{tier}.") for tier in _MCPSERVER_TIER))
+    assert not high, f"{name}/server_lowlevel.py references the MCPServer tier: {high}"
+
+
+@pytest.mark.parametrize("scaffold", ["_harness.py", "_hosting.py"])
+def test_scaffold_imports_no_story_module(scaffold: str) -> None:
+    """The dependency is one-way: ``_harness.py`` / ``_hosting.py`` import no ``stories.<story>`` module."""
+    story_refs = sorted(
+        p for p in _module_paths(_parse(STORIES_DIR / scaffold), package="stories") if _is_story_module(p)
+    )
+    assert not story_refs, f"{scaffold} imports a story module: {story_refs}"

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-"""Call the bearer-gated server through an already-authed transport; assert the ``whoami`` principal."""
	`1`	+"""Call the bearer-gated server through an already-authed (``build_auth``, HTTP-only) transport; assert ``whoami``."""
`2`	`2`
`3`	`3`	`from collections.abc import Generator`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-"""Resource-server-only bearer auth: ``TokenVerifier`` + ``AuthSettings`` → 401/PRM/principal."""
	`1`	+"""Resource-server-only bearer auth: ``TokenVerifier``/``AuthSettings`` → 401/PRM/principal. Exports ``build_app()``."""
`2`	`2`
`3`	`3`	`import time`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-"""Connect to the same server factory twice — once per era — and assert both are served."""`
	`1`	+"""Connect to the same server factory twice — once per era, so `main` takes `targets` — and assert both are served."""
`2`	`2`
`3`	`3`	`from mcp import types`
`4`	`4`	`from mcp.client import Client`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-"""Regular ``Client`` against a JSON-only server; assert mid-call progress is dropped.
	`1`	+"""Plain ``Client`` against a JSON-only server: mid-call progress drops. HTTP-only — ``main`` also takes ``http``.
`2`	`2`
`3`	`3`	``RAW_ENVELOPE_BODY`` / ``MODERN_HEADERS`` are the exact wire shape a 2026-era client
`4`	`4`	sends — this is the only story that shows it. ``main`` posts that body by hand and
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-"""Serve over Streamable HTTP with JSON responses (no SSE stream).`
	`1`	+"""Serve over Streamable HTTP with JSON responses (no SSE stream); HTTP-only, so this exports ``build_app()``.
`2`	`2`
`3`	`3`	`The 2026-07-28 path is stateless and JSON-only by construction today; the`
`4`	`4`	``json_response=True`` flag also forces JSON for the legacy (2025-era) branch on