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

docs_src/tools/tutorial001.py

@@ -0,0 +1,9 @@
+from mcp.server import MCPServer
+
+mcp = MCPServer("Bookshop")
+
+
+@mcp.tool()
+def search_books(query: str, limit: int) -> str:
+    """Search the catalog by title or author."""
+    return f"Found 3 books matching {query!r} (showing up to {limit})."

docs_src/tools/tutorial002.py

@@ -0,0 +1,9 @@
+from mcp.server import MCPServer
+
+mcp = MCPServer("Bookshop")
+
+
+@mcp.tool()
+def search_books(query: str, limit: int = 10) -> str:
+    """Search the catalog by title or author."""
+    return f"Found 3 books matching {query!r} (showing up to {limit})."

docs_src/tools/tutorial003.py

@@ -0,0 +1,18 @@
+from typing import Annotated, Literal
+
+from pydantic import Field
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("Bookshop")
+
+
+@mcp.tool()
+def search_books(
+    query: Annotated[str, Field(description="Title or author to search for.")],
+    limit: Annotated[int, Field(ge=1, le=50, description="Maximum number of results.")] = 10,
+    genre: Literal["fiction", "non-fiction", "poetry"] | None = None,
+) -> str:
+    """Search the catalog by title or author."""
+    where = f" in {genre}" if genre else ""
+    return f"Found 3 books matching {query!r}{where} (showing up to {limit})."

docs_src/tools/tutorial004.py

@@ -0,0 +1,17 @@
+from pydantic import BaseModel, Field
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("Bookshop")
+
+
+class Book(BaseModel):
+    title: str
+    author: str
+    year: int = Field(ge=1450, description="Year of first publication.")
+
+
+@mcp.tool()
+def add_book(book: Book) -> str:
+    """Add a book to the catalog."""
+    return f"Added {book.title!r} by {book.author} ({book.year})."

docs_src/tools/tutorial005.py

@@ -0,0 +1,14 @@
+from mcp_types import ToolAnnotations
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("Bookshop")
+
+
+@mcp.tool(
+    title="Search the catalog",
+    annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
+)
+def search_books(query: str) -> str:
+    """Search the catalog by title or author."""
+    return f"Found 3 books matching {query!r}."