mcp_protocol_sdk/protocol/
messages.rs

1//! MCP Protocol Messages
2//!
3//! This module defines all protocol message types used in MCP communication,
4//! aligned with the 2025-03-26 specification.
5
6use crate::protocol::types::*;
7use serde::{Deserialize, Serialize};
8use std::collections::HashMap;
9
10// ============================================================================
11// Request Parameter Types
12// ============================================================================
13
14/// Parameters for initialize request
15#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
16pub struct InitializeParams {
17    /// Protocol version client supports
18    #[serde(rename = "protocolVersion")]
19    pub protocol_version: String,
20    /// Client capabilities
21    pub capabilities: ClientCapabilities,
22    /// Client implementation info
23    #[serde(rename = "clientInfo")]
24    pub client_info: Implementation,
25    /// Request metadata
26    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
27    pub meta: Option<HashMap<String, serde_json::Value>>,
28}
29
30/// Parameters for tool call request
31#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
32pub struct CallToolParams {
33    /// Name of the tool to call
34    pub name: String,
35    /// Arguments to pass to the tool
36    #[serde(skip_serializing_if = "Option::is_none")]
37    pub arguments: Option<HashMap<String, serde_json::Value>>,
38    /// Request metadata
39    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
40    pub meta: Option<HashMap<String, serde_json::Value>>,
41}
42
43/// Parameters for resource read request
44#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
45pub struct ReadResourceParams {
46    /// URI of the resource to read
47    pub uri: String,
48    /// Request metadata
49    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
50    pub meta: Option<HashMap<String, serde_json::Value>>,
51}
52
53/// Parameters for resource subscription request
54#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
55pub struct SubscribeResourceParams {
56    /// URI of the resource to subscribe to
57    pub uri: String,
58    /// Request metadata
59    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
60    pub meta: Option<HashMap<String, serde_json::Value>>,
61}
62
63/// Parameters for resource unsubscription request
64#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
65pub struct UnsubscribeResourceParams {
66    /// URI of the resource to unsubscribe from
67    pub uri: String,
68    /// Request metadata
69    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
70    pub meta: Option<HashMap<String, serde_json::Value>>,
71}
72
73/// Parameters for prompt get request
74#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
75pub struct GetPromptParams {
76    /// Name of the prompt
77    pub name: String,
78    /// Arguments for prompt templating
79    #[serde(skip_serializing_if = "Option::is_none")]
80    pub arguments: Option<HashMap<String, String>>,
81    /// Request metadata
82    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
83    pub meta: Option<HashMap<String, serde_json::Value>>,
84}
85
86/// Parameters for list requests (with pagination)
87#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
88pub struct ListParams {
89    /// Pagination cursor
90    #[serde(skip_serializing_if = "Option::is_none")]
91    pub cursor: Option<String>,
92    /// Request metadata
93    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
94    pub meta: Option<HashMap<String, serde_json::Value>>,
95}
96
97/// Parameters for list tools request
98#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
99pub struct ListToolsParams {
100    /// Pagination cursor
101    #[serde(skip_serializing_if = "Option::is_none")]
102    pub cursor: Option<String>,
103    /// Request metadata
104    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
105    pub meta: Option<HashMap<String, serde_json::Value>>,
106}
107
108/// Parameters for list resources request
109#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
110pub struct ListResourcesParams {
111    /// Pagination cursor
112    #[serde(skip_serializing_if = "Option::is_none")]
113    pub cursor: Option<String>,
114    /// Request metadata
115    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
116    pub meta: Option<HashMap<String, serde_json::Value>>,
117}
118
119/// Parameters for list prompts request
120#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
121pub struct ListPromptsParams {
122    /// Pagination cursor
123    #[serde(skip_serializing_if = "Option::is_none")]
124    pub cursor: Option<String>,
125    /// Request metadata
126    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
127    pub meta: Option<HashMap<String, serde_json::Value>>,
128}
129
130/// Parameters for ping request
131#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
132pub struct PingParams {
133    /// Request metadata
134    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
135    pub meta: Option<HashMap<String, serde_json::Value>>,
136}
137
138/// Parameters for completion request
139#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
140pub struct CompleteParams {
141    /// Reference to the item being completed
142    #[serde(rename = "ref")]
143    pub reference: CompletionReference,
144    /// Argument being completed
145    pub argument: CompletionArgument,
146    /// Request metadata
147    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
148    pub meta: Option<HashMap<String, serde_json::Value>>,
149}
150
151/// Reference for completion
152#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
153#[serde(tag = "type")]
154pub enum CompletionReference {
155    #[serde(rename = "ref/prompt")]
156    Prompt { name: String },
157    #[serde(rename = "ref/resource")]
158    Resource { uri: String },
159    #[serde(rename = "ref/tool")]
160    Tool { name: String },
161}
162
163/// Argument for completion
164#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
165pub struct CompletionArgument {
166    /// Name of the argument
167    pub name: String,
168    /// Current value for completion
169    pub value: String,
170}
171
172/// Parameters for sampling/createMessage request
173#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
174pub struct CreateMessageParams {
175    /// Messages in the conversation
176    pub messages: Vec<SamplingMessage>,
177    /// Maximum tokens to generate
178    #[serde(rename = "maxTokens")]
179    pub max_tokens: u32,
180    /// Optional system prompt
181    #[serde(rename = "systemPrompt", skip_serializing_if = "Option::is_none")]
182    pub system_prompt: Option<String>,
183    /// Include context from servers
184    #[serde(rename = "includeContext", skip_serializing_if = "Option::is_none")]
185    pub include_context: Option<String>,
186    /// Temperature for sampling
187    #[serde(skip_serializing_if = "Option::is_none")]
188    pub temperature: Option<f32>,
189    /// Stop sequences
190    #[serde(rename = "stopSequences", skip_serializing_if = "Option::is_none")]
191    pub stop_sequences: Option<Vec<String>>,
192    /// Model preferences
193    #[serde(rename = "modelPreferences", skip_serializing_if = "Option::is_none")]
194    pub model_preferences: Option<ModelPreferences>,
195    /// Provider-specific metadata
196    #[serde(skip_serializing_if = "Option::is_none")]
197    pub metadata: Option<HashMap<String, serde_json::Value>>,
198    /// Request metadata
199    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
200    pub meta: Option<HashMap<String, serde_json::Value>>,
201}
202
203/// Parameters for logging level set request
204#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
205pub struct SetLoggingLevelParams {
206    /// Logging level to set
207    pub level: LoggingLevel,
208    /// Request metadata
209    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
210    pub meta: Option<HashMap<String, serde_json::Value>>,
211}
212
213/// Parameters for elicitation request (2025-06-18 NEW)
214#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
215pub struct ElicitParams {
216    /// Message to present to the user
217    pub message: String,
218    /// Schema describing the requested form fields
219    #[serde(rename = "requestedSchema")]
220    pub requested_schema: ElicitationSchema,
221    /// Request metadata
222    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
223    pub meta: Option<HashMap<String, serde_json::Value>>,
224}
225
226// ============================================================================
227// Response Result Types
228// ============================================================================
229
230/// Result for initialize request
231#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
232pub struct InitializeResult {
233    /// Protocol version server supports
234    #[serde(rename = "protocolVersion")]
235    pub protocol_version: String,
236    /// Server capabilities
237    pub capabilities: ServerCapabilities,
238    /// Server implementation info
239    #[serde(rename = "serverInfo")]
240    pub server_info: Implementation,
241    /// Optional instructions for the client
242    #[serde(skip_serializing_if = "Option::is_none")]
243    pub instructions: Option<String>,
244    /// Response metadata
245    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
246    pub meta: Option<HashMap<String, serde_json::Value>>,
247}
248
249/// Result for list tools request
250#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
251pub struct ListToolsResult {
252    /// Available tools
253    pub tools: Vec<Tool>,
254    /// Next cursor for pagination
255    #[serde(rename = "nextCursor", skip_serializing_if = "Option::is_none")]
256    pub next_cursor: Option<String>,
257    /// Response metadata
258    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
259    pub meta: Option<HashMap<String, serde_json::Value>>,
260}
261
262/// Result for list resources request
263#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
264pub struct ListResourcesResult {
265    /// Available resources
266    pub resources: Vec<Resource>,
267    /// Next cursor for pagination
268    #[serde(rename = "nextCursor", skip_serializing_if = "Option::is_none")]
269    pub next_cursor: Option<String>,
270    /// Response metadata
271    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
272    pub meta: Option<HashMap<String, serde_json::Value>>,
273}
274
275/// Result for list resource templates request
276#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
277pub struct ListResourceTemplatesResult {
278    /// Available resource templates
279    #[serde(rename = "resourceTemplates")]
280    pub resource_templates: Vec<ResourceTemplate>,
281    /// Next cursor for pagination
282    #[serde(rename = "nextCursor", skip_serializing_if = "Option::is_none")]
283    pub next_cursor: Option<String>,
284    /// Response metadata
285    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
286    pub meta: Option<HashMap<String, serde_json::Value>>,
287}
288
289/// Result for read resource request
290#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
291pub struct ReadResourceResult {
292    /// Resource contents
293    pub contents: Vec<ResourceContents>,
294    /// Response metadata
295    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
296    pub meta: Option<HashMap<String, serde_json::Value>>,
297}
298
299/// Result for list prompts request
300#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
301pub struct ListPromptsResult {
302    /// Available prompts
303    pub prompts: Vec<Prompt>,
304    /// Next cursor for pagination
305    #[serde(rename = "nextCursor", skip_serializing_if = "Option::is_none")]
306    pub next_cursor: Option<String>,
307    /// Response metadata
308    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
309    pub meta: Option<HashMap<String, serde_json::Value>>,
310}
311
312/// Result for completion request
313#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
314pub struct CompleteResult {
315    /// Completion information
316    pub completion: CompletionData,
317    /// Response metadata
318    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
319    pub meta: Option<HashMap<String, serde_json::Value>>,
320}
321
322/// Completion data
323#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
324pub struct CompletionData {
325    /// Completion values
326    pub values: Vec<String>,
327    /// Total number of completions available
328    #[serde(skip_serializing_if = "Option::is_none")]
329    pub total: Option<u32>,
330    /// Whether there are more completions available
331    #[serde(rename = "hasMore", skip_serializing_if = "Option::is_none")]
332    pub has_more: Option<bool>,
333}
334
335/// Result for list roots request
336#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
337pub struct ListRootsResult {
338    /// Available roots
339    pub roots: Vec<Root>,
340    /// Response metadata
341    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
342    pub meta: Option<HashMap<String, serde_json::Value>>,
343}
344
345/// Result for ping request
346#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
347pub struct PingResult {
348    /// Response metadata
349    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
350    pub meta: Option<HashMap<String, serde_json::Value>>,
351}
352
353/// Result for set logging level request
354#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
355pub struct SetLoggingLevelResult {
356    /// Response metadata
357    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
358    pub meta: Option<HashMap<String, serde_json::Value>>,
359}
360
361/// Result for elicitation request (2025-06-18 NEW)
362#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
363pub struct ElicitResult {
364    /// User action in response to elicitation
365    pub action: ElicitationAction,
366    /// Submitted form data (only present when action is "accept")
367    #[serde(skip_serializing_if = "Option::is_none")]
368    pub content: Option<HashMap<String, serde_json::Value>>,
369    /// Response metadata
370    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
371    pub meta: Option<HashMap<String, serde_json::Value>>,
372}
373
374/// Result for subscribe resource request
375#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
376pub struct SubscribeResourceResult {
377    /// Response metadata
378    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
379    pub meta: Option<HashMap<String, serde_json::Value>>,
380}
381
382/// Result for unsubscribe resource request
383#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
384pub struct UnsubscribeResourceResult {
385    /// Response metadata
386    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
387    pub meta: Option<HashMap<String, serde_json::Value>>,
388}
389
390/// Root definition
391#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
392pub struct Root {
393    /// URI of the root
394    pub uri: String,
395    /// Optional name for the root
396    #[serde(skip_serializing_if = "Option::is_none")]
397    pub name: Option<String>,
398}
399
400// ============================================================================
401// Notification Parameter Types
402// ============================================================================
403
404/// Parameters for progress notification
405#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
406pub struct ProgressParams {
407    /// Progress token from original request
408    #[serde(rename = "progressToken")]
409    pub progress_token: ProgressToken,
410    /// Current progress value
411    pub progress: f32,
412    /// Total progress expected
413    #[serde(skip_serializing_if = "Option::is_none")]
414    pub total: Option<f32>,
415    /// Optional progress message
416    #[serde(skip_serializing_if = "Option::is_none")]
417    pub message: Option<String>,
418}
419
420/// Parameters for resource updated notification
421#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
422pub struct ResourceUpdatedParams {
423    /// URI of the updated resource
424    pub uri: String,
425}
426
427/// Parameters for cancelled notification
428#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
429pub struct CancelledParams {
430    /// ID of the request being cancelled
431    #[serde(rename = "requestId")]
432    pub request_id: RequestId,
433    /// Optional reason for cancellation
434    #[serde(skip_serializing_if = "Option::is_none")]
435    pub reason: Option<String>,
436}
437
438/// Parameters for initialized notification
439#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
440pub struct InitializedParams {
441    /// Notification metadata
442    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
443    pub meta: Option<HashMap<String, serde_json::Value>>,
444}
445
446/// Parameters for logging message notification
447#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
448pub struct LoggingMessageParams {
449    /// Logging level
450    pub level: LoggingLevel,
451    /// Logger name
452    #[serde(skip_serializing_if = "Option::is_none")]
453    pub logger: Option<String>,
454    /// Log data
455    pub data: serde_json::Value,
456}
457
458/// Parameters for tool list changed notification
459#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
460pub struct ToolListChangedParams {
461    /// Response metadata
462    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
463    pub meta: Option<HashMap<String, serde_json::Value>>,
464}
465
466/// Parameters for resource list changed notification
467#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
468pub struct ResourceListChangedParams {
469    /// Response metadata
470    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
471    pub meta: Option<HashMap<String, serde_json::Value>>,
472}
473
474/// Parameters for prompt list changed notification
475#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
476pub struct PromptListChangedParams {
477    /// Response metadata
478    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
479    pub meta: Option<HashMap<String, serde_json::Value>>,
480}
481
482/// Parameters for progress notification (alias for better naming)
483#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
484pub struct ProgressNotificationParams {
485    /// Progress token from original request
486    #[serde(rename = "progressToken")]
487    pub progress_token: ProgressToken,
488    /// Current progress value
489    pub progress: f32,
490    /// Total progress expected
491    #[serde(skip_serializing_if = "Option::is_none")]
492    pub total: Option<f32>,
493    /// Optional progress message
494    #[serde(skip_serializing_if = "Option::is_none")]
495    pub message: Option<String>,
496}
497
498/// Parameters for logging message notification (alias for better naming)
499#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
500pub struct LoggingMessageNotificationParams {
501    /// Logging level
502    pub level: LoggingLevel,
503    /// Logger name
504    #[serde(skip_serializing_if = "Option::is_none")]
505    pub logger: Option<String>,
506    /// Log data
507    pub data: serde_json::Value,
508}
509
510// ============================================================================
511// Helper Constructors
512// ============================================================================
513
514impl CallToolParams {
515    pub fn new(name: String) -> Self {
516        Self {
517            name,
518            arguments: None,
519            meta: None,
520        }
521    }
522
523    pub fn new_with_arguments(name: String, arguments: HashMap<String, serde_json::Value>) -> Self {
524        Self {
525            name,
526            arguments: Some(arguments),
527            meta: None,
528        }
529    }
530
531    pub fn with_arguments(mut self, arguments: HashMap<String, serde_json::Value>) -> Self {
532        self.arguments = Some(arguments);
533        self
534    }
535}
536
537impl ReadResourceParams {
538    pub fn new(uri: String) -> Self {
539        Self { uri, meta: None }
540    }
541}
542
543impl GetPromptParams {
544    pub fn new(name: String) -> Self {
545        Self {
546            name,
547            arguments: None,
548            meta: None,
549        }
550    }
551
552    pub fn new_with_arguments(name: String, arguments: HashMap<String, String>) -> Self {
553        Self {
554            name,
555            arguments: Some(arguments),
556            meta: None,
557        }
558    }
559
560    pub fn with_arguments(mut self, arguments: HashMap<String, String>) -> Self {
561        self.arguments = Some(arguments);
562        self
563    }
564}
565
566impl InitializeParams {
567    pub fn new(
568        protocol_version: String,
569        capabilities: ClientCapabilities,
570        client_info: Implementation,
571    ) -> Self {
572        Self {
573            protocol_version,
574            capabilities,
575            client_info,
576            meta: None,
577        }
578    }
579}
580
581impl InitializeResult {
582    pub fn new(
583        protocol_version: String,
584        capabilities: ServerCapabilities,
585        server_info: Implementation,
586    ) -> Self {
587        Self {
588            protocol_version,
589            capabilities,
590            server_info,
591            instructions: None,
592            meta: None,
593        }
594    }
595}
596
597impl Root {
598    pub fn new(uri: String) -> Self {
599        Self { uri, name: None }
600    }
601
602    pub fn with_name(mut self, name: String) -> Self {
603        self.name = Some(name);
604        self
605    }
606}
607
608// ============================================================================
609// Default Implementations
610// ============================================================================
mcp_protocol_sdk/protocol/messages.rs

mcp_protocol_sdk/protocol/
messages.rs
