From bdc99d746a4dabe1cc4cc1fe52eaf8dad1baac26 Mon Sep 17 00:00:00 2001
From: Prakhya <gotnochill815@gmail.com>
Date: Tue, 2 Jun 2026 08:20:17 +0530
Subject: [PATCH] fix: add Browser MCP connection diagnostics (#662)

---
 src/mcp_manager.py        | 21 ++++++++++++++++++++-
 tests/test_mcp_manager.py | 26 ++++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_mcp_manager.py

diff --git a/src/mcp_manager.py b/src/mcp_manager.py
index 3b0aa92..3cddfab 100644
--- a/src/mcp_manager.py
+++ b/src/mcp_manager.py
@@ -12,6 +12,24 @@ from typing import Any, Dict, List, Optional
 
 logger = logging.getLogger(__name__)
 
+def _format_mcp_connection_error(name: str, command: str = "", args: Optional[List[str]] = None, error: Exception = None) -> str:
+    """Return a user-actionable MCP connection error message."""
+    args = args or []
+    raw_error = str(error) if error else "Unknown error"
+    command_line = " ".join([command or "", *args]).strip()
+    lower_command = command_line.lower()
+
+    if "@playwright/mcp" in lower_command:
+        return (
+            f"{raw_error}\n\n"
+            "Browser MCP could not start. On fresh installs, cache the Playwright MCP package once before connecting:\n\n"
+            "npx -y @playwright/mcp@latest --version\n\n"
+            "Then restart Odysseus and reconnect the Browser MCP server."
+        )
+
+    return raw_error
+
+
 
 class McpManager:
     """Manages MCP server connections and tool routing."""
@@ -47,7 +65,8 @@ class McpManager:
                 return False
         except Exception as e:
             logger.error(f"Failed to connect MCP server {name} ({server_id}): {e}")
-            self._connections[server_id] = {"status": "error", "error": str(e), "name": name}
+            error_message = _format_mcp_connection_error(name, command or "", args or [], e)
+            self._connections[server_id] = {"status": "error", "error": error_message, "name": name}
             return False
 
     async def _connect_stdio(self, server_id: str, name: str, command: str, args: List[str], env: Dict[str, str]) -> bool:
diff --git a/tests/test_mcp_manager.py b/tests/test_mcp_manager.py
new file mode 100644
index 0000000..20a3bc3
--- /dev/null
+++ b/tests/test_mcp_manager.py
@@ -0,0 +1,26 @@
+from src.mcp_manager import _format_mcp_connection_error
+
+
+def test_playwright_mcp_connection_error_includes_install_hint():
+    msg = _format_mcp_connection_error(
+        "Browser (Playwright)",
+        "npx",
+        ["-y", "@playwright/mcp@latest", "--headless"],
+        RuntimeError("package not found"),
+    )
+
+    assert "package not found" in msg
+    assert "Browser MCP could not start" in msg
+    assert "npx -y @playwright/mcp@latest --version" in msg
+    assert "restart Odysseus" in msg
+
+
+def test_generic_mcp_connection_error_preserves_original_error():
+    msg = _format_mcp_connection_error(
+        "Custom MCP",
+        "python",
+        ["server.py"],
+        RuntimeError("boom"),
+    )
+
+    assert msg == "boom"