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

docs_src/client_callbacks/tutorial001.py

@@ -0,0 +1,19 @@
+from pydantic import BaseModel
+
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Context
+
+mcp = MCPServer("Library")
+
+
+class CardHolder(BaseModel):
+    name: str
+
+
+@mcp.tool()
+async def issue_card(ctx: Context) -> str:
+    """Issue a new library card."""
+    answer = await ctx.elicit("What name should go on the card?", schema=CardHolder)
+    if answer.action == "accept":
+        return f"Card issued to {answer.data.name}."
+    return "No card issued."

docs_src/client_callbacks/tutorial002.py

@@ -0,0 +1,21 @@
+from mcp_types import ElicitRequestParams, ElicitResult
+
+from mcp import Client
+from mcp.client import ClientRequestContext
+
+
+async def handle_elicitation(
+    context: ClientRequestContext,
+    params: ElicitRequestParams,
+) -> ElicitResult:
+    return ElicitResult(action="accept", content={"name": "Ada Lovelace"})
+
+
+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("issue_card")
+        print(result.content)

docs_src/client_callbacks/tutorial003.py

@@ -0,0 +1,31 @@
+from mcp_types import ClientCapabilities, ElicitationCapability, RootsCapability, SamplingCapability
+from pydantic import BaseModel
+
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Context
+
+mcp = MCPServer("Library")
+
+
+class CardHolder(BaseModel):
+    name: str
+
+
+@mcp.tool()
+async def issue_card(ctx: Context) -> str:
+    """Issue a new library card."""
+    answer = await ctx.elicit("What name should go on the card?", schema=CardHolder)
+    if answer.action == "accept":
+        return f"Card issued to {answer.data.name}."
+    return "No card issued."
+
+
+@mcp.tool()
+def client_features(ctx: Context) -> list[str]:
+    """Which optional features the connected client declared."""
+    declared = {
+        "elicitation": ClientCapabilities(elicitation=ElicitationCapability()),
+        "sampling": ClientCapabilities(sampling=SamplingCapability()),
+        "roots": ClientCapabilities(roots=RootsCapability()),
+    }
+    return [name for name, capability in declared.items() if ctx.session.check_client_capability(capability)]

docs_src/client_callbacks/tutorial004.py

@@ -0,0 +1,19 @@
+from mcp_types import CreateMessageRequestParams, CreateMessageResult, ListRootsResult, Root, TextContent
+from pydantic import FileUrl
+
+from mcp.client import ClientRequestContext
+
+
+async def handle_sampling(
+    context: ClientRequestContext,
+    params: CreateMessageRequestParams,
+) -> CreateMessageResult:
+    return CreateMessageResult(
+        role="assistant",
+        content=TextContent(type="text", text="The answer is 42."),
+        model="my-llm",
+    )
+
+
+async def handle_list_roots(context: ClientRequestContext) -> ListRootsResult:
+    return ListRootsResult(roots=[Root(uri=FileUrl("file:///home/ada/notebooks"), name="notebooks")])