Python
OPE-228 headless: attach MCP servers to `openworker run`
Devika Vermafafc2ed33d15
diff --git a/coworker/headless/runner.py b/coworker/headless/runner.pyindex 5d32873d..3cadae25 100644--- a/coworker/headless/runner.py+++ b/coworker/headless/runner.py@@ -178,6 +178,23 @@ def parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace:help="reasoning-effort level sent to the provider (Anthropic output_config.effort, ""Together/Moonshot reasoning_effort). Default: nothing sent; the provider default is recorded",)+ p.add_argument(+ "--mcp",+ action="store_true",+ help="attach MCP servers as tools for this run (off by default). Reads this "+ "computer's mcp.json unless --mcp-config points elsewhere; for an --isolated run "+ "that is <out>/state/mcp.json. A server's tools reach the model as "+ "mcp__<server>__<tool>; a server that fails to connect is skipped and the run "+ "goes on. The headless runner attaches only the global (or --mcp-config) file — a "+ "workspace .coworker/mcp.json needs trust it does not establish.",+ )+ p.add_argument(+ "--mcp-config",+ default=None,+ metavar="FILE",+ help="load MCP servers from this mcpServers JSON file only, with no global or "+ "workspace merge (implies --mcp). For a run that brings its own server config.",+ )p.add_argument("--scripted", default=None, help=argparse.SUPPRESS) # tests: a fake modelargs = p.parse_args(argv)# The engine's name for the mode, which is also what the record states.@@ -703,6 +720,64 @@ def _extra_dirs(args: argparse.Namespace, workspace: Path) -> list:return found+def _mcp_server_defs(+ args: argparse.Namespace, workspace: Path, secrets: Any+) -> list:+ """The MCP servers to attach for this run, or [] when MCP is off. `--mcp-config`+ names one explicit file (the only source); otherwise this computer's layered config.+ A workspace `.coworker/mcp.json` is executable provenance that needs trust the+ headless runner does not establish, so only the global (or explicit) file is read."""+ if not (args.mcp or args.mcp_config):+ return []+ from ..mcp import load_mcp_file, load_mcp_servers++ if args.mcp_config:+ return load_mcp_file(args.mcp_config, secrets=secrets)+ return load_mcp_servers(workspace, secrets=secrets, workspace_trusted=False)+++async def _attach_mcp(engine: Any, servers: list, secrets: Any, *, on_note: Any) -> Any:+ """Connect each enabled MCP server and register its tools on the LIVE engine.++ Runs on the engine's own event loop (the `asyncio.run` loop that drives the turn),+ so the sync→async tool bridge in `build_callables` targets the loop the tool thread+ bridges back to. The engine reads `registry.schemas()` per turn, so tools registered+ here are visible from the first model call. A server that fails to connect is noted+ and skipped — the run continues without its tools. Returns the MCPManager to close+ when the run ends, or None when nothing attached (so there is nothing to close)."""+ from ..mcp import MCPManager, build_callables++ manager = MCPManager(secrets=secrets)+ loop = asyncio.get_running_loop()+ attached = 0+ for server in servers:+ if not server.enabled:+ continue+ try:+ conn = await manager.ensure(server)+ except Exception as exc: # noqa: BLE001 - a bad server must never kill the run+ tail = manager.last_stderr(server.name)+ msg = f"{exc}" + (f" — {tail}" if tail else "")+ on_note("mcp_server_failed", {"server": server.name, "error": msg[:600]})+ continue+ callables = build_callables(+ server,+ conn.tools,+ lambda tool, a, name=server.name: manager.call(name, tool, a),+ loop,+ )+ engine.registry.register_all(callables)+ attached += len(callables)+ on_note(+ "mcp_server_attached",+ {"server": server.name, "tools": [c.__name__ for c in callables]},+ )+ if attached == 0:+ await manager.aclose()+ return None+ return manager++class UsageError(Exception):"""The command line cannot be run as given: said on standard error, exit code 2."""@@ -848,6 +923,17 @@ def _run(args: argparse.Namespace) -> int:)secrets = SecretStore(state_dir() / "secrets.json")+ # MCP servers to attach (if any), resolved with this run's SecretStore for ${VAR}+ # refs. Connected later, on the engine's own event loop (see guarded()).+ mcp_servers = _mcp_server_defs(args, workspace, secrets)+ if (args.mcp or args.mcp_config) and not mcp_servers:+ print(+ "openworker run: --mcp was given but no MCP servers were found in "+ + (args.mcp_config or "this computer's mcp.json")+ + "; the run continues with no MCP tools.",+ file=sys.stderr,+ flush=True,+ )if args.scripted:provider = scripted_provider(Path(args.scripted))else:@@ -950,6 +1036,27 @@ def _run(args: argparse.Namespace) -> int:# provisional summary, messages, and trajectory are rewritten. SIGTERM also flushes.events_fh = (out / "events.jsonl").open("w", encoding="utf-8")+ def _mcp_note(kind: str, data: dict[str, Any]) -> None:+ """Record one MCP attach/fail line to the event stream and stderr."""+ rec = {"ts": time.time(), "type": kind, "data": data}+ events.append(rec)+ events_fh.write(json.dumps(rec, default=str) + "\n")+ events_fh.flush()+ if kind == "mcp_server_failed":+ print(+ f"openworker run: MCP server {data.get('server')!r} failed to connect: "+ f"{data.get('error')}",+ file=sys.stderr,+ flush=True,+ )+ else:+ print(+ f"openworker run: MCP {data.get('server')}: "+ f"{len(data.get('tools') or [])} tools attached",+ file=sys.stderr,+ flush=True,+ )+def flush_provisional(status: str) -> None:try:events_fh.flush()@@ -1102,12 +1209,25 @@ def _run(args: argparse.Namespace) -> int:breakasync def guarded() -> None:- # timeout_seconds <= 0 disables the run's own limit (an outer runner may enforce- # its own; a second, shorter limit here would cut long tasks early).- if args.timeout_seconds and args.timeout_seconds > 0:- await asyncio.wait_for(consume(), timeout=args.timeout_seconds)- else:- await consume()+ # MCP servers attach on THIS loop so their sync→async tool bridge targets the loop+ # the engine runs on, and close here too (same task — the SDK's transports require+ # enter and exit on one task). Attachment is outside the run's timeout: it is a+ # one-time local connect, and a slow server should not eat the task's clock.+ mcp_manager = (+ await _attach_mcp(engine, mcp_servers, secrets, on_note=_mcp_note)+ if mcp_servers+ else None+ )+ try:+ # timeout_seconds <= 0 disables the run's own limit (an outer runner may enforce+ # its own; a second, shorter limit here would cut long tasks early).+ if args.timeout_seconds and args.timeout_seconds > 0:+ await asyncio.wait_for(consume(), timeout=args.timeout_seconds)+ else:+ await consume()+ finally:+ if mcp_manager is not None:+ await mcp_manager.aclose()try:asyncio.run(guarded())@@ -1405,8 +1525,16 @@ def _write_records("timeout_seconds": args.timeout_seconds,"workspace": str(Path(args.workspace).resolve()),"extra_dirs": [str(Path(r).expanduser().resolve()) for r in (args.add_dir or [])],+ "mcp": bool(args.mcp or args.mcp_config),+ "mcp_config": args.mcp_config,"scripted": bool(args.scripted),},+ # MCP servers attached this run and the tools each exposed, from the attach events.+ "mcp_servers": [+ {"server": e["data"].get("server"), "tools": e["data"].get("tools")}+ for e in events+ if e["type"] == "mcp_server_attached"+ ],"isolation": isolation,# The window and trigger the engine actually used: an unlisted model shows# window null and the fallback trigger.diff --git a/coworker/mcp/__init__.py b/coworker/mcp/__init__.pyindex bfbc8df5..31ba9da9 100644--- a/coworker/mcp/__init__.py+++ b/coworker/mcp/__init__.py@@ -9,6 +9,7 @@ from .client import MCPManagerfrom .config import (MCPServerDef,delete_global_server,+ load_mcp_file,load_mcp_servers,patch_global_server,put_global_server,@@ -20,6 +21,7 @@ __all__ = ["MCPManager","MCPServerDef","load_mcp_servers",+ "load_mcp_file","read_global","put_global_server","patch_global_server",diff --git a/coworker/mcp/config.py b/coworker/mcp/config.pyindex a0c211df..1b0eb323 100644--- a/coworker/mcp/config.py+++ b/coworker/mcp/config.py@@ -109,6 +109,26 @@ def load_mcp_servers(return [_parse(name, raw, secrets) for name, raw in merged.items()]+def load_mcp_file(+ path: str | Path, *, secrets: Optional[SecretStore] = None+) -> list[MCPServerDef]:+ """Parse the `mcpServers` map from ONE explicit JSON file — no global/workspace merge.++ For a caller that points at a specific config rather than this computer's layered one+ (the headless runner's ``--mcp-config``, e.g. a benchmark's own mcp.json). ``${VAR}``+ refs resolve the same way as in ``load_mcp_servers``; a missing or malformed file+ yields no servers. The file is the sole source, so the workspace-trust gate does not+ apply — the caller chose this path explicitly.+ """+ secrets = secrets or SecretStore()+ raw = _read(Path(path).expanduser())+ return [+ _parse(name, cfg, secrets)+ for name, cfg in (raw.get("mcpServers") or {}).items()+ if isinstance(cfg, dict)+ ]++# -- raw global-file mutation (REST) -------------------------------------------def read_global() -> dict[str, dict[str, Any]]:"""Raw `mcpServers` map from the global file (no `${VAR}` resolution)."""diff --git a/tests/test_headless_mcp.py b/tests/test_headless_mcp.pynew file mode 100644index 00000000..e0a4898b--- /dev/null+++ b/tests/test_headless_mcp.py@@ -0,0 +1,128 @@+"""`openworker run --mcp`: the headless runner attaches MCP servers as tools.++End to end with a scripted fake model (no network, no keys) and a REAL stdio MCP server —+a tiny FastMCP `echo` server spawned as a subprocess, so the whole path is exercised:+connect, list tools, register on the live engine, the model calls the tool, the grader-style+result comes back. Run in a subprocess for the same reason as test_headless_run: the runner+redirects OpenWorker's state/scratch folders before the engine is built.+"""++from __future__ import annotations++import json+import os+import subprocess+import sys+import tempfile+from pathlib import Path++ROOT = Path(__file__).resolve().parents[1]++# A minimal stdio MCP server with one tool. Only depends on the `mcp` SDK, so it starts fast.+ECHO_SERVER = """\+from mcp.server.fastmcp import FastMCP++mcp = FastMCP("echo")+++def ping(text: str) -> str:+ return f"pong:{text}"+++if __name__ == "__main__":+ mcp.run()+"""+++def _env() -> dict:+ env = dict(os.environ)+ env["PYTHONPATH"] = str(ROOT) + os.pathsep + env.get("PYTHONPATH", "")+ env.pop("ANTHROPIC_API_KEY", None)+ env.pop("OPENAI_API_KEY", None)+ env.pop("COWORKER_SCRATCH_BASE", None)+ env["COWORKER_STATE_DIR"] = tempfile.mkdtemp(prefix="ow-run-machine-")+ return env+++def _write(path: Path, text: str) -> Path:+ path.parent.mkdir(parents=True, exist_ok=True)+ path.write_text(text, encoding="utf-8")+ return path+++def _run(tmp_path: Path, script: list[dict], servers: dict) -> tuple[subprocess.CompletedProcess, Path]:+ ws = tmp_path / "ws"+ ws.mkdir(exist_ok=True)+ out = tmp_path / "out"+ script_path = _write(tmp_path / "script.json", json.dumps(script))+ mcp_path = _write(tmp_path / "mcp.json", json.dumps({"mcpServers": servers}))+ cmd = [+ sys.executable, "-m", "coworker.cli", "run",+ "--prompt", "Use the echo tool.",+ "--workspace", str(ws), "--model", "anthropic/claude-sonnet-5",+ "--approval-mode", "bypass-approvals", "--out", str(out),+ "--scripted", str(script_path),+ "--mcp-config", str(mcp_path),+ "--isolated", "--timeout-seconds", "120",+ ]+ proc = subprocess.run(cmd, env=_env(), capture_output=True, text=True, timeout=300)+ return proc, out+++def _events(out: Path) -> list[dict]:+ return [+ json.loads(line)+ for line in (out / "events.jsonl").read_text(encoding="utf-8").splitlines()+ if line.strip()+ ]+++def _summary(out: Path) -> dict:+ return json.loads((out / "summary.json").read_text(encoding="utf-8"))+++def test_mcp_tool_attached_and_callable(tmp_path: Path) -> None:+ """A real stdio MCP server's tool is attached and the scripted model calls it; its+ result lands in the record and the run completes."""+ server = _write(tmp_path / "echo_server.py", ECHO_SERVER)+ script = [+ {"text": "Calling echo.", "tool_calls": [{"name": "mcp__echo__ping", "arguments": {"text": "hi"}}]},+ {"text": "Got the result. Done.", "usage": {"input": 100, "output": 20}},+ ]+ proc, out = _run(+ tmp_path,+ script,+ {"echo": {"command": sys.executable, "args": [str(server)], "requires_approval": False}},+ )+ assert proc.returncode == 0, proc.stdout + proc.stderr++ summary = _summary(out)+ assert summary["outcome"] == "completed"+ assert summary["args"]["mcp"] is True+ # The attach is recorded with the server and its tool.+ assert summary["mcp_servers"] == [{"server": "echo", "tools": ["mcp__echo__ping"]}]++ events = _events(out)+ assert any(e["type"] == "mcp_server_attached" and e["data"]["server"] == "echo" for e in events)+ # The tool call ran against the real server and returned the pong.+ finished = [e for e in events if e["type"] == "tool_finished" and e["data"].get("name") == "mcp__echo__ping"]+ assert finished and finished[0]["data"]["status"] == "ok", events+ assert "pong:hi" in (out / "messages.json").read_text(encoding="utf-8")+++def test_mcp_server_failure_is_noted_and_run_continues(tmp_path: Path) -> None:+ """A server that cannot start is noted and skipped; the run still completes."""+ script = [{"text": "Nothing to do. Done.", "usage": {"input": 100, "output": 20}}]+ proc, out = _run(+ tmp_path,+ script,+ {"nope": {"command": "ow-no-such-command-xyz", "args": [], "requires_approval": False}},+ )+ assert proc.returncode == 0, proc.stdout + proc.stderr++ summary = _summary(out)+ assert summary["outcome"] == "completed"+ assert summary["mcp_servers"] == [] # nothing attached+ events = _events(out)+ assert any(e["type"] == "mcp_server_failed" and e["data"]["server"] == "nope" for e in events)