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

docs_src/resources/tutorial001.py

@@ -0,0 +1,9 @@
+from mcp.server import MCPServer
+
+mcp = MCPServer("Bookshop")
+
+
+@mcp.resource("config://app")
+def get_config() -> str:
+    """The active shop configuration."""
+    return "theme=dark\nlanguage=en"

docs_src/resources/tutorial002.py

@@ -0,0 +1,15 @@
+from mcp.server import MCPServer
+
+mcp = MCPServer("Bookshop")
+
+
+@mcp.resource("config://app")
+def get_config() -> str:
+    """The active shop configuration."""
+    return "theme=dark\nlanguage=en"
+
+
+@mcp.resource("users://{user_id}/profile")
+def get_user_profile(user_id: str) -> str:
+    """A customer's profile."""
+    return f"User {user_id}: 12 orders since 2021."

docs_src/resources/tutorial003.py

@@ -0,0 +1,23 @@
+import base64
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("Bookshop")
+
+
+@mcp.resource("docs://readme", mime_type="text/markdown")
+def readme() -> str:
+    """How to use this server."""
+    return "# Bookshop\n\nSearch the catalog with the `search_books` tool."
+
+
+@mcp.resource("stats://catalog", mime_type="application/json")
+def catalog_stats() -> dict[str, int]:
+    """Live counts for the catalog."""
+    return {"books": 1204, "authors": 391}
+
+
+@mcp.resource("covers://placeholder", mime_type="image/gif")
+def placeholder_cover() -> bytes:
+    """A 1x1 transparent GIF, shown when a book has no cover."""
+    return base64.b64decode("R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7")