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

docs_src/context/tutorial001.py

@@ -0,0 +1,10 @@
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Context
+
+mcp = MCPServer("Bookshop")
+
+
+@mcp.tool()
+def search_books(query: str, ctx: Context) -> str:
+    """Search the catalog by title or author."""
+    return f"[request {ctx.request_id}] Found 3 books matching {query!r}."

docs_src/context/tutorial002.py

@@ -0,0 +1,17 @@
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Context
+
+mcp = MCPServer("Bookshop")
+
+
+@mcp.resource("catalog://genres")
+def genres() -> str:
+    """The genres the catalog is organised into."""
+    return "fiction, non-fiction, poetry"
+
+
+@mcp.tool()
+async def describe_catalog(ctx: Context) -> str:
+    """Describe how the catalog is organised."""
+    [contents] = await ctx.read_resource("catalog://genres")
+    return f"The catalog is organised into: {contents.content}"

docs_src/context/tutorial003.py

@@ -0,0 +1,17 @@
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Context
+
+mcp = MCPServer("Bookshop")
+
+
+def recommend_book(genre: str) -> str:
+    """Recommend a book in the given genre."""
+    return f"In {genre}, try 'Dune'."
+
+
+@mcp.tool()
+async def enable_recommendations(ctx: Context) -> str:
+    """Switch on the recommendation tool."""
+    mcp.add_tool(recommend_book)
+    await ctx.session.send_tool_list_changed()
+    return "Recommendations are now available."