README - replace code snippets with examples - streamable http (#1155)

examples/snippets/clients/completion_client.py

@@ -1,6 +1,4 @@
-"""MCP client example showing completion usage.
-
-This example demonstrates how to use the completion feature in MCP clients.
+"""
 cd to the `examples/snippets` directory and run:
     uv run completion-client
 """

examples/snippets/clients/display_utilities.py

@@ -1,8 +1,4 @@
-"""Client display utilities example.
-
-This example shows how to use the SDK's display utilities to show
-human-readable names for tools, resources, and prompts.
-
+"""
 cd to the `examples/snippets` directory and run:
     uv run display-utilities-client
 """

examples/snippets/clients/stdio_client.py

@@ -1,6 +1,4 @@
-"""MCP client example using stdio transport.
-
-This is a documentation example showing how to write an MCP client.
+"""
 cd to the `examples/snippets/clients` directory and run:
     uv run client
 """

examples/snippets/clients/streamable_basic.py

@@ -0,0 +1,29 @@
+"""
+Run from the repository root:
+    uv run examples/snippets/clients/streamable_basic.py
+"""
+
+import asyncio
+
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+
+async def main():
+    # Connect to a streamable HTTP server
+    async with streamablehttp_client("http://localhost:8000/mcp") as (
+        read_stream,
+        write_stream,
+        _,
+    ):
+        # Create a session using the client streams
+        async with ClientSession(read_stream, write_stream) as session:
+            # Initialize the connection
+            await session.initialize()
+            # List available tools
+            tools = await session.list_tools()
+            print(f"Available tools: {[tool.name for tool in tools.tools]}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/snippets/servers/streamable_config.py

@@ -0,0 +1,28 @@
+"""
+Run from the repository root:
+    uv run examples/snippets/servers/streamable_config.py
+"""
+
+from mcp.server.fastmcp import FastMCP
+
+# Stateful server (maintains session state)
+mcp = FastMCP("StatefulServer")
+
+# Other configuration options:
+# Stateless server (no session persistence)
+# mcp = FastMCP("StatelessServer", stateless_http=True)
+
+# Stateless server (no session persistence, no sse stream with supported client)
+# mcp = FastMCP("StatelessServer", stateless_http=True, json_response=True)
+
+
+# Add a simple tool to demonstrate the server
+@mcp.tool()
+def greet(name: str = "World") -> str:
+    """Greet someone by name."""
+    return f"Hello, {name}!"
+
+
+# Run server with streamable_http transport
+if __name__ == "__main__":
+    mcp.run(transport="streamable-http")

examples/snippets/servers/streamable_starlette_mount.py

@@ -0,0 +1,49 @@
+"""
+Run from the repository root:
+    uvicorn examples.snippets.servers.streamable_starlette_mount:app --reload
+"""
+
+import contextlib
+
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+from mcp.server.fastmcp import FastMCP
+
+# Create the Echo server
+echo_mcp = FastMCP(name="EchoServer", stateless_http=True)
+
+
+@echo_mcp.tool()
+def echo(message: str) -> str:
+    """A simple echo tool"""
+    return f"Echo: {message}"
+
+
+# Create the Math server
+math_mcp = FastMCP(name="MathServer", stateless_http=True)
+
+
+@math_mcp.tool()
+def add_two(n: int) -> int:
+    """Tool to add two to the input"""
+    return n + 2
+
+
+# Create a combined lifespan to manage both session managers
+@contextlib.asynccontextmanager
+async def lifespan(app: Starlette):
+    async with contextlib.AsyncExitStack() as stack:
+        await stack.enter_async_context(echo_mcp.session_manager.run())
+        await stack.enter_async_context(math_mcp.session_manager.run())
+        yield
+
+
+# Create the Starlette app and mount the MCP servers
+app = Starlette(
+    routes=[
+        Mount("/echo", echo_mcp.streamable_http_app()),
+        Mount("/math", math_mcp.streamable_http_app()),
+    ],
+    lifespan=lifespan,
+)