chore: import upstream snapshot with attribution

examples/stories/apps/README.md

@@ -0,0 +1,40 @@
+# apps
+
+MCP Apps: a tool carries a `_meta.ui.resourceUri` reference to a `ui://`
+resource that the host renders as an interactive surface. The server opts in via
+the `Apps` extension (`io.modelcontextprotocol/ui`); the client negotiates it by
+advertising the `text/html;profile=mcp-app` MIME type.
+
+## Run it
+
+```bash
+# stdio (default — the client spawns the server as a subprocess)
+uv run python -m stories.apps.client
+
+# HTTP — the client self-hosts the server on a free port, runs, then tears it down
+uv run python -m stories.apps.client --http
+```
+
+## What to look at
+
+- `server.py` `MCPServer("apps-example", extensions=[apps])` — the extension
+  advertises `io.modelcontextprotocol/ui` under `ServerCapabilities.extensions`
+  and contributes the UI-bound tool and its `ui://` resource. `MCPServer` itself
+  never learns about "ui"; it applies a closed set of contributions.
+- `server.py` `@apps.tool(resource_uri=...)` — stamps `_meta.ui.resourceUri` on
+  the tool; `add_html_resource` registers the matching `ui://` resource at
+  `text/html;profile=mcp-app`.
+- `server.py` `client_supports_apps(ctx)` — SEP-2133 graceful degradation: a
+  client that did not negotiate Apps gets a text-only result.
+- `client.py` `Client(target, extensions=[advertise(...)])` — the client advertises Apps
+  support so the server returns the UI-enabled result, then reads the tool's
+  `_meta.ui.resourceUri` and fetches that resource.
+
+## Spec
+
+[MCP Apps — extensions](https://modelcontextprotocol.io/specification/draft/extensions/apps)
+· [SEP-2133 — extensions capability](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/2133)
+
+## See also
+
+`custom_methods/` (registering a non-spec method without an extension).

examples/stories/apps/client.py

@@ -0,0 +1,37 @@
+"""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, advertise
+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=[advertise(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)

examples/stories/apps/server.py

@@ -0,0 +1,43 @@
+"""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:
+    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")
+    return MCPServer("apps-example", extensions=[apps])
+
+
+if __name__ == "__main__":
+    run_server_from_args(build_server)