chore: import upstream snapshot with attribution

examples/stories/extensions/README.md

@@ -0,0 +1,41 @@
+# extensions
+
+Writing your own extension (SEP-2133): one identifier bundles a settings entry
+under `ServerCapabilities.extensions`, a contributed tool, and a vendor request
+method gated on the client declaring the extension back.
+
+## Run it
+
+```bash
+# stdio (default — the client spawns the server as a subprocess)
+uv run python -m stories.extensions.client
+
+# HTTP — the client self-hosts the server on a free port, runs, then tears it down
+uv run python -m stories.extensions.client --http
+```
+
+## What to look at
+
+- `server.py` `class Catalog(Extension)` — the whole extension: `settings()`
+  becomes the advertised capability entry, `tools()` contributes a regular tool,
+  `methods()` registers a vendor verb. The extension never holds the server; it
+  declares contributions and `MCPServer(extensions=[...])` consumes them.
+- `server.py` `require_client_extension(ctx, EXTENSION_ID)` — the vendor method
+  rejects clients that did not declare the extension with `-32021` (missing
+  required client capability) and a machine-readable `requiredCapabilities`
+  payload.
+- `client.py` `Client(target, extensions=[advertise(EXTENSION_ID)])` — the client-side
+  half of the negotiation; on 2026-07-28 it travels in the per-request `_meta`
+  envelope.
+- `client.py` `client.session.send_request(...)` — vendor methods have no
+  `Client`-level helper; the session escape hatch sends them.
+
+## Spec
+
+[SEP-2133 — extensions capability](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/2133)
+· [Capabilities — `_meta` key grammar](https://modelcontextprotocol.io/specification/draft/basic/index)
+
+## See also
+
+`apps/` (the built-in MCP Apps extension) · `custom_methods/` (the same verb
+registered on the lowlevel `Server` by hand, without an extension).

examples/stories/extensions/client.py

@@ -0,0 +1,53 @@
+"""Discover an extension's capability entry, call its tool, then send its vendor method."""
+
+from typing import Literal
+
+import mcp_types as types
+from mcp_types import TextContent
+
+from mcp.client import Client, advertise
+from stories._harness import Target, run_client
+
+EXTENSION_ID = "com.example/catalog"
+
+
+class SearchParams(types.RequestParams):
+    query: str
+    limit: int = 3
+
+
+class SearchRequest(types.Request[SearchParams, Literal["com.example/search"]]):
+    method: Literal["com.example/search"] = "com.example/search"
+    params: SearchParams
+
+
+class SearchResult(types.Result):
+    items: list[str]
+
+
+async def main(target: Target, *, mode: str = "auto") -> None:
+    # Declare the extension client-side so the server's `require_client_extension`
+    # gate on `com.example/search` passes.
+    async with Client(target, mode=mode, extensions=[advertise(EXTENSION_ID)]) as client:
+        # The extensions capability map rides `server/discover` (modern only). On a
+        # legacy connection it is absent, so assert it only when present.
+        if client.server_capabilities.extensions is not None:
+            assert client.server_capabilities.extensions == {EXTENSION_ID: {"suggest": True}}, (
+                client.server_capabilities.extensions
+            )
+
+        # The extension's tool is a regular tool: listed and callable like any other.
+        listed = await client.list_tools()
+        assert [tool.name for tool in listed.tools] == ["suggest"], listed
+        result = await client.call_tool("suggest", {"prefix": "mcp"})
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "mcp-suggestion", result.content[0].text
+
+        # Vendor methods drop one layer to `client.session` (see custom_methods/).
+        request = SearchRequest(params=SearchParams(query="mcp", limit=3))
+        found = await client.session.send_request(request, SearchResult)
+        assert found.items == ["mcp-0", "mcp-1", "mcp-2"], found
+
+
+if __name__ == "__main__":
+    run_client(main)

examples/stories/extensions/server.py

@@ -0,0 +1,64 @@
+"""Package a vendor verb and a tool as a reusable, advertised extension (SEP-2133).
+
+`custom_methods/` registers a verb on the lowlevel `Server` by hand; this story
+bundles the same idea as an `Extension`: declared contributions, a settings entry
+under `ServerCapabilities.extensions`, and a `require_client_extension` gate on
+the vendor method.
+"""
+
+from collections.abc import Sequence
+from typing import Any
+
+import mcp_types as types
+from pydantic import Field
+
+from mcp.server.context import ServerRequestContext
+from mcp.server.extension import Extension, MethodBinding, ToolBinding
+from mcp.server.mcpserver import MCPServer, require_client_extension
+from stories._hosting import run_server_from_args
+
+EXTENSION_ID = "com.example/catalog"
+
+
+class SearchParams(types.RequestParams):
+    """Subclass `RequestParams` so `_meta` (and the 2026 envelope keys) parse uniformly."""
+
+    query: str
+    limit: int = Field(default=3, ge=1, le=25)
+
+
+class SearchResult(types.Result):
+    items: list[str]
+
+
+def suggest(prefix: str) -> str:
+    """Suggest a catalog entry for a prefix."""
+    return f"{prefix}-suggestion"
+
+
+async def search(ctx: ServerRequestContext[Any, Any], params: SearchParams) -> SearchResult:
+    require_client_extension(ctx, EXTENSION_ID)
+    return SearchResult(items=[f"{params.query}-{n}" for n in range(params.limit)])
+
+
+class Catalog(Extension):
+    """One identifier, three contributions: settings, a tool, a vendor method."""
+
+    identifier = EXTENSION_ID
+
+    def settings(self) -> dict[str, Any]:
+        return {"suggest": True}
+
+    def tools(self) -> Sequence[ToolBinding]:
+        return [ToolBinding(fn=suggest)]
+
+    def methods(self) -> Sequence[MethodBinding]:
+        return [MethodBinding("com.example/search", SearchParams, search)]
+
+
+def build_server() -> MCPServer:
+    return MCPServer("extensions-example", extensions=[Catalog()])
+
+
+if __name__ == "__main__":
+    run_server_from_args(build_server)