Implement SEP-1577: Sampling With Tools

[DaleSeo]

Closes #552

Motivation and Context

This PR implements SEP-1577: Sampling With Tools, enabling MCP servers to run agentic loops using the client's LLM while maintaining user supervision.

Key additions:

• ToolChoice / ToolChoiceMode - Control tool selection behavior
• ToolUseContent / ToolResultContent - Tool calling content types
• SamplingContent<T> - Single or array content wrapper
• SamplingMessageContent - Unified content enum with ToolUse and ToolResult variants
• SamplingCapability - Structured capability with tools and context sub-capabilities

Reference implementations:

• TypeScript SDK: Implement SEP-1577 - Sampling With Tools typescript-sdk#1101
• Python SDK: Implement SEP-1577 - Sampling With Tools python-sdk#1594

How Has This Been Tested?

• New unit tests covering serialization, deserialization, and API usage for all new types
• All existing tests updated and passing
• Backward compatibility tests verifying old JSON formats still deserialize correctly

Breaking Changes

The type signature of SamplingMessage.content changed from Content to SamplingContent<SamplingMessageContent>.

Migration Made Easy

Convenience constructors (recommended):

// Before
let msg = SamplingMessage { role: Role::User, content: Content::text("hi") };

// After - use the new helper methods
let msg = SamplingMessage::user_text("hi");
let msg = SamplingMessage::assistant_text("Hello");

Converting existing Content values:

use std::convert::TryInto;

let content: Content = Content::text("hello");

// Convert to SamplingMessageContent
let sampling_content: SamplingMessageContent = content.try_into()?;

// Or convert directly to SamplingContent<SamplingMessageContent>
let content: Content = Content::text("hello");
let wrapped: SamplingContent<SamplingMessageContent> = content.try_into()?;

Note: TryFrom is used because Content::Resource and Content::ResourceLink variants are not supported in sampling messages.

Wire Format Compatibility

• ✅ Deserialization is backward compatible - Old JSON format (single content object) still deserializes correctly
• ✅ ClientCapabilities.sampling - Empty {} JSON still deserializes to SamplingCapability

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

// Advertise capability
let capabilities = ClientCapabilities::builder()
    .enable_sampling()
    .enable_sampling_tools()
    .build();

// Create request with tools
let params = CreateMessageRequestParams {
    messages: vec![SamplingMessage::user_text("What's the weather?")],
    tools: Some(vec![weather_tool]),
    tool_choice: Some(ToolChoice::auto()),
    max_tokens: 1000,
    ..Default::default()
};

// Handle tool use response  
if result.stop_reason.as_deref() == Some(CreateMessageResult::STOP_REASON_TOOL_USE) {
    for content in result.message.content.iter() {
        if let Some(tool_use) = content.as_tool_use() {
            // Execute tool and continue conversation
        }
    }
}

[DaleSeo]

Hi @alexhancock, could you please take a look at this PR? Thanks!

[alexhancock]

@DaleSeo Sorry it took me a bit. I'm glad to have support for this, but a little worried about the breaking change. Can you think of any alternatives that would keep compat, or make it a but lighter for updaters?

Interested to discuss!

[DaleSeo]

Thanks for the feedback, @alexhancock! I've made a few updates to simplify the migration:

1. I added TryFrom conversions for existing Content values:

use std::convert::TryInto;

let content: Content = Content::text("hello");
let sampling_content: SamplingMessageContent = content.try_into()?;

2. The wire format is backward compatible. The old JSON (single content object) still deserializes correctly, so existing serialized data will remain intact.

3. I created convenience constructors to make common cases easier:

// Before
SamplingMessage { role: Role::User, content: Content::text("hi") }

// After
SamplingMessage::user_text("hi")

The type change is unavoidable to support tool use and result content types from SEP-1577, but I think the migration path is now reasonable. Most users can either use the new constructors or add .try_into() to their existing code.

Let me know if you have any other suggestions!

[alexhancock]

Thanks @DaleSeo, approving but also leaving this list of recommendations.

Generated by Opus 4.5 comparing the diff to https://modelcontextprotocol.io/community/seps/1577--sampling-with-tools.md

## SEP-1577 Implementation Review - Recommended Changes

1. **Missing capability validation (MUST requirement)**: Add runtime validation to throw an error when `tools` or `toolChoice` are provided but `clientCapabilities.sampling.tools` is missing.

2. **Tool use/result balancing not enforced (MUST requirement)**: Add validation that every assistant message with `ToolUseContent` (id: X) is followed by a user message with `ToolResultContent` (toolUseId: X).

3. **Tool result content mixing not enforced**: Spec states "SamplingMessage with tool result content blocks MUST NOT contain other content types" - add validation for this.

4. **Role-content type mismatch possible**: `ToolUseContent` should only appear in assistant messages, `ToolResultContent` only in user messages. Currently not enforced - consider runtime validation.

5. **CreateMessageResult.role not constrained**: Spec says `role: "assistant"` (literal), but implementation allows any `Role`. Minor, but could be tightened.

6. **Dead code**: `AssistantMessageContent` and `UserMessageContent` enums in `content.rs` are defined but never used. Remove or use them.

The validations seem good to do as followups?