Bring in mcp-* crates from goose as a starting point

crates/mcp-client/src/client.rs

@@ -0,0 +1,349 @@
+use mcp_core::protocol::{
+    CallToolResult, Implementation, InitializeResult, JsonRpcError, JsonRpcMessage,
+    JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, ListResourcesResult, ListToolsResult,
+    ReadResourceResult, ServerCapabilities, METHOD_NOT_FOUND,
+};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use std::sync::atomic::{AtomicU64, Ordering};
+use thiserror::Error;
+use tokio::sync::Mutex;
+use tower::{Service, ServiceExt}; // for Service::ready()
+
+pub type BoxError = Box<dyn std::error::Error + Sync + Send>;
+
+/// Error type for MCP client operations.
+#[derive(Debug, Error)]
+pub enum Error {
+    #[error("Transport error: {0}")]
+    Transport(#[from] super::transport::Error),
+
+    #[error("RPC error: code={code}, message={message}")]
+    RpcError { code: i32, message: String },
+
+    #[error("Serialization error: {0}")]
+    Serialization(#[from] serde_json::Error),
+
+    #[error("Unexpected response from server: {0}")]
+    UnexpectedResponse(String),
+
+    #[error("Not initialized")]
+    NotInitialized,
+
+    #[error("Timeout or service not ready")]
+    NotReady,
+
+    #[error("Request timed out")]
+    Timeout(#[from] tower::timeout::error::Elapsed),
+
+    #[error("Error from mcp-server: {0}")]
+    ServerBoxError(BoxError),
+
+    #[error("Call to '{server}' failed for '{method}'. {source}")]
+    McpServerError {
+        method: String,
+        server: String,
+        #[source]
+        source: BoxError,
+    },
+}
+
+// BoxError from mcp-server gets converted to our Error type
+impl From<BoxError> for Error {
+    fn from(err: BoxError) -> Self {
+        Error::ServerBoxError(err)
+    }
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct ClientInfo {
+    pub name: String,
+    pub version: String,
+}
+
+#[derive(Serialize, Deserialize, Default)]
+pub struct ClientCapabilities {
+    // Add fields as needed. For now, empty capabilities are fine.
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct InitializeParams {
+    #[serde(rename = "protocolVersion")]
+    pub protocol_version: String,
+    pub capabilities: ClientCapabilities,
+    #[serde(rename = "clientInfo")]
+    pub client_info: ClientInfo,
+}
+
+#[async_trait::async_trait]
+pub trait McpClientTrait: Send + Sync {
+    async fn initialize(
+        &mut self,
+        info: ClientInfo,
+        capabilities: ClientCapabilities,
+    ) -> Result<InitializeResult, Error>;
+
+    async fn list_resources(
+        &self,
+        next_cursor: Option<String>,
+    ) -> Result<ListResourcesResult, Error>;
+
+    async fn read_resource(&self, uri: &str) -> Result<ReadResourceResult, Error>;
+
+    async fn list_tools(&self, next_cursor: Option<String>) -> Result<ListToolsResult, Error>;
+
+    async fn call_tool(&self, name: &str, arguments: Value) -> Result<CallToolResult, Error>;
+}
+
+/// The MCP client is the interface for MCP operations.
+pub struct McpClient<S>
+where
+    S: Service<JsonRpcMessage, Response = JsonRpcMessage> + Clone + Send + Sync + 'static,
+    S::Error: Into<Error>,
+    S::Future: Send,
+{
+    service: Mutex<S>,
+    next_id: AtomicU64,
+    server_capabilities: Option<ServerCapabilities>,
+    server_info: Option<Implementation>,
+}
+
+impl<S> McpClient<S>
+where
+    S: Service<JsonRpcMessage, Response = JsonRpcMessage> + Clone + Send + Sync + 'static,
+    S::Error: Into<Error>,
+    S::Future: Send,
+{
+    pub fn new(service: S) -> Self {
+        Self {
+            service: Mutex::new(service),
+            next_id: AtomicU64::new(1),
+            server_capabilities: None,
+            server_info: None,
+        }
+    }
+
+    /// Send a JSON-RPC request and check we don't get an error response.
+    async fn send_request<R>(&self, method: &str, params: Value) -> Result<R, Error>
+    where
+        R: for<'de> Deserialize<'de>,
+    {
+        let mut service = self.service.lock().await;
+        service.ready().await.map_err(|_| Error::NotReady)?;
+
+        let id = self.next_id.fetch_add(1, Ordering::SeqCst);
+        let request = JsonRpcMessage::Request(JsonRpcRequest {
+            jsonrpc: "2.0".to_string(),
+            id: Some(id),
+            method: method.to_string(),
+            params: Some(params.clone()),
+        });
+
+        let response_msg = service
+            .call(request)
+            .await
+            .map_err(|e| Error::McpServerError {
+                server: self
+                    .server_info
+                    .as_ref()
+                    .map(|s| s.name.clone())
+                    .unwrap_or("".to_string()),
+                method: method.to_string(),
+                // we don't need include params because it can be really large
+                source: Box::new(e.into()),
+            })?;
+
+        match response_msg {
+            JsonRpcMessage::Response(JsonRpcResponse {
+                id, result, error, ..
+            }) => {
+                // Verify id matches
+                if id != Some(self.next_id.load(Ordering::SeqCst) - 1) {
+                    return Err(Error::UnexpectedResponse(
+                        "id mismatch for JsonRpcResponse".to_string(),
+                    ));
+                }
+                if let Some(err) = error {
+                    Err(Error::RpcError {
+                        code: err.code,
+                        message: err.message,
+                    })
+                } else if let Some(r) = result {
+                    Ok(serde_json::from_value(r)?)
+                } else {
+                    Err(Error::UnexpectedResponse("missing result".to_string()))
+                }
+            }
+            JsonRpcMessage::Error(JsonRpcError { id, error, .. }) => {
+                if id != Some(self.next_id.load(Ordering::SeqCst) - 1) {
+                    return Err(Error::UnexpectedResponse(
+                        "id mismatch for JsonRpcError".to_string(),
+                    ));
+                }
+                Err(Error::RpcError {
+                    code: error.code,
+                    message: error.message,
+                })
+            }
+            _ => {
+                // Requests/notifications not expected as a response
+                Err(Error::UnexpectedResponse(
+                    "unexpected message type".to_string(),
+                ))
+            }
+        }
+    }
+
+    /// Send a JSON-RPC notification.
+    async fn send_notification(&self, method: &str, params: Value) -> Result<(), Error> {
+        let mut service = self.service.lock().await;
+        service.ready().await.map_err(|_| Error::NotReady)?;
+
+        let notification = JsonRpcMessage::Notification(JsonRpcNotification {
+            jsonrpc: "2.0".to_string(),
+            method: method.to_string(),
+            params: Some(params.clone()),
+        });
+
+        service
+            .call(notification)
+            .await
+            .map_err(|e| Error::McpServerError {
+                server: self
+                    .server_info
+                    .as_ref()
+                    .map(|s| s.name.clone())
+                    .unwrap_or("".to_string()),
+                method: method.to_string(),
+                // we don't need include params because it can be really large
+                source: Box::new(e.into()),
+            })?;
+
+        Ok(())
+    }
+
+    // Check if the client has completed initialization
+    fn completed_initialization(&self) -> bool {
+        self.server_capabilities.is_some()
+    }
+}
+
+#[async_trait::async_trait]
+impl<S> McpClientTrait for McpClient<S>
+where
+    S: Service<JsonRpcMessage, Response = JsonRpcMessage> + Clone + Send + Sync + 'static,
+    S::Error: Into<Error>,
+    S::Future: Send,
+{
+    async fn initialize(
+        &mut self,
+        info: ClientInfo,
+        capabilities: ClientCapabilities,
+    ) -> Result<InitializeResult, Error> {
+        let params = InitializeParams {
+            protocol_version: "1.0.0".into(),
+            client_info: info,
+            capabilities,
+        };
+        let result: InitializeResult = self
+            .send_request("initialize", serde_json::to_value(params)?)
+            .await?;
+
+        self.send_notification("notifications/initialized", serde_json::json!({}))
+            .await?;
+
+        self.server_capabilities = Some(result.capabilities.clone());
+
+        self.server_info = Some(result.server_info.clone());
+
+        Ok(result)
+    }
+
+    async fn list_resources(
+        &self,
+        next_cursor: Option<String>,
+    ) -> Result<ListResourcesResult, Error> {
+        if !self.completed_initialization() {
+            return Err(Error::NotInitialized);
+        }
+        // If resources is not supported, return an empty list
+        if self
+            .server_capabilities
+            .as_ref()
+            .unwrap()
+            .resources
+            .is_none()
+        {
+            return Ok(ListResourcesResult {
+                resources: vec![],
+                next_cursor: None,
+            });
+        }
+
+        let payload = next_cursor
+            .map(|cursor| serde_json::json!({"cursor": cursor}))
+            .unwrap_or_else(|| serde_json::json!({}));
+
+        self.send_request("resources/list", payload).await
+    }
+
+    async fn read_resource(&self, uri: &str) -> Result<ReadResourceResult, Error> {
+        if !self.completed_initialization() {
+            return Err(Error::NotInitialized);
+        }
+        // If resources is not supported, return an error
+        if self
+            .server_capabilities
+            .as_ref()
+            .unwrap()
+            .resources
+            .is_none()
+        {
+            return Err(Error::RpcError {
+                code: METHOD_NOT_FOUND,
+                message: "Server does not support 'resources' capability".to_string(),
+            });
+        }
+
+        let params = serde_json::json!({ "uri": uri });
+        self.send_request("resources/read", params).await
+    }
+
+    async fn list_tools(&self, next_cursor: Option<String>) -> Result<ListToolsResult, Error> {
+        if !self.completed_initialization() {
+            return Err(Error::NotInitialized);
+        }
+        // If tools is not supported, return an empty list
+        if self.server_capabilities.as_ref().unwrap().tools.is_none() {
+            return Ok(ListToolsResult {
+                tools: vec![],
+                next_cursor: None,
+            });
+        }
+
+        let payload = next_cursor
+            .map(|cursor| serde_json::json!({"cursor": cursor}))
+            .unwrap_or_else(|| serde_json::json!({}));
+
+        self.send_request("tools/list", payload).await
+    }
+
+    async fn call_tool(&self, name: &str, arguments: Value) -> Result<CallToolResult, Error> {
+        if !self.completed_initialization() {
+            return Err(Error::NotInitialized);
+        }
+        // If tools is not supported, return an error
+        if self.server_capabilities.as_ref().unwrap().tools.is_none() {
+            return Err(Error::RpcError {
+                code: METHOD_NOT_FOUND,
+                message: "Server does not support 'tools' capability".to_string(),
+            });
+        }
+
+        let params = serde_json::json!({ "name": name, "arguments": arguments });
+
+        // TODO ERROR: check that if there is an error, we send back is_error: true with msg
+        // https://modelcontextprotocol.io/docs/concepts/tools#error-handling-2
+        self.send_request("tools/call", params).await
+    }
+}

crates/mcp-client/src/lib.rs

@@ -0,0 +1,7 @@
+pub mod client;
+pub mod service;
+pub mod transport;
+
+pub use client::{ClientCapabilities, ClientInfo, Error, McpClient, McpClientTrait};
+pub use service::McpService;
+pub use transport::{SseTransport, StdioTransport, Transport, TransportHandle};

crates/mcp-client/src/service.rs

@@ -0,0 +1,52 @@
+use futures::future::BoxFuture;
+use mcp_core::protocol::JsonRpcMessage;
+use std::sync::Arc;
+use std::task::{Context, Poll};
+use tower::{timeout::Timeout, Service, ServiceBuilder};
+
+use crate::transport::{Error, TransportHandle};
+
+/// A wrapper service that implements Tower's Service trait for MCP transport
+#[derive(Clone)]
+pub struct McpService<T: TransportHandle> {
+    inner: Arc<T>,
+}
+
+impl<T: TransportHandle> McpService<T> {
+    pub fn new(transport: T) -> Self {
+        Self {
+            inner: Arc::new(transport),
+        }
+    }
+}
+
+impl<T> Service<JsonRpcMessage> for McpService<T>
+where
+    T: TransportHandle + Send + Sync + 'static,
+{
+    type Response = JsonRpcMessage;
+    type Error = Error;
+    type Future = BoxFuture<'static, Result<Self::Response, Self::Error>>;
+
+    fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
+        // Most transports are always ready, but this could be customized if needed
+        Poll::Ready(Ok(()))
+    }
+
+    fn call(&mut self, request: JsonRpcMessage) -> Self::Future {
+        let transport = self.inner.clone();
+        Box::pin(async move { transport.send(request).await })
+    }
+}
+
+// Add a convenience constructor for creating a service with timeout
+impl<T> McpService<T>
+where
+    T: TransportHandle,
+{
+    pub fn with_timeout(transport: T, timeout: std::time::Duration) -> Timeout<McpService<T>> {
+        ServiceBuilder::new()
+            .timeout(timeout)
+            .service(McpService::new(transport))
+    }
+}

crates/mcp-client/src/transport/mod.rs

@@ -0,0 +1,127 @@
+use async_trait::async_trait;
+use mcp_core::protocol::JsonRpcMessage;
+use std::collections::HashMap;
+use thiserror::Error;
+use tokio::sync::{mpsc, oneshot, RwLock};
+
+pub type BoxError = Box<dyn std::error::Error + Sync + Send>;
+/// A generic error type for transport operations.
+#[derive(Debug, Error)]
+pub enum Error {
+    #[error("I/O error: {0}")]
+    Io(#[from] std::io::Error),
+
+    #[error("Transport was not connected or is already closed")]
+    NotConnected,
+
+    #[error("Channel closed")]
+    ChannelClosed,
+
+    #[error("Serialization error: {0}")]
+    Serialization(#[from] serde_json::Error),
+
+    #[error("Unsupported message type. JsonRpcMessage can only be Request or Notification.")]
+    UnsupportedMessage,
+
+    #[error("Stdio process error: {0}")]
+    StdioProcessError(String),
+
+    #[error("SSE connection error: {0}")]
+    SseConnection(String),
+
+    #[error("HTTP error: {status} - {message}")]
+    HttpError { status: u16, message: String },
+}
+
+/// A message that can be sent through the transport
+#[derive(Debug)]
+pub struct TransportMessage {
+    /// The JSON-RPC message to send
+    pub message: JsonRpcMessage,
+    /// Channel to receive the response on (None for notifications)
+    pub response_tx: Option<oneshot::Sender<Result<JsonRpcMessage, Error>>>,
+}
+
+/// A generic asynchronous transport trait with channel-based communication
+#[async_trait]
+pub trait Transport {
+    type Handle: TransportHandle;
+
+    /// Start the transport and establish the underlying connection.
+    /// Returns the transport handle for sending messages.
+    async fn start(&self) -> Result<Self::Handle, Error>;
+
+    /// Close the transport and free any resources.
+    async fn close(&self) -> Result<(), Error>;
+}
+
+#[async_trait]
+pub trait TransportHandle: Send + Sync + Clone + 'static {
+    async fn send(&self, message: JsonRpcMessage) -> Result<JsonRpcMessage, Error>;
+}
+
+// Helper function that contains the common send implementation
+pub async fn send_message(
+    sender: &mpsc::Sender<TransportMessage>,
+    message: JsonRpcMessage,
+) -> Result<JsonRpcMessage, Error> {
+    match message {
+        JsonRpcMessage::Request(request) => {
+            let (respond_to, response) = oneshot::channel();
+            let msg = TransportMessage {
+                message: JsonRpcMessage::Request(request),
+                response_tx: Some(respond_to),
+            };
+            sender.send(msg).await.map_err(|_| Error::ChannelClosed)?;
+            Ok(response.await.map_err(|_| Error::ChannelClosed)??)
+        }
+        JsonRpcMessage::Notification(notification) => {
+            let msg = TransportMessage {
+                message: JsonRpcMessage::Notification(notification),
+                response_tx: None,
+            };
+            sender.send(msg).await.map_err(|_| Error::ChannelClosed)?;
+            Ok(JsonRpcMessage::Nil)
+        }
+        _ => Err(Error::UnsupportedMessage),
+    }
+}
+
+// A data structure to store pending requests and their response channels
+pub struct PendingRequests {
+    requests: RwLock<HashMap<String, oneshot::Sender<Result<JsonRpcMessage, Error>>>>,
+}
+
+impl Default for PendingRequests {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl PendingRequests {
+    pub fn new() -> Self {
+        Self {
+            requests: RwLock::new(HashMap::new()),
+        }
+    }
+
+    pub async fn insert(&self, id: String, sender: oneshot::Sender<Result<JsonRpcMessage, Error>>) {
+        self.requests.write().await.insert(id, sender);
+    }
+
+    pub async fn respond(&self, id: &str, response: Result<JsonRpcMessage, Error>) {
+        if let Some(tx) = self.requests.write().await.remove(id) {
+            let _ = tx.send(response);
+        }
+    }
+
+    pub async fn clear(&self) {
+        self.requests.write().await.clear();
+    }
+}
+
+pub mod stdio;
+pub use stdio::StdioTransport;
+
+pub mod sse;
+pub use sse::SseTransport;

crates/mcp-client/src/transport/sse.rs

@@ -0,0 +1,299 @@
+use crate::transport::{Error, PendingRequests, TransportMessage};
+use async_trait::async_trait;
+use eventsource_client::{Client, SSE};
+use futures::TryStreamExt;
+use mcp_core::protocol::{JsonRpcMessage, JsonRpcRequest};
+use reqwest::Client as HttpClient;
+use std::collections::HashMap;
+use std::sync::Arc;
+use tokio::sync::{mpsc, RwLock};
+use tokio::time::{timeout, Duration};
+use tracing::warn;
+use url::Url;
+
+use super::{send_message, Transport, TransportHandle};
+
+// Timeout for the endpoint discovery
+const ENDPOINT_TIMEOUT_SECS: u64 = 5;
+
+/// The SSE-based actor that continuously:
+/// - Reads incoming events from the SSE stream.
+/// - Sends outgoing messages via HTTP POST (once the post endpoint is known).
+pub struct SseActor {
+    /// Receives messages (requests/notifications) from the handle
+    receiver: mpsc::Receiver<TransportMessage>,
+    /// Map of request-id -> oneshot sender
+    pending_requests: Arc<PendingRequests>,
+    /// Base SSE URL
+    sse_url: String,
+    /// For sending HTTP POST requests
+    http_client: HttpClient,
+    /// The discovered endpoint for POST requests (once "endpoint" SSE event arrives)
+    post_endpoint: Arc<RwLock<Option<String>>>,
+}
+
+impl SseActor {
+    pub fn new(
+        receiver: mpsc::Receiver<TransportMessage>,
+        pending_requests: Arc<PendingRequests>,
+        sse_url: String,
+        post_endpoint: Arc<RwLock<Option<String>>>,
+    ) -> Self {
+        Self {
+            receiver,
+            pending_requests,
+            sse_url,
+            post_endpoint,
+            http_client: HttpClient::new(),
+        }
+    }
+
+    /// The main entry point for the actor. Spawns two concurrent loops:
+    /// 1) handle_incoming_messages (SSE events)
+    /// 2) handle_outgoing_messages (sending messages via POST)
+    pub async fn run(self) {
+        tokio::join!(
+            Self::handle_incoming_messages(
+                self.sse_url.clone(),
+                Arc::clone(&self.pending_requests),
+                Arc::clone(&self.post_endpoint)
+            ),
+            Self::handle_outgoing_messages(
+                self.receiver,
+                self.http_client.clone(),
+                Arc::clone(&self.post_endpoint),
+                Arc::clone(&self.pending_requests),
+            )
+        );
+    }
+
+    /// Continuously reads SSE events from `sse_url`.
+    /// - If an `endpoint` event is received, store it in `post_endpoint`.
+    /// - If a `message` event is received, parse it as `JsonRpcMessage`
+    ///   and respond to pending requests if it's a `Response`.
+    async fn handle_incoming_messages(
+        sse_url: String,
+        pending_requests: Arc<PendingRequests>,
+        post_endpoint: Arc<RwLock<Option<String>>>,
+    ) {
+        let client = match eventsource_client::ClientBuilder::for_url(&sse_url) {
+            Ok(builder) => builder.build(),
+            Err(e) => {
+                pending_requests.clear().await;
+                warn!("Failed to connect SSE client: {}", e);
+                return;
+            }
+        };
+        let mut stream = client.stream();
+
+        // First, wait for the "endpoint" event
+        while let Ok(Some(event)) = stream.try_next().await {
+            match event {
+                SSE::Event(e) if e.event_type == "endpoint" => {
+                    // SSE server uses the "endpoint" event to tell us the POST URL
+                    let base_url = Url::parse(&sse_url).expect("Invalid base URL");
+                    let post_url = base_url
+                        .join(&e.data)
+                        .expect("Failed to resolve endpoint URL");
+
+                    tracing::debug!("Discovered SSE POST endpoint: {}", post_url);
+                    *post_endpoint.write().await = Some(post_url.to_string());
+                    break;
+                }
+                _ => continue,
+            }
+        }
+
+        // Now handle subsequent events
+        while let Ok(Some(event)) = stream.try_next().await {
+            match event {
+                SSE::Event(e) if e.event_type == "message" => {
+                    // Attempt to parse the SSE data as a JsonRpcMessage
+                    match serde_json::from_str::<JsonRpcMessage>(&e.data) {
+                        Ok(message) => {
+                            // If it's a response, complete the pending request
+                            if let JsonRpcMessage::Response(resp) = &message {
+                                if let Some(id) = &resp.id {
+                                    pending_requests.respond(&id.to_string(), Ok(message)).await;
+                                }
+                            }
+                            // If it's something else (notification, etc.), handle as needed
+                        }
+                        Err(err) => {
+                            warn!("Failed to parse SSE message: {err}");
+                        }
+                    }
+                }
+                _ => { /* ignore other events */ }
+            }
+        }
+
+        // SSE stream ended or errored; signal any pending requests
+        tracing::error!("SSE stream ended or encountered an error; clearing pending requests.");
+        pending_requests.clear().await;
+    }
+
+    /// Continuously receives messages from the `mpsc::Receiver`.
+    /// - If it's a request, store the oneshot in `pending_requests`.
+    /// - POST the message to the discovered endpoint (once known).
+    async fn handle_outgoing_messages(
+        mut receiver: mpsc::Receiver<TransportMessage>,
+        http_client: HttpClient,
+        post_endpoint: Arc<RwLock<Option<String>>>,
+        pending_requests: Arc<PendingRequests>,
+    ) {
+        while let Some(transport_msg) = receiver.recv().await {
+            let post_url = match post_endpoint.read().await.as_ref() {
+                Some(url) => url.clone(),
+                None => {
+                    if let Some(response_tx) = transport_msg.response_tx {
+                        let _ = response_tx.send(Err(Error::NotConnected));
+                    }
+                    continue;
+                }
+            };
+
+            // Serialize the JSON-RPC message
+            let message_str = match serde_json::to_string(&transport_msg.message) {
+                Ok(s) => s,
+                Err(e) => {
+                    if let Some(tx) = transport_msg.response_tx {
+                        let _ = tx.send(Err(Error::Serialization(e)));
+                    }
+                    continue;
+                }
+            };
+
+            // If it's a request, store the channel so we can respond later
+            if let Some(response_tx) = transport_msg.response_tx {
+                if let JsonRpcMessage::Request(JsonRpcRequest { id: Some(id), .. }) =
+                    &transport_msg.message
+                {
+                    pending_requests.insert(id.to_string(), response_tx).await;
+                }
+            }
+
+            // Perform the HTTP POST
+            match http_client
+                .post(&post_url)
+                .header("Content-Type", "application/json")
+                .body(message_str)
+                .send()
+                .await
+            {
+                Ok(resp) => {
+                    if !resp.status().is_success() {
+                        let err = Error::HttpError {
+                            status: resp.status().as_u16(),
+                            message: resp.status().to_string(),
+                        };
+                        warn!("HTTP request returned error: {err}");
+                        // This doesn't directly fail the request,
+                        // because we rely on SSE to deliver the error response
+                    }
+                }
+                Err(e) => {
+                    warn!("HTTP POST failed: {e}");
+                    // Similarly, SSE might eventually reveal the error
+                }
+            }
+        }
+
+        // mpsc channel closed => no more outgoing messages
+        tracing::error!("SseActor: outgoing message loop ended. Clearing pending requests.");
+        pending_requests.clear().await;
+    }
+}
+
+#[derive(Clone)]
+pub struct SseTransportHandle {
+    sender: mpsc::Sender<TransportMessage>,
+}
+
+#[async_trait::async_trait]
+impl TransportHandle for SseTransportHandle {
+    async fn send(&self, message: JsonRpcMessage) -> Result<JsonRpcMessage, Error> {
+        send_message(&self.sender, message).await
+    }
+}
+
+#[derive(Clone)]
+pub struct SseTransport {
+    sse_url: String,
+    env: HashMap<String, String>,
+}
+
+/// The SSE transport spawns an `SseActor` on `start()`.
+impl SseTransport {
+    pub fn new<S: Into<String>>(sse_url: S, env: HashMap<String, String>) -> Self {
+        Self {
+            sse_url: sse_url.into(),
+            env,
+        }
+    }
+
+    /// Waits for the endpoint to be set, up to 10 attempts.
+    async fn wait_for_endpoint(
+        post_endpoint: Arc<RwLock<Option<String>>>,
+    ) -> Result<String, Error> {
+        // Check every 100ms for the endpoint, for up to 10 attempts
+        let check_interval = Duration::from_millis(100);
+        let mut attempts = 0;
+        let max_attempts = 10;
+
+        while attempts < max_attempts {
+            if let Some(url) = post_endpoint.read().await.clone() {
+                return Ok(url);
+            }
+            tokio::time::sleep(check_interval).await;
+            attempts += 1;
+        }
+        Err(Error::SseConnection("No endpoint discovered".to_string()))
+    }
+}
+
+#[async_trait]
+impl Transport for SseTransport {
+    type Handle = SseTransportHandle;
+
+    async fn start(&self) -> Result<Self::Handle, Error> {
+        // Set environment variables
+        for (key, value) in &self.env {
+            std::env::set_var(key, value);
+        }
+
+        // Create a channel for outgoing TransportMessages
+        let (tx, rx) = mpsc::channel(32);
+
+        let post_endpoint: Arc<RwLock<Option<String>>> = Arc::new(RwLock::new(None));
+        let post_endpoint_clone = Arc::clone(&post_endpoint);
+
+        // Build the actor
+        let actor = SseActor::new(
+            rx,
+            Arc::new(PendingRequests::new()),
+            self.sse_url.clone(),
+            post_endpoint,
+        );
+
+        // Spawn the actor task
+        tokio::spawn(actor.run());
+
+        // Wait for the endpoint to be discovered before returning the handle
+        match timeout(
+            Duration::from_secs(ENDPOINT_TIMEOUT_SECS),
+            Self::wait_for_endpoint(post_endpoint_clone),
+        )
+        .await
+        {
+            Ok(_) => Ok(SseTransportHandle { sender: tx }),
+            Err(e) => Err(Error::SseConnection(e.to_string())),
+        }
+    }
+
+    async fn close(&self) -> Result<(), Error> {
+        // For SSE, you might close the stream or send a shutdown signal to the actor.
+        // Here, we do nothing special.
+        Ok(())
+    }
+}

crates/mcp-client/src/transport/stdio.rs

@@ -0,0 +1,270 @@
+use std::collections::HashMap;
+use std::sync::Arc;
+use tokio::process::{Child, ChildStderr, ChildStdin, ChildStdout, Command};
+
+use async_trait::async_trait;
+use mcp_core::protocol::JsonRpcMessage;
+use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader};
+use tokio::sync::{mpsc, Mutex};
+
+use super::{send_message, Error, PendingRequests, Transport, TransportHandle, TransportMessage};
+
+/// A `StdioTransport` uses a child process's stdin/stdout as a communication channel.
+///
+/// It uses channels for message passing and handles responses asynchronously through a background task.
+pub struct StdioActor {
+    receiver: mpsc::Receiver<TransportMessage>,
+    pending_requests: Arc<PendingRequests>,
+    _process: Child, // we store the process to keep it alive
+    error_sender: mpsc::Sender<Error>,
+    stdin: ChildStdin,
+    stdout: ChildStdout,
+    stderr: ChildStderr,
+}
+
+impl StdioActor {
+    pub async fn run(mut self) {
+        use tokio::pin;
+
+        let incoming = Self::handle_incoming_messages(self.stdout, self.pending_requests.clone());
+        let outgoing = Self::handle_outgoing_messages(
+            self.receiver,
+            self.stdin,
+            self.pending_requests.clone(),
+        );
+
+        // take ownership of futures for tokio::select
+        pin!(incoming);
+        pin!(outgoing);
+
+        // Use select! to wait for either I/O completion or process exit
+        tokio::select! {
+            result = &mut incoming => {
+                tracing::debug!("Stdin handler completed: {:?}", result);
+            }
+            result = &mut outgoing => {
+                tracing::debug!("Stdout handler completed: {:?}", result);
+            }
+            // capture the status so we don't need to wait for a timeout
+            status = self._process.wait() => {
+                tracing::debug!("Process exited with status: {:?}", status);
+            }
+        }
+
+        // Then always try to read stderr before cleaning up
+        let mut stderr_buffer = Vec::new();
+        if let Ok(bytes) = self.stderr.read_to_end(&mut stderr_buffer).await {
+            let err_msg = if bytes > 0 {
+                String::from_utf8_lossy(&stderr_buffer).to_string()
+            } else {
+                "Process ended unexpectedly".to_string()
+            };
+
+            tracing::info!("Process stderr: {}", err_msg);
+            let _ = self
+                .error_sender
+                .send(Error::StdioProcessError(err_msg))
+                .await;
+        }
+
+        // Clean up regardless of which path we took
+        self.pending_requests.clear().await;
+    }
+
+    async fn handle_incoming_messages(stdout: ChildStdout, pending_requests: Arc<PendingRequests>) {
+        let mut reader = BufReader::new(stdout);
+        let mut line = String::new();
+        loop {
+            match reader.read_line(&mut line).await {
+                Ok(0) => {
+                    tracing::error!("Child process ended (EOF on stdout)");
+                    break;
+                } // EOF
+                Ok(_) => {
+                    if let Ok(message) = serde_json::from_str::<JsonRpcMessage>(&line) {
+                        tracing::debug!(
+                            message = ?message,
+                            "Received incoming message"
+                        );
+
+                        if let JsonRpcMessage::Response(response) = &message {
+                            if let Some(id) = &response.id {
+                                pending_requests.respond(&id.to_string(), Ok(message)).await;
+                            }
+                        }
+                    }
+                    line.clear();
+                }
+                Err(e) => {
+                    tracing::error!(error = ?e, "Error reading line");
+                    break;
+                }
+            }
+        }
+    }
+
+    async fn handle_outgoing_messages(
+        mut receiver: mpsc::Receiver<TransportMessage>,
+        mut stdin: ChildStdin,
+        pending_requests: Arc<PendingRequests>,
+    ) {
+        while let Some(mut transport_msg) = receiver.recv().await {
+            let message_str = match serde_json::to_string(&transport_msg.message) {
+                Ok(s) => s,
+                Err(e) => {
+                    if let Some(tx) = transport_msg.response_tx.take() {
+                        let _ = tx.send(Err(Error::Serialization(e)));
+                    }
+                    continue;
+                }
+            };
+
+            tracing::debug!(message = ?transport_msg.message, "Sending outgoing message");
+
+            if let Some(response_tx) = transport_msg.response_tx.take() {
+                if let JsonRpcMessage::Request(request) = &transport_msg.message {
+                    if let Some(id) = &request.id {
+                        pending_requests.insert(id.to_string(), response_tx).await;
+                    }
+                }
+            }
+
+            if let Err(e) = stdin
+                .write_all(format!("{}\n", message_str).as_bytes())
+                .await
+            {
+                tracing::error!(error = ?e, "Error writing message to child process");
+                pending_requests.clear().await;
+                break;
+            }
+
+            if let Err(e) = stdin.flush().await {
+                tracing::error!(error = ?e, "Error flushing message to child process");
+                pending_requests.clear().await;
+                break;
+            }
+        }
+    }
+}
+
+#[derive(Clone)]
+pub struct StdioTransportHandle {
+    sender: mpsc::Sender<TransportMessage>,
+    error_receiver: Arc<Mutex<mpsc::Receiver<Error>>>,
+}
+
+#[async_trait::async_trait]
+impl TransportHandle for StdioTransportHandle {
+    async fn send(&self, message: JsonRpcMessage) -> Result<JsonRpcMessage, Error> {
+        let result = send_message(&self.sender, message).await;
+        // Check for any pending errors even if send is successful
+        self.check_for_errors().await?;
+        result
+    }
+}
+
+impl StdioTransportHandle {
+    /// Check if there are any process errors
+    pub async fn check_for_errors(&self) -> Result<(), Error> {
+        match self.error_receiver.lock().await.try_recv() {
+            Ok(error) => {
+                tracing::debug!("Found error: {:?}", error);
+                Err(error)
+            }
+            Err(_) => Ok(()),
+        }
+    }
+}
+
+pub struct StdioTransport {
+    command: String,
+    args: Vec<String>,
+    env: HashMap<String, String>,
+}
+
+impl StdioTransport {
+    pub fn new<S: Into<String>>(
+        command: S,
+        args: Vec<String>,
+        env: HashMap<String, String>,
+    ) -> Self {
+        Self {
+            command: command.into(),
+            args,
+            env,
+        }
+    }
+
+    async fn spawn_process(&self) -> Result<(Child, ChildStdin, ChildStdout, ChildStderr), Error> {
+        let mut command = Command::new(&self.command);
+        command
+            .envs(&self.env)
+            .args(&self.args)
+            .stdin(std::process::Stdio::piped())
+            .stdout(std::process::Stdio::piped())
+            .stderr(std::process::Stdio::piped())
+            .kill_on_drop(true);
+
+        // Set process group only on Unix systems
+        #[cfg(unix)]
+        command.process_group(0); // don't inherit signal handling from parent process
+
+        // Hide console window on Windows
+        #[cfg(windows)]
+        command.creation_flags(0x08000000); // CREATE_NO_WINDOW flag
+
+        let mut process = command
+            .spawn()
+            .map_err(|e| Error::StdioProcessError(e.to_string()))?;
+
+        let stdin = process
+            .stdin
+            .take()
+            .ok_or_else(|| Error::StdioProcessError("Failed to get stdin".into()))?;
+
+        let stdout = process
+            .stdout
+            .take()
+            .ok_or_else(|| Error::StdioProcessError("Failed to get stdout".into()))?;
+
+        let stderr = process
+            .stderr
+            .take()
+            .ok_or_else(|| Error::StdioProcessError("Failed to get stderr".into()))?;
+
+        Ok((process, stdin, stdout, stderr))
+    }
+}
+
+#[async_trait]
+impl Transport for StdioTransport {
+    type Handle = StdioTransportHandle;
+
+    async fn start(&self) -> Result<Self::Handle, Error> {
+        let (process, stdin, stdout, stderr) = self.spawn_process().await?;
+        let (message_tx, message_rx) = mpsc::channel(32);
+        let (error_tx, error_rx) = mpsc::channel(1);
+
+        let actor = StdioActor {
+            receiver: message_rx,
+            pending_requests: Arc::new(PendingRequests::new()),
+            _process: process,
+            error_sender: error_tx,
+            stdin,
+            stdout,
+            stderr,
+        };
+
+        tokio::spawn(actor.run());
+
+        let handle = StdioTransportHandle {
+            sender: message_tx,
+            error_receiver: Arc::new(Mutex::new(error_rx)),
+        };
+        Ok(handle)
+    }
+
+    async fn close(&self) -> Result<(), Error> {
+        Ok(())
+    }
+}