pyqt-runtime-mcp 0.1.0__py3-none-any.whl

pyqt_runtime_mcp/__init__.py

@@ -0,0 +1,18 @@
+"""Reusable PyQt5 runtime MCP bridge and server.
+
+Importing this package does not import PyQt5. The in-app bridge is loaded
+lazily so the Cursor MCP stdio process can run without Qt.
+"""
+
+from typing import Any
+
+__all__ = ["PyQtMCPBridge", "install_pyqt_mcp"]
+__version__ = "0.1.0"
+
+
+def __getattr__(name: str) -> Any:
+    if name in {"PyQtMCPBridge", "install_pyqt_mcp"}:
+        from pyqt_runtime_mcp.bridge.bridge import PyQtMCPBridge, install_pyqt_mcp
+
+        return PyQtMCPBridge if name == "PyQtMCPBridge" else install_pyqt_mcp
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

pyqt_runtime_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m pyqt_runtime_mcp` to start the MCP stdio server."""
+
+from pyqt_runtime_mcp.server import main
+
+if __name__ == "__main__":
+    main()

pyqt_runtime_mcp/bridge/__init__.py

@@ -0,0 +1,5 @@
+"""In-app PyQt5 runtime bridge."""
+
+from pyqt_runtime_mcp.bridge.bridge import PyQtMCPBridge, install_pyqt_mcp
+
+__all__ = ["PyQtMCPBridge", "install_pyqt_mcp"]

pyqt_runtime_mcp/bridge/bridge.py

@@ -0,0 +1,381 @@
+"""In-app PyQt5 runtime bridge: TCP server + GUI dispatcher + widget registry."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import socket
+import threading
+from pathlib import Path
+from typing import Any, Optional
+
+from PyQt5.QtCore import QObject
+from PyQt5.QtWidgets import QApplication
+
+from pyqt_runtime_mcp.bridge.dispatcher import GuiDispatcher
+from pyqt_runtime_mcp.bridge.logging import (
+    ExceptionCapture,
+    PythonLogCapture,
+    QtLogCapture,
+    RingBuffer,
+)
+from pyqt_runtime_mcp.bridge.registry import WidgetRegistry
+from pyqt_runtime_mcp.bridge.router import register_handlers
+from pyqt_runtime_mcp.protocol.errors import BridgeError
+from pyqt_runtime_mcp.protocol.messages import (
+    DEFAULT_HOST,
+    DEFAULT_PORT,
+    PROTOCOL_NAME,
+    Handshake,
+    Request,
+    Response,
+)
+from pyqt_runtime_mcp.protocol.transport import (
+    StreamClosed,
+    StreamCorrupted,
+    discovery_path,
+    recv_json,
+    send_json,
+)
+
+_LOG = logging.getLogger("pyqt_runtime_mcp.bridge")
+_INSTALLED: Optional["PyQtMCPBridge"] = None
+SCREENSHOT_TIMEOUT = 15.0
+DEFAULT_TIMEOUT = 10.0
+MAX_TIMEOUT = 120.0
+# Answer a little before the client's own deadline, so a slow handler produces a
+# TIMEOUT reply on this connection instead of an unread frame the client would
+# later mistake for the next response.
+DEADLINE_MARGIN = 0.5
+HEAVY_METHODS = frozenset(
+    {
+        "get_widget_tree",
+        "find_widgets",
+        "get_ui_snapshot",
+        "visual_snapshot",
+        "analyze_layout",
+        "capture_window",
+        "capture_widget",
+        "capture_region",
+        "capture_screen_region",
+        "capture_sections",
+    }
+)
+# Poll interval while idle; connections are kept open across it.
+IDLE_POLL = 1.0
+
+
+class BridgeContext:
+    __slots__ = (
+        "app",
+        "registry",
+        "screenshot_dir",
+        "logs",
+        "exceptions",
+        "events",
+        "signal_events",
+        "signal_watches",
+        "overlay",
+        "token",
+    )
+
+    def __init__(self, app: QApplication, screenshot_dir: Path, token: Optional[str]) -> None:
+        self.app = app
+        self.registry = WidgetRegistry()
+        self.screenshot_dir = screenshot_dir
+        self.logs = RingBuffer()
+        self.exceptions = RingBuffer()
+        self.events = RingBuffer()
+        self.signal_events = RingBuffer()
+        self.signal_watches: dict[str, list] = {}
+        self.overlay = None
+        self.token = token
+
+
+class PyQtMCPBridge(QObject):
+    def __init__(
+        self,
+        app: QApplication,
+        host: str = DEFAULT_HOST,
+        port: int = DEFAULT_PORT,
+        token: Optional[str] = None,
+        screenshot_dir: Optional[str] = None,
+        parent: Optional[QObject] = None,
+    ) -> None:
+        super().__init__(parent if parent is not None else app)
+        if app is None:
+            raise BridgeError("APPLICATION_NOT_CONNECTED", "QApplication is required")
+        if host not in {"127.0.0.1", "localhost", "::1"}:
+            raise BridgeError("INVALID_ARGUMENT", "Bridge must bind to localhost")
+        self._app = app
+        self._host = "127.0.0.1" if host == "localhost" else host
+        self._requested_port = int(port)
+        self._port = int(port)
+        self._token = token or os.environ.get("PYQT_MCP_TOKEN") or None
+        sandbox = screenshot_dir or os.environ.get("PYQT_MCP_SCREENSHOT_DIR")
+        if sandbox:
+            self._screenshot_dir = Path(sandbox)
+        else:
+            self._screenshot_dir = discovery_path().parent / "screenshots"
+        self._screenshot_dir.mkdir(parents=True, exist_ok=True)
+        self._ctx = BridgeContext(app, self._screenshot_dir, self._token)
+        self._dispatcher = GuiDispatcher(parent=self)
+        register_handlers(self._dispatcher, self._ctx)
+        self._qt_logs = QtLogCapture(self._ctx.logs)
+        self._py_logs = PythonLogCapture(self._ctx.logs)
+        self._exc = ExceptionCapture(self._ctx.exceptions)
+        self._sock: Optional[socket.socket] = None
+        self._thread: Optional[threading.Thread] = None
+        self._stop = threading.Event()
+        self._clients: list[socket.socket] = []
+        self._clients_lock = threading.Lock()
+
+    @property
+    def port(self) -> int:
+        return self._port
+
+    @property
+    def host(self) -> str:
+        return self._host
+
+    @property
+    def context(self) -> BridgeContext:
+        return self._ctx
+
+    def start(self) -> "PyQtMCPBridge":
+        if self._thread is not None:
+            return self
+        self._qt_logs.install()
+        self._py_logs.install()
+        self._exc.install()
+        self._sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self._sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        bound = False
+        last_err: Optional[OSError] = None
+        start_port = self._requested_port
+        attempts = [0] if start_port == 0 else list(range(start_port, start_port + 21))
+        for candidate in attempts:
+            try:
+                self._sock.bind((self._host, candidate))
+                self._port = int(self._sock.getsockname()[1])
+                bound = True
+                break
+            except OSError as exc:
+                last_err = exc
+                continue
+        if not bound:
+            raise BridgeError(
+                "INVALID_ARGUMENT",
+                f"Could not bind {self._host}:{start_port}: {last_err}",
+            )
+        self._sock.listen(8)
+        self._sock.settimeout(0.5)
+        self._write_discovery()
+        self._stop.clear()
+        self._thread = threading.Thread(target=self._accept_loop, name="pyqt-mcp-bridge", daemon=True)
+        self._thread.start()
+        _LOG.info("PyQt MCP bridge listening on %s:%s", self._host, self._port)
+        return self
+
+    def stop(self) -> None:
+        self._stop.set()
+        with self._clients_lock:
+            clients = list(self._clients)
+            self._clients.clear()
+        for client in clients:
+            try:
+                client.close()
+            except OSError:
+                pass
+        if self._sock is not None:
+            try:
+                self._sock.close()
+            except OSError:
+                pass
+            self._sock = None
+        if self._thread is not None and self._thread.is_alive() and threading.current_thread() is not self._thread:
+            self._thread.join(timeout=2.0)
+        self._thread = None
+        self._qt_logs.uninstall()
+        self._py_logs.uninstall()
+        self._exc.uninstall()
+        from pyqt_runtime_mcp.bridge.overlay import hide_overlay
+
+        hide_overlay(self._ctx)
+        _remove_discovery()
+        global _INSTALLED
+        if _INSTALLED is self:
+            _INSTALLED = None
+
+    def _write_discovery(self) -> None:
+        path = discovery_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "protocol": PROTOCOL_NAME,
+            "host": self._host,
+            "port": self._port,
+            "pid": os.getpid(),
+            "token_required": bool(self._token),
+        }
+        path.write_text(json.dumps(payload), encoding="utf-8")
+
+    def _accept_loop(self) -> None:
+        while not self._stop.is_set():
+            sock = self._sock
+            if sock is None:
+                break
+            try:
+                client, _addr = sock.accept()
+            except socket.timeout:
+                continue
+            except OSError:
+                if self._stop.is_set():
+                    break
+                continue
+            worker = threading.Thread(target=self._client_loop, args=(client,), daemon=True)
+            worker.start()
+
+    def _client_loop(self, client: socket.socket) -> None:
+        with self._clients_lock:
+            self._clients.append(client)
+        try:
+            client.settimeout(30.0)
+            raw = recv_json(client)
+            try:
+                handshake = Handshake.from_dict(raw)
+            except BridgeError as exc:
+                send_json(client, {"ok": False, "error": exc.to_dict()})
+                return
+            if handshake.protocol != PROTOCOL_NAME:
+                send_json(
+                    client,
+                    {
+                        "ok": False,
+                        "error": {
+                            "code": "PROTOCOL_ERROR",
+                            "message": f"Unsupported protocol {handshake.protocol!r}",
+                        },
+                    },
+                )
+                return
+            if self._token and handshake.token != self._token:
+                send_json(
+                    client,
+                    {
+                        "ok": False,
+                        "error": {
+                            "code": "AUTHENTICATION_FAILED",
+                            "message": "Invalid or missing token",
+                        },
+                    },
+                )
+                return
+            send_json(client, {"ok": True, "protocol": PROTOCOL_NAME, "port": self._port})
+            client.settimeout(IDLE_POLL)
+            while not self._stop.is_set():
+                try:
+                    message = recv_json(client)
+                except socket.timeout:
+                    continue  # idle connections stay open
+                except StreamClosed:
+                    break
+                except StreamCorrupted as exc:
+                    # Framing cannot be resynchronised; report once and hang up.
+                    _LOG.warning("Dropping client after framing error: %s", exc.message)
+                    self._send(client, Response(id="", ok=False, error=exc.to_dict()).to_dict())
+                    break
+                except BridgeError as exc:
+                    if not self._send(client, Response(id="", ok=False, error=exc.to_dict()).to_dict()):
+                        break
+                    continue
+                except OSError:
+                    break
+                if not self._handle_request(client, message):
+                    break
+        except (StreamClosed, OSError):
+            pass
+        except BridgeError as exc:
+            _LOG.warning("Bridge client aborted: %s", exc.message)
+        finally:
+            try:
+                client.close()
+            except OSError:
+                pass
+            with self._clients_lock:
+                if client in self._clients:
+                    self._clients.remove(client)
+
+    def _handle_request(self, client: socket.socket, message: Any) -> bool:
+        """Serve one request. Returns False when the connection must be closed."""
+        try:
+            request = Request.from_dict(message)
+        except BridgeError as exc:
+            return self._send(client, Response(id="", ok=False, error=exc.to_dict()).to_dict())
+        try:
+            result = self._dispatcher.submit(
+                request.method, request.params, timeout=_gui_timeout(request)
+            )
+            response = Response(id=request.id, ok=True, result=result)
+        except BridgeError as exc:
+            response = Response(id=request.id, ok=False, error=exc.to_dict())
+        except Exception as exc:  # never let one bad handler kill the connection
+            _LOG.exception("Unhandled error in %s", request.method)
+            error = BridgeError("GUI_THREAD_ERROR", f"{type(exc).__name__}: {exc}")
+            response = Response(id=request.id, ok=False, error=error.to_dict())
+        payload = response.to_dict()
+        try:
+            return self._send(client, payload)
+        except BridgeError as exc:
+            # Result could not be encoded (too large, or not JSON-serialisable).
+            return self._send(client, Response(id=request.id, ok=False, error=exc.to_dict()).to_dict())
+
+    def _send(self, client: socket.socket, payload: dict[str, Any]) -> bool:
+        try:
+            send_json(client, payload)
+        except OSError:
+            return False
+        return True
+
+
+def _gui_timeout(request: Request) -> float:
+    """GUI budget for one request, kept just inside the client's own deadline."""
+    default = SCREENSHOT_TIMEOUT if request.method in HEAVY_METHODS else DEFAULT_TIMEOUT
+    budget = request.timeout if request.timeout is not None else default
+    extra = request.params.get("timeout")
+    if isinstance(extra, (int, float)) and extra > 0:
+        budget = float(extra)
+    budget = min(float(budget), MAX_TIMEOUT)
+    return max(budget - DEADLINE_MARGIN, 0.5)
+
+
+def install_pyqt_mcp(
+    app: QApplication,
+    host: str = DEFAULT_HOST,
+    port: int = DEFAULT_PORT,
+    token: Optional[str] = None,
+    screenshot_dir: Optional[str] = None,
+) -> PyQtMCPBridge:
+    """Start the in-process runtime bridge. Bind is localhost-only."""
+    global _INSTALLED
+    if _INSTALLED is not None:
+        return _INSTALLED
+    bridge = PyQtMCPBridge(
+        app,
+        host=host,
+        port=port,
+        token=token,
+        screenshot_dir=screenshot_dir,
+    )
+    bridge.start()
+    app.aboutToQuit.connect(bridge.stop)
+    _INSTALLED = bridge
+    return bridge
+
+
+def _remove_discovery() -> None:
+    path = discovery_path()
+    try:
+        path.unlink()
+    except OSError:
+        pass

pyqt_runtime_mcp/bridge/diagnostics.py

@@ -0,0 +1,248 @@
+"""Heuristic layout diagnostics. Unusual is not always a bug."""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import TYPE_CHECKING, Any
+
+from PyQt5.QtWidgets import (
+    QAbstractScrollArea,
+    QAbstractSpinBox,
+    QComboBox,
+    QHeaderView,
+    QMenu,
+    QMenuBar,
+    QSizePolicy,
+    QTabBar,
+    QToolBar,
+    QWidget,
+)
+
+from pyqt_runtime_mcp.bridge.qtutil import is_deleted, widget_class_name
+from pyqt_runtime_mcp.bridge.registry import iter_widgets
+
+if TYPE_CHECKING:
+    from pyqt_runtime_mcp.bridge.bridge import BridgeContext
+
+HUGE_MIN = 2000
+MIN_HINT_SLACK = 8
+
+# Widgets that position their own children without a QLayout. Reporting a
+# "missing layout" on these is always a false positive.
+SELF_MANAGED = (
+    QAbstractScrollArea,
+    QAbstractSpinBox,
+    QComboBox,
+    QHeaderView,
+    QMenu,
+    QMenuBar,
+    QTabBar,
+    QToolBar,
+)
+
+
+def analyze_layout(ctx: "BridgeContext", params: dict[str, Any]) -> dict[str, Any]:
+    root_spec = params.get("widget_id") or params.get("root")
+    root = ctx.registry.resolve_scoped(str(root_spec), params.get("window")) if root_spec else None
+    findings: list[dict[str, Any]] = []
+    names: Counter[str] = Counter()
+    widgets = list(iter_widgets(root))
+    for widget in widgets:
+        if is_deleted(widget):
+            continue
+        rid = ctx.registry.ensure(widget)
+        name = widget.objectName() or ""
+        if name and widget.isVisible() and not _is_internal(widget):
+            # Only visible duplicates matter: they are what makes a name-based
+            # lookup ambiguous. Hidden dialogs legitimately reuse names.
+            names[name] += 1
+        _outside_parent(findings, widget, rid)
+        _zero_size(findings, widget, rid)
+        _clipped(findings, widget, rid)
+        _below_min_hint(findings, widget, rid)
+        _minmax(findings, widget, rid)
+        _fixed_size(findings, widget, rid)
+        _invisible_in_layout(findings, widget, rid)
+        _missing_layout(findings, widget, rid)
+    _overlapping_siblings(ctx, findings, widgets)
+    for name, count in names.items():
+        if count > 1:
+            findings.append(
+                {
+                    "severity": "info",
+                    "widget": None,
+                    "message": (
+                        f"Duplicate objectName {name!r} appears on {count} visible widgets; "
+                        "scope lookups with window=<window id>"
+                    ),
+                }
+            )
+    return {"findings": findings, "widget_count": len(widgets)}
+
+
+def _finding(severity: str, rid: str, message: str) -> dict[str, Any]:
+    return {"severity": severity, "widget": rid, "message": message}
+
+
+def _is_internal(widget: QWidget) -> bool:
+    """Qt names its own helper children (viewports, scrollbars, popups) qt_*."""
+    return (widget.objectName() or "").startswith("qt_")
+
+
+def _below_min_hint(findings: list, widget: QWidget, rid: str) -> None:
+    """Rendered smaller than Qt says it needs, i.e. its content is clipped."""
+    if not widget.isVisible() or widget.isWindow() or _is_internal(widget):
+        return
+    policy = widget.sizePolicy()
+    if QSizePolicy.Ignored in (policy.horizontalPolicy(), policy.verticalPolicy()):
+        return
+    hint = widget.minimumSizeHint()
+    short_w = hint.width() - widget.width() if hint.width() > 0 else 0
+    short_h = hint.height() - widget.height() if hint.height() > 0 else 0
+    if max(short_w, short_h) <= MIN_HINT_SLACK:
+        return
+    parts = []
+    if short_w > MIN_HINT_SLACK:
+        parts.append(f"{short_w} px narrower")
+    if short_h > MIN_HINT_SLACK:
+        parts.append(f"{short_h} px shorter")
+    findings.append(
+        _finding(
+            "warning",
+            rid,
+            f"Rendered {' and '.join(parts)} than its minimumSizeHint "
+            f"({hint.width()}x{hint.height()}); content is likely clipped",
+        )
+    )
+
+
+def _outside_parent(findings: list, widget: QWidget, rid: str) -> None:
+    parent = widget.parentWidget()
+    if parent is None or not widget.isVisible() or widget.isWindow():
+        # A window's geometry is in screen coordinates; its Qt parent only owns
+        # its lifetime, so comparing the two rectangles is meaningless.
+        return
+    geo = widget.geometry()
+    overflow_x = max(0, -geo.x()) + max(0, geo.right() - parent.width() + 1)
+    overflow_y = max(0, -geo.y()) + max(0, geo.bottom() - parent.height() + 1)
+    overflow = max(overflow_x, overflow_y)
+    if overflow > 2:
+        findings.append(_finding("warning", rid, f"Widget extends {overflow} px outside parent bounds"))
+
+
+def _zero_size(findings: list, widget: QWidget, rid: str) -> None:
+    if widget.isVisible() and (widget.width() <= 0 or widget.height() <= 0):
+        findings.append(_finding("warning", rid, "Visible widget has zero width or height"))
+
+
+def _clipped(findings: list, widget: QWidget, rid: str) -> None:
+    parent = widget.parentWidget()
+    if parent is None or not widget.isVisible() or widget.isWindow():
+        return
+    geo = widget.geometry()
+    if geo.x() < 0 or geo.y() < 0:
+        findings.append(_finding("warning", rid, "Widget is clipped by its parent (negative origin)"))
+        return
+    if geo.right() > parent.width() + 1 or geo.bottom() > parent.height() + 1:
+        findings.append(_finding("info", rid, "Widget may be clipped by parent bounds"))
+
+
+def _minmax(findings: list, widget: QWidget, rid: str) -> None:
+    mn = widget.minimumSize()
+    mx = widget.maximumSize()
+    if mn.width() > mx.width() or mn.height() > mx.height():
+        findings.append(_finding("error", rid, "Minimum size is larger than maximum size"))
+    if mn.width() >= HUGE_MIN or mn.height() >= HUGE_MIN:
+        findings.append(
+            _finding("warning", rid, f"Extremely large minimum size {mn.width()}x{mn.height()}")
+        )
+
+
+def _fixed_size(findings: list, widget: QWidget, rid: str) -> None:
+    sp = widget.sizePolicy()
+    if sp.horizontalPolicy() == QSizePolicy.Fixed and widget.minimumWidth() == widget.maximumWidth() and widget.width() > 0:
+        if widget.maximumWidth() > 800:
+            findings.append(_finding("info", rid, "Suspicious large fixed width"))
+    if sp.verticalPolicy() == QSizePolicy.Fixed and widget.minimumHeight() == widget.maximumHeight() and widget.height() > 400:
+        findings.append(_finding("info", rid, "Suspicious large fixed height"))
+
+
+def _invisible_in_layout(findings: list, widget: QWidget, rid: str) -> None:
+    """Flag only when a non-hidden widget is invisible yet still a layout item.
+
+    Qt layouts already skip ``isHidden()`` children (capability gates, inactive
+    stack/tab pages), so those must not be reported as occupying space.
+    """
+    parent = widget.parentWidget()
+    if parent is None or widget.isVisibleTo(parent):
+        return
+    # Hidden widgets / inactive pages: QWidgetItem.isEmpty() → no layout space.
+    if widget.isHidden():
+        return
+    ancestor = parent
+    while ancestor is not None:
+        if ancestor.isHidden():
+            return
+        ancestor = ancestor.parentWidget()
+    layout = parent.layout()
+    if layout is None:
+        return
+    for i in range(layout.count()):
+        item = layout.itemAt(i)
+        if item is not None and item.widget() is widget:
+            # Still empty ⇒ layout is not allocating space; skip noise.
+            if item.isEmpty():
+                return
+            findings.append(
+                _finding("info", rid, "Invisible widget still occupies layout space")
+            )
+            return
+
+
+def _missing_layout(findings: list, widget: QWidget, rid: str) -> None:
+    if widget.layout() is not None or isinstance(widget, SELF_MANAGED) or _is_internal(widget):
+        return
+    direct = [
+        c
+        for c in widget.findChildren(QWidget)
+        if c.parentWidget() is widget and not _is_internal(c)
+    ]
+    if len(direct) >= 4:
+        findings.append(
+            _finding(
+                "warning",
+                rid,
+                f"Container has {len(direct)} direct children but no QLayout",
+            )
+        )
+
+
+def _overlapping_siblings(ctx: "BridgeContext", findings: list, widgets: list[QWidget]) -> None:
+    by_parent: dict[int, list[QWidget]] = {}
+    for widget in widgets:
+        parent = widget.parentWidget()
+        if parent is None or widget.isWindow():
+            continue  # separate windows are not siblings laid out in a parent
+        by_parent.setdefault(id(parent), []).append(widget)
+    reported = 0
+    for siblings in by_parent.values():
+        visible = [w for w in siblings if w.isVisible() and w.width() > 1 and w.height() > 1]
+        for i, a in enumerate(visible):
+            for b in visible[i + 1 :]:
+                if a.geometry().intersects(b.geometry()):
+                    inter = a.geometry().intersected(b.geometry())
+                    if inter.width() < 4 or inter.height() < 4:
+                        continue
+                    findings.append(
+                        {
+                            "severity": "warning",
+                            "widget": ctx.registry.ensure(a),
+                            "message": (
+                                f"Overlaps sibling {ctx.registry.ensure(b)} "
+                                f"by {inter.width()}x{inter.height()} px"
+                            ),
+                        }
+                    )
+                    reported += 1
+                    if reported >= 40:
+                        return