Skip to main content

graphrt_mcp/
runtime.rs

1//! [`McpToolRuntime`]: a [`ToolRuntime`] backed by one MCP server connection.
2
3use std::fmt;
4use std::future::Future;
5use std::sync::Arc;
6use std::time::Duration;
7
8use futures::future::BoxFuture;
9use graphrt_core::tool::{ToolError, ToolOutput, ToolRuntime, ToolSpec};
10use rmcp::model::CallToolRequestParams;
11use rmcp::service::RunningService;
12use rmcp::transport::IntoTransport;
13use rmcp::{RoleClient, ServiceExt};
14use tokio::sync::RwLock;
15
16use crate::config::{McpServerConfig, McpTransport};
17use crate::content::{tool_output, tool_spec};
18
19/// Error establishing an MCP connection.
20#[derive(Debug, thiserror::Error)]
21#[non_exhaustive]
22pub enum McpError {
23    #[error("invalid MCP configuration: {0}")]
24    Config(String),
25    #[error("tool provider `{0}` is already registered")]
26    DuplicateProvider(String),
27    #[error("MCP server `{server}`: failed to start process: {source}")]
28    Spawn {
29        server: String,
30        #[source]
31        source: std::io::Error,
32    },
33    #[error("MCP server `{server}`: initialization failed: {message}")]
34    Initialize { server: String, message: String },
35    #[error("MCP server `{server}`: timed out after {timeout_ms} ms")]
36    Timeout { server: String, timeout_ms: u64 },
37    #[error("MCP server `{server}`: invalid header `{header}`")]
38    InvalidHeader { server: String, header: String },
39    #[error("MCP server `{server}`: the `{transport}` transport is not enabled in this build")]
40    TransportDisabled { server: String, transport: &'static str },
41}
42
43type Client = RunningService<RoleClient, ()>;
44
45/// Tools of a single connected MCP server.
46///
47/// The tool list is fetched lazily and cached; call [`McpToolRuntime::refresh`]
48/// to re-fetch it. Every request is bounded by the configured timeout.
49pub struct McpToolRuntime {
50    name: String,
51    client: Client,
52    timeout: Duration,
53    allowed_tools: Option<Vec<String>>,
54    cache: RwLock<Option<Arc<Vec<ToolSpec>>>>,
55}
56
57impl fmt::Debug for McpToolRuntime {
58    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
59        f.debug_struct("McpToolRuntime")
60            .field("name", &self.name)
61            .field("timeout", &self.timeout)
62            .field("allowed_tools", &self.allowed_tools)
63            .finish_non_exhaustive()
64    }
65}
66
67impl McpToolRuntime {
68    /// Connect to the server described by `config` and complete the MCP handshake.
69    pub async fn connect(config: &McpServerConfig) -> Result<Self, McpError> {
70        match &config.transport {
71            McpTransport::Stdio(stdio) => Self::connect_stdio(config, stdio).await,
72            McpTransport::Http(http) => Self::connect_http(config, http).await,
73        }
74    }
75
76    #[cfg(feature = "stdio")]
77    async fn connect_stdio(config: &McpServerConfig, stdio: &crate::config::StdioConfig) -> Result<Self, McpError> {
78        use std::process::Stdio;
79
80        use crate::config::DEFAULT_PASS_ENV;
81
82        let mut cmd = tokio::process::Command::new(&stdio.command);
83        cmd.args(&stdio.args);
84        if !stdio.inherit_env {
85            cmd.env_clear();
86            let names = DEFAULT_PASS_ENV.iter().copied().chain(stdio.pass_env.iter().map(String::as_str));
87            for name in names {
88                if let Some(value) = std::env::var_os(name) {
89                    cmd.env(name, value);
90                }
91            }
92        }
93        cmd.envs(&stdio.env);
94        if let Some(dir) = &stdio.cwd {
95            cmd.current_dir(dir);
96        }
97        let stderr = if stdio.show_stderr { Stdio::inherit() } else { Stdio::null() };
98        let (transport, _stderr) = rmcp::transport::TokioChildProcess::builder(cmd)
99            .stderr(stderr)
100            .spawn()
101            .map_err(|source| McpError::Spawn { server: config.name.clone(), source })?;
102        Self::from_transport(config, transport).await
103    }
104
105    #[cfg(not(feature = "stdio"))]
106    async fn connect_stdio(config: &McpServerConfig, _stdio: &crate::config::StdioConfig) -> Result<Self, McpError> {
107        Err(McpError::TransportDisabled { server: config.name.clone(), transport: "stdio" })
108    }
109
110    #[cfg(feature = "http")]
111    async fn connect_http(config: &McpServerConfig, http_cfg: &crate::config::HttpConfig) -> Result<Self, McpError> {
112        use std::collections::HashMap;
113
114        use rmcp::transport::StreamableHttpClientTransport;
115        use rmcp::transport::streamable_http_client::StreamableHttpClientTransportConfig;
116
117        // reqwest is built without a bundled crypto provider; install ring once.
118        // An error only means a provider is already installed, which is fine.
119        let _ = rustls::crypto::ring::default_provider().install_default();
120
121        let mut headers = HashMap::with_capacity(http_cfg.headers.len());
122        for (name, value) in &http_cfg.headers {
123            let invalid = || McpError::InvalidHeader { server: config.name.clone(), header: name.clone() };
124            let header_name = http::HeaderName::from_bytes(name.as_bytes()).map_err(|_| invalid())?;
125            let header_value = http::HeaderValue::from_str(value).map_err(|_| invalid())?;
126            headers.insert(header_name, header_value);
127        }
128        let mut transport_cfg =
129            StreamableHttpClientTransportConfig::with_uri(http_cfg.url.as_str()).custom_headers(headers);
130        if let Some(token) = &http_cfg.bearer_token {
131            transport_cfg = transport_cfg.auth_header(token.clone());
132        }
133        let transport = StreamableHttpClientTransport::from_config(transport_cfg);
134        Self::from_transport(config, transport).await
135    }
136
137    #[cfg(not(feature = "http"))]
138    async fn connect_http(config: &McpServerConfig, _http: &crate::config::HttpConfig) -> Result<Self, McpError> {
139        Err(McpError::TransportDisabled { server: config.name.clone(), transport: "http" })
140    }
141
142    /// Complete the MCP handshake over any rmcp client transport (stdio,
143    /// Streamable HTTP, an in-memory duplex stream, ...). The transport part of
144    /// `config` is ignored; its name, timeout and allow-list are used.
145    pub async fn from_transport<T, E, A>(config: &McpServerConfig, transport: T) -> Result<Self, McpError>
146    where
147        T: IntoTransport<RoleClient, E, A>,
148        E: std::error::Error + Send + Sync + 'static,
149    {
150        let timeout = Duration::from_millis(config.timeout_ms);
151        let client = with_timeout(timeout, ().serve(transport))
152            .await
153            .ok_or_else(|| McpError::Timeout { server: config.name.clone(), timeout_ms: config.timeout_ms })?
154            .map_err(|e| McpError::Initialize { server: config.name.clone(), message: e.to_string() })?;
155        Ok(Self {
156            name: config.name.clone(),
157            client,
158            timeout,
159            allowed_tools: config.allowed_tools.clone(),
160            cache: RwLock::new(None),
161        })
162    }
163
164    /// Server name (provider id).
165    pub fn name(&self) -> &str {
166        &self.name
167    }
168
169    /// Re-fetch the tool list from the server and update the cache.
170    pub async fn refresh(&self) -> Result<Vec<ToolSpec>, ToolError> {
171        let tools = with_timeout(self.timeout, self.client.list_all_tools())
172            .await
173            .ok_or_else(|| self.error("*", format!("listing tools timed out after {} ms", self.timeout.as_millis())))?
174            .map_err(|e| self.error("*", format!("listing tools failed: {e}")))?;
175        let specs: Vec<ToolSpec> = tools.iter().filter(|t| self.allows(&t.name)).map(tool_spec).collect();
176        *self.cache.write().await = Some(Arc::new(specs.clone()));
177        Ok(specs)
178    }
179
180    /// Close the connection (and stop a child process server).
181    pub async fn close(self) {
182        // A cancellation error only means the connection was already gone.
183        let _ = self.client.cancel().await;
184    }
185
186    fn allows(&self, tool: &str) -> bool {
187        self.allowed_tools.as_ref().is_none_or(|list| list.iter().any(|t| t == tool))
188    }
189
190    fn error(&self, tool: &str, message: impl Into<String>) -> ToolError {
191        ToolError { tool: format!("{}/{tool}", self.name), message: message.into() }
192    }
193
194    async fn list_cached(&self) -> Result<Vec<ToolSpec>, ToolError> {
195        if let Some(cached) = self.cache.read().await.as_ref() {
196            return Ok(cached.as_ref().clone());
197        }
198        self.refresh().await
199    }
200
201    async fn call_tool(&self, name: &str, arguments: serde_json::Value) -> Result<ToolOutput, ToolError> {
202        if !self.allows(name) {
203            return Err(self.error(name, "tool is not in the allowed list"));
204        }
205        let mut params = CallToolRequestParams::new(name.to_owned());
206        match arguments {
207            serde_json::Value::Object(map) => params = params.with_arguments(map),
208            serde_json::Value::Null => {}
209            _ => return Err(self.error(name, "arguments must be a JSON object")),
210        }
211        let result = with_timeout(self.timeout, self.client.call_tool(params))
212            .await
213            .ok_or_else(|| self.error(name, format!("call timed out after {} ms", self.timeout.as_millis())))?
214            .map_err(|e| self.error(name, e.to_string()))?;
215        Ok(tool_output(result))
216    }
217}
218
219impl ToolRuntime for McpToolRuntime {
220    fn list(&self) -> BoxFuture<'_, Result<Vec<ToolSpec>, ToolError>> {
221        Box::pin(self.list_cached())
222    }
223
224    fn call<'a>(&'a self, name: &'a str, arguments: serde_json::Value) -> BoxFuture<'a, Result<ToolOutput, ToolError>> {
225        Box::pin(self.call_tool(name, arguments))
226    }
227}
228
229/// `None` when `fut` does not finish within `timeout`.
230async fn with_timeout<F: Future>(timeout: Duration, fut: F) -> Option<F::Output> {
231    tokio::time::timeout(timeout, fut).await.ok()
232}