Rebuild the docs around tested examples; shrink README.v2.md to a pitch (#2978)

docs_src/pagination/tutorial001.py

@@ -0,0 +1,20 @@
+from typing import Any
+
+from mcp_types import ListResourcesResult, PaginatedRequestParams, Resource
+
+from mcp.server import Server, ServerRequestContext
+
+BOOKS = [f"book-{n}" for n in range(1, 101)]
+
+PAGE_SIZE = 10
+
+
+async def list_books(ctx: ServerRequestContext[Any], params: PaginatedRequestParams | None) -> ListResourcesResult:
+    start = 0 if params is None or params.cursor is None else int(params.cursor)
+    end = start + PAGE_SIZE
+    page = [Resource(uri=f"books://catalog/{name}", name=name) for name in BOOKS[start:end]]
+    next_cursor = str(end) if end < len(BOOKS) else None
+    return ListResourcesResult(resources=page, next_cursor=next_cursor)
+
+
+server = Server("Bookshop", on_list_resources=list_books)