chore: import upstream snapshot with attribution

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)

docs_src/elicitation/tutorial004.py

@@ -0,0 +1,47 @@
+from typing import Annotated
+
+from pydantic import BaseModel
+
+from mcp.server import MCPServer
+from mcp.server.mcpserver import (
+    AcceptedElicitation,
+    CancelledElicitation,
+    DeclinedElicitation,
+    Elicit,
+    ElicitationResult,
+    Resolve,
+)
+
+mcp = MCPServer("Files")
+
+_FOLDERS: dict[str, list[str]] = {"/tmp/empty": [], "/tmp/project": ["main.py", "README.md"]}
+
+
+class Confirm(BaseModel):
+    ok: bool
+
+
+async def confirm_delete(path: str) -> Confirm | Elicit[Confirm]:
+    """Resolver: ask for confirmation only when the folder is not empty."""
+    file_count = len(_FOLDERS.get(path, []))
+    if file_count == 0:
+        return Confirm(ok=True)  # nothing to confirm, no round-trip to the client
+    return Elicit(f"{path} has {file_count} file(s). Delete anyway?", Confirm)
+
+
+@mcp.tool()
+async def delete_folder(
+    path: str,
+    confirm: Annotated[ElicitationResult[Confirm], Resolve(confirm_delete)],
+) -> str:
+    """Delete a folder, asking for confirmation when it is not empty."""
+    match confirm:
+        case AcceptedElicitation(data=Confirm(ok=True)):
+            _FOLDERS.pop(path, None)
+            return f"deleted {path}"
+        case AcceptedElicitation():
+            return "kept the folder"
+        case DeclinedElicitation():
+            return "declined: folder not deleted"
+        case CancelledElicitation():
+            return "cancelled: folder not deleted"