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

docs_src/deploy/tutorial001.py

@@ -0,0 +1,17 @@
+from mcp.server import MCPServer
+from mcp.server.transport_security import TransportSecuritySettings
+
+mcp = MCPServer("Notes")
+
+
+@mcp.tool()
+def add_note(text: str) -> str:
+    """Save a note."""
+    return f"Saved: {text}"
+
+
+security = TransportSecuritySettings(
+    allowed_hosts=["mcp.example.com", "mcp.example.com:*"],
+    allowed_origins=["https://app.example.com"],
+)
+app = mcp.streamable_http_app(transport_security=security)

docs_src/deploy/tutorial002.py

@@ -0,0 +1,27 @@
+from mcp_types import ElicitRequest, ElicitRequestFormParams, ElicitResult, InputRequiredResult
+
+from mcp.server.mcpserver import Context, MCPServer
+
+CONFIRM = ElicitRequest(
+    params=ElicitRequestFormParams(
+        message="Issue this refund?",
+        requested_schema={"type": "object", "properties": {"ok": {"type": "boolean"}}, "required": ["ok"]},
+    )
+)
+
+
+def make_server() -> MCPServer:
+    """Every worker process builds one of these, once, at import."""
+    mcp = MCPServer("billing")
+
+    @mcp.tool()
+    async def refund(amount: int, ctx: Context) -> str | InputRequiredResult:
+        """Refund an amount, once a human has confirmed it."""
+        if ctx.input_responses is None:
+            return InputRequiredResult(input_requests={"ok": CONFIRM}, request_state=f"refund:{amount}")
+        answer = (ctx.input_responses or {}).get("ok")
+        if not isinstance(answer, ElicitResult) or answer.action != "accept" or not (answer.content or {}).get("ok"):
+            return "refund cancelled"
+        return f"refunded ${amount}"
+
+    return mcp

docs_src/deploy/tutorial003.py

@@ -0,0 +1,27 @@
+from mcp_types import ElicitRequest, ElicitRequestFormParams, ElicitResult, InputRequiredResult
+
+from mcp.server.mcpserver import Context, MCPServer, RequestStateSecurity
+
+CONFIRM = ElicitRequest(
+    params=ElicitRequestFormParams(
+        message="Issue this refund?",
+        requested_schema={"type": "object", "properties": {"ok": {"type": "boolean"}}, "required": ["ok"]},
+    )
+)
+
+
+def make_server(key: str) -> MCPServer:
+    """Every worker process: the same key, and the same name."""
+    mcp = MCPServer("billing", request_state_security=RequestStateSecurity(keys=[key]))
+
+    @mcp.tool()
+    async def refund(amount: int, ctx: Context) -> str | InputRequiredResult:
+        """Refund an amount, once a human has confirmed it."""
+        if ctx.input_responses is None:
+            return InputRequiredResult(input_requests={"ok": CONFIRM}, request_state=f"refund:{amount}")
+        answer = (ctx.input_responses or {}).get("ok")
+        if not isinstance(answer, ElicitResult) or answer.action != "accept" or not (answer.content or {}).get("ok"):
+            return "refund cancelled"
+        return f"refunded ${amount}"
+
+    return mcp

docs_src/deploy/tutorial004.py

@@ -0,0 +1,23 @@
+from mcp.server.mcpserver import Context, MCPServer
+from mcp.server.subscriptions import SubscriptionBus
+
+NOTES = {"todo": "buy milk"}
+
+
+def make_server(bus: SubscriptionBus) -> MCPServer:
+    """Every replica gets its own server object; all of them hold the same bus."""
+    mcp = MCPServer("Notebook", subscriptions=bus)
+
+    @mcp.resource("note://{name}")
+    def note(name: str) -> str:
+        """One note, by name."""
+        return NOTES[name]
+
+    @mcp.tool()
+    async def edit_note(name: str, text: str, ctx: Context) -> str:
+        """Replace a note's text."""
+        NOTES[name] = text
+        await ctx.notify_resource_updated(f"note://{name}")
+        return "saved"
+
+    return mcp