Rename sampling capability types for clarity

Rename SamplingCapabilityNested to SamplingCapability and the old
SamplingCapability to SamplingContextCapability for better clarity.

- SamplingCapability is now the main structured type with context and tools fields
- SamplingContextCapability represents the deprecated context capability
- Updates all exports and tests to use the new names

All tests pass and type checking passes.

Author: ochafik

src/mcp/__init__.py

@@ -42,6 +42,8 @@
     ResourcesCapability,
     ResourceUpdatedNotification,
     RootsCapability,
+    SamplingCapability,
+    SamplingContextCapability,
     SamplingMessage,
     SamplingToolsCapability,
     ServerCapabilities,
@@ -104,6 +106,8 @@
     "ResourcesCapability",
     "ResourceUpdatedNotification",
     "RootsCapability",
+    "SamplingCapability",
+    "SamplingContextCapability",
     "SamplingMessage",
     "SamplingRole",
     "SamplingToolsCapability",

src/mcp/types.py

@@ -250,8 +250,13 @@ class RootsCapability(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-class SamplingCapability(BaseModel):
-    """Capability for sampling operations."""
+class SamplingContextCapability(BaseModel):
+    """
+    Capability for context inclusion during sampling.
+
+    Indicates support for non-'none' values in the includeContext parameter.
+    SOFT-DEPRECATED: New implementations should use tools parameter instead.
+    """
 
     model_config = ConfigDict(extra="allow")
 
@@ -273,12 +278,12 @@ class ElicitationCapability(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-class SamplingCapabilityNested(BaseModel):
+class SamplingCapability(BaseModel):
     """
-    Nested structure for sampling capabilities, allowing fine-grained capability advertisement.
+    Sampling capability structure, allowing fine-grained capability advertisement.
     """
 
-    context: SamplingCapability | None = None
+    context: SamplingContextCapability | None = None
     """
     Present if the client supports non-'none' values for includeContext parameter.
     SOFT-DEPRECATED: New implementations should use tools parameter instead.
@@ -296,11 +301,10 @@ class ClientCapabilities(BaseModel):
 
     experimental: dict[str, dict[str, Any]] | None = None
     """Experimental, non-standard capabilities that the client supports."""
-    sampling: SamplingCapabilityNested | SamplingCapability | None = None
+    sampling: SamplingCapability | None = None
     """
     Present if the client supports sampling from an LLM.
-    Can be a structured object (SamplingCapabilityNested) with fine-grained capabilities,
-    or a simple marker object (SamplingCapability) for backward compatibility.
+    Can contain fine-grained capabilities like context and tools support.
     """
     elicitation: ElicitationCapability | None = None
     """Present if the client supports elicitation from the user."""

tests/test_types.py

@@ -12,7 +12,7 @@
     InitializeRequestParams,
     JSONRPCMessage,
     JSONRPCRequest,
-    SamplingCapabilityNested,
+    SamplingCapability,
     SamplingMessage,
     TextContent,
     Tool,
@@ -257,12 +257,12 @@ async def test_client_capabilities_with_sampling_tools():
     }
     capabilities = ClientCapabilities.model_validate(capabilities_data)
     assert capabilities.sampling is not None
-    assert isinstance(capabilities.sampling, SamplingCapabilityNested)
+    assert isinstance(capabilities.sampling, SamplingCapability)
     assert capabilities.sampling.tools is not None
 
     # With both context and tools
     full_capabilities_data = {"sampling": {"context": {}, "tools": {}}}
     full_caps = ClientCapabilities.model_validate(full_capabilities_data)
-    assert isinstance(full_caps.sampling, SamplingCapabilityNested)
+    assert isinstance(full_caps.sampling, SamplingCapability)
     assert full_caps.sampling.context is not None
     assert full_caps.sampling.tools is not None