chore: import upstream snapshot with attribution

examples/stories/resources/README.md

@@ -0,0 +1,50 @@
+# resources
+
+Expose data by URI: a static resource (`config://app`) and an RFC-6570
+template (`greeting://{name}`). One `@mcp.resource()` decorator handles both —
+the SDK infers static-vs-template from whether the URI contains `{...}`. The
+client lists resources, lists templates, then reads each.
+
+## Run it
+
+```bash
+# stdio (default — the client spawns the server as a subprocess)
+uv run python -m stories.resources.client
+
+# HTTP — the client self-hosts the server on a free port, runs, then tears it down
+uv run python -m stories.resources.client --http
+# same, against the lowlevel-API server variant
+uv run python -m stories.resources.client --http --server server_lowlevel
+```
+
+## What to look at
+
+- `client.py` `async with Client(target, mode=mode) as client:` — the one line
+  every client example exists to teach. `target` is anything `Client()`
+  accepts (an in-process server, a transport, or an HTTP URL) and `mode=` is
+  always explicit; the rest of the story is the body of that `async with`.
+- `server.py` `app_config` vs `greeting` — a URI with no `{}` registers a
+  static resource (appears in `resources/list`); a URI with `{name}` registers
+  a template (appears only in `resources/templates/list`) and the placeholder
+  must match the function parameter name.
+- `server_lowlevel.py` `read_resource` — without `MCPServer` you own the URI
+  dispatch yourself, including raising `MCPError(code=INVALID_PARAMS, ...)` for
+  unknown URIs (matches what `MCPServer` sends).
+- `client.py` `isinstance(entry, TextResourceContents)` — `contents` is a list
+  of `TextResourceContents | BlobResourceContents`; narrow before reading
+  `.text`.
+
+## Not shown here
+
+Subscriptions. Per-URI `resources/subscribe` is a 2025-era RPC being replaced
+by `subscriptions/listen` in 2026-07-28; neither is shown in this story. See
+`stickynotes/` for `list_changed` notifications.
+
+## Spec
+
+[Resources — server features](https://modelcontextprotocol.io/specification/2025-11-25/server/resources)
+
+## See also
+
+`stickynotes/` (list-changed notifications), `pagination/` (cursor over a long
+resource list).

examples/stories/resources/client.py

@@ -0,0 +1,30 @@
+"""List resources and templates, then read both the static and templated URIs."""
+
+from mcp_types import TextResourceContents
+
+from mcp.client import Client
+from stories._harness import Target, run_client
+
+
+async def main(target: Target, *, mode: str = "auto") -> None:
+    async with Client(target, mode=mode) as client:
+        listed = await client.list_resources()
+        assert [r.uri for r in listed.resources] == ["config://app"]
+
+        templates = await client.list_resource_templates()
+        assert [t.uri_template for t in templates.resource_templates] == ["greeting://{name}"]
+
+        config = await client.read_resource("config://app")
+        entry = config.contents[0]
+        assert isinstance(entry, TextResourceContents)
+        assert entry.text == '{"feature": true}'
+        assert entry.mime_type == "application/json"
+
+        hello = await client.read_resource("greeting://world")
+        entry = hello.contents[0]
+        assert isinstance(entry, TextResourceContents)
+        assert entry.text == "Hello, world!"
+
+
+if __name__ == "__main__":
+    run_client(main)

examples/stories/resources/server.py

@@ -0,0 +1,24 @@
+"""Resources primitive: a static URI and an RFC-6570 template via @mcp.resource()."""
+
+from mcp.server.mcpserver import MCPServer
+from stories._hosting import run_server_from_args
+
+
+def build_server() -> MCPServer:
+    mcp = MCPServer("resources-example")
+
+    @mcp.resource("config://app", mime_type="application/json")
+    def app_config() -> str:
+        """Static application config."""
+        return '{"feature": true}'
+
+    @mcp.resource("greeting://{name}")
+    def greeting(name: str) -> str:
+        """A greeting for the named subject."""
+        return f"Hello, {name}!"
+
+    return mcp
+
+
+if __name__ == "__main__":
+    run_server_from_args(build_server)

examples/stories/resources/server_lowlevel.py

@@ -0,0 +1,65 @@
+"""Resources primitive (lowlevel API): hand-built list/templates/read handlers."""
+
+from typing import Any
+
+import mcp_types as types
+from mcp_types.jsonrpc import INVALID_PARAMS
+
+from mcp.server.context import ServerRequestContext
+from mcp.server.lowlevel import Server
+from mcp.shared.exceptions import MCPError
+from stories._hosting import run_server_from_args
+
+
+def build_server() -> Server[Any]:
+    async def list_resources(
+        ctx: ServerRequestContext[Any], params: types.PaginatedRequestParams | None
+    ) -> types.ListResourcesResult:
+        return types.ListResourcesResult(
+            resources=[
+                types.Resource(
+                    uri="config://app",
+                    name="app_config",
+                    description="Static application config.",
+                    mime_type="application/json",
+                )
+            ]
+        )
+
+    async def list_resource_templates(
+        ctx: ServerRequestContext[Any], params: types.PaginatedRequestParams | None
+    ) -> types.ListResourceTemplatesResult:
+        return types.ListResourceTemplatesResult(
+            resource_templates=[
+                types.ResourceTemplate(
+                    uri_template="greeting://{name}",
+                    name="greeting",
+                    description="A greeting for the named subject.",
+                    mime_type="text/plain",
+                )
+            ]
+        )
+
+    async def read_resource(
+        ctx: ServerRequestContext[Any], params: types.ReadResourceRequestParams
+    ) -> types.ReadResourceResult:
+        if params.uri == "config://app":
+            text, mime = '{"feature": true}', "application/json"
+        elif params.uri.startswith("greeting://"):
+            text, mime = f"Hello, {params.uri.removeprefix('greeting://')}!", "text/plain"
+        else:
+            raise MCPError(code=INVALID_PARAMS, message=f"Resource not found: {params.uri}")
+        return types.ReadResourceResult(
+            contents=[types.TextResourceContents(uri=params.uri, mime_type=mime, text=text)]
+        )
+
+    return Server(
+        "resources-example",
+        on_list_resources=list_resources,
+        on_list_resource_templates=list_resource_templates,
+        on_read_resource=read_resource,
+    )
+
+
+if __name__ == "__main__":
+    run_server_from_args(build_server)