Skip to content

Business operating system for Claude Code — 57 skills, 21 agents, smart daemon. Unified inbox (WhatsApp/Email/Slack/Telegram), autonomous PR merge, full-AWS monitoring, revenue (Stripe+RevenueCat), e-commerce (Shopify), marketing (Klaviyo/Meta/GA4), voice (Bland/ElevenLabs), APM (Datadog/NewRelic/OTEL), YOLO mode.

21.4 KB
Raw Blame
#!/usr/bin/env python3
"""desktop-act stdio CLI — call the MCP server without an MCP host.

Use this from shell scripts, CI, or other agents when you need
status / acquire / screenshot / act / release over JSON-RPC stdio.

Path resolution (first match wins):

  1. ``DESKTOP_ACT_COMMAND`` — executable that starts the server (e.g. run.sh)
  2. ``DESKTOP_ACT_HOME`` — install root; uses ``$DESKTOP_ACT_HOME/mcp-server/run.sh``
     or ``server.py`` with ``$DESKTOP_ACT_VENV/bin/python``
  3. This repo checkout — ``<repo>/mcp-server/run.sh`` next to this file
  4. ``$XDG_CACHE_HOME/desktop-act-mcp/src`` (Linux) or
     ``~/Library/Caches/desktop-act-mcp/src`` (macOS)

No host-specific paths are hard-coded. Override with env vars as needed.

Examples::

  desktop-act status
  desktop-act acquire
  desktop-act screenshot --session-id SID
  desktop-act act --goal "Open a browser and go to example.com"
  desktop-act run --goal "Take a screenshot of the desktop"
  desktop-act call list_windows --arg session_id=SID
  desktop-act release --session-id SID
"""

from __future__ import annotations

import argparse
import json
import os
import platform
import subprocess
import sys
import time
from pathlib import Path
from typing import Any

# ─── discovery ───────────────────────────────────────────────────────────────


def _cache_src() -> Path:
    system = platform.system().lower()
    if system == "darwin":
        return Path.home() / "Library" / "Caches" / "desktop-act-mcp" / "src"
    base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
    return Path(base) / "desktop-act-mcp" / "src"


def _repo_root() -> Path:
    """cli/ lives one level under the repo root."""
    return Path(__file__).resolve().parent.parent


def resolve_server_cmd() -> list[str]:
    """Return argv that launches the desktop-act MCP server on stdio."""
    # 1. Explicit command (may be a multi-word string)
    explicit = (os.environ.get("DESKTOP_ACT_COMMAND") or "").strip()
    if explicit:
        # Allow "python /path/server.py" or a single run.sh path
        parts = explicit.split()
        if len(parts) == 1 and Path(parts[0]).is_file():
            return parts
        if len(parts) >= 2:
            return parts
        if Path(parts[0]).exists():
            return parts

    candidates: list[Path] = []
    home = (os.environ.get("DESKTOP_ACT_HOME") or "").strip()
    if home:
        candidates.append(Path(home))
    candidates.append(_repo_root())
    candidates.append(_cache_src())

    venv = (os.environ.get("DESKTOP_ACT_VENV") or "").strip()
    py_override = (os.environ.get("DESKTOP_ACT_PYTHON") or "").strip()

    for root in candidates:
        if not root.is_dir():
            continue
        run_sh = root / "mcp-server" / "run.sh"
        server_py = root / "mcp-server" / "server.py"
        if run_sh.is_file() and os.access(run_sh, os.X_OK):
            return [str(run_sh)]
        if server_py.is_file():
            venv_root = Path(venv) if venv else root / ".venv"
            py = Path(py_override) if py_override else venv_root / "bin" / "python"
            if not py.is_file():
                py = Path(py_override or sys.executable)
            return [str(py), str(server_py)]

    raise FileNotFoundError(
        "desktop-act server not found. Set DESKTOP_ACT_HOME or DESKTOP_ACT_COMMAND, "
        "or run this CLI from a full checkout (mcp-server/run.sh present)."
    )


# ─── MCP client ──────────────────────────────────────────────────────────────


class McpClient:
    """Minimal JSON-RPC-over-stdio MCP client (initialize + tools/call)."""

    def __init__(self, cmd: list[str], env: dict[str, str] | None = None, timeout: float = 120.0):
        self.timeout = timeout
        merged = os.environ.copy()
        if env:
            merged.update(env)
        # Inherit stderr so server INFO logs do not fill a PIPE and deadlock act/run.
        # stdout stays piped for JSON-RPC; stderr is diagnostic only.
        self.proc = subprocess.Popen(
            cmd,
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=None,
            text=True,
            env=merged,
            bufsize=1,
        )
        self._id = 0

    def _send(self, method: str, params: dict | None = None, *, notify: bool = False) -> Any:
        self._id += 1
        msg: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
        if not notify:
            msg["id"] = self._id
        if params is not None:
            msg["params"] = params
        if not self.proc.stdin or not self.proc.stdout:
            raise RuntimeError("MCP process has no stdio")
        self.proc.stdin.write(json.dumps(msg) + "\n")
        self.proc.stdin.flush()
        if notify:
            return None
        deadline = time.time() + self.timeout
        while time.time() < deadline:
            line = self.proc.stdout.readline()
            if not line:
                rc = self.proc.poll()
                raise RuntimeError(
                    f"MCP EOF while waiting for {method}"
                    + (f" (exit {rc})" if rc is not None else "")
                )
            line = line.strip()
            if not line.startswith("{"):
                continue
            try:
                obj = json.loads(line)
            except json.JSONDecodeError:
                continue
            if obj.get("id") != self._id:
                continue
            if "error" in obj:
                raise RuntimeError(json.dumps(obj["error"])[:500])
            return obj.get("result")
        raise TimeoutError(f"timeout waiting for {method}")

    def initialize(self) -> None:
        self._send(
            "initialize",
            {
                "protocolVersion": "2024-11-05",
                "capabilities": {},
                "clientInfo": {"name": "desktop-act-cli", "version": "1.0.0"},
            },
        )
        self._send("notifications/initialized", notify=True)

    def call_tool(self, name: str, arguments: dict | None = None) -> Any:
        return self._send("tools/call", {"name": name, "arguments": arguments or {}})

    def close(self) -> None:
        try:
            if self.proc.poll() is None:
                self.proc.terminate()
                try:
                    self.proc.wait(timeout=3)
                except subprocess.TimeoutExpired:
                    self.proc.kill()
        except Exception:
            pass


def unwrap_tool_result(result: Any) -> Any:
    """Normalize FastMCP / MCP tool result envelopes to a plain value."""
    if not isinstance(result, dict):
        return result
    if "structuredContent" in result and result["structuredContent"] is not None:
        return result["structuredContent"]
    content = result.get("content")
    if isinstance(content, list) and content:
        texts = [
            c.get("text", "") for c in content if isinstance(c, dict) and c.get("type") == "text"
        ]
        joined = "\n".join(t for t in texts if t)
        if joined.strip().startswith("{") or joined.strip().startswith("["):
            try:
                return json.loads(joined)
            except json.JSONDecodeError:
                pass
        if joined:
            return {"text": joined}
    # already a plain dict from some servers
    if "ok" in result or "session_id" in result or "error" in result:
        return result
    return result


def emit(data: Any) -> None:
    if isinstance(data, (dict, list)):
        print(json.dumps(data, indent=2, default=str))
    else:
        print(data)


# ─── commands ────────────────────────────────────────────────────────────────


def _client_from_args(args: argparse.Namespace) -> McpClient:
    cmd = resolve_server_cmd()
    env: dict[str, str] = {}
    if getattr(args, "display", None):
        env["DISPLAY"] = args.display
        env.setdefault("DESKTOP_ACT_DISPLAY", args.display)
    # CLI is short-lived; do not free pool desktops when the stdio server exits.
    # Long-lived MCP hosts keep default RELEASE_ON_EXIT=1.
    env.setdefault("DESKTOP_ACT_RELEASE_ON_EXIT", "0")
    if getattr(args, "owner_id", None):
        env.setdefault("DESKTOP_ACT_OWNER", args.owner_id)
    if getattr(args, "geometry", None):
        env.setdefault("DESKTOP_ACT_GEOMETRY", args.geometry)
    timeout = float(getattr(args, "rpc_timeout", 120) or 120)
    client = McpClient(cmd, env=env or None, timeout=timeout)
    try:
        client.initialize()
    except Exception:
        client.close()
        raise
    return client


def cmd_status(args: argparse.Namespace) -> int:
    client = _client_from_args(args)
    try:
        emit(unwrap_tool_result(client.call_tool("status", {})))
        return 0
    finally:
        client.close()


def cmd_list(args: argparse.Namespace) -> int:
    client = _client_from_args(args)
    try:
        emit(unwrap_tool_result(client.call_tool("list_desktops", {})))
        return 0
    finally:
        client.close()


def cmd_acquire(args: argparse.Namespace) -> int:
    client = _client_from_args(args)
    try:
        params: dict[str, Any] = {}
        if getattr(args, "geometry", None):
            params["geometry"] = args.geometry
        if getattr(args, "owner_id", None):
            params["owner_id"] = args.owner_id
        if getattr(args, "force_new", False):
            params["force_new"] = True
        out = unwrap_tool_result(client.call_tool("acquire_desktop", params))
        emit(out)
        return 0
    finally:
        client.close()


def cmd_ensure(args: argparse.Namespace) -> int:
    """Multi-agent entry: reuse own lease or auto-spawn if busy."""
    client = _client_from_args(args)
    try:
        params: dict[str, Any] = {}
        if getattr(args, "geometry", None):
            params["geometry"] = args.geometry
        if getattr(args, "owner_id", None):
            params["owner_id"] = args.owner_id
        out = unwrap_tool_result(client.call_tool("ensure_desktop", params))
        emit(out)
        return 0 if not (isinstance(out, dict) and out.get("ok") is False) else 1
    finally:
        client.close()


def cmd_heartbeat(args: argparse.Namespace) -> int:
    if not args.session_id:
        print("error: --session-id required", file=sys.stderr)
        return 2
    client = _client_from_args(args)
    try:
        params: dict[str, Any] = {"session_id": args.session_id}
        if getattr(args, "owner_id", None):
            params["owner_id"] = args.owner_id
        out = unwrap_tool_result(client.call_tool("heartbeat_desktop", params))
        emit(out)
        return 0 if not (isinstance(out, dict) and out.get("ok") is False) else 1
    finally:
        client.close()


def cmd_reap(args: argparse.Namespace) -> int:
    client = _client_from_args(args)
    try:
        out = unwrap_tool_result(client.call_tool("reap_idle_desktops", {}))
        emit(out)
        return 0
    finally:
        client.close()


def cmd_release(args: argparse.Namespace) -> int:
    if not args.session_id:
        print("error: --session-id required", file=sys.stderr)
        return 2
    client = _client_from_args(args)
    try:
        emit(
            unwrap_tool_result(client.call_tool("release_desktop", {"session_id": args.session_id}))
        )
        return 0
    finally:
        client.close()


def cmd_screenshot(args: argparse.Namespace) -> int:
    client = _client_from_args(args)
    try:
        params: dict[str, Any] = {}
        if args.session_id:
            params["session_id"] = args.session_id
        if args.fmt:
            params["fmt"] = args.fmt
        emit(unwrap_tool_result(client.call_tool("screenshot", params)))
        return 0
    finally:
        client.close()


def cmd_observe(args: argparse.Namespace) -> int:
    client = _client_from_args(args)
    try:
        params: dict[str, Any] = {}
        if args.session_id:
            params["session_id"] = args.session_id
        emit(unwrap_tool_result(client.call_tool("observe", params)))
        return 0
    finally:
        client.close()


def cmd_act(args: argparse.Namespace) -> int:
    if not args.goal:
        print("error: --goal required", file=sys.stderr)
        return 2
    client = _client_from_args(args)
    # act() can run for a long time — raise RPC wait
    client.timeout = float(args.timeout) + 30
    try:
        params: dict[str, Any] = {
            "goal": args.goal,
            "max_iterations": args.max_iterations,
            "timeout_seconds": args.timeout,
        }
        if args.session_id:
            params["session_id"] = args.session_id
        if args.model:
            params["model"] = args.model
        result = unwrap_tool_result(client.call_tool("act", params))
        emit(result)
        if isinstance(result, dict) and result.get("ok") is False:
            return 1
        return 0
    finally:
        client.close()


def cmd_run(args: argparse.Namespace) -> int:
    """Acquire -> act(goal) -> release. Exit 0 only if act reports ok."""
    if not args.goal:
        print("error: --goal required", file=sys.stderr)
        return 2
    client = _client_from_args(args)
    client.timeout = float(args.timeout) + 30
    session_id = args.session_id or ""
    acquired = False
    try:
        if not session_id:
            acq_params: dict[str, Any] = {}
            if getattr(args, "owner_id", None):
                acq_params["owner_id"] = args.owner_id
            if getattr(args, "geometry", None):
                acq_params["geometry"] = args.geometry
            acq = unwrap_tool_result(client.call_tool("ensure_desktop", acq_params))
            emit({"phase": "ensure", "result": acq})
            if isinstance(acq, dict):
                session_id = acq.get("session_id") or acq.get("id") or ""
            acquired = bool(session_id)

        try:
            shot = unwrap_tool_result(
                client.call_tool("screenshot", {"session_id": session_id} if session_id else {})
            )
            emit({"phase": "screenshot", "result": shot})
        except Exception as exc:  # noqa: BLE001
            emit({"phase": "screenshot", "warn": str(exc)})

        params: dict[str, Any] = {
            "goal": args.goal,
            "max_iterations": args.max_iterations,
            "timeout_seconds": args.timeout,
        }
        if session_id:
            params["session_id"] = session_id
        if args.model:
            params["model"] = args.model
        result = unwrap_tool_result(client.call_tool("act", params))
        emit({"phase": "act", "result": result})
        ok = True
        if isinstance(result, dict):
            if result.get("ok") is False:
                ok = False
            elif result.get("error") and not result.get("ok"):
                ok = False
        return 0 if ok else 1
    except Exception as exc:  # noqa: BLE001
        print(json.dumps({"ok": False, "error": str(exc)}), file=sys.stderr)
        return 2
    finally:
        if acquired and session_id:
            try:
                client.call_tool("release_desktop", {"session_id": session_id})
            except Exception:
                pass
        client.close()


def cmd_call(args: argparse.Namespace) -> int:
    """Raw tools/call for any server tool."""
    tool_args: dict[str, Any] = {}
    for item in args.arg or []:
        if "=" not in item:
            print(f"error: --arg expects key=value, got {item!r}", file=sys.stderr)
            return 2
        key, raw = item.split("=", 1)
        # try JSON coerce
        try:
            tool_args[key] = json.loads(raw)
        except json.JSONDecodeError:
            tool_args[key] = raw
    client = _client_from_args(args)
    client.timeout = float(getattr(args, "timeout", 120) or 120)
    try:
        emit(unwrap_tool_result(client.call_tool(args.tool, tool_args)))
        return 0
    finally:
        client.close()


def cmd_which(args: argparse.Namespace) -> int:
    """Print resolved server command (debug / smoke)."""
    try:
        cmd = resolve_server_cmd()
        emit({"ok": True, "command": cmd})
        return 0
    except FileNotFoundError as exc:
        emit({"ok": False, "error": str(exc)})
        return 1


# ─── argparse ────────────────────────────────────────────────────────────────


def _add_common(p: argparse.ArgumentParser) -> None:
    p.add_argument(
        "--display",
        default=os.environ.get("DISPLAY") or os.environ.get("DESKTOP_ACT_DISPLAY") or None,
        help="X11 DISPLAY to pass through (Linux). Default: $DISPLAY or $DESKTOP_ACT_DISPLAY",
    )
    p.add_argument(
        "--rpc-timeout",
        type=float,
        default=float(os.environ.get("DESKTOP_ACT_RPC_TIMEOUT", "120")),
        help="Seconds to wait for a single MCP response (default 120)",
    )


def _add_session(p: argparse.ArgumentParser, required: bool = False) -> None:
    p.add_argument("--session-id", default="", required=required, help="Pool session id")


def _add_owner(p: argparse.ArgumentParser) -> None:
    p.add_argument(
        "--owner-id",
        default=os.environ.get("DESKTOP_ACT_OWNER") or "",
        help="Exclusive lease owner (default: $DESKTOP_ACT_OWNER or process id)",
    )
    p.add_argument(
        "--geometry",
        default=os.environ.get("DESKTOP_ACT_GEOMETRY") or "",
        help="Desktop geometry e.g. 2560x1440 (default server/env)",
    )


def _add_act_opts(p: argparse.ArgumentParser) -> None:
    p.add_argument("--goal", default="", help="Natural-language goal for act()")
    p.add_argument(
        "--max-iterations",
        type=int,
        default=int(os.environ.get("DESKTOP_ACT_MAX_ITERATIONS", "20")),
        help="act() max_iterations (server param name; not max_steps)",
    )
    p.add_argument(
        "--timeout",
        type=int,
        default=int(os.environ.get("DESKTOP_ACT_ACT_TIMEOUT", "600")),
        help="act() timeout_seconds wall clock",
    )
    p.add_argument(
        "--model",
        default=os.environ.get("DESKTOP_ACT_MODEL") or "",
        help="Optional model id for act()",
    )


def build_parser() -> argparse.ArgumentParser:
    ap = argparse.ArgumentParser(
        prog="desktop-act",
        description="Call desktop-act MCP tools over stdio without an MCP host.",
    )
    sub = ap.add_subparsers(dest="command", required=True)

    p = sub.add_parser("which", help="Print resolved server launch command")
    _add_common(p)
    p.set_defaults(func=cmd_which)

    p = sub.add_parser("status", help="Pool + binary inventory")
    _add_common(p)
    p.set_defaults(func=cmd_status)

    p = sub.add_parser("list", help="List pool desktops")
    _add_common(p)
    p.set_defaults(func=cmd_list)

    p = sub.add_parser(
        "ensure",
        help="Multi-agent: reuse own lease or auto-spawn if another agent holds a desktop",
    )
    _add_common(p)
    _add_owner(p)
    p.set_defaults(func=cmd_ensure)

    p = sub.add_parser(
        "acquire", help="Acquire a desktop (ensure by default; --force-new always spawns)"
    )
    _add_common(p)
    _add_owner(p)
    p.add_argument(
        "--force-new",
        action="store_true",
        help="Always spawn a fresh exclusive desktop",
    )
    p.set_defaults(func=cmd_acquire)

    p = sub.add_parser(
        "heartbeat", help="Refresh lease TTL so idle reaper will not free the session"
    )
    _add_common(p)
    _add_session(p, required=True)
    _add_owner(p)
    p.set_defaults(func=cmd_heartbeat)

    p = sub.add_parser("reap", help="Free locks + stop VNC for idle/dead pool sessions")
    _add_common(p)
    p.set_defaults(func=cmd_reap)

    p = sub.add_parser("release", help="Release a session (free lock + stop pool VNC)")
    _add_common(p)
    _add_session(p, required=True)
    p.set_defaults(func=cmd_release)

    p = sub.add_parser("screenshot", help="Capture a screenshot")
    _add_common(p)
    _add_session(p)
    p.add_argument("--fmt", default="jpeg", choices=("jpeg", "png"))
    p.set_defaults(func=cmd_screenshot)

    p = sub.add_parser("observe", help="Screenshot + window list")
    _add_common(p)
    _add_session(p)
    p.set_defaults(func=cmd_observe)

    p = sub.add_parser("act", help="Run autonomous act() on an existing or default session")
    _add_common(p)
    _add_session(p)
    _add_act_opts(p)
    p.set_defaults(func=cmd_act)

    p = sub.add_parser(
        "run",
        help="Ensure desktop -> screenshot -> act(goal) -> release (one-shot goal loop)",
    )
    _add_common(p)
    _add_session(p)
    _add_owner(p)
    _add_act_opts(p)
    p.set_defaults(func=cmd_run)

    p = sub.add_parser("call", help="Raw tools/call by name")
    _add_common(p)
    p.add_argument("tool", help="MCP tool name, e.g. list_windows")
    p.add_argument(
        "--arg",
        action="append",
        default=[],
        help="Tool arg key=value (value JSON-parsed when possible). Repeatable.",
    )
    p.add_argument(
        "--timeout",
        type=float,
        default=120.0,
        help="RPC wait seconds for this call",
    )
    p.set_defaults(func=cmd_call)

    return ap


def main(argv: list[str] | None = None) -> int:
    parser = build_parser()
    args = parser.parse_args(argv)
    return int(args.func(args))


if __name__ == "__main__":
    sys.exit(main())