Skip to main content

graphrt_mcp/
config.rs

1//! MCP server configuration.
2//!
3//! Parsing is strict: unknown keys (typically typos such as `alowed_tools`) are
4//! rejected, because a silently ignored allow-list would expose every tool of a
5//! server. The camelCase spellings common in MCP client configs
6//! (`allowedTools`, `timeoutMs`, `passEnv`, `inheritEnv`, `showStderr`,
7//! `bearerToken`) are accepted as aliases.
8
9use indexmap::IndexMap;
10use serde::{Deserialize, Serialize};
11
12/// Default per-call timeout.
13pub const DEFAULT_TIMEOUT_MS: u64 = 30_000;
14
15/// Host variables passed to stdio servers when `inherit_env` is false.
16/// Most launchers (`npx`, `uvx`, `docker`) need these to start at all.
17pub const DEFAULT_PASS_ENV: &[&str] = &["PATH", "HOME", "LANG", "TMPDIR", "SYSTEMROOT", "USERPROFILE", "APPDATA"];
18
19/// One MCP server.
20///
21/// ```json
22/// { "name": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"] }
23/// { "name": "remote", "url": "https://mcp.example.com/mcp", "bearer_token": "..." }
24/// ```
25///
26/// Exactly one of `command` (stdio) or `url` (Streamable HTTP) must be present, and
27/// transport-specific keys must match the chosen transport.
28#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
29#[serde(try_from = "RawServer")]
30pub struct McpServerConfig {
31    /// Provider name used to reference the server's tools (`<name>` and `mcp:<name>`).
32    /// Optional when the config comes from a named map ([`McpServers`]).
33    pub name: String,
34    #[serde(flatten)]
35    pub transport: McpTransport,
36    /// Timeout for each request (connect handshake, list, call), in milliseconds.
37    /// Defaults to [`DEFAULT_TIMEOUT_MS`].
38    pub timeout_ms: u64,
39    /// When set, only these tools are listed and callable.
40    #[serde(skip_serializing_if = "Option::is_none")]
41    pub allowed_tools: Option<Vec<String>>,
42}
43
44/// How to reach an MCP server. Chosen by the presence of `command` or `url`.
45#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
46#[serde(untagged)]
47pub enum McpTransport {
48    /// Spawn a child process speaking MCP over stdin/stdout.
49    Stdio(StdioConfig),
50    /// Connect to a Streamable HTTP endpoint.
51    Http(HttpConfig),
52}
53
54/// Child-process server. `Debug` shows `env` names only.
55#[derive(Clone, PartialEq, Serialize, Deserialize)]
56#[serde(deny_unknown_fields)]
57pub struct StdioConfig {
58    pub command: String,
59    #[serde(default)]
60    pub args: Vec<String>,
61    /// Explicit environment variables for the child.
62    #[serde(default)]
63    pub env: IndexMap<String, String>,
64    /// Names of host variables copied into the child's environment
65    /// (in addition to [`DEFAULT_PASS_ENV`]).
66    #[serde(default, alias = "passEnv")]
67    pub pass_env: Vec<String>,
68    /// Inherit the full host environment. Off by default so host secrets are
69    /// not leaked to third-party servers.
70    #[serde(default, alias = "inheritEnv")]
71    pub inherit_env: bool,
72    #[serde(default)]
73    pub cwd: Option<String>,
74    /// Forward the server's stderr to this process's stderr (default: discarded).
75    #[serde(default, alias = "showStderr")]
76    pub show_stderr: bool,
77}
78
79/// Streamable HTTP server. `Debug` shows header names only and hides the token.
80#[derive(Clone, PartialEq, Serialize, Deserialize)]
81#[serde(deny_unknown_fields)]
82pub struct HttpConfig {
83    pub url: String,
84    /// Extra headers sent with every request.
85    #[serde(default)]
86    pub headers: IndexMap<String, String>,
87    /// Bearer token for the `Authorization` header (without the `Bearer ` prefix).
88    #[serde(default, alias = "bearerToken")]
89    pub bearer_token: Option<String>,
90}
91
92impl std::fmt::Debug for StdioConfig {
93    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
94        let env_names: Vec<&String> = self.env.keys().collect();
95        f.debug_struct("StdioConfig")
96            .field("command", &self.command)
97            .field("args", &self.args)
98            .field("env", &env_names)
99            .field("pass_env", &self.pass_env)
100            .field("inherit_env", &self.inherit_env)
101            .field("cwd", &self.cwd)
102            .field("show_stderr", &self.show_stderr)
103            .finish()
104    }
105}
106
107impl std::fmt::Debug for HttpConfig {
108    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
109        let header_names: Vec<&String> = self.headers.keys().collect();
110        f.debug_struct("HttpConfig")
111            .field("url", &self.url)
112            .field("headers", &header_names)
113            .field("bearer_token", &self.bearer_token.as_ref().map(|_| "******"))
114            .finish()
115    }
116}
117
118/// Every key a server entry may contain, used to validate configs strictly.
119#[derive(Deserialize)]
120#[serde(deny_unknown_fields)]
121struct RawServer {
122    #[serde(default)]
123    name: String,
124    /// Optional explicit transport kind, as written by many MCP clients.
125    #[serde(default, rename = "type", alias = "transport")]
126    kind: Option<String>,
127    #[serde(default, alias = "timeoutMs")]
128    timeout_ms: Option<u64>,
129    #[serde(default, alias = "allowedTools")]
130    allowed_tools: Option<Vec<String>>,
131    // stdio
132    #[serde(default)]
133    command: Option<String>,
134    #[serde(default)]
135    args: Option<Vec<String>>,
136    #[serde(default)]
137    env: Option<IndexMap<String, String>>,
138    #[serde(default, alias = "passEnv")]
139    pass_env: Option<Vec<String>>,
140    #[serde(default, alias = "inheritEnv")]
141    inherit_env: Option<bool>,
142    #[serde(default)]
143    cwd: Option<String>,
144    #[serde(default, alias = "showStderr")]
145    show_stderr: Option<bool>,
146    // http
147    #[serde(default)]
148    url: Option<String>,
149    #[serde(default)]
150    headers: Option<IndexMap<String, String>>,
151    #[serde(default, alias = "bearerToken")]
152    bearer_token: Option<String>,
153}
154
155impl TryFrom<RawServer> for McpServerConfig {
156    type Error = String;
157
158    fn try_from(raw: RawServer) -> Result<Self, String> {
159        let label = if raw.name.is_empty() { "MCP server".to_owned() } else { format!("MCP server `{}`", raw.name) };
160        let transport = match (raw.command, raw.url) {
161            (Some(_), Some(_)) => {
162                return Err(format!("{label}: set either `command` (stdio) or `url` (http), not both"));
163            }
164            (None, None) => return Err(format!("{label}: needs `command` (stdio) or `url` (http)")),
165            (Some(command), None) => {
166                if let Some(kind) = raw.kind.as_deref().filter(|k| !k.eq_ignore_ascii_case("stdio")) {
167                    return Err(format!("{label}: `type: {kind}` does not match a stdio `command`"));
168                }
169                let http_keys = [("headers", raw.headers.is_some()), ("bearer_token", raw.bearer_token.is_some())];
170                reject_foreign_keys(&label, "stdio", &http_keys)?;
171                McpTransport::Stdio(StdioConfig {
172                    command,
173                    args: raw.args.unwrap_or_default(),
174                    env: raw.env.unwrap_or_default(),
175                    pass_env: raw.pass_env.unwrap_or_default(),
176                    inherit_env: raw.inherit_env.unwrap_or(false),
177                    cwd: raw.cwd,
178                    show_stderr: raw.show_stderr.unwrap_or(false),
179                })
180            }
181            (None, Some(url)) => {
182                let http_kinds = ["http", "streamable-http", "streamable_http", "streamablehttp"];
183                if let Some(kind) =
184                    raw.kind.as_deref().filter(|k| !http_kinds.iter().any(|h| h.eq_ignore_ascii_case(k)))
185                {
186                    return Err(format!("{label}: `type: {kind}` does not match an http `url`"));
187                }
188                let stdio_keys = [
189                    ("args", raw.args.is_some()),
190                    ("env", raw.env.is_some()),
191                    ("pass_env", raw.pass_env.is_some()),
192                    ("inherit_env", raw.inherit_env.is_some()),
193                    ("cwd", raw.cwd.is_some()),
194                    ("show_stderr", raw.show_stderr.is_some()),
195                ];
196                reject_foreign_keys(&label, "http", &stdio_keys)?;
197                McpTransport::Http(HttpConfig {
198                    url,
199                    headers: raw.headers.unwrap_or_default(),
200                    bearer_token: raw.bearer_token,
201                })
202            }
203        };
204        Ok(McpServerConfig {
205            name: raw.name,
206            transport,
207            timeout_ms: raw.timeout_ms.unwrap_or(DEFAULT_TIMEOUT_MS),
208            allowed_tools: raw.allowed_tools,
209        })
210    }
211}
212
213fn reject_foreign_keys(label: &str, transport: &str, keys: &[(&str, bool)]) -> Result<(), String> {
214    match keys.iter().find(|(_, present)| *present) {
215        Some((key, _)) => Err(format!("{label}: `{key}` does not apply to {transport} servers")),
216        None => Ok(()),
217    }
218}
219
220/// A named collection of servers, e.g. a config file:
221///
222/// ```json
223/// { "mcpServers": { "fs": { "command": "npx", "args": ["..."] } } }
224/// ```
225#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
226#[serde(deny_unknown_fields)]
227pub struct McpServers {
228    #[serde(alias = "mcpServers", alias = "mcp_servers")]
229    pub servers: IndexMap<String, McpServerConfig>,
230}
231
232impl McpServers {
233    /// Server configs with `name` filled from the map keys.
234    pub fn into_configs(self) -> Vec<McpServerConfig> {
235        self.servers
236            .into_iter()
237            .map(|(key, mut cfg)| {
238                if cfg.name.is_empty() {
239                    cfg.name = key;
240                }
241                cfg
242            })
243            .collect()
244    }
245}
246
247impl McpServerConfig {
248    /// Whether `tool` passes the allow-list.
249    pub fn allows(&self, tool: &str) -> bool {
250        self.allowed_tools.as_ref().is_none_or(|list| list.iter().any(|t| t == tool))
251    }
252}
253
254#[cfg(test)]
255mod tests {
256    use super::*;
257
258    fn parse(value: serde_json::Value) -> Result<McpServerConfig, String> {
259        serde_json::from_value::<McpServerConfig>(value).map_err(|e| e.to_string())
260    }
261
262    #[test]
263    fn debug_hides_secret_values() {
264        let stdio = parse(serde_json::json!({"name": "a", "command": "x", "env": {"TOKEN": "env-secret-1"}})).unwrap();
265        let http = parse(serde_json::json!({
266            "name": "b", "url": "https://x/mcp", "bearer_token": "bearer-secret-2", "headers": {"x-key": "hdr-secret-3"}
267        }))
268        .unwrap();
269        let shown = format!("{stdio:?} {http:?}");
270        for secret in ["env-secret-1", "bearer-secret-2", "hdr-secret-3"] {
271            assert!(!shown.contains(secret), "{shown}");
272        }
273        assert!(shown.contains("TOKEN") && shown.contains("x-key"), "{shown}");
274    }
275
276    #[test]
277    fn parses_stdio_and_http() {
278        let stdio = parse(serde_json::json!({
279            "name": "fs", "command": "npx", "args": ["-y", "srv"], "env": {"A": "1"}, "pass_env": ["GITHUB_TOKEN"]
280        }))
281        .unwrap();
282        match &stdio.transport {
283            McpTransport::Stdio(s) => {
284                assert_eq!(s.command, "npx");
285                assert_eq!(s.args, ["-y", "srv"]);
286                assert!(!s.inherit_env);
287                assert_eq!(s.pass_env, ["GITHUB_TOKEN"]);
288            }
289            other => panic!("unexpected {other:?}"),
290        }
291        assert_eq!(stdio.timeout_ms, DEFAULT_TIMEOUT_MS);
292
293        let http = parse(serde_json::json!({
294            "name": "r", "url": "https://x/mcp", "bearer_token": "t", "timeout_ms": 5,
295            "allowed_tools": ["a"]
296        }))
297        .unwrap();
298        assert!(matches!(&http.transport, McpTransport::Http(h) if h.bearer_token.as_deref() == Some("t")));
299        assert!(http.allows("a"));
300        assert!(!http.allows("b"));
301        assert!(stdio.allows("anything"));
302    }
303
304    #[test]
305    fn accepts_camel_case_aliases() {
306        let cfg = parse(serde_json::json!({
307            "name": "fs", "type": "stdio", "command": "srv", "allowedTools": ["read"], "timeoutMs": 7,
308            "passEnv": ["X"], "inheritEnv": true, "showStderr": true
309        }))
310        .unwrap();
311        assert_eq!(cfg.allowed_tools, Some(vec!["read".to_owned()]));
312        assert_eq!(cfg.timeout_ms, 7);
313        assert!(!cfg.allows("write"));
314        match &cfg.transport {
315            McpTransport::Stdio(s) => assert!(s.inherit_env && s.show_stderr && s.pass_env == ["X"]),
316            other => panic!("unexpected {other:?}"),
317        }
318        let http =
319            parse(serde_json::json!({"url": "https://x", "type": "streamable-http", "bearerToken": "t"})).unwrap();
320        assert!(matches!(&http.transport, McpTransport::Http(h) if h.bearer_token.as_deref() == Some("t")));
321    }
322
323    #[test]
324    fn rejects_typos_and_mixed_transports() {
325        let typo = parse(serde_json::json!({"command": "srv", "alowed_tools": ["a"]})).unwrap_err();
326        assert!(typo.contains("alowed_tools"), "{typo}");
327        let both = parse(serde_json::json!({"command": "srv", "url": "https://x"})).unwrap_err();
328        assert!(both.contains("not both"), "{both}");
329        let foreign = parse(serde_json::json!({"url": "https://x", "args": ["a"]})).unwrap_err();
330        assert!(foreign.contains("`args`"), "{foreign}");
331        let kind = parse(serde_json::json!({"command": "srv", "type": "http"})).unwrap_err();
332        assert!(kind.contains("type"), "{kind}");
333    }
334
335    #[test]
336    fn rejects_config_without_transport() {
337        assert!(parse(serde_json::json!({"name": "x"})).is_err());
338    }
339
340    #[test]
341    fn serialization_round_trips() {
342        let cfg = parse(serde_json::json!({"name": "fs", "command": "srv", "allowedTools": ["a"]})).unwrap();
343        let text = serde_json::to_value(&cfg).unwrap();
344        assert_eq!(parse(text).unwrap(), cfg);
345    }
346
347    #[test]
348    fn named_map_fills_names() {
349        let servers: McpServers = serde_json::from_value(serde_json::json!({
350            "mcpServers": {"fs": {"command": "srv"}, "web": {"name": "custom", "url": "http://h"}}
351        }))
352        .unwrap();
353        let cfgs = servers.into_configs();
354        assert_eq!(cfgs[0].name, "fs");
355        assert_eq!(cfgs[1].name, "custom");
356        assert!(serde_json::from_value::<McpServers>(serde_json::json!({"mcpServer": {}})).is_err());
357    }
358}