chore: import upstream snapshot with attribution

examples/stories/pagination/README.md

@@ -0,0 +1,52 @@
+# pagination
+
+Walk a paginated `resources/list` by hand: feed each result's `next_cursor`
+back into `list_resources(cursor=...)` until it is `None`. The cursor is an
+opaque server-chosen string — never parse it, and never terminate on a falsy
+check (an empty string is a valid cursor under the spec).
+
+## Run it
+
+```bash
+# stdio (default — the client spawns the server as a subprocess)
+uv run python -m stories.pagination.client --server server_lowlevel
+
+# HTTP — the client self-hosts the server on a free port, runs, then tears it down
+uv run python -m stories.pagination.client --http --server server_lowlevel
+```
+
+Drop `--server server_lowlevel` (on either transport) to run against the
+`MCPServer` variant (single page).
+
+## What to look at
+
+- `client.py` `main` — `async with Client(target, mode=mode) as client:` is the
+  whole connection. The story owns the construction; `target` is whatever
+  `Client()` accepts (an in-process server, a transport, or an HTTP URL) and
+  the entry point picks it.
+- `client.py` — `if page.next_cursor is None: break`. Termination is
+  key-absent, not falsy; `while cursor:` would be a spec bug.
+- `server_lowlevel.py` — the handler owns the cursor encoding (here: an
+  integer offset as a string) and rejects an unrecognised cursor with
+  `-32602 Invalid params`, the spec-recommended response.
+- `server.py` — `MCPServer`'s decorator-registered resources are returned in
+  a single page; the inbound `cursor` is accepted but ignored. The same client
+  loop still terminates correctly after one request.
+
+## Caveats
+
+- **No `iter_*()` helper** — `Client` has no `iter_resources()` /
+  `iter_tools()` async-iterator yet; the manual `while True` loop shown here
+  is the supported pattern.
+- **MCPServer is single-page** — `MCPServer` ignores `cursor` and never sets
+  `next_cursor`. Whether it grows a `page_size=` knob or stays single-page by
+  design is open; use the lowlevel server when you need to emit pages today.
+
+## Spec
+
+[Pagination — server utilities](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/pagination)
+
+## See also
+
+`resources/`, `tools/`, `prompts/` — every `*/list` method paginates the same
+way. Reference test: `tests/interaction/lowlevel/test_pagination.py`.

examples/stories/pagination/client.py

@@ -0,0 +1,27 @@
+"""Walk every page of resources/list by hand until next_cursor is absent."""
+
+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:
+        names: list[str] = []
+        cursor: str | None = None
+        pages_fetched = 0
+        while True:
+            page = await client.list_resources(cursor=cursor)
+            pages_fetched += 1
+            assert pages_fetched <= 6, "server kept returning next_cursor — runaway guard"
+            names.extend(r.name for r in page.resources)
+            if page.next_cursor is None:  # terminate on absent, NOT on falsy: "" is a valid cursor
+                break
+            cursor = page.next_cursor
+
+        assert names == ["alpha", "beta", "gamma", "delta", "epsilon", "zeta"], names
+        # server_lowlevel.py emits 3 pages of 2; server.py (MCPServer's flat registry) emits 1.
+        assert pages_fetched in (1, 3), pages_fetched
+
+
+if __name__ == "__main__":
+    run_client(main)

examples/stories/pagination/server.py

@@ -0,0 +1,24 @@
+"""Six static resources on MCPServer; its built-in registry serves them as one page."""
+
+from mcp.server.mcpserver import MCPServer
+from stories._hosting import run_server_from_args
+
+WORDS = ("alpha", "beta", "gamma", "delta", "epsilon", "zeta")
+
+
+def build_server() -> MCPServer:
+    mcp = MCPServer("pagination-example")
+
+    def register(word: str) -> None:
+        @mcp.resource(f"word://{word}", name=word, mime_type="text/plain")
+        def read() -> str:
+            return word
+
+    for word in WORDS:
+        register(word)
+
+    return mcp
+
+
+if __name__ == "__main__":
+    run_server_from_args(build_server)

examples/stories/pagination/server_lowlevel.py

@@ -0,0 +1,36 @@
+"""Paginated resources/list (lowlevel API): pages of two via an opaque integer-offset cursor."""
+
+from typing import Any
+
+import mcp_types as types
+
+from mcp.server.context import ServerRequestContext
+from mcp.server.lowlevel import Server
+from mcp.shared.exceptions import MCPError
+from stories._hosting import run_server_from_args
+
+WORDS = ("alpha", "beta", "gamma", "delta", "epsilon", "zeta")
+PAGE_SIZE = 2
+
+
+def build_server() -> Server[Any]:
+    async def list_resources(
+        ctx: ServerRequestContext[Any], params: types.PaginatedRequestParams | None
+    ) -> types.ListResourcesResult:
+        start = 0
+        if params is not None and params.cursor is not None:
+            if not params.cursor.isdigit() or int(params.cursor) >= len(WORDS):
+                raise MCPError(code=types.INVALID_PARAMS, message=f"Unknown cursor: {params.cursor!r}")
+            start = int(params.cursor)
+        page = WORDS[start : start + PAGE_SIZE]
+        next_start = start + PAGE_SIZE
+        return types.ListResourcesResult(
+            resources=[types.Resource(uri=f"word://{w}", name=w) for w in page],
+            next_cursor=str(next_start) if next_start < len(WORDS) else None,
+        )
+
+    return Server("pagination-example", on_list_resources=list_resources)
+
+
+if __name__ == "__main__":
+    run_server_from_args(build_server)