Add apps and tasks example stories and migration notes

Kludex · Kludex · commit ff285f492479 · 2026-06-26T20:18:11.000+02:00
Wire runnable `apps` and `tasks` stories (in-memory + http-asgi) into the manifest
and document the extensions API in the migration guide.
diff --git a/examples/stories/apps/__init__.py b/examples/stories/apps/__init__.py
diff --git a/examples/stories/apps/client.py b/examples/stories/apps/client.py
@@ -0,0 +1,35 @@
+"""Negotiate MCP Apps, discover a tool's `ui://` UI, fetch it, and call the tool."""
+
+from mcp_types import TextContent, TextResourceContents
+
+from mcp.client import Client
+from mcp.server.apps import APP_MIME_TYPE, EXTENSION_ID
+from stories._harness import Target, run_client
+
+
+async def main(target: Target, *, mode: str = "auto") -> None:
+    # Advertise MCP Apps support so the server returns the UI-enabled result; a
+    # client that omits this gets the text-only fallback (graceful degradation).
+    async with Client(target, mode=mode, extensions={EXTENSION_ID: {"mimeTypes": [APP_MIME_TYPE]}}) as client:
+        # The extensions capability map rides `server/discover` (modern only). On a
+        # legacy connection (today's stdio) it is absent, so assert it only when present.
+        if client.server_capabilities.extensions is not None:
+            assert client.server_capabilities.extensions == {EXTENSION_ID: {}}, client.server_capabilities.extensions
+
+        listed = await client.list_tools()
+        tool = next(t for t in listed.tools if t.name == "get_time")
+        assert tool.meta is not None, tool
+        assert tool.meta["ui"]["resourceUri"] == "ui://get-time/app.html", tool.meta
+
+        ui = await client.read_resource("ui://get-time/app.html")
+        contents = ui.contents[0]
+        assert isinstance(contents, TextResourceContents)
+        assert contents.mime_type == APP_MIME_TYPE, contents.mime_type
+
+        result = await client.call_tool("get_time", {})
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "2026-06-26T00:00:00Z", result.content[0].text
+
+
+if __name__ == "__main__":
+    run_client(main)
diff --git a/examples/stories/apps/server.py b/examples/stories/apps/server.py
@@ -0,0 +1,45 @@
+"""MCP Apps: a tool bound to a `ui://` resource the host renders as an interactive surface.
+
+`Apps` is an opt-in `Extension` passed to `MCPServer(extensions=[...])`. The
+`@apps.tool(resource_uri=...)` decorator stamps `_meta.ui.resourceUri` onto the
+tool; `add_html_resource` registers the matching `ui://` HTML resource. The tool
+degrades gracefully: `client_supports_apps(ctx)` reports whether the client
+negotiated Apps, so it returns text-only output otherwise.
+"""
+
+from mcp.server.apps import Apps, client_supports_apps
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.context import Context
+from stories._hosting import run_server_from_args
+
+RESOURCE_URI = "ui://get-time/app.html"
+CLOCK_HTML = """<!doctype html>
+<title>Current time</title>
+<h1 id="now">…</h1>
+<script>
+  window.addEventListener("message", (event) => {
+    const text = event.data?.result?.content?.[0]?.text;
+    if (text) document.getElementById("now").textContent = text;
+  });
+</script>
+"""
+
+
+def build_server() -> MCPServer:
+    mcp = MCPServer("apps-example")
+    apps = Apps()
+
+    @apps.tool(resource_uri=RESOURCE_URI, title="Get Time", description="Return the current time.")
+    def get_time(ctx: Context) -> str:
+        now = "2026-06-26T00:00:00Z"
+        if not client_supports_apps(ctx):
+            return f"The time is {now}."
+        return now
+
+    apps.add_html_resource(RESOURCE_URI, CLOCK_HTML, title="Clock")
+    mcp.add_extension(apps)
+    return mcp
+
+
+if __name__ == "__main__":
+    run_server_from_args(build_server)
diff --git a/examples/stories/tasks/__init__.py b/examples/stories/tasks/__init__.py
diff --git a/examples/stories/tasks/client.py b/examples/stories/tasks/client.py
@@ -0,0 +1,46 @@
+"""Request task-augmented execution, then drive the task lifecycle via `tasks/*`."""
+
+from typing import cast
+
+import mcp_types as types
+
+from mcp.client import Client
+from mcp.server.tasks import EXTENSION_ID, RELATED_TASK_META_KEY
+from stories._harness import Target, run_client
+
+
+async def main(target: Target, *, mode: str = "auto") -> None:
+    async with Client(target, mode=mode) as client:
+        # The extensions capability map rides `server/discover` (modern only); a legacy
+        # connection (today's stdio) omits it, so assert it only when present.
+        if client.server_capabilities.extensions is not None:
+            assert client.server_capabilities.extensions == {EXTENSION_ID: {"list": {}, "cancel": {}}}
+
+        # `Client` exposes only spec verbs, so task-augmented calls and the
+        # `tasks/*` methods drop to `client.session` (see custom_methods/). The
+        # casts satisfy the closed `ClientRequest` union; at runtime the body
+        # only calls `.model_dump()`.
+        session = client.session
+        call = types.CallToolRequest(
+            params=types.CallToolRequestParams(
+                name="echo", arguments={"text": "async"}, task=types.TaskMetadata(ttl=60)
+            )
+        )
+        result = await session.send_request(cast("types.ClientRequest", call), types.CallToolResult)
+        assert result.meta is not None, result
+        task_id = result.meta[RELATED_TASK_META_KEY]["taskId"]
+        assert isinstance(result.content[0], types.TextContent)
+        assert result.content[0].text == "async", result
+
+        get = types.GetTaskRequest(params=types.GetTaskRequestParams(task_id=task_id))
+        status = await session.send_request(cast("types.ClientRequest", get), types.GetTaskResult)
+        assert status.status == "completed", status
+
+        payload_req = types.GetTaskPayloadRequest(params=types.GetTaskPayloadRequestParams(task_id=task_id))
+        payload = await session.send_request(cast("types.ClientRequest", payload_req), types.CallToolResult)
+        assert isinstance(payload.content[0], types.TextContent)
+        assert payload.content[0].text == "async", payload
+
+
+if __name__ == "__main__":
+    run_client(main)
diff --git a/examples/stories/tasks/server.py b/examples/stories/tasks/server.py
@@ -0,0 +1,25 @@
+"""Tasks: task-augmented tool execution via the interceptive half of the extension API.
+
+`Tasks` is an opt-in `Extension`. It intercepts `tools/call`: a plain call passes
+through, but a call carrying a `task` field is recorded under a task id and
+returned with that id in `_meta`. It also serves the `tasks/*` methods so a
+client can poll status and fetch the payload.
+"""
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.tasks import Tasks
+from stories._hosting import run_server_from_args
+
+
+def build_server() -> MCPServer:
+    mcp = MCPServer("tasks-example", extensions=[Tasks()])
+
+    @mcp.tool(description="Echo the input back as plain text.", structured_output=False)
+    def echo(text: str) -> str:
+        return text
+
+    return mcp
+
+
+if __name__ == "__main__":
+    run_server_from_args(build_server)
