turbomcp_protocol/types/
completion.rs

1//! Argument autocompletion types
2//!
3//! This module contains types for the MCP argument completion system,
4//! allowing servers to provide completion suggestions for tool and prompt arguments.
5
6use serde::{Deserialize, Serialize};
7
8/// Argument information for completion
9#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
10pub struct ArgumentInfo {
11    /// The name of the argument being completed
12    pub name: String,
13    /// The current value of the argument (may be partial)
14    pub value: String,
15}
16
17/// Reference to a prompt for completion
18#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
19pub struct PromptReference {
20    /// Reference type (always "ref/prompt")
21    #[serde(rename = "type")]
22    pub ref_type: String,
23    /// The name of the prompt
24    pub name: String,
25    /// Human-readable title
26    #[serde(skip_serializing_if = "Option::is_none")]
27    pub title: Option<String>,
28}
29
30impl PromptReference {
31    /// Create a new prompt reference
32    pub fn new<N: Into<String>>(name: N) -> Self {
33        Self {
34            ref_type: "ref/prompt".to_string(),
35            name: name.into(),
36            title: None,
37        }
38    }
39
40    /// Create a new prompt reference with title
41    pub fn with_title<N: Into<String>, T: Into<String>>(name: N, title: T) -> Self {
42        Self {
43            ref_type: "ref/prompt".to_string(),
44            name: name.into(),
45            title: Some(title.into()),
46        }
47    }
48}
49
50/// Data for prompt reference (excluding the type field)
51#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
52pub struct PromptReferenceData {
53    /// The name of the prompt
54    pub name: String,
55    /// Human-readable title
56    #[serde(skip_serializing_if = "Option::is_none")]
57    pub title: Option<String>,
58}
59
60/// Data for resource template reference (excluding the type field)
61#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
62pub struct ResourceTemplateReferenceData {
63    /// The URI or URI template of the resource
64    pub uri: String,
65}
66
67/// Reference types for completion
68#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
69#[serde(tag = "type")]
70pub enum CompletionReference {
71    /// Reference to a prompt
72    #[serde(rename = "ref/prompt")]
73    Prompt(PromptReferenceData),
74    /// Reference to a resource template
75    #[serde(rename = "ref/resource")]
76    ResourceTemplate(ResourceTemplateReferenceData),
77}
78
79/// Additional context for completions
80#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
81pub struct CompletionContext {
82    /// Previously-resolved variables in a URI template or prompt
83    #[serde(skip_serializing_if = "Option::is_none")]
84    pub arguments: Option<std::collections::HashMap<String, String>>,
85}
86
87/// Parameters for completion/complete request
88#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
89pub struct CompleteRequestParams {
90    /// The argument's information
91    pub argument: ArgumentInfo,
92    /// Reference to the item being completed
93    #[serde(rename = "ref")]
94    pub reference: CompletionReference,
95    /// Additional, optional context for completions
96    #[serde(skip_serializing_if = "Option::is_none")]
97    pub context: Option<CompletionContext>,
98}
99
100/// Completion option/suggestion
101#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
102pub struct CompletionOption {
103    /// The completion value
104    pub value: String,
105    /// Human-readable label (optional, falls back to value)
106    #[serde(skip_serializing_if = "Option::is_none")]
107    pub label: Option<String>,
108    /// Type of completion (file, directory, function, etc.)
109    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
110    pub completion_type: Option<String>,
111    /// Documentation for this completion
112    #[serde(skip_serializing_if = "Option::is_none")]
113    pub documentation: Option<String>,
114    /// Sort priority (lower numbers appear first)
115    #[serde(rename = "sortPriority", skip_serializing_if = "Option::is_none")]
116    pub sort_priority: Option<u32>,
117    /// Text to insert (if different from value)
118    #[serde(rename = "insertText", skip_serializing_if = "Option::is_none")]
119    pub insert_text: Option<String>,
120}
121
122/// Completion data structure per MCP specification
123#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
124pub struct CompletionData {
125    /// An array of completion values. Must not exceed 100 items.
126    pub values: Vec<String>,
127    /// The total number of completion options available. This can exceed the number of values actually sent.
128    #[serde(skip_serializing_if = "Option::is_none")]
129    pub total: Option<u32>,
130    /// Indicates whether there are additional completion options beyond those provided
131    #[serde(rename = "hasMore", skip_serializing_if = "Option::is_none")]
132    pub has_more: Option<bool>,
133}
134
135/// Completion response
136#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
137pub struct CompletionResponse {
138    /// Completion data per MCP 2025-06-18 specification
139    pub completion: CompletionData,
140    /// Optional metadata per MCP 2025-06-18 specification
141    #[serde(skip_serializing_if = "Option::is_none")]
142    pub _meta: Option<serde_json::Value>,
143}
144
145/// Server's response to a completion/complete request per MCP 2025-06-18 specification
146#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
147pub struct CompleteResult {
148    /// Completion data
149    pub completion: CompletionData,
150    /// Optional metadata per MCP 2025-06-18 specification
151    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
152    pub _meta: Option<serde_json::Value>,
153}
154
155impl CompleteResult {
156    /// Create a new completion result
157    pub fn new(completion: CompletionData) -> Self {
158        Self {
159            completion,
160            _meta: None,
161        }
162    }
163
164    /// Create a completion result with values
165    pub fn with_values(values: Vec<String>) -> Self {
166        Self::new(CompletionData {
167            values,
168            total: None,
169            has_more: None,
170        })
171    }
172
173    /// Create a completion result with values and metadata
174    pub fn with_values_and_total(values: Vec<String>, total: u32, has_more: bool) -> Self {
175        Self::new(CompletionData {
176            values,
177            total: Some(total),
178            has_more: Some(has_more),
179        })
180    }
181
182    /// Add metadata to this result
183    pub fn with_meta(mut self, meta: serde_json::Value) -> Self {
184        self._meta = Some(meta);
185        self
186    }
187}
turbomcp_protocol/types/completion.rs

turbomcp_protocol/types/
completion.rs
