Feature: Add Sampling Support

[ezynda3]

Priority: High
Breaking Change: No

Description: Implement MCP sampling support to allow servers to request LLM sampling ("completions" or "generations") from language models via clients. This enables servers to implement agentic behaviors with nested LLM calls while maintaining client control over model access and permissions.

Overview

The sampling feature allows servers to request text, audio, or image-based interactions from language models through the client, with no server API keys necessary. Clients maintain control over model selection, permissions, and user approval.

Key Features

• sampling/createMessage request support
• Model preference system with capability priorities and hints
• Support for text, image, and audio content
• User approval controls and security considerations
• Rate limiting and sensitive data handling

Implementation Tasks

Core Implementation

• Add sampling capability declaration during initialization
• Implement sampling/createMessage request/response handling
• Add message content types (text, image, audio)
• Implement model preference system with priorities and hints
• Add proper error handling for sampling requests
• Implement security controls and user approval mechanisms

Transport-Specific Tasks

STDIO Transport

• Implement sampling support in STDIO client transport
• Add bidirectional message handling for sampling requests
• Test sampling flow with STDIO server examples
• Add STDIO-specific error handling for sampling

Streamable HTTP Transport

• Implement sampling support in Streamable HTTP client transport
• Add HTTP-specific headers and request handling for sampling
• Test sampling flow with HTTP server examples
• Add HTTP-specific error handling and status codes for sampling

Data Types and Validation

• Add SamplingMessage types with role and content fields
• Add ModelPreferences struct with priorities and hints
• Add SamplingResult struct with model and stop reason
• Implement content validation for text, image, and audio
• Add JSON schema validation for sampling requests

Security and User Experience

• Implement user approval UI/controls for sampling requests
• Add prompt review and editing capabilities
• Add response review before delivery
• Implement rate limiting for sampling requests
• Add logging and audit trail for sampling operations

Testing and Documentation

• Add unit tests for sampling message types
• Add integration tests for both transport types
• Add examples demonstrating sampling usage
• Update documentation with sampling capabilities
• Add security best practices documentation

Files to Update

• mcp/types.go - Add sampling message types
• client/interface.go - Add sampling methods
• client/stdio.go - STDIO sampling implementation
• client/http.go - HTTP sampling implementation
• server/server.go - Server-side sampling support
• examples/ - Add sampling examples

Security Considerations

1. Clients SHOULD implement user approval controls
2. Both parties SHOULD validate message content
3. Clients SHOULD respect model preference hints
4. Clients SHOULD implement rate limiting
5. Both parties MUST handle sensitive data appropriately

Reference

Based on MCP Specification 2025-06-18: https://modelcontextprotocol.io/specification/2025-06-18/client/sampling