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!