Skip to main content

infinity_mcp_bridge/
lib.rs

1#![warn(missing_docs)]
2
3//! Connect MCP servers to Infinity agent systems.
4//!
5//! [`McpToolSet`] exposes a lazily connected stdio or Streamable HTTP MCP
6//! server as local Infinity tools. [`McpClient`] is the shared transport layer
7//! used by adapters that expose the same MCP session through another protocol.
8
9use std::collections::HashMap;
10use std::future::Future;
11use std::pin::Pin;
12use std::sync::Arc;
13
14use async_trait::async_trait;
15use infinity_agent_core::message::{InputMessage, InputMessageContent};
16use infinity_agent_core::system::local::ChannelSender;
17use infinity_agent_core::tools::{Tool, ToolContext};
18use infinity_agent_core::traits::InputSender;
19use infinity_provider_protocol::message::Text;
20use infinity_provider_protocol::message::{ToolResult, ToolResultContent, UserContent};
21use rap_protocol::DisplaySegment;
22use serde::{Deserialize, Serialize};
23use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
24use tokio::process::{Child, Command};
25use tokio::sync::Mutex;
26
27/// Error type returned by MCP transports and operations.
28pub type BoxError = Box<dyn std::error::Error + Send + Sync>;
29
30#[derive(Serialize)]
31struct JsonRpcRequest {
32    jsonrpc: &'static str,
33    id: u64,
34    method: String,
35    #[serde(skip_serializing_if = "Option::is_none")]
36    params: Option<serde_json::Value>,
37}
38
39#[derive(Deserialize)]
40struct JsonRpcResponse {
41    result: Option<serde_json::Value>,
42    error: Option<JsonRpcError>,
43}
44
45#[derive(Deserialize)]
46struct JsonRpcError {
47    message: String,
48}
49
50/// A transport capable of sending requests to one initialized MCP session.
51#[async_trait]
52pub trait McpTransport: Send {
53    /// Send one JSON-RPC request and return its `result` value.
54    async fn request(
55        &mut self,
56        method: &str,
57        params: Option<serde_json::Value>,
58    ) -> Result<serde_json::Value, BoxError>;
59}
60
61struct StdioMcpTransport {
62    stdin: tokio::process::ChildStdin,
63    reader: BufReader<tokio::process::ChildStdout>,
64    next_id: u64,
65    _child: Child,
66}
67
68impl StdioMcpTransport {
69    async fn new(command: &[String], env: &HashMap<String, String>) -> Result<Self, BoxError> {
70        let (executable, args) = command.split_first().ok_or("empty MCP command")?;
71        let mut child = Command::new(executable)
72            .args(args)
73            .envs(env)
74            .stdin(std::process::Stdio::piped())
75            .stdout(std::process::Stdio::piped())
76            .stderr(std::process::Stdio::null())
77            .kill_on_drop(true)
78            .spawn()
79            .map_err(|error| format!("failed to spawn MCP server: {error}"))?;
80        let stdin = child.stdin.take().ok_or("MCP server has no stdin")?;
81        let stdout = child.stdout.take().ok_or("MCP server has no stdout")?;
82        let mut transport = Self {
83            stdin,
84            reader: BufReader::new(stdout),
85            next_id: 0,
86            _child: child,
87        };
88        initialize(&mut transport).await?;
89        Ok(transport)
90    }
91}
92
93#[async_trait]
94impl McpTransport for StdioMcpTransport {
95    async fn request(
96        &mut self,
97        method: &str,
98        params: Option<serde_json::Value>,
99    ) -> Result<serde_json::Value, BoxError> {
100        self.next_id += 1;
101        let request = JsonRpcRequest {
102            jsonrpc: "2.0",
103            id: self.next_id,
104            method: method.to_owned(),
105            params,
106        };
107        let mut line = serde_json::to_string(&request)?;
108        line.push('\n');
109        self.stdin.write_all(line.as_bytes()).await?;
110        self.stdin.flush().await?;
111
112        loop {
113            let mut line = String::new();
114            if self.reader.read_line(&mut line).await? == 0 {
115                return Err("MCP server closed stdout".into());
116            }
117            let line = line.trim();
118            if line.is_empty() {
119                continue;
120            }
121            if let Ok(response) = serde_json::from_str::<JsonRpcResponse>(line) {
122                return response_result(response);
123            }
124        }
125    }
126}
127
128struct HttpMcpTransport {
129    url: String,
130    headers: HashMap<String, String>,
131    session_id: Option<String>,
132    next_id: u64,
133    http: reqwest::Client,
134}
135
136impl HttpMcpTransport {
137    async fn new(url: String, headers: HashMap<String, String>) -> Result<Self, BoxError> {
138        let mut transport = Self {
139            url,
140            headers,
141            session_id: None,
142            next_id: 0,
143            http: reqwest::Client::new(),
144        };
145        initialize(&mut transport).await?;
146        transport.notify_initialized().await?;
147        Ok(transport)
148    }
149
150    async fn notify_initialized(&self) -> Result<(), BoxError> {
151        let body = serde_json::json!({
152            "jsonrpc": "2.0",
153            "method": "notifications/initialized",
154            "params": {}
155        });
156        let mut request = self
157            .http
158            .post(&self.url)
159            .header("content-type", "application/json");
160        for (name, value) in &self.headers {
161            request = request.header(name, value);
162        }
163        if let Some(session_id) = &self.session_id {
164            request = request.header("mcp-session-id", session_id);
165        }
166        request
167            .body(body.to_string())
168            .send()
169            .await?
170            .error_for_status()?;
171        Ok(())
172    }
173}
174
175#[async_trait]
176impl McpTransport for HttpMcpTransport {
177    async fn request(
178        &mut self,
179        method: &str,
180        params: Option<serde_json::Value>,
181    ) -> Result<serde_json::Value, BoxError> {
182        self.next_id += 1;
183        let body = serde_json::json!({
184            "jsonrpc": "2.0",
185            "id": self.next_id,
186            "method": method,
187            "params": params.unwrap_or(serde_json::Value::Null),
188        });
189        let mut request = self
190            .http
191            .post(&self.url)
192            .header("content-type", "application/json")
193            .header("accept", "application/json, text/event-stream");
194        for (name, value) in &self.headers {
195            request = request.header(name, value);
196        }
197        if let Some(session_id) = &self.session_id {
198            request = request.header("mcp-session-id", session_id);
199        }
200        let response = request.body(body.to_string()).send().await?;
201        if let Some(session_id) = response.headers().get("mcp-session-id") {
202            self.session_id = session_id.to_str().ok().map(str::to_owned);
203        }
204        let response = response.error_for_status()?;
205        let is_event_stream = response
206            .headers()
207            .get("content-type")
208            .and_then(|value| value.to_str().ok())
209            .is_some_and(|value| value.contains("text/event-stream"));
210        let body = response.text().await?;
211        if is_event_stream {
212            for line in body.lines() {
213                if let Some(data) = line.strip_prefix("data: ")
214                    && let Ok(response) = serde_json::from_str::<JsonRpcResponse>(data)
215                {
216                    return response_result(response);
217                }
218            }
219            return Err("MCP event stream contained no response".into());
220        }
221        response_result(serde_json::from_str(&body)?)
222    }
223}
224
225fn response_result(response: JsonRpcResponse) -> Result<serde_json::Value, BoxError> {
226    if let Some(error) = response.error {
227        return Err(format!("MCP error: {}", error.message).into());
228    }
229    Ok(response.result.unwrap_or(serde_json::Value::Null))
230}
231
232async fn initialize(transport: &mut dyn McpTransport) -> Result<(), BoxError> {
233    transport
234        .request(
235            "initialize",
236            Some(serde_json::json!({
237                "protocolVersion": "2024-11-05",
238                "capabilities": {},
239                "clientInfo": {"name": "infinity-mcp-bridge", "version": env!("CARGO_PKG_VERSION")}
240            })),
241        )
242        .await?;
243    Ok(())
244}
245
246/// Factory for a lazily initialized MCP transport.
247pub type McpTransportFactory = Arc<
248    dyn Fn() -> Pin<Box<dyn Future<Output = Result<Box<dyn McpTransport>, BoxError>> + Send>>
249        + Send
250        + Sync,
251>;
252
253/// A lazily initialized, serialized MCP session.
254#[derive(Clone)]
255pub struct McpClient {
256    name: Arc<str>,
257    factory: McpTransportFactory,
258    transport: Arc<Mutex<Option<Box<dyn McpTransport>>>>,
259}
260
261impl McpClient {
262    /// Create a client backed by a custom transport factory.
263    pub fn new(name: impl Into<String>, factory: McpTransportFactory) -> Self {
264        Self {
265            name: Arc::from(name.into()),
266            factory,
267            transport: Arc::new(Mutex::new(None)),
268        }
269    }
270
271    /// Create a lazy stdio MCP client.
272    pub fn stdio(
273        name: impl Into<String>,
274        command: Vec<String>,
275        env: HashMap<String, String>,
276    ) -> Self {
277        Self::new(
278            name,
279            Arc::new(move || {
280                let command = command.clone();
281                let env = env.clone();
282                Box::pin(async move {
283                    Ok(Box::new(StdioMcpTransport::new(&command, &env).await?)
284                        as Box<dyn McpTransport>)
285                })
286            }),
287        )
288    }
289
290    /// Create a lazy Streamable HTTP MCP client.
291    pub fn http(
292        name: impl Into<String>,
293        url: impl Into<String>,
294        headers: HashMap<String, String>,
295    ) -> Self {
296        let url = url.into();
297        Self::new(
298            name,
299            Arc::new(move || {
300                let url = url.clone();
301                let headers = headers.clone();
302                Box::pin(async move {
303                    Ok(Box::new(HttpMcpTransport::new(url, headers).await?)
304                        as Box<dyn McpTransport>)
305                })
306            }),
307        )
308    }
309
310    /// Logical server name used to prefix the generated tool names.
311    pub fn name(&self) -> &str {
312        &self.name
313    }
314
315    async fn request(
316        &self,
317        method: &str,
318        params: Option<serde_json::Value>,
319    ) -> Result<serde_json::Value, BoxError> {
320        let mut transport = self.transport.lock().await;
321        if transport.is_none() {
322            *transport = Some((self.factory)().await?);
323        }
324        transport
325            .as_mut()
326            .expect("bug: MCP transport missing after initialization")
327            .request(method, params)
328            .await
329    }
330
331    /// List the server's tools as text suitable for a model and optional display segments.
332    async fn list_tools(&self) -> Result<(String, Option<Vec<DisplaySegment>>), BoxError> {
333        let result = self
334            .request("tools/list", Some(serde_json::json!({})))
335            .await?;
336        let tools = result
337            .get("tools")
338            .and_then(serde_json::Value::as_array)
339            .cloned()
340            .unwrap_or_default();
341        if tools.is_empty() {
342            return Ok(("No tools available from this MCP server.".to_owned(), None));
343        }
344        let mut text = format!("Available tools ({}):\n\n", tools.len());
345        for tool in &tools {
346            let name = tool
347                .get("name")
348                .and_then(serde_json::Value::as_str)
349                .unwrap_or("?");
350            let description = tool
351                .get("description")
352                .and_then(serde_json::Value::as_str)
353                .unwrap_or("No description");
354            text.push_str(&format!("**{name}**\n{description}\n"));
355            if let Some(schema) = tool.get("inputSchema") {
356                text.push_str(&format!(
357                    "Parameters: {}\n",
358                    serde_json::to_string_pretty(schema)?
359                ));
360            }
361            text.push('\n');
362        }
363        Ok((
364            text,
365            Some(vec![DisplaySegment::Text(format!(
366                "Loaded {} tools",
367                tools.len()
368            ))]),
369        ))
370    }
371
372    /// Invoke one MCP tool and format its content for the model.
373    async fn invoke_tool(
374        &self,
375        tool_name: &str,
376        arguments: serde_json::Value,
377    ) -> Result<String, BoxError> {
378        let result = self
379            .request(
380                "tools/call",
381                Some(serde_json::json!({"name": tool_name, "arguments": arguments})),
382            )
383            .await?;
384        let mut text = format!("Tool \"{tool_name}\" completed.\n\n");
385        if let Some(content) = result.get("content").and_then(serde_json::Value::as_array) {
386            for item in content {
387                match item.get("type").and_then(serde_json::Value::as_str) {
388                    Some("text") => {
389                        if let Some(value) = item.get("text").and_then(serde_json::Value::as_str) {
390                            text.push_str(value);
391                            text.push('\n');
392                        }
393                    }
394                    Some("image") => {
395                        let mime = item
396                            .get("mimeType")
397                            .and_then(serde_json::Value::as_str)
398                            .unwrap_or("unknown");
399                        text.push_str(&format!("[Image: {mime}]\n"));
400                    }
401                    Some("resource") => {
402                        let uri = item
403                            .pointer("/resource/uri")
404                            .and_then(serde_json::Value::as_str)
405                            .unwrap_or("unknown");
406                        text.push_str(&format!("[Resource: {uri}]\n"));
407                    }
408                    _ => {}
409                }
410            }
411        }
412        if result
413            .get("isError")
414            .and_then(serde_json::Value::as_bool)
415            .unwrap_or(false)
416        {
417            text = format!("Tool \"{tool_name}\" failed: {text}");
418        }
419        Ok(text)
420    }
421}
422
423/// A local-agent toolset backed by one shared MCP session.
424pub struct McpToolSet {
425    client: McpClient,
426}
427
428impl McpToolSet {
429    /// Create a toolset for a lazy stdio MCP server.
430    pub fn stdio(
431        name: impl Into<String>,
432        command: Vec<String>,
433        env: HashMap<String, String>,
434    ) -> Self {
435        Self {
436            client: McpClient::stdio(name, command, env),
437        }
438    }
439
440    /// Create a toolset for a lazy Streamable HTTP MCP server.
441    pub fn http(
442        name: impl Into<String>,
443        url: impl Into<String>,
444        headers: HashMap<String, String>,
445    ) -> Self {
446        Self {
447            client: McpClient::http(name, url, headers),
448        }
449    }
450
451    /// Build the list and invoke tools for registration on a local agent system.
452    pub fn tools(&self) -> Vec<Box<dyn Tool<ChannelSender>>> {
453        self.client
454            .tool_definitions()
455            .into_iter()
456            .map(|definition| {
457                Box::new(McpTool {
458                    definition,
459                    client: self.client.clone(),
460                }) as Box<dyn Tool<ChannelSender>>
461            })
462            .collect()
463    }
464}
465
466/// One of the two operations the adapter exposes for each MCP server.
467#[derive(Clone, Copy, Debug, PartialEq, Eq)]
468enum McpOperation {
469    /// List the server's tools (`{server}_list_tools`).
470    ListTools,
471    /// Invoke one of the server's tools by name (`{server}_invoke_tool`).
472    InvokeTool,
473}
474
475impl McpOperation {
476    /// Recognize an adapter tool name by its operation suffix.
477    ///
478    /// Returns `None` for names that do not belong to this adapter.
479    /// [`McpClient::dispatch`] reports unknown names in its result text.
480    fn parse(tool_name: &str) -> Option<Self> {
481        if tool_name.ends_with("_list_tools") {
482            Some(Self::ListTools)
483        } else if tool_name.ends_with("_invoke_tool") {
484            Some(Self::InvokeTool)
485        } else {
486            None
487        }
488    }
489
490    fn suffix(self) -> &'static str {
491        match self {
492            Self::ListTools => "list_tools",
493            Self::InvokeTool => "invoke_tool",
494        }
495    }
496
497    fn definition(self, server_name: &str) -> McpToolDefinition {
498        McpToolDefinition {
499            name: format!("{server_name}_{}", self.suffix()),
500            description: match self {
501                Self::ListTools => format!(
502                    "List the tools available from the {server_name} MCP server before invoking one."
503                ),
504                Self::InvokeTool => format!(
505                    "Invoke a tool from the {server_name} MCP server by name. Use {server_name}_list_tools first to see the available tools."
506                ),
507            },
508            input_schema: match self {
509                Self::ListTools => {
510                    serde_json::json!({"type": "object", "properties": {}, "required": []})
511                }
512                Self::InvokeTool => serde_json::json!({
513                    "type": "object",
514                    "properties": {
515                        "tool_name": {"type": "string", "description": "Name of the MCP tool to invoke."},
516                        "arguments": {"type": "object", "description": "Arguments to pass to the MCP tool."}
517                    },
518                    "required": ["tool_name"]
519                }),
520            },
521            display_script: None,
522        }
523    }
524}
525
526/// The model-facing definition of one adapter tool.
527///
528/// Definitions are the single source for the adapter's tool names,
529/// descriptions, and schemas: the local [`Tool`] adapters returned by
530/// [`McpToolSet::tools`] read them, and protocol
531/// adapters (such as a RAP proxy) convert them into their own manifest
532/// entries.
533#[derive(Clone, Debug, PartialEq)]
534pub struct McpToolDefinition {
535    /// Tool name: `{server}_list_tools` or `{server}_invoke_tool`.
536    pub name: String,
537    /// Model-facing description of the tool.
538    pub description: String,
539    /// JSON Schema for the tool's argument object.
540    pub input_schema: serde_json::Value,
541    /// Optional Rhai display script for pretty-printing calls.
542    pub display_script: Option<String>,
543}
544
545impl From<McpToolDefinition> for rap_protocol::ToolDef {
546    fn from(definition: McpToolDefinition) -> Self {
547        Self {
548            name: definition.name,
549            description: definition.description,
550            input_schema: definition.input_schema,
551            annotations: None,
552            display_script: definition.display_script,
553        }
554    }
555}
556
557/// A protocol-agnostic summary of the adapter for one MCP server: a toolset
558/// name, a usage description, and the tool definitions.
559#[derive(Clone, Debug)]
560pub struct McpToolsetDescriptor {
561    /// Toolset name derived from the server name.
562    pub name: String,
563    /// Usage description referencing the adapter's tool names.
564    pub description: String,
565    /// The adapter's tool definitions, in dispatch order.
566    pub tools: Vec<McpToolDefinition>,
567}
568
569impl McpClient {
570    /// The adapter's tool definitions for this server, in dispatch order.
571    ///
572    /// Every surface that exposes this client must derive its tool metadata
573    /// from these definitions so the model sees identical tools regardless of
574    /// the transport in between.
575    fn tool_definitions(&self) -> Vec<McpToolDefinition> {
576        vec![
577            McpOperation::ListTools.definition(self.name()),
578            McpOperation::InvokeTool.definition(self.name()),
579        ]
580    }
581
582    /// Describe the adapter as a toolset for protocol manifests.
583    pub fn describe_toolset(&self) -> McpToolsetDescriptor {
584        let name = self.name();
585        McpToolsetDescriptor {
586            name: format!("{name}-mcp"),
587            description: format!(
588                "MCP server proxy for {name}. Use {name}_list_tools to discover available tools, then {name}_invoke_tool to call them."
589            ),
590            tools: self.tool_definitions(),
591        }
592    }
593
594    /// Execute one adapter tool call and format the outcome for the model.
595    ///
596    /// `tool_name` is an adapter tool name (`{server}_list_tools` or
597    /// `{server}_invoke_tool`); `arguments` is the tool-call argument object.
598    /// Failures, including unknown tool names, are formatted into the
599    /// returned text so the model receives the same error message from every
600    /// adapter surface.
601    pub async fn dispatch(
602        &self,
603        tool_name: &str,
604        arguments: &serde_json::Value,
605    ) -> (String, Option<Vec<DisplaySegment>>) {
606        let result = match McpOperation::parse(tool_name) {
607            Some(McpOperation::ListTools) => self.list_tools().await,
608            Some(McpOperation::InvokeTool) => {
609                let target = arguments
610                    .get("tool_name")
611                    .and_then(serde_json::Value::as_str)
612                    .unwrap_or_default();
613                let target_arguments = arguments
614                    .get("arguments")
615                    .cloned()
616                    .unwrap_or_else(|| serde_json::json!({}));
617                self.invoke_tool(target, target_arguments)
618                    .await
619                    .map(|text| (text, None))
620            }
621            None => Err(format!("unknown operation: {tool_name}").into()),
622        };
623        result.unwrap_or_else(|error| (format!("MCP tool error: {error}"), None))
624    }
625}
626
627struct McpTool {
628    definition: McpToolDefinition,
629    client: McpClient,
630}
631
632#[async_trait]
633impl Tool<ChannelSender> for McpTool {
634    fn name(&self) -> &str {
635        &self.definition.name
636    }
637
638    fn description(&self) -> &str {
639        &self.definition.description
640    }
641
642    fn parameters(&self) -> serde_json::Value {
643        self.definition.input_schema.clone()
644    }
645
646    fn display_script(&self) -> Option<&str> {
647        self.definition.display_script.as_deref()
648    }
649
650    async fn execute(
651        &self,
652        arguments: serde_json::Value,
653        id: rap_protocol::ToolCallId,
654        call_id: Option<rap_protocol::ProviderCallId>,
655        context: &ToolContext<ChannelSender>,
656    ) -> Result<(), BoxError> {
657        let client = self.client.clone();
658        let tool_name = self.definition.name.clone();
659        let group_id = context.group_id.clone();
660        let sender = context.message_sender.clone();
661        tokio::spawn(async move {
662            let (text, display_as) = client.dispatch(&tool_name, &arguments).await;
663            let message = InputMessage {
664                content: InputMessageContent::User(UserContent::ToolResult(ToolResult {
665                    id: id.clone().into_inner(),
666                    call_id: call_id.map(|c| c.into_inner()),
667                    content: vec![ToolResultContent::Text(Text { text })],
668                })),
669                group_id: group_id.clone(),
670                metadata: None,
671                synthetic: None,
672                display_as,
673                subscription: false,
674            };
675            if let Err(error) = sender.send_to_input_queue(message, id.as_str()).await {
676                tracing::warn!(%error, "failed to deliver MCP tool result");
677            }
678        });
679        Ok(())
680    }
681}
682
683#[cfg(test)]
684mod tests {
685    use std::sync::atomic::{AtomicUsize, Ordering};
686
687    use super::*;
688
689    type RecordedRequests = Arc<Mutex<Vec<(String, Option<serde_json::Value>)>>>;
690
691    struct RecordingTransport {
692        requests: RecordedRequests,
693    }
694
695    #[async_trait]
696    impl McpTransport for RecordingTransport {
697        async fn request(
698            &mut self,
699            method: &str,
700            params: Option<serde_json::Value>,
701        ) -> Result<serde_json::Value, BoxError> {
702            self.requests
703                .lock()
704                .await
705                .push((method.to_owned(), params.clone()));
706            match method {
707                "tools/list" => Ok(serde_json::json!({
708                    "tools": [{
709                        "name": "echo",
710                        "description": "Echo input",
711                        "inputSchema": {"type": "object"}
712                    }]
713                })),
714                "tools/call" => Ok(serde_json::json!({
715                    "content": [{"type": "text", "text": "hello"}]
716                })),
717                other => Err(format!("unexpected method: {other}").into()),
718            }
719        }
720    }
721
722    fn test_client() -> (McpClient, RecordedRequests, Arc<AtomicUsize>) {
723        let requests = Arc::new(Mutex::new(Vec::new()));
724        let factory_calls = Arc::new(AtomicUsize::new(0));
725        let client = McpClient::new("test", {
726            let requests = requests.clone();
727            let factory_calls = factory_calls.clone();
728            Arc::new(move || {
729                factory_calls.fetch_add(1, Ordering::SeqCst);
730                let requests = requests.clone();
731                Box::pin(async move {
732                    Ok(Box::new(RecordingTransport { requests }) as Box<dyn McpTransport>)
733                })
734            })
735        });
736        (client, requests, factory_calls)
737    }
738
739    #[tokio::test]
740    async fn client_connects_lazily_and_reuses_transport() {
741        let (client, requests, factory_calls) = test_client();
742        assert_eq!(factory_calls.load(Ordering::SeqCst), 0);
743
744        let (tools, display) = client.list_tools().await.expect("list MCP tools");
745        assert!(tools.contains("**echo**"));
746        assert!(matches!(
747            display.as_deref(),
748            Some([DisplaySegment::Text(text)]) if text == "Loaded 1 tools"
749        ));
750
751        let result = client
752            .invoke_tool("echo", serde_json::json!({"text": "hello"}))
753            .await
754            .expect("invoke MCP tool");
755        assert!(result.contains("hello"));
756        assert_eq!(factory_calls.load(Ordering::SeqCst), 1);
757
758        let requests = requests.lock().await;
759        assert_eq!(requests[0].0, "tools/list");
760        assert_eq!(requests[1].0, "tools/call");
761        assert_eq!(
762            requests[1].1.as_ref().expect("call parameters")["name"],
763            "echo"
764        );
765    }
766
767    #[tokio::test]
768    async fn dispatch_routes_operations_and_formats_errors() {
769        let (client, requests, _) = test_client();
770
771        let (text, display) = client
772            .dispatch("test_list_tools", &serde_json::json!({}))
773            .await;
774        assert!(text.contains("**echo**"));
775        assert!(display.is_some());
776
777        let (text, display) = client
778            .dispatch(
779                "test_invoke_tool",
780                &serde_json::json!({"tool_name": "echo", "arguments": {"text": "hello"}}),
781            )
782            .await;
783        assert!(text.contains("hello"));
784        assert!(display.is_none());
785
786        let (text, display) = client.dispatch("bogus", &serde_json::json!({})).await;
787        assert_eq!(text, "MCP tool error: unknown operation: bogus");
788        assert!(display.is_none());
789
790        let requests = requests.lock().await;
791        assert_eq!(
792            requests.len(),
793            2,
794            "unknown operation must not hit the server"
795        );
796    }
797}