turbomcp_client/

lib.rs

//! # `TurboMCP` Client
//!
//! MCP (Model Context Protocol) client implementation for connecting to MCP servers
//! and consuming their capabilities (tools, prompts, resources, and sampling).
//!
//! ## Features
//!
//! - Connection management with automatic reconnection
//! - Error handling and recovery mechanisms
//! - Support for all MCP capabilities including bidirectional sampling
//! - Elicitation response handling for server-initiated user input requests
//! - Transport-agnostic design (works with any `Transport` implementation)
//! - Type-safe protocol communication
//! - Request/response correlation tracking
//! - Timeout and cancellation support
//! - Automatic capability negotiation
//! - Handler support for server-initiated requests (sampling and elicitation)
//!
//! ## Architecture
//!
//! The client follows a layered architecture:
//!
//! ```text
//! Application Layer
//!        ↓
//! Client API (this crate)
//!        ↓  
//! Protocol Layer (turbomcp-protocol)
//!        ↓
//! Transport Layer (turbomcp-transport)
//! ```
//!
//! ## Usage
//!
//! ```rust,no_run
//! use turbomcp_client::{Client, ClientBuilder};
//! use turbomcp_transport::stdio::StdioTransport;
//!
//! # async fn example() -> turbomcp_protocol::Result<()> {
//! // Create a client with stdio transport
//! let transport = StdioTransport::new();
//! let mut client = Client::new(transport);
//!
//! // Initialize connection and negotiate capabilities
//! let result = client.initialize().await?;
//! println!("Connected to: {}", result.server_info.name);
//!
//! // List and call tools
//! let tools = client.list_tools().await?;
//! for tool in tools {
//!     println!("Tool: {} - {}", tool.name, tool.description.as_deref().unwrap_or("No description"));
//! }
//!
//! // Access resources
//! let resources = client.list_resources().await?;
//! for resource in resources {
//!     println!("Resource: {} ({})", resource.name, resource.uri);
//! }
//! # Ok(())
//! # }
//! ```
//!
//! ## Elicitation Response Handling
//!
//! The client supports handling server-initiated elicitation requests:
//!
//! ```rust,no_run
//! use turbomcp_client::Client;
//! use std::collections::HashMap;
//!
//! // Simple elicitation handling example
//! async fn handle_server_elicitation() {
//!     // When server requests user input, you would:
//!     // 1. Present the schema to the user
//!     // 2. Collect their input  
//!     // 3. Send response back to server
//!     
//!     let user_preferences: HashMap<String, String> = HashMap::new();
//!     // Your UI/CLI interaction logic here
//!     println!("Server requesting user preferences");
//! }
//! ```
//!
//! ## Sampling Support
//!
//! Handle server-initiated sampling requests for LLM capabilities:
//!
//! ```rust,no_run
//! use turbomcp_client::Client;
//! use turbomcp_client::sampling::SamplingHandler;
//! use turbomcp_protocol::types::{ContentBlock, CreateMessageRequest, CreateMessageResult, Role, StopReason, TextContent};
//! use std::future::Future;
//! use std::pin::Pin;
//!
//! #[derive(Debug)]
//! struct MySamplingHandler {
//!     // Your LLM client would go here
//! }
//!
//! impl SamplingHandler for MySamplingHandler {
//!     fn handle_create_message(
//!         &self,
//!         request_id: String,
//!         request: CreateMessageRequest
//!     ) -> Pin<Box<dyn Future<Output = Result<CreateMessageResult, Box<dyn std::error::Error + Send + Sync>>> + Send + '_>> {
//!         Box::pin(async move {
//!             // Forward to your LLM provider (OpenAI, Anthropic, etc.)
//!             // Use request_id for correlation tracking
//!             // Allows the server to request LLM sampling through the client
//!
//!             Ok(CreateMessageResult {
//!                 role: Role::Assistant,
//!                 content: ContentBlock::Text(
//!                     TextContent {
//!                         text: "Response from LLM".to_string(),
//!                         annotations: None,
//!                         meta: None,
//!                     }
//!                 ),
//!                 model: "gpt-4".to_string(),
//!                 stop_reason: Some(StopReason::EndTurn),
//!                 _meta: None,
//!             })
//!         })
//!     }
//! }
//! ```
//!
//! ## Error Handling
//!
//! The client provides comprehensive error handling with automatic retry logic:
//!
//! ```rust,no_run
//! # use turbomcp_client::Client;
//! # use turbomcp_transport::stdio::StdioTransport;
//! # async fn example() -> turbomcp_protocol::Result<()> {
//! # let mut client = Client::new(StdioTransport::new());
//! match client.call_tool("my_tool", None, None).await {
//!     Ok(result) => println!("Tool result: {:?}", result),
//!     Err(e) => eprintln!("Tool call failed: {}", e),
//! }
//! # Ok(())
//! # }
//! ```

/// TurboMCP Client version from Cargo.toml
///
/// This constant provides easy programmatic access to the current version.
///
/// # Example
///
/// ```rust
/// println!("TurboMCP Client version: {}", turbomcp_client::VERSION);
/// ```
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// TurboMCP Client crate name
pub const CRATE_NAME: &str = env!("CARGO_PKG_NAME");

pub mod client;
pub mod handlers;
pub mod integration;
pub mod prelude;
pub mod sampling;

// v3.0 Tower-native middleware
pub mod middleware;

// Re-export key types for convenience
pub use client::{ConnectionInfo, ConnectionState, ManagerConfig, ServerGroup, SessionManager};

use std::sync::Arc;
use std::time::Duration;

// Re-export Transport trait for generic bounds in integrations
pub use turbomcp_transport::Transport;

// ============================================================================
// TOP-LEVEL RE-EXPORTS FOR ERGONOMIC IMPORTS
// ============================================================================

// Result/Error types - re-export from protocol for consistency
pub use turbomcp_protocol::{Error, Result};

// Handler types (most commonly used)
pub use handlers::{
    // Cancellation (current MCP spec)
    CancellationHandler,
    CancelledNotification,
    ElicitationAction,
    // Elicitation
    ElicitationHandler,
    ElicitationRequest,
    ElicitationResponse,
    // Error handling
    HandlerError,
    HandlerResult,
    // Logging (current MCP spec)
    LogHandler,
    LoggingNotification,
    // Progress (current MCP spec)
    ProgressHandler,
    ProgressNotification,
    PromptListChangedHandler,
    // List changed handlers (current MCP spec)
    ResourceListChangedHandler,
    // Resource updates (current MCP spec)
    ResourceUpdateHandler,
    ResourceUpdatedNotification,
    // Roots
    RootsHandler,
    ToolListChangedHandler,
};

// Sampling types
pub use sampling::{SamplingHandler, ServerInfo, UserInteractionHandler};

// v3.0 Tower middleware
pub use middleware::{
    Cache, CacheConfig, CacheLayer, CacheService, McpRequest, McpResponse, Metrics, MetricsLayer,
    MetricsService, MetricsSnapshot, TracingLayer, TracingService,
};

// Common protocol types
pub use turbomcp_protocol::types::{
    // Resource content types (for processing embedded resources)
    BlobResourceContents,
    // Tool result types (for LLM integrations like rig)
    CallToolResult,
    // Core types
    ContentBlock,
    EmbeddedResource,
    LogLevel,
    Prompt,
    Resource,
    ResourceContent,
    ResourceContents,
    Role,
    TextResourceContents,
    Tool,
};

// Transport re-exports (with feature gates)
#[cfg(feature = "stdio")]
pub use turbomcp_transport::stdio::StdioTransport;

#[cfg(feature = "http")]
pub use turbomcp_transport::streamable_http_client::{
    RetryPolicy, StreamableHttpClientConfig, StreamableHttpClientTransport,
};

#[cfg(feature = "tcp")]
pub use turbomcp_transport::tcp::{TcpTransport, TcpTransportBuilder};

#[cfg(feature = "unix")]
pub use turbomcp_transport::unix::{UnixTransport, UnixTransportBuilder};

#[cfg(feature = "websocket")]
pub use turbomcp_transport::websocket_bidirectional::{
    WebSocketBidirectionalConfig, WebSocketBidirectionalTransport,
};

/// Client capability configuration
///
/// Defines the capabilities that this client supports when connecting to MCP servers.
/// These capabilities are sent during the initialization handshake to negotiate
/// which features will be available during the session.
///
/// # Examples
///
/// ```
/// use turbomcp_client::ClientCapabilities;
///
/// let capabilities = ClientCapabilities {
///     tools: true,
///     prompts: true,
///     resources: true,
///     sampling: false,
///     max_concurrent_handlers: 100,
/// };
/// ```
#[derive(Debug, Clone)]
pub struct ClientCapabilities {
    /// Whether the client supports tool calling
    pub tools: bool,

    /// Whether the client supports prompts
    pub prompts: bool,

    /// Whether the client supports resources
    pub resources: bool,

    /// Whether the client supports sampling
    pub sampling: bool,

    /// Maximum concurrent request/notification handlers (default: 100)
    ///
    /// This limits how many server-initiated requests/notifications can be processed simultaneously.
    /// Provides automatic backpressure when the limit is reached.
    ///
    /// **Tuning Guide:**
    /// - Low-resource clients: 50
    /// - Standard clients: 100 (default)
    /// - High-performance: 200-500
    /// - Maximum recommended: 1000
    pub max_concurrent_handlers: usize,
}

impl Default for ClientCapabilities {
    fn default() -> Self {
        Self {
            tools: false,
            prompts: false,
            resources: false,
            sampling: false,
            max_concurrent_handlers: 100,
        }
    }
}

impl ClientCapabilities {
    /// All capabilities enabled (tools, prompts, resources, sampling)
    ///
    /// This is the most comprehensive configuration, enabling full MCP protocol support.
    ///
    /// # Example
    ///
    /// ```rust
    /// use turbomcp_client::ClientCapabilities;
    ///
    /// let capabilities = ClientCapabilities::all();
    /// assert!(capabilities.tools);
    /// assert!(capabilities.prompts);
    /// assert!(capabilities.resources);
    /// assert!(capabilities.sampling);
    /// ```
    #[must_use]
    pub fn all() -> Self {
        Self {
            tools: true,
            prompts: true,
            resources: true,
            sampling: true,
            max_concurrent_handlers: 100,
        }
    }

    /// Core capabilities without sampling (tools, prompts, resources)
    ///
    /// This is the recommended default for most applications. It enables
    /// all standard MCP features except server-initiated sampling requests.
    ///
    /// # Example
    ///
    /// ```rust
    /// use turbomcp_client::ClientCapabilities;
    ///
    /// let capabilities = ClientCapabilities::core();
    /// assert!(capabilities.tools);
    /// assert!(capabilities.prompts);
    /// assert!(capabilities.resources);
    /// assert!(!capabilities.sampling);
    /// ```
    #[must_use]
    pub fn core() -> Self {
        Self {
            tools: true,
            prompts: true,
            resources: true,
            sampling: false,
            max_concurrent_handlers: 100,
        }
    }

    /// Minimal capabilities (tools only)
    ///
    /// Use this for simple tool-calling clients that don't need prompts,
    /// resources, or sampling support.
    ///
    /// # Example
    ///
    /// ```rust
    /// use turbomcp_client::ClientCapabilities;
    ///
    /// let capabilities = ClientCapabilities::minimal();
    /// assert!(capabilities.tools);
    /// assert!(!capabilities.prompts);
    /// assert!(!capabilities.resources);
    /// assert!(!capabilities.sampling);
    /// ```
    #[must_use]
    pub fn minimal() -> Self {
        Self {
            tools: true,
            prompts: false,
            resources: false,
            sampling: false,
            max_concurrent_handlers: 100,
        }
    }

    /// Only tools enabled
    ///
    /// Same as `minimal()`, provided for clarity.
    #[must_use]
    pub fn only_tools() -> Self {
        Self::minimal()
    }

    /// Only resources enabled
    ///
    /// Use this for resource-focused clients that don't need tools or prompts.
    ///
    /// # Example
    ///
    /// ```rust
    /// use turbomcp_client::ClientCapabilities;
    ///
    /// let capabilities = ClientCapabilities::only_resources();
    /// assert!(!capabilities.tools);
    /// assert!(!capabilities.prompts);
    /// assert!(capabilities.resources);
    /// ```
    #[must_use]
    pub fn only_resources() -> Self {
        Self {
            tools: false,
            prompts: false,
            resources: true,
            sampling: false,
            max_concurrent_handlers: 100,
        }
    }

    /// Only prompts enabled
    ///
    /// Use this for prompt-focused clients that don't need tools or resources.
    ///
    /// # Example
    ///
    /// ```rust
    /// use turbomcp_client::ClientCapabilities;
    ///
    /// let capabilities = ClientCapabilities::only_prompts();
    /// assert!(!capabilities.tools);
    /// assert!(capabilities.prompts);
    /// assert!(!capabilities.resources);
    /// ```
    #[must_use]
    pub fn only_prompts() -> Self {
        Self {
            tools: false,
            prompts: true,
            resources: false,
            sampling: false,
            max_concurrent_handlers: 100,
        }
    }

    /// Only sampling enabled
    ///
    /// Use this for clients that exclusively handle server-initiated sampling requests.
    #[must_use]
    pub fn only_sampling() -> Self {
        Self {
            tools: false,
            prompts: false,
            resources: false,
            sampling: true,
            max_concurrent_handlers: 100,
        }
    }
}

/// JSON-RPC protocol handler for MCP communication
// Note: ProtocolClient implementation moved to client/protocol.rs for better modularity
/// MCP client for communicating with servers
///
/// The `Client` struct provides an ergonomic interface for interacting with MCP servers.
/// It handles protocol complexity internally, exposing clean, type-safe methods.
///
/// # Type Parameters
///
/// * `T` - The transport implementation used for communication
///
/// # Examples
///
/// ```rust,no_run
/// use turbomcp_client::Client;
/// use turbomcp_transport::stdio::StdioTransport;
///
/// # async fn example() -> turbomcp_protocol::Result<()> {
/// let transport = StdioTransport::new();
/// let mut client = Client::new(transport);
///
/// // Initialize and start using the client
/// client.initialize().await?;
/// # Ok(())
/// # }
/// ```
// Re-export Client from the core module
pub use client::core::Client;

// Thread-safe wrapper for sharing Client across async tasks
//
// This wrapper encapsulates the Arc/Mutex complexity and provides a clean API
// for concurrent access to MCP client functionality. It addresses the limitations
// identified in PR feedback where Client requires `&mut self` for all operations
// but needs to be shared across multiple async tasks.
//
// # Design Rationale
//
// All Client methods require `&mut self` because:
// - MCP connections maintain state (initialized flag, connection status)
// - Request correlation tracking for JSON-RPC requires mutation
// - Handler and plugin registries need mutable access
//
// Note: SharedClient has been removed in v2 - Client is now directly cloneable via Arc

// ----------------------------------------------------------------------------
// Re-exports
// ----------------------------------------------------------------------------

#[doc = "Result of client initialization"]
#[doc = ""]
#[doc = "Contains information about the server and the negotiated capabilities"]
#[doc = "after a successful initialization handshake."]
pub use client::config::InitializeResult;

// ServerCapabilities is now imported from turbomcp_protocol::types

/// Connection configuration for the client
#[derive(Debug, Clone)]
pub struct ConnectionConfig {
    /// Request timeout in milliseconds
    pub timeout_ms: u64,

    /// Maximum number of retry attempts
    pub max_retries: u32,

    /// Retry delay in milliseconds
    pub retry_delay_ms: u64,

    /// Keep-alive interval in milliseconds
    pub keepalive_ms: u64,
}

fn protocol_transport_config(
    connection_config: &ConnectionConfig,
) -> turbomcp_transport::TransportConfig {
    let timeout = Duration::from_millis(connection_config.timeout_ms);

    turbomcp_transport::TransportConfig {
        connect_timeout: timeout,
        keep_alive: Some(Duration::from_millis(connection_config.keepalive_ms)),
        timeouts: turbomcp_transport::config::TimeoutConfig {
            connect: timeout,
            request: Some(timeout),
            total: Some(timeout),
            read: Some(timeout),
        },
        ..Default::default()
    }
}

fn resilience_requested(builder: &ClientBuilder) -> bool {
    builder.enable_resilience
        || builder.retry_config.is_some()
        || builder.circuit_breaker_config.is_some()
        || builder.health_check_config.is_some()
}

impl Default for ConnectionConfig {
    fn default() -> Self {
        Self {
            timeout_ms: 30_000,    // 30 seconds
            max_retries: 3,        // 3 attempts
            retry_delay_ms: 1_000, // 1 second
            keepalive_ms: 60_000,  // 60 seconds
        }
    }
}

/// Builder for configuring and creating MCP clients
///
/// Provides a fluent interface for configuring client options before creation.
/// The enhanced builder pattern supports comprehensive configuration including:
/// - Protocol capabilities
/// - Plugin registration
/// - Handler registration
/// - Connection settings
/// - Resilience configuration
///
/// # Examples
///
/// Basic usage:
/// ```rust,no_run
/// use turbomcp_client::ClientBuilder;
/// use turbomcp_transport::stdio::StdioTransport;
///
/// # async fn example() -> turbomcp_protocol::Result<()> {
/// let client = ClientBuilder::new()
///     .with_tools(true)
///     .with_prompts(true)
///     .with_resources(false)
///     .build(StdioTransport::new());
/// # Ok(())
/// # }
/// ```
///
/// Advanced configuration with Tower middleware:
/// ```rust,no_run
/// use turbomcp_client::{ClientBuilder, ConnectionConfig};
/// use turbomcp_client::middleware::MetricsLayer;
/// use turbomcp_transport::stdio::StdioTransport;
/// use tower::ServiceBuilder;
///
/// # async fn example() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
/// let client = ClientBuilder::new()
///     .with_tools(true)
///     .with_prompts(true)
///     .with_resources(true)
///     .with_sampling(true)
///     .with_connection_config(ConnectionConfig {
///         timeout_ms: 60_000,
///         max_retries: 5,
///         retry_delay_ms: 2_000,
///         keepalive_ms: 30_000,
///     })
///     .build(StdioTransport::new())
///     .await?;
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Default)]
pub struct ClientBuilder {
    capabilities: ClientCapabilities,
    connection_config: ConnectionConfig,
    elicitation_handler: Option<Arc<dyn crate::handlers::ElicitationHandler>>,
    log_handler: Option<Arc<dyn crate::handlers::LogHandler>>,
    resource_update_handler: Option<Arc<dyn crate::handlers::ResourceUpdateHandler>>,
    progress_handler: Option<Arc<dyn crate::handlers::ProgressHandler>>,
    // Robustness configuration
    enable_resilience: bool,
    retry_config: Option<turbomcp_transport::resilience::RetryConfig>,
    circuit_breaker_config: Option<turbomcp_transport::resilience::CircuitBreakerConfig>,
    health_check_config: Option<turbomcp_transport::resilience::HealthCheckConfig>,
}

// Default implementation is now derived

impl ClientBuilder {
    /// Create a new client builder
    ///
    /// Returns a new builder with default configuration.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    // ============================================================================
    // CAPABILITY CONFIGURATION
    // ============================================================================

    /// Enable or disable tool support
    ///
    /// # Arguments
    ///
    /// * `enabled` - Whether to enable tool support
    #[must_use]
    pub fn with_tools(mut self, enabled: bool) -> Self {
        self.capabilities.tools = enabled;
        self
    }

    /// Enable or disable prompt support
    ///
    /// # Arguments
    ///
    /// * `enabled` - Whether to enable prompt support
    #[must_use]
    pub fn with_prompts(mut self, enabled: bool) -> Self {
        self.capabilities.prompts = enabled;
        self
    }

    /// Enable or disable resource support
    ///
    /// # Arguments
    ///
    /// * `enabled` - Whether to enable resource support
    #[must_use]
    pub fn with_resources(mut self, enabled: bool) -> Self {
        self.capabilities.resources = enabled;
        self
    }

    /// Enable or disable sampling support
    ///
    /// # Arguments
    ///
    /// * `enabled` - Whether to enable sampling support
    #[must_use]
    pub fn with_sampling(mut self, enabled: bool) -> Self {
        self.capabilities.sampling = enabled;
        self
    }

    /// Set maximum concurrent request/notification handlers
    ///
    /// This limits how many server-initiated requests/notifications can be processed simultaneously.
    /// Provides automatic backpressure when the limit is reached.
    ///
    /// # Arguments
    ///
    /// * `limit` - Maximum concurrent handlers (default: 100)
    ///
    /// # Tuning Guide
    ///
    /// - Low-resource clients: 50
    /// - Standard clients: 100 (default)
    /// - High-performance: 200-500
    /// - Maximum recommended: 1000
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use turbomcp_client::ClientBuilder;
    /// # use turbomcp_transport::StdioTransport;
    ///
    /// let builder = ClientBuilder::new()
    ///     .with_max_concurrent_handlers(200);
    /// ```
    #[must_use]
    pub fn with_max_concurrent_handlers(mut self, limit: usize) -> Self {
        self.capabilities.max_concurrent_handlers = limit;
        self
    }

    /// Configure all capabilities at once
    ///
    /// # Arguments
    ///
    /// * `capabilities` - The capabilities configuration
    #[must_use]
    pub fn with_capabilities(mut self, capabilities: ClientCapabilities) -> Self {
        self.capabilities = capabilities;
        self
    }

    // ============================================================================
    // CONNECTION CONFIGURATION
    // ============================================================================

    /// Configure connection settings
    ///
    /// # Arguments
    ///
    /// * `config` - The connection configuration
    #[must_use]
    pub fn with_connection_config(mut self, config: ConnectionConfig) -> Self {
        self.connection_config = config;
        self
    }

    /// Set request timeout
    ///
    /// # Arguments
    ///
    /// * `timeout_ms` - Timeout in milliseconds
    #[must_use]
    pub fn with_timeout(mut self, timeout_ms: u64) -> Self {
        self.connection_config.timeout_ms = timeout_ms;
        self
    }

    /// Set maximum retry attempts
    ///
    /// # Arguments
    ///
    /// * `max_retries` - Maximum number of retries
    #[must_use]
    pub fn with_max_retries(mut self, max_retries: u32) -> Self {
        self.connection_config.max_retries = max_retries;
        self
    }

    /// Set retry delay
    ///
    /// # Arguments
    ///
    /// * `delay_ms` - Retry delay in milliseconds
    #[must_use]
    pub fn with_retry_delay(mut self, delay_ms: u64) -> Self {
        self.connection_config.retry_delay_ms = delay_ms;
        self
    }

    /// Set keep-alive interval
    ///
    /// # Arguments
    ///
    /// * `interval_ms` - Keep-alive interval in milliseconds
    #[must_use]
    pub fn with_keepalive(mut self, interval_ms: u64) -> Self {
        self.connection_config.keepalive_ms = interval_ms;
        self
    }

    // ============================================================================
    // ROBUSTNESS & RESILIENCE CONFIGURATION
    // ============================================================================

    /// Enable resilient transport with circuit breaker, retry, and health checking
    ///
    /// When enabled, the transport layer will automatically:
    /// - Retry failed operations with exponential backoff
    /// - Use circuit breaker pattern to prevent cascade failures
    /// - Perform periodic health checks
    /// - Deduplicate messages
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use turbomcp_client::ClientBuilder;
    /// use turbomcp_transport::stdio::StdioTransport;
    ///
    /// let client = ClientBuilder::new()
    ///     .enable_resilience()
    ///     .build(StdioTransport::new());
    /// ```
    #[must_use]
    pub fn enable_resilience(mut self) -> Self {
        self.enable_resilience = true;
        self
    }

    /// Configure retry behavior for resilient transport
    ///
    /// # Arguments
    ///
    /// * `config` - Retry configuration
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use turbomcp_client::ClientBuilder;
    /// use turbomcp_transport::resilience::RetryConfig;
    /// use turbomcp_transport::stdio::StdioTransport;
    /// use std::time::Duration;
    ///
    /// let client = ClientBuilder::new()
    ///     .enable_resilience()
    ///     .with_retry_config(RetryConfig {
    ///         max_attempts: 5,
    ///         base_delay: Duration::from_millis(100),
    ///         max_delay: Duration::from_secs(30),
    ///         backoff_multiplier: 2.0,
    ///         jitter_factor: 0.1,
    ///         retry_on_connection_error: true,
    ///         retry_on_timeout: true,
    ///         custom_retry_conditions: Vec::new(),
    ///     })
    ///     .build(StdioTransport::new());
    /// ```
    #[must_use]
    pub fn with_retry_config(
        mut self,
        config: turbomcp_transport::resilience::RetryConfig,
    ) -> Self {
        self.retry_config = Some(config);
        self.enable_resilience = true; // Auto-enable resilience
        self
    }

    /// Configure circuit breaker for resilient transport
    ///
    /// # Arguments
    ///
    /// * `config` - Circuit breaker configuration
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use turbomcp_client::ClientBuilder;
    /// use turbomcp_transport::resilience::CircuitBreakerConfig;
    /// use turbomcp_transport::stdio::StdioTransport;
    /// use std::time::Duration;
    ///
    /// let client = ClientBuilder::new()
    ///     .enable_resilience()
    ///     .with_circuit_breaker_config(CircuitBreakerConfig {
    ///         failure_threshold: 5,
    ///         success_threshold: 2,
    ///         timeout: Duration::from_secs(60),
    ///         rolling_window_size: 100,
    ///         minimum_requests: 10,
    ///     })
    ///     .build(StdioTransport::new());
    /// ```
    #[must_use]
    pub fn with_circuit_breaker_config(
        mut self,
        config: turbomcp_transport::resilience::CircuitBreakerConfig,
    ) -> Self {
        self.circuit_breaker_config = Some(config);
        self.enable_resilience = true; // Auto-enable resilience
        self
    }

    /// Configure health checking for resilient transport
    ///
    /// # Arguments
    ///
    /// * `config` - Health check configuration
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use turbomcp_client::ClientBuilder;
    /// use turbomcp_transport::resilience::HealthCheckConfig;
    /// use turbomcp_transport::stdio::StdioTransport;
    /// use std::time::Duration;
    ///
    /// let client = ClientBuilder::new()
    ///     .enable_resilience()
    ///     .with_health_check_config(HealthCheckConfig {
    ///         interval: Duration::from_secs(30),
    ///         timeout: Duration::from_secs(5),
    ///         failure_threshold: 3,
    ///         success_threshold: 1,
    ///         custom_check: None,
    ///     })
    ///     .build(StdioTransport::new());
    /// ```
    #[must_use]
    pub fn with_health_check_config(
        mut self,
        config: turbomcp_transport::resilience::HealthCheckConfig,
    ) -> Self {
        self.health_check_config = Some(config);
        self.enable_resilience = true; // Auto-enable resilience
        self
    }

    // ============================================================================
    // HANDLER REGISTRATION
    // ============================================================================

    /// Register an elicitation handler for processing user input requests
    ///
    /// # Arguments
    ///
    /// * `handler` - The elicitation handler implementation
    pub fn with_elicitation_handler(
        mut self,
        handler: Arc<dyn crate::handlers::ElicitationHandler>,
    ) -> Self {
        self.elicitation_handler = Some(handler);
        self
    }

    /// Register a log handler for processing server log messages
    ///
    /// # Arguments
    ///
    /// * `handler` - The log handler implementation
    pub fn with_log_handler(mut self, handler: Arc<dyn crate::handlers::LogHandler>) -> Self {
        self.log_handler = Some(handler);
        self
    }

    /// Register a resource update handler for processing resource change notifications
    ///
    /// # Arguments
    ///
    /// * `handler` - The resource update handler implementation
    pub fn with_resource_update_handler(
        mut self,
        handler: Arc<dyn crate::handlers::ResourceUpdateHandler>,
    ) -> Self {
        self.resource_update_handler = Some(handler);
        self
    }

    /// Register a progress handler for processing progress notifications
    ///
    /// # Arguments
    ///
    /// * `handler` - The progress handler implementation
    pub fn with_progress_handler(
        mut self,
        handler: Arc<dyn crate::handlers::ProgressHandler>,
    ) -> Self {
        self.progress_handler = Some(handler);
        self
    }

    // ============================================================================
    // BUILD METHODS
    // ============================================================================

    /// Build a client with the configured options
    ///
    /// Creates a new client instance with all the configured options. The client
    /// will be initialized with the registered plugins, handlers, and providers.
    ///
    /// # Arguments
    ///
    /// * `transport` - The transport to use for the client
    ///
    /// # Returns
    ///
    /// Returns a configured `Client` instance wrapped in a Result for async setup.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use turbomcp_client::ClientBuilder;
    /// use turbomcp_transport::stdio::StdioTransport;
    ///
    /// # async fn example() -> turbomcp_protocol::Result<()> {
    /// let client = ClientBuilder::new()
    ///     .with_tools(true)
    ///     .with_prompts(true)
    ///     .build(StdioTransport::new())
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn build<T: Transport + 'static>(self, transport: T) -> Result<Client<T>> {
        if resilience_requested(&self) {
            return Err(Error::configuration(
                "resilience settings require build_resilient(); build() would otherwise ignore them"
                    .to_string(),
            ));
        }

        // Create base client with capabilities
        let client = Client::with_capabilities_and_config(
            transport,
            self.capabilities,
            protocol_transport_config(&self.connection_config),
        );

        // Register handlers
        if let Some(handler) = self.elicitation_handler {
            client.set_elicitation_handler(handler);
        }
        if let Some(handler) = self.log_handler {
            client.set_log_handler(handler);
        }
        if let Some(handler) = self.resource_update_handler {
            client.set_resource_update_handler(handler);
        }
        if let Some(handler) = self.progress_handler {
            client.set_progress_handler(handler);
        }

        Ok(client)
    }

    /// Build a client with resilient transport (circuit breaker, retry, health checking)
    ///
    /// When resilience features are enabled via `enable_resilience()` or any resilience
    /// configuration method, this wraps the transport in a `TurboTransport` that provides:
    /// - Automatic retry with exponential backoff
    /// - Circuit breaker pattern for fast failure
    /// - Health checking and monitoring
    /// - Message deduplication
    ///
    /// # Arguments
    ///
    /// * `transport` - The base transport to wrap with resilience features
    ///
    /// # Returns
    ///
    /// Returns a configured `Client<TurboTransport>` instance.
    ///
    /// # Errors
    ///
    /// Returns an error if plugin initialization fails.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use turbomcp_client::ClientBuilder;
    /// use turbomcp_transport::stdio::StdioTransport;
    /// use turbomcp_transport::resilience::{RetryConfig, CircuitBreakerConfig, HealthCheckConfig};
    /// use std::time::Duration;
    ///
    /// # async fn example() -> turbomcp_protocol::Result<()> {
    /// let client = ClientBuilder::new()
    ///     .with_retry_config(RetryConfig {
    ///         max_attempts: 5,
    ///         base_delay: Duration::from_millis(200),
    ///         ..Default::default()
    ///     })
    ///     .with_circuit_breaker_config(CircuitBreakerConfig {
    ///         failure_threshold: 3,
    ///         timeout: Duration::from_secs(30),
    ///         ..Default::default()
    ///     })
    ///     .with_health_check_config(HealthCheckConfig {
    ///         interval: Duration::from_secs(15),
    ///         timeout: Duration::from_secs(5),
    ///         ..Default::default()
    ///     })
    ///     .build_resilient(StdioTransport::new())
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn build_resilient<T: Transport + 'static>(
        self,
        transport: T,
    ) -> Result<Client<turbomcp_transport::resilience::TurboTransport>> {
        use turbomcp_transport::resilience::TurboTransport;

        // Get configurations or use defaults
        let retry_config =
            self.retry_config
                .unwrap_or_else(|| turbomcp_transport::resilience::RetryConfig {
                    max_attempts: self.connection_config.max_retries.max(1),
                    base_delay: Duration::from_millis(self.connection_config.retry_delay_ms),
                    ..Default::default()
                });
        let circuit_config = self.circuit_breaker_config.unwrap_or_default();
        let health_config = self.health_check_config.unwrap_or_else(|| {
            turbomcp_transport::resilience::HealthCheckConfig {
                timeout: Duration::from_millis(self.connection_config.timeout_ms),
                ..Default::default()
            }
        });

        // Wrap transport in TurboTransport
        let robust_transport = TurboTransport::new(
            Box::new(transport),
            retry_config,
            circuit_config,
            health_config,
        );

        // Create client with resilient transport
        let client = Client::with_capabilities_and_config(
            robust_transport,
            self.capabilities,
            protocol_transport_config(&self.connection_config),
        );

        // Register handlers
        if let Some(handler) = self.elicitation_handler {
            client.set_elicitation_handler(handler);
        }
        if let Some(handler) = self.log_handler {
            client.set_log_handler(handler);
        }
        if let Some(handler) = self.resource_update_handler {
            client.set_resource_update_handler(handler);
        }
        if let Some(handler) = self.progress_handler {
            client.set_progress_handler(handler);
        }

        Ok(client)
    }

    /// Build a client synchronously with basic configuration only
    ///
    /// This is a convenience method for simple use cases.
    ///
    /// # Arguments
    ///
    /// * `transport` - The transport to use for the client
    ///
    /// # Returns
    ///
    /// Returns a configured `Client` instance.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use turbomcp_client::ClientBuilder;
    /// use turbomcp_transport::stdio::StdioTransport;
    ///
    /// let client = ClientBuilder::new()
    ///     .with_tools(true)
    ///     .build_sync(StdioTransport::new());
    /// ```
    pub fn build_sync<T: Transport + 'static>(self, transport: T) -> Client<T> {
        assert!(
            !resilience_requested(&self),
            "resilience settings require build_resilient(); build_sync() would otherwise ignore them"
        );

        let client = Client::with_capabilities_and_config(
            transport,
            self.capabilities,
            protocol_transport_config(&self.connection_config),
        );

        // Register synchronous handlers only
        if let Some(handler) = self.elicitation_handler {
            client.set_elicitation_handler(handler);
        }
        if let Some(handler) = self.log_handler {
            client.set_log_handler(handler);
        }
        if let Some(handler) = self.resource_update_handler {
            client.set_resource_update_handler(handler);
        }
        if let Some(handler) = self.progress_handler {
            client.set_progress_handler(handler);
        }

        client
    }

    // ============================================================================
    // CONFIGURATION ACCESS
    // ============================================================================

    /// Get the current capabilities configuration
    #[must_use]
    pub fn capabilities(&self) -> &ClientCapabilities {
        &self.capabilities
    }

    /// Get the current connection configuration
    #[must_use]
    pub fn connection_config(&self) -> &ConnectionConfig {
        &self.connection_config
    }

    /// Check if any handlers are registered
    #[must_use]
    pub fn has_handlers(&self) -> bool {
        self.elicitation_handler.is_some()
            || self.log_handler.is_some()
            || self.resource_update_handler.is_some()
            || self.progress_handler.is_some()
    }
}

// Re-export types for public API
pub use turbomcp_protocol::types::ServerCapabilities as PublicServerCapabilities;

#[cfg(test)]
mod tests {
    use super::*;
    use std::future::Future;
    use std::pin::Pin;
    use turbomcp_transport::{
        TransportCapabilities, TransportConfig, TransportMessage, TransportMetrics,
        TransportResult, TransportState, TransportType,
    };

    #[derive(Debug, Default)]
    struct NoopTransport {
        capabilities: TransportCapabilities,
    }

    impl Transport for NoopTransport {
        fn transport_type(&self) -> TransportType {
            TransportType::Stdio
        }

        fn capabilities(&self) -> &TransportCapabilities {
            &self.capabilities
        }

        fn state(&self) -> Pin<Box<dyn Future<Output = TransportState> + Send + '_>> {
            Box::pin(async { TransportState::Disconnected })
        }

        fn connect(&self) -> Pin<Box<dyn Future<Output = TransportResult<()>> + Send + '_>> {
            Box::pin(async { Ok(()) })
        }

        fn disconnect(&self) -> Pin<Box<dyn Future<Output = TransportResult<()>> + Send + '_>> {
            Box::pin(async { Ok(()) })
        }

        fn send(
            &self,
            _message: TransportMessage,
        ) -> Pin<Box<dyn Future<Output = TransportResult<()>> + Send + '_>> {
            Box::pin(async { Ok(()) })
        }

        fn receive(
            &self,
        ) -> Pin<Box<dyn Future<Output = TransportResult<Option<TransportMessage>>> + Send + '_>>
        {
            Box::pin(async { Ok(None) })
        }

        fn metrics(&self) -> Pin<Box<dyn Future<Output = TransportMetrics> + Send + '_>> {
            Box::pin(async { TransportMetrics::default() })
        }

        fn configure(
            &self,
            _config: TransportConfig,
        ) -> Pin<Box<dyn Future<Output = TransportResult<()>> + Send + '_>> {
            Box::pin(async { Ok(()) })
        }
    }

    #[tokio::test]
    async fn build_rejects_resilience_flags() {
        let result = ClientBuilder::new()
            .enable_resilience()
            .build(NoopTransport::default())
            .await;

        assert!(result.is_err());
        let err = match result {
            Ok(_) => panic!("expected build() to reject resilience settings"),
            Err(err) => err,
        };
        assert!(err.to_string().contains("build_resilient"));
    }
}