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