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

docs_src/asgi/tutorial001.py

@@ -0,0 +1,12 @@
+from mcp.server import MCPServer
+
+mcp = MCPServer("Notes")
+
+
+@mcp.tool()
+def add_note(text: str) -> str:
+    """Save a note."""
+    return f"Saved: {text}"
+
+
+app = mcp.streamable_http_app()

docs_src/asgi/tutorial002.py

@@ -0,0 +1,27 @@
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("Notes")
+
+
+@mcp.tool()
+def add_note(text: str) -> str:
+    """Save a note."""
+    return f"Saved: {text}"
+
+
+@asynccontextmanager
+async def lifespan(app: Starlette) -> AsyncIterator[None]:
+    async with mcp.session_manager.run():
+        yield
+
+
+app = Starlette(
+    routes=[Mount("/", app=mcp.streamable_http_app())],
+    lifespan=lifespan,
+)

docs_src/asgi/tutorial003.py

@@ -0,0 +1,39 @@
+from collections.abc import AsyncIterator
+from contextlib import AsyncExitStack, asynccontextmanager
+
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+from mcp.server import MCPServer
+
+notes = MCPServer("Notes")
+tasks = MCPServer("Tasks")
+
+
+@notes.tool()
+def add_note(text: str) -> str:
+    """Save a note."""
+    return f"Saved: {text}"
+
+
+@tasks.tool()
+def add_task(title: str) -> str:
+    """Create a task."""
+    return f"Created: {title}"
+
+
+@asynccontextmanager
+async def lifespan(app: Starlette) -> AsyncIterator[None]:
+    async with AsyncExitStack() as stack:
+        await stack.enter_async_context(notes.session_manager.run())
+        await stack.enter_async_context(tasks.session_manager.run())
+        yield
+
+
+app = Starlette(
+    routes=[
+        Mount("/notes", app=notes.streamable_http_app()),
+        Mount("/tasks", app=tasks.streamable_http_app()),
+    ],
+    lifespan=lifespan,
+)

docs_src/asgi/tutorial004.py

@@ -0,0 +1,27 @@
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("Notes")
+
+
+@mcp.tool()
+def add_note(text: str) -> str:
+    """Save a note."""
+    return f"Saved: {text}"
+
+
+@asynccontextmanager
+async def lifespan(app: Starlette) -> AsyncIterator[None]:
+    async with mcp.session_manager.run():
+        yield
+
+
+app = Starlette(
+    routes=[Mount("/notes", app=mcp.streamable_http_app(streamable_http_path="/"))],
+    lifespan=lifespan,
+)

docs_src/asgi/tutorial005.py

@@ -0,0 +1,52 @@
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
+from starlette.routing import Mount
+
+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}"
+
+
+@asynccontextmanager
+async def lifespan(app: Starlette) -> AsyncIterator[None]:
+    async with mcp.session_manager.run():
+        yield
+
+
+security = TransportSecuritySettings(
+    allowed_hosts=["mcp.example.com", "mcp.example.com:*"],
+    allowed_origins=["https://app.example.com"],
+)
+
+app = Starlette(
+    routes=[Mount("/", app=mcp.streamable_http_app(transport_security=security))],
+    middleware=[
+        Middleware(
+            CORSMiddleware,
+            allow_origins=["https://app.example.com"],
+            allow_methods=["GET", "POST", "DELETE"],
+            allow_headers=[
+                "Authorization",
+                "Content-Type",
+                "Last-Event-ID",
+                "Mcp-Method",
+                "Mcp-Name",
+                "Mcp-Protocol-Version",
+                "Mcp-Session-Id",
+            ],
+            expose_headers=["Mcp-Session-Id"],
+        )
+    ],
+    lifespan=lifespan,
+)

docs_src/asgi/tutorial006.py

@@ -0,0 +1,20 @@
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("Notes")
+
+
+@mcp.tool()
+def add_note(text: str) -> str:
+    """Save a note."""
+    return f"Saved: {text}"
+
+
+@mcp.custom_route("/health", methods=["GET"])
+async def health(request: Request) -> Response:
+    return JSONResponse({"status": "ok"})
+
+
+app = mcp.streamable_http_app()