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

docs_src/elicitation/tutorial001.py

@@ -0,0 +1,26 @@
+from pydantic import BaseModel, Field
+
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Context
+
+mcp = MCPServer("Bistro")
+
+
+class AlternativeDate(BaseModel):
+    accept_alternative: bool = Field(description="Try another date?")
+    date: str = Field(default="2025-12-26", description="Alternative date (YYYY-MM-DD)")
+
+
+@mcp.tool()
+async def book_table(date: str, party_size: int, ctx: Context) -> str:
+    """Book a table at the bistro."""
+    if date != "2025-12-25":
+        return f"Booked a table for {party_size} on {date}."
+
+    result = await ctx.elicit(
+        message=f"No tables for {party_size} on {date}. Would you like to try another date?",
+        schema=AlternativeDate,
+    )
+    if result.action == "accept" and result.data.accept_alternative:
+        return await book_table(result.data.date, party_size, ctx)
+    return "No booking made."

docs_src/elicitation/tutorial002.py

@@ -0,0 +1,24 @@
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Context
+
+mcp = MCPServer("Bistro")
+
+
+@mcp.tool()
+async def pay_deposit(booking_id: str, ctx: Context) -> str:
+    """Take the deposit that confirms a booking."""
+    result = await ctx.elicit_url(
+        message="A 20 EUR deposit confirms your booking.",
+        url=f"https://pay.example.com/deposit/{booking_id}",
+        elicitation_id=f"deposit-{booking_id}",
+    )
+    if result.action == "accept":
+        return "Complete the payment in your browser."
+    return "No deposit taken. The booking expires in one hour."
+
+
+@mcp.tool()
+async def confirm_deposit(booking_id: str, ctx: Context) -> str:
+    """Record a payment reported by the payment provider."""
+    await ctx.session.send_elicit_complete(f"deposit-{booking_id}")
+    return f"Deposit received for booking {booking_id}."

docs_src/elicitation/tutorial003.py

@@ -0,0 +1,22 @@
+from mcp_types import ElicitRequestParams, ElicitRequestURLParams, ElicitResult
+
+from mcp import Client
+from mcp.client import ClientRequestContext
+
+
+async def handle_elicitation(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
+    if isinstance(params, ElicitRequestURLParams):
+        print(f"Open this link to continue: {params.url}")
+        return ElicitResult(action="accept")
+    print(params.message)
+    return ElicitResult(action="accept", content={"accept_alternative": True, "date": "2025-12-27"})
+
+
+async def main() -> None:
+    async with Client(
+        "http://127.0.0.1:8000/mcp",
+        mode="legacy",
+        elicitation_callback=handle_elicitation,
+    ) as client:
+        result = await client.call_tool("book_table", {"date": "2025-12-25", "party_size": 2})
+        print(result.content)