chore: import upstream snapshot with attribution

docs_src/subscriptions/tutorial001.py

@@ -0,0 +1,33 @@
+from mcp.server.mcpserver import Context, MCPServer
+
+mcp = MCPServer("Sprint Board")
+
+BOARDS = {
+    "sprint": {"design": False, "build": False, "ship": False},
+    "backlog": {"tidy docs": False},
+}
+
+
+@mcp.resource("board://{name}")
+def board(name: str) -> str:
+    tasks = BOARDS[name]
+    return "\n".join(f"[{'x' if done else ' '}] {task}" for task, done in tasks.items())
+
+
+@mcp.tool()
+async def complete_task(board: str, task: str, ctx: Context) -> str:
+    BOARDS[board][task] = True
+    await ctx.notify_resource_updated(f"board://{board}")
+    return f"{task}: done"
+
+
+def sprint_report() -> str:
+    done = sum(done for tasks in BOARDS.values() for done in tasks.values())
+    return f"{done} task(s) done"
+
+
+@mcp.tool()
+async def enable_reports(ctx: Context) -> str:
+    mcp.add_tool(sprint_report)
+    await ctx.notify_tools_changed()
+    return "reporting is live"

docs_src/subscriptions/tutorial002.py

@@ -0,0 +1,49 @@
+from typing import Any
+
+import mcp_types as types
+
+from mcp.server.context import ServerRequestContext
+from mcp.server.lowlevel import Server
+from mcp.server.subscriptions import InMemorySubscriptionBus, ListenHandler, ResourceUpdated
+
+bus = InMemorySubscriptionBus()
+listen_handler = ListenHandler(bus)
+
+BOARD = {"design": False, "build": False}
+
+COMPLETE_TASK_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {"task": {"type": "string"}},
+    "required": ["task"],
+}
+
+
+async def read_resource(
+    ctx: ServerRequestContext[Any], params: types.ReadResourceRequestParams
+) -> types.ReadResourceResult:
+    board = "\n".join(f"[{'x' if done else ' '}] {task}" for task, done in BOARD.items())
+    return types.ReadResourceResult(contents=[types.TextResourceContents(uri=params.uri, text=board)])
+
+
+async def list_tools(
+    ctx: ServerRequestContext[Any], params: types.PaginatedRequestParams | None
+) -> types.ListToolsResult:
+    return types.ListToolsResult(
+        tools=[types.Tool(name="complete_task", description="Mark a task done.", input_schema=COMPLETE_TASK_SCHEMA)]
+    )
+
+
+async def call_tool(ctx: ServerRequestContext[Any], params: types.CallToolRequestParams) -> types.CallToolResult:
+    args = params.arguments or {}
+    BOARD[args["task"]] = True
+    await bus.publish(ResourceUpdated(uri="board://sprint"))
+    return types.CallToolResult(content=[types.TextContent(type="text", text="done")])
+
+
+server = Server(
+    "sprint-board",
+    on_read_resource=read_resource,
+    on_list_tools=list_tools,
+    on_call_tool=call_tool,
+    on_subscriptions_listen=listen_handler,
+)

docs_src/subscriptions/tutorial003.py

@@ -0,0 +1,30 @@
+from mcp_types import TextResourceContents
+
+from mcp import Client
+from mcp.client.subscriptions import ResourceUpdated, ToolsListChanged
+
+BOARD = "board://sprint"
+
+
+async def read_board(client: Client, uri: str = BOARD) -> str:
+    [contents] = (await client.read_resource(uri)).contents
+    assert isinstance(contents, TextResourceContents)
+    return contents.text
+
+
+async def follow_board(client: Client) -> None:
+    async with client.listen(tools_list_changed=True, resource_subscriptions=[BOARD]) as sub:
+        async for event in sub:
+            match event:
+                case ResourceUpdated(uri=uri):
+                    print(await read_board(client, uri))
+                case ToolsListChanged():
+                    tools = await client.list_tools()
+                    print("tools:", [tool.name for tool in tools.tools])
+                case _:
+                    pass  # kinds the filter did not ask for never arrive
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000/mcp") as client:
+        await follow_board(client)

docs_src/subscriptions/tutorial004_anyio.py

@@ -0,0 +1,32 @@
+import anyio
+
+from mcp import Client
+from mcp.client.subscriptions import Subscription
+
+from .tutorial003 import BOARD, read_board
+
+
+async def watch(client: Client, sub: Subscription) -> None:
+    async for _event in sub:
+        board = await read_board(client)
+        print(board)
+        if "[ ]" not in board:
+            return  # sprint finished: the stream closes when run_sprint leaves the block
+
+
+async def run_sprint(client: Client) -> None:
+    async with client.listen(resource_subscriptions=[BOARD]) as sub:
+        print(await read_board(client))  # snapshot: acknowledged, so nothing after this is missed
+        async with anyio.create_task_group() as tg:
+            tg.start_soon(watch, client, sub)
+            for task in ("design", "build", "ship"):
+                await client.call_tool("complete_task", {"board": "sprint", "task": task})
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000/mcp") as client:
+        await run_sprint(client)
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/subscriptions/tutorial004_asyncio.py

@@ -0,0 +1,32 @@
+import asyncio
+
+from mcp import Client
+from mcp.client.subscriptions import Subscription
+
+from .tutorial003 import BOARD, read_board
+
+
+async def watch(client: Client, sub: Subscription) -> None:
+    async for _event in sub:
+        board = await read_board(client)
+        print(board)
+        if "[ ]" not in board:
+            return  # sprint finished: the stream closes when run_sprint leaves the block
+
+
+async def run_sprint(client: Client) -> None:
+    async with client.listen(resource_subscriptions=[BOARD]) as sub:
+        print(await read_board(client))  # snapshot: acknowledged, so nothing after this is missed
+        watcher = asyncio.create_task(watch(client, sub))
+        for task in ("design", "build", "ship"):
+            await client.call_tool("complete_task", {"board": "sprint", "task": task})
+        await watcher  # returns once the watcher has seen the finished board
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000/mcp") as client:
+        await run_sprint(client)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs_src/subscriptions/tutorial004_trio.py

@@ -0,0 +1,32 @@
+import trio
+
+from mcp import Client
+from mcp.client.subscriptions import Subscription
+
+from .tutorial003 import BOARD, read_board
+
+
+async def watch(client: Client, sub: Subscription) -> None:
+    async for _event in sub:
+        board = await read_board(client)
+        print(board)
+        if "[ ]" not in board:
+            return  # sprint finished: the stream closes when run_sprint leaves the block
+
+
+async def run_sprint(client: Client) -> None:
+    async with client.listen(resource_subscriptions=[BOARD]) as sub:
+        print(await read_board(client))  # snapshot: acknowledged, so nothing after this is missed
+        async with trio.open_nursery() as nursery:
+            nursery.start_soon(watch, client, sub)
+            for task in ("design", "build", "ship"):
+                await client.call_tool("complete_task", {"board": "sprint", "task": task})
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000/mcp") as client:
+        await run_sprint(client)
+
+
+if __name__ == "__main__":
+    trio.run(main)

docs_src/subscriptions/tutorial005.py

@@ -0,0 +1,20 @@
+import anyio
+
+from mcp import Client
+from mcp.client.subscriptions import SubscriptionLost
+
+from .tutorial003 import read_board
+
+
+async def keep_following(client: Client) -> None:
+    while True:
+        try:
+            async with client.listen(resource_subscriptions=["board://sprint"]) as sub:
+                print(await read_board(client))  # refetch: no replay across streams
+                async for _event in sub:
+                    print(await read_board(client))
+        except SubscriptionLost:
+            pass
+        # Either ending means the stream is gone. Back off before re-listening:
+        # a graceful close may be the server shedding load.
+        await anyio.sleep(1)