muse_code_sdk/msp/method/lifecycle/
session_mcp.rs1use serde::Deserialize;
4use serde::Deserializer;
5use serde::Serialize;
6use serde::de::Error as _;
7use std::collections::BTreeMap;
8use std::fmt;
9
10#[derive(Clone, Default, PartialEq, Eq, Serialize)]
20#[serde(rename_all = "camelCase")]
21pub struct SessionConfig {
22 #[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#[derive(Clone, PartialEq, Eq, Serialize)]
79#[serde(tag = "transport", rename_all = "camelCase")]
80pub enum SessionMcpServerConfig {
81 Stdio {
83 command: String,
85 #[serde(default, skip_serializing_if = "Vec::is_empty")]
87 args: Vec<String>,
88 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
90 env: BTreeMap<String, String>,
91 #[serde(default, skip_serializing_if = "SessionMcpStdioFraming::is_auto")]
93 framing: SessionMcpStdioFraming,
94 #[serde(default, skip_serializing_if = "SessionMcpServerMode::is_required")]
96 mode: SessionMcpServerMode,
97 },
98 StreamableHttp {
100 url: String,
102 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
104 headers: BTreeMap<String, String>,
105 #[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#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
325#[serde(rename_all = "camelCase")]
326pub enum SessionMcpStdioFraming {
327 #[default]
329 Auto,
330 ContentLength,
332 LineDelimitedJson,
334}
335
336impl SessionMcpStdioFraming {
337 fn is_auto(value: &Self) -> bool {
338 *value == Self::Auto
339 }
340}
341
342#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
344#[serde(rename_all = "camelCase")]
345pub enum SessionMcpServerMode {
346 #[default]
348 Required,
349 Optional,
351}
352
353impl SessionMcpServerMode {
354 fn is_required(value: &Self) -> bool {
355 *value == Self::Required
356 }
357}