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

docs_src/handling_errors/tutorial001.py

@@ -0,0 +1,13 @@
+from mcp.server import MCPServer
+
+mcp = MCPServer("Bookshop")
+
+CATALOG = {"Dune": "Frank Herbert", "Neuromancer": "William Gibson"}
+
+
+@mcp.tool()
+def get_author(title: str) -> str:
+    """Look up the author of a book in the catalog."""
+    if title not in CATALOG:
+        raise ValueError(f"No book titled {title!r} in the catalog.")
+    return CATALOG[title]

docs_src/handling_errors/tutorial002.py

@@ -0,0 +1,16 @@
+from mcp_types import INVALID_PARAMS
+
+from mcp import MCPError
+from mcp.server import MCPServer
+
+mcp = MCPServer("Bookshop")
+
+CATALOG = {"Dune": "Frank Herbert", "Neuromancer": "William Gibson"}
+
+
+@mcp.tool()
+def get_author(title: str) -> str:
+    """Look up the author of a book in the catalog."""
+    if title not in CATALOG:
+        raise MCPError(code=INVALID_PARAMS, message=f"No book titled {title!r} in the catalog.")
+    return CATALOG[title]

docs_src/handling_errors/tutorial003.py

@@ -0,0 +1,14 @@
+from mcp.server import MCPServer
+from mcp.server.mcpserver.exceptions import ResourceNotFoundError
+
+mcp = MCPServer("Bookshop")
+
+CATALOG = {"Dune": "Frank Herbert", "Neuromancer": "William Gibson"}
+
+
+@mcp.resource("books://{title}")
+def book(title: str) -> str:
+    """The catalog entry for one book."""
+    if title not in CATALOG:
+        raise ResourceNotFoundError(f"No book titled {title!r} in the catalog.")
+    return f"{title} by {CATALOG[title]}"