Skip to main content

muse_code_sdk/msp/method/lifecycle/
session_mcp.rs

1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3use serde::Deserialize;
4use serde::Deserializer;
5use serde::Serialize;
6use serde::de::Error as _;
7use std::collections::BTreeMap;
8use std::fmt;
9
10/// The open configuration extension object shared by `session/start` and
11/// `session/resume`.
12///
13/// Unknown keys are ignored on the wire, never rejected: the live decoder is
14/// the governing rules tolerant path, and the governing rules keeps every
15/// exported bundle free of `additionalProperties: false`. The Rust typed
16/// model's `deny_unknown_fields` is internal and never exported — the
17/// closedness export applies nowhere, and the `x-msp-closed` opt-in mechanism
18/// stays inert. Recognized `mcpServers` values are typed and validated before
19/// they leave the wire boundary.
20#[derive(Clone, Default, PartialEq, Eq, Serialize)]
21#[serde(rename_all = "camelCase")]
22pub struct SessionConfig {
23    /// Native MCP servers added only to this session runtime.
24    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
25    pub mcp_servers: BTreeMap<String, SessionMcpServerConfig>,
26}
27
28impl fmt::Debug for SessionConfig {
29    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
30        formatter
31            .debug_struct("SessionConfig")
32            .field(
33                "mcp_server_names",
34                &self.mcp_servers.keys().collect::<Vec<_>>(),
35            )
36            .finish()
37    }
38}
39
40impl<'de> Deserialize<'de> for SessionConfig {
41    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
42    where
43        D: Deserializer<'de>,
44    {
45        #[derive(Deserialize)]
46        #[serde(rename_all = "camelCase")]
47        struct Wire {
48            #[serde(default)]
49            mcp_servers: BTreeMap<String, SessionMcpServerConfig>,
50        }
51
52        let value = serde_json::Value::deserialize(deserializer)?;
53        let object = value
54            .as_object()
55            .ok_or_else(|| D::Error::custom("session config must be an object"))?;
56        if object
57            .get("mcpServers")
58            .is_some_and(|servers| !servers.is_object())
59        {
60            return Err(D::Error::custom(
61                "session config mcpServers must be an object",
62            ));
63        }
64        let wire: Wire = serde_json::from_value(value).map_err(D::Error::custom)?;
65        for name in wire.mcp_servers.keys() {
66            validate_name(name, SessionMcpNameKind::Server).map_err(D::Error::custom)?;
67        }
68        Ok(Self {
69            mcp_servers: wire.mcp_servers,
70        })
71    }
72}
73
74/// One native MCP server supplied at session construction.
75///
76/// **Closed union**: a validator MUST reject an undeclared `transport` arm —
77/// the server fails `session/start` decode on an unknown transport, and a
78/// future transport arrives as an explicit schema addition.
79#[derive(Clone, PartialEq, Eq, Serialize)]
80#[serde(tag = "transport", rename_all = "camelCase")]
81pub enum SessionMcpServerConfig {
82    /// A child process speaking MCP over stdin/stdout.
83    Stdio {
84        /// Executable name or path. Configuration diagnostics never echo it.
85        command: String,
86        /// Ordered child arguments.
87        #[serde(default, skip_serializing_if = "Vec::is_empty")]
88        args: Vec<String>,
89        /// Explicit child environment additions.
90        #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
91        env: BTreeMap<String, String>,
92        /// Stdio framing mode; defaults to automatic detection.
93        #[serde(default, skip_serializing_if = "SessionMcpStdioFraming::is_auto")]
94        framing: SessionMcpStdioFraming,
95        /// Required/optional startup posture; defaults to required.
96        #[serde(default, skip_serializing_if = "SessionMcpServerMode::is_required")]
97        mode: SessionMcpServerMode,
98    },
99    /// A streamable-HTTP MCP endpoint.
100    StreamableHttp {
101        /// HTTP(S) endpoint. Configuration diagnostics never echo it.
102        url: String,
103        /// Explicit request headers.
104        #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
105        headers: BTreeMap<String, String>,
106        /// Required/optional startup posture; defaults to required.
107        #[serde(default, skip_serializing_if = "SessionMcpServerMode::is_required")]
108        mode: SessionMcpServerMode,
109    },
110}
111
112impl fmt::Debug for SessionMcpServerConfig {
113    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
114        match self {
115            Self::Stdio {
116                args,
117                env,
118                framing,
119                mode,
120                ..
121            } => formatter
122                .debug_struct("SessionMcpServerConfig::Stdio")
123                .field("argument_count", &args.len())
124                .field("environment_name_count", &env.len())
125                .field("framing", framing)
126                .field("mode", mode)
127                .finish(),
128            Self::StreamableHttp { headers, mode, .. } => formatter
129                .debug_struct("SessionMcpServerConfig::StreamableHttp")
130                .field("header_name_count", &headers.len())
131                .field("mode", mode)
132                .finish(),
133        }
134    }
135}
136
137#[derive(Deserialize)]
138#[serde(tag = "transport", rename_all = "camelCase")]
139enum SessionMcpServerConfigWire {
140    Stdio {
141        command: String,
142        #[serde(default)]
143        args: Vec<String>,
144        #[serde(default)]
145        env: BTreeMap<String, String>,
146        #[serde(default)]
147        framing: SessionMcpStdioFraming,
148        #[serde(default)]
149        mode: SessionMcpServerMode,
150    },
151    StreamableHttp {
152        url: String,
153        #[serde(default)]
154        headers: BTreeMap<String, String>,
155        #[serde(default)]
156        mode: SessionMcpServerMode,
157    },
158}
159
160impl<'de> Deserialize<'de> for SessionMcpServerConfig {
161    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
162    where
163        D: Deserializer<'de>,
164    {
165        let value = serde_json::Value::deserialize(deserializer)?;
166        let object = value
167            .as_object()
168            .ok_or_else(|| D::Error::custom("MCP server definition must be an object"))?;
169        let transport = object
170            .get("transport")
171            .and_then(serde_json::Value::as_str)
172            .ok_or_else(|| D::Error::custom("MCP server transport must be a string"))?;
173        let (forbidden, required, missing_message): (&[&str], &str, &str) = match transport {
174            "stdio" => (
175                &["url", "headers"],
176                "command",
177                "MCP transport `stdio` requires field `command`",
178            ),
179            "streamableHttp" => (
180                &["command", "args", "env", "framing"],
181                "url",
182                "MCP transport `streamableHttp` requires field `url`",
183            ),
184            _ => {
185                return Err(D::Error::custom(
186                    "MCP server transport must be `stdio` or `streamableHttp`",
187                ));
188            }
189        };
190        if !object.contains_key(required) {
191            return Err(D::Error::custom(missing_message));
192        }
193        if let Some(field) = forbidden.iter().find(|field| object.contains_key(**field)) {
194            return Err(D::Error::custom(format!(
195                "field `{field}` is not valid for MCP transport `{transport}`"
196            )));
197        }
198        let wire: SessionMcpServerConfigWire = serde_json::from_value(value).map_err(|_| {
199            D::Error::custom(
200                "MCP server definition has a field with the wrong type or an unknown option",
201            )
202        })?;
203        let config = match wire {
204            SessionMcpServerConfigWire::Stdio {
205                command,
206                args,
207                env,
208                framing,
209                mode,
210            } => Self::Stdio {
211                command,
212                args,
213                env,
214                framing,
215                mode,
216            },
217            SessionMcpServerConfigWire::StreamableHttp { url, headers, mode } => {
218                Self::StreamableHttp { url, headers, mode }
219            }
220        };
221        config.validate().map_err(D::Error::custom)?;
222        Ok(config)
223    }
224}
225
226impl SessionMcpServerConfig {
227    fn validate(&self) -> Result<(), &'static str> {
228        match self {
229            Self::Stdio { command, env, .. } => {
230                if command.trim().is_empty() {
231                    return Err("stdio MCP command must not be blank");
232                }
233                validate_map_keys(env, SessionMcpNameKind::Environment)
234            }
235            Self::StreamableHttp { url, headers, .. } => {
236                validate_streamable_http_url(url)?;
237                validate_map_keys(headers, SessionMcpNameKind::Header)
238            }
239        }
240    }
241}
242
243fn validate_streamable_http_url(url: &str) -> Result<(), &'static str> {
244    let (scheme, remainder) = url
245        .split_once("://")
246        .ok_or("streamable HTTP MCP URL is invalid")?;
247    if !(scheme.eq_ignore_ascii_case("http") || scheme.eq_ignore_ascii_case("https")) {
248        return Err("streamable HTTP MCP URL must be an absolute HTTP(S) URL");
249    }
250    if url
251        .bytes()
252        .any(|byte| byte.is_ascii_whitespace() || byte.is_ascii_control())
253    {
254        return Err("streamable HTTP MCP URL is invalid");
255    }
256
257    let authority = remainder.split(['/', '?', '#']).next().unwrap_or_default();
258    let host_and_port = authority
259        .rsplit_once('@')
260        .map_or(authority, |(_, host_and_port)| host_and_port);
261    let valid_authority = if let Some(bracketed) = host_and_port.strip_prefix('[') {
262        bracketed
263            .split_once(']')
264            .is_some_and(|(host, suffix)| !host.is_empty() && valid_optional_port(suffix))
265    } else {
266        host_and_port.rsplit_once(':').map_or_else(
267            || !host_and_port.is_empty(),
268            |(host, port)| !host.is_empty() && !host.contains(':') && valid_port(port),
269        )
270    };
271    if !valid_authority {
272        return Err("streamable HTTP MCP URL must be an absolute HTTP(S) URL");
273    }
274    Ok(())
275}
276
277fn valid_optional_port(suffix: &str) -> bool {
278    suffix.is_empty() || suffix.strip_prefix(':').is_some_and(valid_port)
279}
280
281fn valid_port(port: &str) -> bool {
282    !port.is_empty()
283        && port.bytes().all(|byte| byte.is_ascii_digit())
284        && port.parse::<u16>().is_ok()
285}
286
287#[derive(Clone, Copy)]
288enum SessionMcpNameKind {
289    Server,
290    Environment,
291    Header,
292}
293
294fn validate_map_keys(
295    values: &BTreeMap<String, String>,
296    kind: SessionMcpNameKind,
297) -> Result<(), &'static str> {
298    for name in values.keys() {
299        validate_name(name, kind)?;
300    }
301    Ok(())
302}
303
304fn validate_name(name: &str, kind: SessionMcpNameKind) -> Result<(), &'static str> {
305    if name.trim().is_empty() {
306        return Err(match kind {
307            SessionMcpNameKind::Server => "MCP server name must not be blank",
308            SessionMcpNameKind::Environment => "MCP environment name must not be blank",
309            SessionMcpNameKind::Header => "MCP header name must not be blank",
310        });
311    }
312    if name.trim() != name {
313        return Err(match kind {
314            SessionMcpNameKind::Server => "MCP server name must not contain surrounding whitespace",
315            SessionMcpNameKind::Environment => {
316                "MCP environment name must not contain surrounding whitespace"
317            }
318            SessionMcpNameKind::Header => "MCP header name must not contain surrounding whitespace",
319        });
320    }
321    Ok(())
322}
323
324/// Stdio framing choices exposed by session MCP configuration.
325#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
326#[serde(rename_all = "camelCase")]
327pub enum SessionMcpStdioFraming {
328    /// Probe line-delimited JSON, then fall back to Content-Length framing.
329    #[default]
330    Auto,
331    /// Require LSP-style Content-Length framing.
332    ContentLength,
333    /// Require one JSON object per line.
334    LineDelimitedJson,
335}
336
337impl SessionMcpStdioFraming {
338    fn is_auto(value: &Self) -> bool {
339        *value == Self::Auto
340    }
341}
342
343/// Startup failure posture for a session MCP server.
344#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
345#[serde(rename_all = "camelCase")]
346pub enum SessionMcpServerMode {
347    /// Failure prevents provider contact.
348    #[default]
349    Required,
350    /// Failure is reported through the existing diagnostic path and startup continues.
351    Optional,
352}
353
354impl SessionMcpServerMode {
355    fn is_required(value: &Self) -> bool {
356        *value == Self::Required
357    }
358}