Skip to main content

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