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

docs_src/media/tutorial001.py

@@ -0,0 +1,16 @@
+import base64
+
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Image
+
+mcp = MCPServer("Brand kit")
+
+LOGO_PNG = base64.b64decode(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGOQ9bsBAAHPAURf8l/aAAAAAElFTkSuQmCC"
+)
+
+
+@mcp.tool()
+def logo() -> Image:
+    """The brand logo as a PNG."""
+    return Image(data=LOGO_PNG, format="png")

docs_src/media/tutorial002.py

@@ -0,0 +1,24 @@
+import base64
+
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Audio, Image
+
+mcp = MCPServer("Brand kit")
+
+LOGO_PNG = base64.b64decode(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGOQ9bsBAAHPAURf8l/aAAAAAElFTkSuQmCC"
+)
+
+CHIME_WAV = base64.b64decode("UklGRjQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YRAAAAAAAAAAAAAAAAAAAAAAAAAA")
+
+
+@mcp.tool()
+def logo() -> Image:
+    """The brand logo as a PNG."""
+    return Image(data=LOGO_PNG, format="png")
+
+
+@mcp.tool()
+def chime() -> Audio:
+    """The notification chime as a WAV."""
+    return Audio(data=CHIME_WAV, format="wav")

docs_src/media/tutorial003.py

@@ -0,0 +1,20 @@
+from mcp_types import Icon
+
+from mcp.server import MCPServer
+
+LOGO = Icon(src="https://example.com/brand-kit.png", mime_type="image/png", sizes=["48x48"])
+PALETTE = Icon(src="https://example.com/palette.svg", mime_type="image/svg+xml", sizes=["any"])
+
+mcp = MCPServer("Brand kit", icons=[LOGO])
+
+
+@mcp.tool(icons=[PALETTE])
+def palette() -> list[str]:
+    """The brand colour palette as hex codes."""
+    return ["#1d4ed8", "#f59e0b", "#10b981"]
+
+
+@mcp.resource("brand://guidelines", icons=[LOGO])
+def guidelines() -> str:
+    """How to use the brand assets."""
+    return "Use the primary colour for calls to action."