mistralrs_mcp/lib.rs
1//! Model Context Protocol (MCP) Client Implementation
2//!
3//! This crate provides a comprehensive client implementation for the Model Context Protocol (MCP),
4//! enabling AI assistants to connect to and interact with external tools and resources through
5//! standardized server interfaces.
6//!
7//! # Overview
8//!
9//! The MCP client supports multiple transport protocols and provides automatic tool discovery,
10//! registration, and execution. It seamlessly integrates with tool calling systems,
11//! allowing MCP tools to be used alongside built-in tools.
12//!
13//! # Features
14//!
15//! - **Multiple Transport Protocols**: HTTP, WebSocket, and Process-based connections
16//! - **Automatic Tool Discovery**: Discovers and registers tools from connected MCP servers
17//! - **Bearer Token Authentication**: Supports authentication for secured MCP servers
18//! - **Concurrent Tool Execution**: Handles multiple tool calls efficiently
19//! - **Resource Access**: Access to MCP server resources like files and data
20//! - **Tool Naming Prefix**: Avoid conflicts with customizable tool name prefixes
21//!
22//! # Transport Protocols
23//!
24//! ## HTTP Transport
25//!
26//! For MCP servers accessible via HTTP endpoints with JSON-RPC over HTTP.
27//! Supports both regular JSON responses and Server-Sent Events (SSE).
28//!
29//! ## WebSocket Transport
30//!
31//! For real-time bidirectional communication with MCP servers over WebSocket.
32//! Ideal for interactive applications requiring low-latency tool calls.
33//!
34//! ## Process Transport
35//!
36//! For local MCP servers running as separate processes, communicating via stdin/stdout
37//! using JSON-RPC messages.
38//!
39//! # Example Usage
40//!
41//! ## Simple Configuration
42//!
43//! ```rust,no_run
44//! use mistralrs_mcp::{McpClientConfig, McpServerConfig, McpServerSource, McpClient};
45//!
46//! #[tokio::main]
47//! async fn main() -> anyhow::Result<()> {
48//! // Simple configuration with minimal settings
49//! // Most fields use sensible defaults (enabled=true, UUID for id/prefix, no timeouts)
50//! let config = McpClientConfig {
51//! servers: vec![
52//! McpServerConfig {
53//! name: "Hugging Face MCP Server".to_string(),
54//! source: McpServerSource::Http {
55//! url: "https://hf.co/mcp".to_string(),
56//! timeout_secs: None,
57//! headers: None,
58//! },
59//! bearer_token: Some("hf_xxx".to_string()),
60//! ..Default::default()
61//! },
62//! ],
63//! ..Default::default()
64//! };
65//!
66//! // Initialize MCP client
67//! let mut client = McpClient::new(config);
68//! client.initialize().await?;
69//!
70//! // Get tool callbacks for integration with model builder
71//! let tool_callbacks = client.get_tool_callbacks_with_tools();
72//! println!("Registered {} MCP tools", tool_callbacks.len());
73//!
74//! Ok(())
75//! }
76//! ```
77//!
78//! ## Advanced Configuration
79//!
80//! ```rust,no_run
81//! use mistralrs_mcp::{McpClientConfig, McpServerConfig, McpServerSource, McpClient};
82//! use std::collections::HashMap;
83//!
84//! #[tokio::main]
85//! async fn main() -> anyhow::Result<()> {
86//! // Configure MCP client with multiple servers and custom settings
87//! let config = McpClientConfig {
88//! servers: vec![
89//! // HTTP server with Bearer token
90//! McpServerConfig {
91//! id: "web_search".to_string(),
92//! name: "Web Search MCP".to_string(),
93//! source: McpServerSource::Http {
94//! url: "https://api.example.com/mcp".to_string(),
95//! timeout_secs: Some(30),
96//! headers: None,
97//! },
98//! enabled: true,
99//! tool_prefix: Some("web".to_string()),
100//! resources: None,
101//! bearer_token: Some("your-api-token".to_string()),
102//! },
103//! // WebSocket server
104//! McpServerConfig {
105//! id: "realtime_data".to_string(),
106//! name: "Real-time Data MCP".to_string(),
107//! source: McpServerSource::WebSocket {
108//! url: "wss://realtime.example.com/mcp".to_string(),
109//! timeout_secs: Some(60),
110//! headers: None,
111//! },
112//! enabled: true,
113//! tool_prefix: Some("rt".to_string()),
114//! resources: None,
115//! bearer_token: Some("ws-token".to_string()),
116//! },
117//! // Process-based server
118//! McpServerConfig {
119//! id: "filesystem".to_string(),
120//! name: "Filesystem MCP".to_string(),
121//! source: McpServerSource::Process {
122//! command: "mcp-server-filesystem".to_string(),
123//! args: vec!["--root".to_string(), "/tmp".to_string()],
124//! work_dir: None,
125//! env: None,
126//! },
127//! enabled: true,
128//! tool_prefix: Some("fs".to_string()),
129//! resources: Some(vec!["file://**".to_string()]),
130//! bearer_token: None,
131//! },
132//! ],
133//! auto_register_tools: true,
134//! tool_timeout_secs: Some(30),
135//! max_concurrent_calls: Some(5),
136//! };
137//!
138//! // Initialize MCP client
139//! let mut client = McpClient::new(config);
140//! client.initialize().await?;
141//!
142//! // Get tool callbacks for integration with model builder
143//! let tool_callbacks = client.get_tool_callbacks_with_tools();
144//! println!("Registered {} MCP tools", tool_callbacks.len());
145//!
146//! Ok(())
147//! }
148//! ```
149
150pub mod client;
151pub mod tools;
152pub mod transport;
153pub mod types;
154
155pub use client::{McpClient, McpServerConnection};
156pub use tools::{CalledFunction, Function, Tool, ToolCallback, ToolCallbackWithTool, ToolType};
157pub use types::McpToolResult;
158
159use serde::{Deserialize, Serialize};
160use std::collections::HashMap;
161use uuid::Uuid;
162
163/// Supported MCP server transport sources
164///
165/// Defines the different ways to connect to MCP servers, each optimized for
166/// specific use cases and deployment scenarios.
167#[derive(Debug, Clone, Serialize, Deserialize)]
168#[serde(tag = "type")]
169pub enum McpServerSource {
170 /// HTTP-based MCP server using JSON-RPC over HTTP
171 ///
172 /// Best for: Public APIs, RESTful services, servers behind load balancers
173 /// Features: SSE support, standard HTTP semantics, easy debugging
174 Http {
175 /// Base URL of the MCP server (http:// or https://)
176 url: String,
177 /// Optional timeout in seconds for HTTP requests
178 /// Defaults to no timeout if not specified.
179 timeout_secs: Option<u64>,
180 /// Optional headers to include in requests (e.g., API keys, custom headers)
181 headers: Option<HashMap<String, String>>,
182 },
183 /// Local process-based MCP server using stdin/stdout communication
184 ///
185 /// Best for: Local tools, development servers, sandboxed environments
186 /// Features: Process isolation, no network overhead, easy deployment
187 Process {
188 /// Command to execute (e.g., "mcp-server-filesystem")
189 command: String,
190 /// Arguments to pass to the command
191 args: Vec<String>,
192 /// Optional working directory for the process
193 work_dir: Option<String>,
194 /// Optional environment variables for the process
195 env: Option<HashMap<String, String>>,
196 },
197 /// WebSocket-based MCP server for real-time bidirectional communication
198 ///
199 /// Best for: Interactive applications, real-time data, low-latency requirements
200 /// Features: Persistent connections, server-initiated notifications, minimal overhead
201 WebSocket {
202 /// WebSocket URL (ws:// or wss://)
203 url: String,
204 /// Optional timeout in seconds for connection establishment
205 /// Defaults to no timeout if not specified.
206 timeout_secs: Option<u64>,
207 /// Optional headers for the WebSocket handshake
208 headers: Option<HashMap<String, String>>,
209 },
210}
211
212/// Configuration for MCP client integration
213///
214/// This structure defines how the MCP client should connect to and manage
215/// multiple MCP servers, including authentication, tool registration, and
216/// execution policies.
217#[derive(Debug, Clone, Serialize, Deserialize)]
218pub struct McpClientConfig {
219 /// List of MCP servers to connect to
220 pub servers: Vec<McpServerConfig>,
221 /// Whether to automatically register discovered tools with the model
222 ///
223 /// When enabled, tools from MCP servers are automatically converted to
224 /// the internal Tool format and registered for automatic tool calling.
225 pub auto_register_tools: bool,
226 /// Timeout for individual tool execution in seconds
227 ///
228 /// Controls how long to wait for a tool call to complete before timing out.
229 /// Defaults to no timeout if not specified.
230 pub tool_timeout_secs: Option<u64>,
231 /// Maximum number of concurrent tool calls across all MCP servers
232 ///
233 /// Limits resource usage and prevents overwhelming servers with too many
234 /// simultaneous requests. Defaults to 1 if not specified.
235 pub max_concurrent_calls: Option<usize>,
236}
237
238/// Configuration for an individual MCP server
239///
240/// Defines connection parameters, authentication, and tool management
241/// settings for a single MCP server instance.
242#[derive(Debug, Clone, Serialize, Deserialize)]
243#[serde(default)]
244pub struct McpServerConfig {
245 /// Unique identifier for this server
246 ///
247 /// Used internally to track connections and route tool calls.
248 /// Must be unique across all servers in a single MCP client configuration.
249 /// Defaults to a UUID if not specified.
250 #[serde(default = "generate_uuid")]
251 pub id: String,
252 /// Human-readable name for this server
253 ///
254 /// Used for logging, debugging, and user-facing displays.
255 pub name: String,
256 /// Transport-specific connection configuration
257 pub source: McpServerSource,
258 /// Whether this server should be activated
259 ///
260 /// Disabled servers are ignored during client initialization.
261 /// Defaults to true if not specified.
262 #[serde(default = "default_true")]
263 pub enabled: bool,
264 /// Optional prefix to add to all tool names from this server
265 ///
266 /// Helps prevent naming conflicts when multiple servers provide
267 /// tools with similar names. For example, with prefix "web",
268 /// a tool named "search" becomes "web_search".
269 /// Defaults to a UUID-based prefix if not specified.
270 #[serde(default = "generate_uuid_prefix")]
271 pub tool_prefix: Option<String>,
272 /// Optional resource URI patterns this server provides
273 ///
274 /// Used for resource discovery and subscription.
275 /// Supports glob patterns like "file://**" for filesystem access.
276 pub resources: Option<Vec<String>>,
277 /// Optional Bearer token for authentication
278 ///
279 /// Automatically included as "Authorization: Bearer <token>" header
280 /// for HTTP and WebSocket connections. Process connections typically
281 /// don't require authentication tokens.
282 pub bearer_token: Option<String>,
283}
284
285/// Information about a tool discovered from an MCP server
286#[derive(Debug, Clone)]
287pub struct McpToolInfo {
288 /// Name of the tool as reported by the MCP server
289 pub name: String,
290 /// Optional human-readable description of what the tool does
291 pub description: Option<String>,
292 /// JSON schema describing the tool's input parameters
293 pub input_schema: serde_json::Value,
294 /// ID of the server this tool comes from
295 ///
296 /// Used to route tool calls to the correct MCP server connection.
297 pub server_id: String,
298 /// Display name of the server for logging and debugging
299 pub server_name: String,
300}
301
302impl Default for McpClientConfig {
303 fn default() -> Self {
304 Self {
305 servers: Vec::new(),
306 auto_register_tools: true,
307 tool_timeout_secs: None,
308 max_concurrent_calls: Some(1),
309 }
310 }
311}
312
313fn generate_uuid() -> String {
314 Uuid::new_v4().to_string()
315}
316
317fn default_true() -> bool {
318 true
319}
320
321fn generate_uuid_prefix() -> Option<String> {
322 Some(format!("mcp_{}", Uuid::new_v4().simple()))
323}
324
325impl Default for McpServerConfig {
326 fn default() -> Self {
327 Self {
328 id: generate_uuid(),
329 name: String::new(),
330 source: McpServerSource::Http {
331 url: String::new(),
332 timeout_secs: None,
333 headers: None,
334 },
335 enabled: true,
336 tool_prefix: generate_uuid_prefix(),
337 resources: None,
338 bearer_token: None,
339 }
340 }
341}