feat: add Docker-specific hints for stdio connection errors

When a stdio MCP server uses docker as the command and fails to connect,
the error message now includes "Ensure Docker Desktop is installed and
running." This helps developers who have Docker stopped or not installed.

Also fixes e2e desktop CI flakiness on Ubuntu by combining
gnome-keyring-daemon --unlock and --start into a single invocation
with eval to properly export GNOME_KEYRING_CONTROL.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>

Author: its-mash

.github/workflows/e2e-desktop.yml

@@ -115,10 +115,11 @@ jobs:
       - name: Run desktop E2E tests (Linux)
         if: matrix.os == 'ubuntu-latest'
         run: |
-          # Start dbus session and unlock gnome-keyring with a dummy password for CI
+          # Start dbus session and unlock gnome-keyring with a dummy password for CI.
+          # Use a single daemon invocation (--unlock + --start) and eval to export
+          # GNOME_KEYRING_CONTROL so the keyring stays unlocked across all test specs.
           dbus-run-session -- bash -c '
-            echo "test" | gnome-keyring-daemon --unlock --components=secrets
-            export $(gnome-keyring-daemon --start --components=secrets)
+            eval $(echo "test" | gnome-keyring-daemon --unlock --start --components=secrets 2>/dev/null)
             sleep 1
             xvfb-run --auto-servernum pnpm test:e2e
           '

crates/mcpmux-gateway/src/pool/transport/stdio.rs

@@ -41,6 +41,16 @@ pub fn configure_child_process_platform(cmd: &mut Command) {
     }
 }
 
+/// Returns a helpful hint for common runtime-dependent commands when they fail.
+fn command_hint(command: &str) -> &'static str {
+    let cmd = command.rsplit(['/', '\\']).next().unwrap_or(command);
+    if cmd == "docker" || cmd == "docker.exe" || cmd.starts_with("docker-") {
+        " Ensure Docker Desktop is installed and running."
+    } else {
+        ""
+    }
+}
+
 /// STDIO transport for child process MCP servers
 pub struct StdioTransport {
     command: String,
@@ -114,8 +124,9 @@ impl Transport for StdioTransport {
         {
             Ok(path) => path,
             Err(_) => {
+                let hint = command_hint(&self.command);
                 let err = format!(
-                    "Command not found: {}. Ensure it's installed and in PATH.",
+                    "Command not found: {}. Ensure it's installed and in PATH.{hint}",
                     self.command
                 );
                 error!(server_id = %self.server_id, "{}", err);
@@ -156,7 +167,8 @@ impl Transport for StdioTransport {
             })) {
                 Ok(t) => t,
                 Err(e) => {
-                    let err = format!("Failed to spawn process: {}", e);
+                    let hint = command_hint(&self.command);
+                    let err = format!("Failed to spawn process: {e}.{hint}");
                     error!(server_id = %self.server_id, "{}", err);
                     self.log(LogLevel::Error, LogSource::Connection, err.clone())
                         .await;
@@ -173,14 +185,16 @@ impl Transport for StdioTransport {
         let client = match tokio::time::timeout(self.connect_timeout, connect_future).await {
             Ok(Ok(client)) => client,
             Ok(Err(e)) => {
-                let err = format!("MCP handshake failed: {}", e);
+                let hint = command_hint(&self.command);
+                let err = format!("MCP handshake failed: {e}.{hint}");
                 error!(server_id = %self.server_id, "{}", err);
                 self.log(LogLevel::Error, LogSource::Connection, err.clone())
                     .await;
                 return TransportConnectResult::Failed(err);
             }
             Err(_) => {
-                let err = format!("Connection timeout ({:?})", self.connect_timeout);
+                let hint = command_hint(&self.command);
+                let err = format!("Connection timeout ({:?}).{hint}", self.connect_timeout);
                 error!(server_id = %self.server_id, "{}", err);
                 self.log(LogLevel::Error, LogSource::Connection, err.clone())
                     .await;

tests/rust/tests/gateway/stdio_transport.rs

@@ -170,6 +170,52 @@ async fn test_platform_flags_idempotent() {
     assert!(status.success(), "Child process should exit successfully");
 }
 
+/// Verify that a docker command not found error includes a Docker-specific hint
+#[tokio::test]
+async fn test_docker_command_not_found_includes_hint() {
+    use mcpmux_gateway::pool::transport::StdioTransport;
+    use mcpmux_gateway::pool::{Transport, TransportConnectResult};
+    use std::collections::HashMap;
+    use std::time::Duration;
+    use uuid::Uuid;
+
+    let transport = StdioTransport::new(
+        "docker".to_string(),
+        vec![
+            "run".to_string(),
+            "-i".to_string(),
+            "some-image".to_string(),
+        ],
+        HashMap::new(),
+        Uuid::new_v4(),
+        "test-docker-server".to_string(),
+        None,
+        Duration::from_secs(5),
+        None,
+    );
+
+    let result = transport.connect().await;
+    match result {
+        TransportConnectResult::Failed(msg) => {
+            // If docker is not installed, we get "Command not found" with hint.
+            // If docker IS installed but daemon isn't running, we'd get a different error with hint.
+            // Either way, the hint should be present.
+            assert!(
+                msg.contains("Docker Desktop"),
+                "Expected Docker hint in error message, got: {msg}"
+            );
+        }
+        // If docker happens to be installed and running, the test still passes
+        // (connect would succeed or fail with handshake error that includes the hint)
+        TransportConnectResult::Connected(_) => {
+            // Docker is installed and running - that's fine, test passes
+        }
+        TransportConnectResult::OAuthRequired { .. } => {
+            panic!("Unexpected OAuthRequired for docker stdio transport")
+        }
+    }
+}
+
 /// Verify that environment variables are passed through correctly
 /// when platform flags are applied (important because CREATE_NO_WINDOW
 /// is OR'd with CREATE_UNICODE_ENVIRONMENT internally).