Python
Surface MCP server startup failures
Rohit C Prasadb0d2bbd18314
diff --git a/coworker/mcp/client.py b/coworker/mcp/client.pyindex 04f8fcc0..ad343e36 100644--- a/coworker/mcp/client.py+++ b/coworker/mcp/client.py@@ -13,8 +13,9 @@ Tool execution from the (sync) ToolRegistry bridges back here viafrom __future__ import annotationsimport asyncio+import tempfilefrom contextlib import AsyncExitStack-from typing import Any, Optional+from typing import Any, IO, Optionalfrom mcp import ClientSession, StdioServerParametersfrom mcp.client.stdio import stdio_client@@ -23,6 +24,25 @@ from mcp.client.streamable_http import streamablehttp_clientfrom .config import MCPServerDef+_STDERR_TAIL_LINES = 20+_STDERR_TAIL_CHARS = 1500+++def _read_tail(errfile: Optional[IO[str]]) -> Optional[str]:+ """Last few lines of a captured stderr file — the crash evidence, not the log."""+ if errfile is None:+ return None+ try:+ errfile.seek(0)+ text = errfile.read()+ except (OSError, ValueError):+ return None+ lines = [ln for ln in text.strip().splitlines() if ln.strip()]+ if not lines:+ return None+ return "\n".join(lines[-_STDERR_TAIL_LINES:])[-_STDERR_TAIL_CHARS:]++class _Conn:def __init__(self, session: ClientSession, tools: list[Any]) -> None:self.session = session@@ -36,6 +56,7 @@ class MCPManager:def __init__(self, secrets: Any = None) -> None:self._conns: dict[str, _Conn] = {}self._tasks: dict[str, asyncio.Task] = {}+ self._stderr_tails: dict[str, str] = {}self._lock = asyncio.Lock()# SecretStore for OAuth servers' token persistence (mcp/oauth.py); lazy default# so library/CLI construction without secrets keeps working.@@ -64,6 +85,10 @@ class MCPManager:async def tools(self, server: MCPServerDef) -> list[Any]:return (await self.ensure(server)).tools+ def last_stderr(self, name: str) -> Optional[str]:+ """Stderr tail from the most recent failed startup of `name`, if any."""+ return self._stderr_tails.get(name)+async def call(self, name: str, tool: str, arguments: Optional[dict[str, Any]]) -> Any:@@ -88,6 +113,7 @@ class MCPManager:async def _serve(self, server: MCPServerDef, ready: asyncio.Future, *, interactive: bool = False) -> None:+ errfile = Nonetry:async with AsyncExitStack() as stack:if server.transport == "http":@@ -124,18 +150,34 @@ class MCPManager:env=server.env or None,cwd=server.cwd,)- read, write = await stack.enter_async_context(stdio_client(params))+ # Capture the child's stderr so a startup crash leaves evidence+ # the UI can show (the SDK needs a real file descriptor here).+ errfile = tempfile.TemporaryFile(+ mode="w+", encoding="utf-8", errors="replace"+ )+ read, write = await stack.enter_async_context(+ stdio_client(params, errlog=errfile)+ )session = await stack.enter_async_context(ClientSession(read, write))await session.initialize()listed = await session.list_tools()conn = _Conn(session, list(listed.tools))+ self._stderr_tails.pop(server.name, None)if not ready.done():ready.set_result(conn)await conn.shutdown.wait()except Exception as exc: # connection / init failure+ tail = _read_tail(errfile)+ if tail:+ self._stderr_tails[server.name] = tailif not ready.done():ready.set_exception(exc)finally:+ if errfile is not None:+ try:+ errfile.close()+ except OSError:+ passself._conns.pop(server.name, None)self._tasks.pop(server.name, None)diff --git a/coworker/server/app.py b/coworker/server/app.pyindex e8b97638..2e8340c2 100644--- a/coworker/server/app.py+++ b/coworker/server/app.py@@ -1784,6 +1784,16 @@ def create_app(manager: SessionManager) -> FastAPI:)await ws.close()return+ # MCP servers that failed to start while preparing this session's tools:+ # leave a quiet, persistent notice instead of the session silently lacking+ # them (drill 2026-08-20: three silent startup failures in a row).+ for name, err in manager.pop_mcp_failures(session_id):+ detail = f": {err}" if err else ""+ engine._append_notice(+ "mcp_error",+ f"MCP server “{name}” failed to start{detail}"[:300]+ + " — see Settings ▸ MCP",+ )# Auto-compaction failure prompt (OPE-27): only an ATTENDED session may be asked# Retry/Trim — unattended runs auto-trim (the policy in engine._compact_now).engine.is_attended = lambda: _visibility() == VIS_INLINEdiff --git a/coworker/server/manager.py b/coworker/server/manager.pyindex 66a51ecc..9e4be4c8 100644--- a/coworker/server/manager.py+++ b/coworker/server/manager.py@@ -166,6 +166,9 @@ class SessionManager:# feeds list_mcp's status so the GUI can show "authorizing…" and failures.self._mcp_authorizing: set[str] = set()self._mcp_errors: dict[str, str] = {}+ # Servers that failed to connect while preparing a session's tools —+ # drained once by the WS handler to append a transcript notice.+ self._mcp_session_failures: dict[str, list[str]] = {}self.gateway: Optional[Gateway] = Noneself._data_base = base# Desktop/UI prefs (default model, onboarding state) — not secrets; a plain JSON file.@@ -957,6 +960,7 @@ class SessionManager:]try:conn = await self.mcp.ensure(server)+ self._mcp_errors.pop(server.name, None)except Exception as exc:if mcp_oauth.is_auth_required(exc):# Stored tokens no longer refresh (vendor rotated/expired@@ -969,7 +973,22 @@ class SessionManager:logger.info("mcp %s needs re-auth; skipped for this session", server.name)- # else: bad command / unreachable url — skip, don't break the session+ else:+ # Bad command / crashed child / unreachable url — the session+ # still runs without the tools, but the failure must not be+ # silent (three-for-three silent failures in the 2026-08-20+ # drill): record it for the MCP page and the session notice.+ msg = str(exc) or exc.__class__.__name__+ tail = self.mcp.last_stderr(server.name)+ if tail:+ msg = f"{msg} — {tail}"+ self._mcp_errors[server.name] = msg[:500]+ logger.warning(+ "mcp %s failed to connect: %s", server.name, msg[:500]+ )+ self._mcp_session_failures.setdefault(session_id, []).append(+ server.name+ )continuecallables = build_callables(server,@@ -988,6 +1007,12 @@ class SessionManager:out.extend(callables)return out+ def pop_mcp_failures(self, session_id: str) -> list[tuple[str, Optional[str]]]:+ """Drain (name, error) for servers that failed while preparing this session's+ tools — consumed once by the WS handler to append a transcript notice."""+ names = self._mcp_session_failures.pop(session_id, [])+ return [(n, self._mcp_errors.get(n)) for n in names]+def list_mcp(self) -> list[dict[str, Any]]:"""Servers from the global config + connection status (does not connect)."""from ..mcp import oauth as mcp_oauth@@ -1011,6 +1036,12 @@ class SessionManager:status = "authorizing"elif is_oauth and not mcp_oauth.has_tokens(name, self.secrets):status = "needs_auth"+ elif name in self._mcp_errors and not is_oauth:+ # Startup/connection failure (stdio crash, unreachable url) — the+ # drill class. OAuth servers keep their softer statuses: acquiring+ # tokens supersedes a stale sign-in error (the GUI still prints+ # last_error under the row either way).+ status = "error"else:status = "configured"out.append(diff --git a/surfaces/gui/node_modules b/surfaces/gui/node_modulesnew file mode 120000index 00000000..542a3b2b--- /dev/null+++ b/surfaces/gui/node_modules@@ -0,0 +1 @@+/Users/rohit/fleet/ro4d/openworker/surfaces/gui/node_modules\ No newline at end of filediff --git a/surfaces/gui/src/itemsFromMessages.test.ts b/surfaces/gui/src/itemsFromMessages.test.tsindex b87b8717..412f2de7 100644--- a/surfaces/gui/src/itemsFromMessages.test.ts+++ b/surfaces/gui/src/itemsFromMessages.test.ts@@ -108,3 +108,17 @@ describe("itemsFromMessages reasoning", () => {expect(items[2]).toEqual({ kind: "assistant", text: "", reasoning: "stopped mid-thought" });});});++describe("itemsFromMessages mcp failure", () => {+ it("replays the persisted mcp_error marker as a warn notice WITHOUT retry", () => {+ const items = itemsFromMessages([+ { role: "user", content: "hi" },+ { role: "notice", kind: "mcp_error", text: "MCP server “sales-db” failed to start — see Settings ▸ MCP" },+ ] as any);+ expect(items[1]).toEqual({+ kind: "notice",+ tone: "warn",+ text: "MCP server “sales-db” failed to start — see Settings ▸ MCP",+ });+ });+});diff --git a/surfaces/gui/src/itemsFromMessages.ts b/surfaces/gui/src/itemsFromMessages.tsindex 54cc3364..d78e7ace 100644--- a/surfaces/gui/src/itemsFromMessages.ts+++ b/surfaces/gui/src/itemsFromMessages.ts@@ -78,7 +78,11 @@ export function itemsFromMessages(messages: ConversationMessage[]): Item[] {: m.kind === "compacted"? // The subtle "compacted here" divider (OPE-27) — the transcript itself is intact.{ kind: "notice", tone: "info", text: m.text || "Context compacted" }- : { kind: "notice", tone: "warn", text: "Error: " + (m.text || "unknown"), retriable: true },+ : m.kind === "mcp_error"+ ? // A configured MCP server failed to start for this session — informational,+ // NOT retriable (retry re-runs the model turn, which can't fix a dead server).+ { kind: "notice", tone: "warn", text: m.text || "An MCP server failed to start" }+ : { kind: "notice", tone: "warn", text: "Error: " + (m.text || "unknown"), retriable: true },);}// system messages are omitted; tool-result messages are folded into the tool row abovediff --git a/tests/test_mcp.py b/tests/test_mcp.pyindex dba6d68b..a198cf73 100644--- a/tests/test_mcp.py+++ b/tests/test_mcp.py@@ -254,3 +254,61 @@ def test_rest_crud(tmp_path, monkeypatch):assert client.delete("/v1/mcp/fs").json()["ok"] is Trueassert client.get("/v1/mcp").json()["servers"] == []assert client.delete("/v1/mcp/fs").json()["ok"] is False+++# -- failure surfacing (drill 2026-08-20: silent startup crashes) ----------------+++async def test_stdio_startup_crash_captures_stderr_tail(tmp_path, monkeypatch):+ """A stdio server that dies before initialize leaves its stderr tail behind."""+ from coworker.mcp.client import MCPManager++ mgr = MCPManager()+ server = MCPServerDef(+ name="doomed",+ transport="stdio",+ command="/bin/sh",+ args=["-c", "echo 'usage: doomed --flag' >&2; exit 7"],+ )+ with pytest.raises(Exception):+ await mgr.ensure(server)+ tail = mgr.last_stderr("doomed")+ assert tail is not None and "usage: doomed --flag" in tail+++async def test_prepare_records_failure_status_and_session_notice(+ tmp_path, monkeypatch+):+ """A crashing global server surfaces: last_error + status=error + one-shot+ session failure drain — instead of the pre-drill silent skip."""+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))+ _write_json(+ tmp_path / "state" / "mcp.json",+ {+ "mcpServers": {+ "sales-db": {+ "command": "/bin/sh",+ "args": ["-c", "echo 'boom: bad args' >&2; exit 2"],+ "enabled": True,+ }+ }+ },+ )+ manager = SessionManager(data_dir=tmp_path / "data")++ tools = await manager.prepare_mcp_tools("s1", workspace=str(tmp_path / "wsp"))+ assert tools == []++ err = manager._mcp_errors.get("sales-db")+ assert err and "boom: bad args" in err++ listed = {s["name"]: s for s in manager.list_mcp()}+ assert listed["sales-db"]["status"] == "error"+ assert "boom: bad args" in (listed["sales-db"]["last_error"] or "")++ drained = manager.pop_mcp_failures("s1")+ assert [n for n, _ in drained] == ["sales-db"]+ assert "boom: bad args" in (drained[0][1] or "")+ assert manager.pop_mcp_failures("s1") == [] # one-shot