feat: backwards-compatible create_message overloads for SEP-1577 (#1713)

tests/client/test_sampling_callback.py

@@ -8,8 +8,10 @@ from mcp.shared.memory import (
 from mcp.types import (
     CreateMessageRequestParams,
     CreateMessageResult,
+    CreateMessageResultWithTools,
     SamplingMessage,
     TextContent,
+    ToolUseContent,
 )
 
 
@@ -56,3 +58,79 @@ async def test_sampling_callback():
         assert result.isError is True
         assert isinstance(result.content[0], TextContent)
         assert result.content[0].text == "Error executing tool test_sampling: Sampling not supported"
+
+
+@pytest.mark.anyio
+async def test_create_message_backwards_compat_single_content():
+    """Test backwards compatibility: create_message without tools returns single content."""
+    from mcp.server.fastmcp import FastMCP
+
+    server = FastMCP("test")
+
+    # Callback returns single content (text)
+    callback_return = CreateMessageResult(
+        role="assistant",
+        content=TextContent(type="text", text="Hello from LLM"),
+        model="test-model",
+        stopReason="endTurn",
+    )
+
+    async def sampling_callback(
+        context: RequestContext[ClientSession, None],
+        params: CreateMessageRequestParams,
+    ) -> CreateMessageResult:
+        return callback_return
+
+    @server.tool("test_backwards_compat")
+    async def test_tool(message: str):
+        # Call create_message WITHOUT tools
+        result = await server.get_context().session.create_message(
+            messages=[SamplingMessage(role="user", content=TextContent(type="text", text=message))],
+            max_tokens=100,
+        )
+        # Backwards compat: result should be CreateMessageResult
+        assert isinstance(result, CreateMessageResult)
+        # Content should be single (not a list) - this is the key backwards compat check
+        assert isinstance(result.content, TextContent)
+        assert result.content.text == "Hello from LLM"
+        # CreateMessageResult should NOT have content_as_list (that's on WithTools)
+        assert not hasattr(result, "content_as_list") or not callable(getattr(result, "content_as_list", None))
+        return True
+
+    async with create_session(server._mcp_server, sampling_callback=sampling_callback) as client_session:
+        result = await client_session.call_tool("test_backwards_compat", {"message": "Test"})
+        assert result.isError is False
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "true"
+
+
+@pytest.mark.anyio
+async def test_create_message_result_with_tools_type():
+    """Test that CreateMessageResultWithTools supports content_as_list."""
+    # Test the type itself, not the overload (overload requires client capability setup)
+    result = CreateMessageResultWithTools(
+        role="assistant",
+        content=ToolUseContent(type="tool_use", id="call_123", name="get_weather", input={"city": "SF"}),
+        model="test-model",
+        stopReason="toolUse",
+    )
+
+    # CreateMessageResultWithTools should have content_as_list
+    content_list = result.content_as_list
+    assert len(content_list) == 1
+    assert content_list[0].type == "tool_use"
+
+    # It should also work with array content
+    result_array = CreateMessageResultWithTools(
+        role="assistant",
+        content=[
+            TextContent(type="text", text="Let me check the weather"),
+            ToolUseContent(type="tool_use", id="call_456", name="get_weather", input={"city": "NYC"}),
+        ],
+        model="test-model",
+        stopReason="toolUse",
+    )
+    content_list_array = result_array.content_as_list
+    assert len(content_list_array) == 2
+    assert content_list_array[0].type == "text"
+    assert content_list_array[1].type == "tool_use"

tests/shared/test_streamable_http.py

@@ -242,8 +242,9 @@ class ServerTest(Server):  # pragma: no cover
                 )
 
                 # Return the sampling result in the tool response
-                if all(c.type == "text" for c in sampling_result.content_as_list):
-                    response = "\n".join(c.text for c in sampling_result.content_as_list if c.type == "text")
+                # Since we're not passing tools param, result.content is single content
+                if sampling_result.content.type == "text":
+                    response = sampling_result.content.text
                 else:
                     response = str(sampling_result.content)
                 return [

tests/test_types.py

@@ -8,6 +8,7 @@ from mcp.types import (
     ClientRequest,
     CreateMessageRequestParams,
     CreateMessageResult,
+    CreateMessageResultWithTools,
     Implementation,
     InitializeRequest,
     InitializeRequestParams,
@@ -239,7 +240,7 @@ async def test_create_message_request_params_with_tools():
 
 @pytest.mark.anyio
 async def test_create_message_result_with_tool_use():
-    """Test CreateMessageResult with tool use content for SEP-1577."""
+    """Test CreateMessageResultWithTools with tool use content for SEP-1577."""
     result_data = {
         "role": "assistant",
         "content": {"type": "tool_use", "name": "search", "id": "call_123", "input": {"query": "test"}},
@@ -247,7 +248,8 @@ async def test_create_message_result_with_tool_use():
         "stopReason": "toolUse",
     }
 
-    result = CreateMessageResult.model_validate(result_data)
+    # Tool use content uses CreateMessageResultWithTools
+    result = CreateMessageResultWithTools.model_validate(result_data)
     assert result.role == "assistant"
     assert isinstance(result.content, ToolUseContent)
     assert result.stopReason == "toolUse"
@@ -259,6 +261,25 @@ async def test_create_message_result_with_tool_use():
     assert content_list[0] == result.content
 
 
+@pytest.mark.anyio
+async def test_create_message_result_basic():
+    """Test CreateMessageResult with basic text content (backwards compatible)."""
+    result_data = {
+        "role": "assistant",
+        "content": {"type": "text", "text": "Hello!"},
+        "model": "claude-3",
+        "stopReason": "endTurn",
+    }
+
+    # Basic content uses CreateMessageResult (single content, no arrays)
+    result = CreateMessageResult.model_validate(result_data)
+    assert result.role == "assistant"
+    assert isinstance(result.content, TextContent)
+    assert result.content.text == "Hello!"
+    assert result.stopReason == "endTurn"
+    assert result.model == "claude-3"
+
+
 @pytest.mark.anyio
 async def test_client_capabilities_with_sampling_tools():
     """Test ClientCapabilities with nested sampling capabilities for SEP-1577."""