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

docs_src/mrtr/tutorial001.py

@@ -0,0 +1,53 @@
+from mcp_types import (
+    CallToolRequestParams,
+    CallToolResult,
+    ElicitRequest,
+    ElicitRequestFormParams,
+    ElicitResult,
+    InputRequiredResult,
+    ListToolsResult,
+    PaginatedRequestParams,
+    TextContent,
+    Tool,
+)
+
+from mcp.server import Server, ServerRequestContext
+
+ASK_REGION = ElicitRequest(
+    params=ElicitRequestFormParams(
+        message="Which region should the database live in?",
+        requested_schema={
+            "type": "object",
+            "properties": {"region": {"type": "string"}},
+            "required": ["region"],
+        },
+    )
+)
+
+
+async def list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
+    return ListToolsResult(
+        tools=[
+            Tool(
+                name="provision",
+                description="Provision a database. Asks which region to put it in.",
+                input_schema={
+                    "type": "object",
+                    "properties": {"name": {"type": "string"}},
+                    "required": ["name"],
+                },
+            )
+        ]
+    )
+
+
+async def call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult | InputRequiredResult:
+    answer = (params.input_responses or {}).get("region")
+    if not isinstance(answer, ElicitResult) or answer.content is None:
+        return InputRequiredResult(input_requests={"region": ASK_REGION}, request_state="provision-v1")
+    name = (params.arguments or {})["name"]
+    text = f"Provisioned {name!r} in {answer.content['region']}."
+    return CallToolResult(content=[TextContent(type="text", text=text)])
+
+
+server = Server("Provisioner", on_list_tools=list_tools, on_call_tool=call_tool)

docs_src/mrtr/tutorial002.py

@@ -0,0 +1,23 @@
+from mcp_types import CallToolResult, ElicitRequest, ElicitResult, InputRequest, InputRequiredResult, InputResponse
+
+from mcp import Client
+
+
+def fulfil(request: InputRequest) -> InputResponse:
+    if not isinstance(request, ElicitRequest):
+        raise NotImplementedError(f"this client cannot answer a {request.method!r} request")
+    return ElicitResult(action="accept", content={"region": "eu-west-1"})
+
+
+async def provision(client: Client, name: str) -> CallToolResult:
+    result = await client.call_tool("provision", {"name": name}, allow_input_required=True)
+    while isinstance(result, InputRequiredResult):
+        responses = {key: fulfil(request) for key, request in (result.input_requests or {}).items()}
+        result = await client.call_tool(
+            "provision",
+            {"name": name},
+            input_responses=responses,
+            request_state=result.request_state,
+            allow_input_required=True,
+        )
+    return result