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)]
21#[serde(rename_all = "camelCase")]
22pub struct SessionConfig {
23 #[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#[derive(Clone, PartialEq, Eq, Serialize)]
80#[serde(tag = "transport", rename_all = "camelCase")]
81pub enum SessionMcpServerConfig {
82 Stdio {
84 command: String,
86 #[serde(default, skip_serializing_if = "Vec::is_empty")]
88 args: Vec<String>,
89 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
91 env: BTreeMap<String, String>,
92 #[serde(default, skip_serializing_if = "SessionMcpStdioFraming::is_auto")]
94 framing: SessionMcpStdioFraming,
95 #[serde(default, skip_serializing_if = "SessionMcpServerMode::is_required")]
97 mode: SessionMcpServerMode,
98 },
99 StreamableHttp {
101 url: String,
103 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
105 headers: BTreeMap<String, String>,
106 #[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#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
326#[serde(rename_all = "camelCase")]
327pub enum SessionMcpStdioFraming {
328 #[default]
330 Auto,
331 ContentLength,
333 LineDelimitedJson,
335}
336
337impl SessionMcpStdioFraming {
338 fn is_auto(value: &Self) -> bool {
339 *value == Self::Auto
340 }
341}
342
343#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
345#[serde(rename_all = "camelCase")]
346pub enum SessionMcpServerMode {
347 #[default]
349 Required,
350 Optional,
352}
353
354impl SessionMcpServerMode {
355 fn is_required(value: &Self) -> bool {
356 *value == Self::Required
357 }
358}