chore: import upstream snapshot with attribution

tests/docs_src/test_sampling_and_roots.py

@@ -0,0 +1,62 @@
+"""`docs/handlers/sampling-and-roots.md`: every claim the page makes, proved against the real SDK."""
+
+from typing import Literal
+
+import pytest
+from mcp_types import (
+    MISSING_REQUIRED_CLIENT_CAPABILITY,
+    CreateMessageRequestParams,
+    CreateMessageResult,
+    ListRootsResult,
+    Root,
+    TextContent,
+)
+from pydantic import FileUrl
+
+from docs_src.sampling_and_roots import tutorial001, tutorial002
+from mcp import Client
+from mcp.client import ClientRequestContext
+from mcp.shared.exceptions import MCPError
+
+pytestmark = [pytest.mark.anyio, pytest.mark.filterwarnings("error::mcp.MCPDeprecationWarning")]
+
+
+@pytest.mark.parametrize("mode", ["legacy", "auto"])
+async def test_a_sampling_dependency_receives_the_clients_completion(mode: Literal["legacy", "auto"]) -> None:
+    """tutorial001: `draft_blurb` runs through the client's model on both protocol versions."""
+    prompts: list[str] = []
+
+    async def sampler(context: ClientRequestContext, params: CreateMessageRequestParams) -> CreateMessageResult:
+        content = params.messages[0].content
+        assert isinstance(content, TextContent)
+        prompts.append(content.text)
+        return CreateMessageResult(
+            role="assistant", content=TextContent(type="text", text="A desert planet holds the key."), model="m"
+        )
+
+    async with Client(tutorial001.mcp, mode=mode, sampling_callback=sampler) as client:
+        result = await client.call_tool("blurb", {"title": "Dune"})
+
+    assert result.content == [TextContent(type="text", text="A desert planet holds the key.")]
+    assert prompts == ["Write a one-sentence blurb for the book 'Dune'."]
+
+
+@pytest.mark.parametrize("mode", ["legacy", "auto"])
+async def test_a_roots_dependency_receives_the_clients_folders(mode: Literal["legacy", "auto"]) -> None:
+    """tutorial002: `workspace_roots` fetches the client's roots list."""
+
+    async def client_roots(context: ClientRequestContext) -> ListRootsResult:
+        return ListRootsResult(roots=[Root(uri=FileUrl("file:///workspace/catalog"), name="catalog")])
+
+    async with Client(tutorial002.mcp, mode=mode, list_roots_callback=client_roots) as client:
+        result = await client.call_tool("catalog_folder", {})
+
+    assert result.content == [TextContent(type="text", text="file:///workspace/catalog")]
+
+
+async def test_an_undeclared_capability_fails_before_a_request_is_sent() -> None:
+    """The page's gate claim: no `sampling` capability means a -32021 protocol error."""
+    async with Client(tutorial001.mcp) as client:
+        with pytest.raises(MCPError) as exc_info:
+            await client.call_tool("blurb", {"title": "Dune"})
+    assert exc_info.value.code == MISSING_REQUIRED_CLIENT_CAPABILITY