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

docs_src/client_transports/tutorial001.py

@@ -0,0 +1,16 @@
+from mcp import Client
+from mcp.server import MCPServer
+
+mcp = MCPServer("Bookshop")
+
+
+@mcp.tool()
+def search_books(query: str) -> str:
+    """Search the catalog by title or author."""
+    return f"Found 3 books matching {query!r}."
+
+
+async def main() -> None:
+    async with Client(mcp) as client:
+        result = await client.call_tool("search_books", {"query": "dune"})
+        print(result.structured_content)

docs_src/client_transports/tutorial002.py

@@ -0,0 +1,7 @@
+from mcp import Client
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000/mcp") as client:
+        result = await client.list_tools()
+        print([tool.name for tool in result.tools])

docs_src/client_transports/tutorial003.py

@@ -0,0 +1,16 @@
+import httpx
+
+from mcp import Client
+from mcp.client.streamable_http import streamable_http_client
+
+
+async def main() -> None:
+    async with httpx.AsyncClient(
+        headers={"Authorization": "Bearer ..."},
+        timeout=httpx.Timeout(30.0, read=300.0),
+        follow_redirects=True,
+    ) as http_client:
+        transport = streamable_http_client("http://localhost:8000/mcp", http_client=http_client)
+        async with Client(transport) as client:
+            result = await client.list_tools()
+            print([tool.name for tool in result.tools])

docs_src/client_transports/tutorial004.py

@@ -0,0 +1,14 @@
+from mcp import Client, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+server = StdioServerParameters(
+    command="uv",
+    args=["run", "server.py"],
+    env={"BOOKSHOP_API_KEY": "secret"},
+)
+
+
+async def main() -> None:
+    async with Client(stdio_client(server)) as client:
+        result = await client.list_tools()
+        print([tool.name for tool in result.tools])