docs: restructure into topical sections and add the four most-asked-for pages (#3044)

docs_src/legacy_clients/tutorial001.py

@@ -0,0 +1,42 @@
+from typing import Annotated
+
+from mcp_types import ElicitRequestParams, ElicitResult
+from pydantic import BaseModel
+
+from mcp import Client
+from mcp.client import ClientRequestContext
+from mcp.server import MCPServer
+from mcp.server.mcpserver import AcceptedElicitation, Elicit, ElicitationResult, Resolve
+
+mcp = MCPServer("Bookshop")
+
+
+class Quantity(BaseModel):
+    copies: int
+
+
+async def ask_quantity() -> Elicit[Quantity]:
+    """Resolver: ask the user how many copies to put aside."""
+    return Elicit("How many copies?", Quantity)
+
+
+@mcp.tool()
+async def reserve(title: str, quantity: Annotated[ElicitationResult[Quantity], Resolve(ask_quantity)]) -> str:
+    """Reserve copies of a book, asking the user how many."""
+    if isinstance(quantity, AcceptedElicitation):
+        return f"Reserved {quantity.data.copies} of {title!r}."
+    return "Nothing reserved."
+
+
+async def answer(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
+    return ElicitResult(action="accept", content={"copies": 2})
+
+
+async def main() -> None:
+    async with (
+        Client(mcp, mode="legacy", elicitation_callback=answer) as legacy,
+        Client(mcp, elicitation_callback=answer) as modern,
+    ):
+        for client in (legacy, modern):
+            result = await client.call_tool("reserve", {"title": "Dune"})
+            print(client.protocol_version, result.structured_content)

docs_src/legacy_clients/tutorial002.py

@@ -0,0 +1,28 @@
+from typing import Annotated
+
+from pydantic import BaseModel
+
+from mcp.server import MCPServer
+from mcp.server.mcpserver import AcceptedElicitation, Elicit, ElicitationResult, Resolve
+
+mcp = MCPServer("Bookshop")
+
+
+class Quantity(BaseModel):
+    copies: int
+
+
+async def ask_quantity() -> Elicit[Quantity]:
+    """Resolver: ask the user how many copies to put aside."""
+    return Elicit("How many copies?", Quantity)
+
+
+@mcp.tool()
+async def reserve(title: str, quantity: Annotated[ElicitationResult[Quantity], Resolve(ask_quantity)]) -> str:
+    """Reserve copies of a book, asking the user how many."""
+    if isinstance(quantity, AcceptedElicitation):
+        return f"Reserved {quantity.data.copies} of {title!r}."
+    return "Nothing reserved."
+
+
+app = mcp.streamable_http_app(stateless_http=True)

docs_src/legacy_clients/tutorial003.py

@@ -0,0 +1,21 @@
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Context
+
+mcp = MCPServer("Bookshop")
+
+STOCK = {"Dune": 3}
+
+
+@mcp.resource("stock://{title}")
+def stock(title: str) -> str:
+    """How many copies of one book are on the shelf."""
+    return f"{STOCK[title]} in stock"
+
+
+@mcp.tool()
+async def restock(title: str, copies: int, ctx: Context) -> str:
+    """Put copies of a book back on the shelf."""
+    STOCK[title] = STOCK.get(title, 0) + copies
+    await ctx.notify_resource_updated(f"stock://{title}")
+    await ctx.session.send_resource_updated(f"stock://{title}")
+    return f"{STOCK[title]} in stock"