Struct McpClient 

pub struct McpClient { /* private fields */ }

MCP Client for connecting to and interacting with MCP servers.

The client can operate in two modes:

• Real mode: Uses rmcp SDK via RmcpClientAdapter
• Mock mode: Returns canned responses for testing

Validation

Enable parameter validation with with_validation():

let client = McpClient::new(config)?
    .with_validation(ValidationConfig::default());

When validation is enabled:

1. connect() caches tool schemas from list_tools()
2. call_tool() validates params before calling the server
3. Errors are enhanced with required fields and suggestions

Implementations

impl McpClient

pub fn new(config: McpConfig) -> Result<McpClient, McpError>

Create a new MCP client from configuration.

Validates the configuration and returns an error if invalid. The client is created in disconnected state.

Errors

Returns McpError::ValidationError if:

• config.name is empty
• config.command is empty

Example

let config = McpConfig::new("novanet", "npx")
    .with_args(["-y", "@novanet/mcp-server"]);
let client = McpClient::new(config)?;
assert!(!client.is_connected());

pub fn with_validation(self, config: ValidationConfig) -> McpClient

Enable parameter validation with the given config.

When validation is enabled:

• connect() will cache tool schemas from list_tools()
• call_tool() will validate params before calling the server
• Errors will be enhanced with required fields and suggestions

Example

let client = McpClient::new(config)?
    .with_validation(ValidationConfig::default());

pub fn with_cache(self, config: CacheConfig) -> McpClient

Enable response caching with the given config.

When caching is enabled:

• Successful tool responses are cached by tool:params_hash key
• Subsequent calls with same params return cached results
• Cache entries expire after TTL
• Error responses are never cached

Example

use std::time::Duration;

let client = McpClient::new(config)?
    .with_cache(CacheConfig {
        ttl: Duration::from_secs(300), // 5 minutes
        max_entries: 1000,
    });

pub fn cache_stats(&self) -> Option<ResponseCacheStats>

Get cache statistics (hits, misses, entries).

Returns None if caching is disabled.

pub fn was_last_call_cached(&self) -> bool

Check if the last call_tool() invocation was served from cache.

This method returns the cached status from the most recent tool call. Use this after call_tool() to determine if the response was cached.

pub fn mock(name: &str) -> McpClient

Create a mock MCP client for testing.

The mock client is pre-connected and returns canned responses:

• novanet_describe: Returns {"nodes": 62, "arcs": 182}
• novanet_context: Returns entity context JSON
• Other tools: Returns a generic success response

Example

let client = McpClient::mock("novanet");
assert!(client.is_connected());

pub fn name(&self) -> &str

Get the server name.

pub fn is_connected(&self) -> bool

Check if the client is connected to the server.

For real clients, delegates to adapter’s sync check (non-blocking). This avoids race conditions where AtomicBool becomes stale.

pub async fn is_connected_async(&self) -> bool

Check connection state asynchronously (accurate for real clients).

pub async fn ping(&self) -> Result<McpPingResult, McpPingError>

Ping the MCP server to verify it’s responsive.

This method:

1. Connects to the server if not already connected
2. Calls list_tools() to verify the server responds
3. Returns latency and tool count

Example

let result = client.ping().await?;
println!("Server {} responded in {:?} with {} tools",
    result.server, result.latency, result.tool_count);

pub fn is_configured(&self) -> bool

Quick check if MCP server is likely to be reachable.

Returns true if:

• Mock client: always true
• Real client: adapter exists and is configured

This is a synchronous check that doesn’t actually connect. Use ping() for a full health check.

pub async fn connect(&self) -> Result<(), McpError>

Connect to the MCP server.

For mock clients, this is a no-op that always succeeds. For real clients, this uses rmcp SDK to connect.

When validation is enabled, this also caches tool schemas from list_tools().

This method is idempotent - calling it when already connected succeeds.

Errors

Returns McpError::McpStartError if the server process fails to start. Returns McpError::McpSchemaError if schema caching fails.

pub async fn disconnect(&self) -> Result<(), McpError>

Disconnect from the MCP server.

For mock clients, this just updates the connection state. For real clients, this terminates the server process via rmcp.

This method is idempotent - calling it when already disconnected succeeds.

pub async fn reconnect(&self) -> Result<(), McpError>

Reconnect to the MCP server.

Useful when the connection is broken (e.g., broken pipe, server crashed). This terminates any existing connection and establishes a new one.

Errors

Returns McpError::McpStartError if reconnection fails.

Example

// After detecting a broken connection
client.reconnect().await?;
// Retry the failed operation

pub fn is_connection_error(error: &McpError) -> bool

Check if an error indicates a broken connection.

Used to determine if a reconnection attempt should be made before the next retry.

pub async fn call_tool( &self, name: &str, params: Value, ) -> Result<ToolCallResult, McpError>

Call an MCP tool with the given parameters.

Arguments

• name - Tool name (e.g., “novanet_context”, “read_file”)
• params - Tool parameters as JSON value

Validation

When validation is enabled via with_validation():

• Parameters are validated against the tool schema before calling
• Errors include required fields and suggestions

Errors

Returns McpError::McpValidationFailed if parameter validation fails. Returns McpError::McpNotConnected if the client is not connected. Returns McpError::McpToolError if the tool call fails.

Example

let result = client.call_tool("novanet_context", json!({
    "mode": "page",
    "focus_key": "qr-code",
    "locale": "fr-FR"
})).await?;

pub async fn call_tool_with_retry_events( &self, name: &str, params: Value, task_id: &Arc<str>, event_log: &EventLog, ) -> Result<ToolCallResult, McpError>

Call an MCP tool with retry event emission.

This method is similar to call_tool() but emits McpRetry events through the provided EventLog when connection errors trigger retries. This enables TUI observability of MCP retry attempts.

Arguments

• name - Tool name (e.g., “novanet_context”)
• params - Tool parameters as JSON
• task_id - Task ID for event correlation
• event_log - EventLog for emitting McpRetry events

Example

let result = client.call_tool_with_retry_events(
    "novanet_context",
    json!({"mode": "page", "locale": "fr-FR"}),
    &task_id,
    &event_log,
).await?;

pub async fn read_resource( &self, uri: &str, ) -> Result<ResourceContent, McpError>

Read a resource from the MCP server.

Arguments

• uri - Resource URI (e.g., “file:///path”, “neo4j://entity/qr-code”)

Errors

Returns McpError::McpNotConnected if the client is not connected. Returns McpError::McpResourceNotFound if the resource doesn’t exist.

Example

let resource = client.read_resource("neo4j://entity/qr-code").await?;

pub async fn list_tools(&self) -> Result<Vec<ToolDefinition>, McpError>

List all available tools from the MCP server.

Errors

Returns McpError::McpNotConnected if the client is not connected.

Example

let tools = client.list_tools().await?;
for tool in tools {
    println!("Tool: {}", tool.name);
}

pub fn get_tool_definitions(&self) -> Vec<ToolDefinition>

Get tool definitions synchronously.

For mock clients, returns mock tool definitions. For real clients, returns cached tools from the last list_tools() call.

Important: For real clients, you must call list_tools().await first to populate the cache before this method returns useful results.

This method is primarily used for building rig agents where we need tool definitions during construction.

pub fn is_tool_cache_fresh(&self, ttl: Duration) -> bool

Check if the tool cache is still fresh within the given TTL.

Returns true for mock clients (always fresh). For real clients, checks if tools were fetched within ttl duration.

pub fn invalidate_tool_cache(&self)

Invalidate the tool cache, forcing re-fetch on next list_tools() call.

No-op for mock clients.

Trait Implementations

impl Debug for McpClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.