muse_code_sdk/msp/method/lifecycle/
session_mcp_server.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, PartialEq, Eq, Serialize)]
16#[serde(tag = "transport", rename_all = "camelCase")]
17pub enum SessionMcpServerConfig {
18 Stdio {
20 command: String,
22 #[serde(default, skip_serializing_if = "Vec::is_empty")]
24 args: Vec<String>,
25 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
27 env: BTreeMap<String, String>,
28 #[serde(default, skip_serializing_if = "SessionMcpStdioFraming::is_auto")]
30 framing: SessionMcpStdioFraming,
31 #[serde(default, skip_serializing_if = "SessionMcpServerMode::is_required")]
33 mode: SessionMcpServerMode,
34 },
35 StreamableHttp {
37 url: String,
39 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
41 headers: BTreeMap<String, String>,
42 #[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#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
262#[serde(rename_all = "camelCase")]
263pub enum SessionMcpStdioFraming {
264 #[default]
266 Auto,
267 ContentLength,
269 LineDelimitedJson,
271}
272
273impl SessionMcpStdioFraming {
274 fn is_auto(value: &Self) -> bool {
275 *value == Self::Auto
276 }
277}
278
279#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
281#[serde(rename_all = "camelCase")]
282pub enum SessionMcpServerMode {
283 #[default]
285 Required,
286 Optional,
288}
289
290impl SessionMcpServerMode {
291 fn is_required(value: &Self) -> bool {
292 *value == Self::Required
293 }
294}