pyqt-runtime-mcp 0.1.0__tar.gz

pyqt_runtime_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tigran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyqt_runtime_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: pyqt-runtime-mcp
+Version: 0.1.0
+Summary: MCP server and in-app bridge for inspecting and controlling running PyQt5 applications
+Author-email: Tigran <tyavroyan@gmail.com>
+License: MIT
+Keywords: pyqt5,mcp,qt,devtools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2
+Provides-Extra: qt
+Requires-Dist: PyQt5>=5.15; extra == "qt"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: PyQt5>=5.15; extra == "dev"
+Dynamic: license-file
+
+# PyQt Runtime MCP
+
+Runtime inspection and interaction for **any PyQt5 QWidget application**, in the same spirit as browser DevTools / Playwright — but Qt-native.
+
+Cursor talks to an MCP stdio server. That server talks over localhost TCP to a small **bridge running inside the target app**. All `QWidget` work happens on the Qt GUI thread.
+
+This package is reusable. GCS is only one consumer.
+
+## Installation
+
+From PyPI (after the package is published):
+
+```powershell
+pip install pyqt-runtime-mcp
+```
+
+From this folder (development):
+
+```powershell
+pip install -e .
+```
+
+The in-app bridge needs **PyQt5** (already present in a PyQt app). The Cursor MCP process needs this package — it pulls in the `mcp` SDK and does **not** need Qt. Optional extra for the demo app only: `pip install "pyqt-runtime-mcp[qt]"`.
+
+In this repository, adding the `pyqt-runtime` entry to `.cursor/mcp.json` is enough. Cursor starts the server the same way as the other project MCP servers. GCS starts the in-app bridge automatically with `python main.py` — no extra environment variables.
+
+## Quick start
+
+1. Run the app (`python main.py` or the demo below). The in-app bridge listens on `127.0.0.1:8765`.
+
+2. Point Cursor at the MCP server (see [Cursor configuration](#cursor-configuration)). Reload MCP servers if you just added it.
+
+3. Ask:
+
+```text
+Inspect the current PyQt application and give me its widget hierarchy.
+```
+
+Demo without GCS (from this folder, with PyQt5 installed):
+
+```powershell
+python examples/demo_app.py
+```
+
+## Integration into an existing PyQt5 application
+
+```python
+from PyQt5.QtWidgets import QApplication
+from pyqt_runtime_mcp import install_pyqt_mcp
+
+app = QApplication(sys.argv)
+window = MainWindow()
+
+install_pyqt_mcp(app)
+
+window.show()
+sys.exit(app.exec_())
+```
+
+Equivalent:
+
+```python
+from pyqt_runtime_mcp import PyQtMCPBridge
+
+bridge = PyQtMCPBridge(app)
+bridge.start()
+```
+
+The bridge **must** be started inside the process that owns `QApplication`. It will not attach to a random already-running PyQt process.
+
+### GCS (this repository)
+
+`main.py` always starts the localhost bridge. Run the app as usual:
+
+```powershell
+python .\main.py
+```
+
+If the bridge cannot bind, GCS still runs and logs a warning.
+
+## Starting the MCP server
+
+After `pip install pyqt-runtime-mcp`, either command works:
+
+```powershell
+pyqt-runtime-mcp
+python -m pyqt_runtime_mcp
+```
+
+From this source tree without installing, use `python run_server.py`.
+
+If the app is not running, tools return `APPLICATION_NOT_CONNECTED` instead of hanging.
+
+## Cursor configuration
+
+After a PyPI / editable install, use the console script (same Python that ran `pip install`):
+
+```json
+"pyqt-runtime": {
+  "command": "pyqt-runtime-mcp"
+}
+```
+
+Equivalent:
+
+```json
+"pyqt-runtime": {
+  "command": "python",
+  "args": ["-m", "pyqt_runtime_mcp"]
+}
+```
+
+This repository's `.cursor/mcp.json` still launches `run_server.py` so GCS works without a prior `pip install`. Reload MCP servers in Cursor after saving. Start the PyQt app, then ask Cursor to inspect it.
+
+## Available MCP tools
+
+Inspection: `qt_get_application_info`, `qt_list_windows`, `qt_get_widget_tree`, `qt_find_widgets`, `qt_get_widget`, `qt_get_layout`, `qt_get_geometry`, `qt_get_ui_snapshot`
+
+Visual: `qt_capture_window`, `qt_capture_widget`, `qt_capture_region`, `qt_capture_screen_region`, `qt_capture_sections`, `qt_visual_snapshot`
+
+Interaction: `qt_click`, `qt_double_click`, `qt_move_mouse`, `qt_set_focus`, `qt_type_text`, `qt_key_press`
+
+Semantic: `qt_set_text`, `qt_set_value`, `qt_set_checked`, `qt_select_combobox`, `qt_set_current_page`
+
+Window: `qt_resize_window`, `qt_move_window`, `qt_activate_window`, `qt_close_window`, `qt_close_windows` (`confirm=true` required on both close tools)
+
+Style / meta: `qt_get_stylesheet`, `qt_set_stylesheet`, `qt_list_properties`, `qt_get_property`, `qt_set_property`
+
+Diagnostics: `qt_analyze_layout`, `qt_list_signals`, `qt_watch_signal`, `qt_get_event_log`, `qt_get_logs`, `qt_get_exceptions`, `qt_show_debug_overlay`, `qt_hide_debug_overlay`
+
+There is **no** `execute_python` / eval / shell tool.
+
+### Runtime logs
+
+`qt_get_logs` returns one bounded ring buffer holding both Qt messages (captured through
+`qInstallMessageHandler`) and the application's own stdlib `logging` records (captured with a
+handler added to the root logger). Entries are tagged `source: "qt" | "python"`; filter with
+`source`, `level`, or `contains`. Neither capture changes what the application already prints,
+and the root logger's level is left untouched — records the app filters out stay filtered out.
+
+### Selecting a widget
+
+Every tool that takes `widget_id` accepts a runtime id (`qt://widget/N`) or an `objectName`.
+Detaching a view usually clones objectNames into a second window, which makes a bare name
+ambiguous; the error then lists each candidate with the window it lives in. Pass
+`window=<window id or objectName>` to scope the lookup to one window's subtree.
+`qt_find_widgets` takes the same `window` argument.
+
+### Closing windows
+
+`qt_close_window` closes one window and verifies the result: `closed` is `false` when a
+`closeEvent` handler refused, and `force=true` then hides and deletes the widget. Dialogs are
+rejected first so an `exec_()` loop unwinds. `qt_close_windows` sweeps every visible top-level
+window — the way to clean up detached views, popups, and leftover dialogs after a test run.
+It protects `QMainWindow` instances unless `include_main=true`, and can be narrowed with
+`windows`, `class_name`, or `title_contains`. The reply splits results into `closed`,
+`failed`, `skipped`, and the `remaining` visible windows.
+
+### Example prompts
+
+```text
+Inspect the current PyQt application and give me its widget hierarchy.
+
+Take a screenshot of MainWindow.
+
+Find the widget named telemetryPanel and inspect its geometry.
+
+Resize MainWindow to 1024x600 and identify layout problems.
+
+Find all QLabel widgets whose contents are clipped.
+
+Open page 3 of the main QStackedWidget.
+
+Click the Settings button.
+
+Capture the Settings page.
+
+Capture labeled sections for the status bar, emergency rail, and map area so each can be checked separately.
+
+Inspect the layout and tell me why the bottom controls are outside the visible area.
+```
+
+### Section screenshots
+
+`qt_capture_region` grabs a rectangle in **widget-local** coordinates (default base: active window). Prefer it over `qt_capture_screen_region` when correlating to layout geometry from `qt_get_geometry` / `qt_visual_snapshot`.
+
+`qt_capture_sections` takes a list of labeled pieces in one call. Each section may be a full widget (`widget_id`), a crop of that widget (`widget_id` + `x/y/width/height`), or a region on a window. Replies include every PNG plus metadata with `label`, `source` (`widget` | `widget_region` | `region`), and paths under `sections/<label>.png` in the screenshot sandbox — so agents can cite specific crops when verifying UI.
+
+### Agent workflow (token-aware, normal for this app)
+
+Cost is expected to be normal when used this way — not “avoid trees forever.”
+
+1. **First orientation** — one `qt_get_widget_tree` (optionally `visible_only=true`, or a `root` panel) to learn objectNames / hierarchy. GCS is a deep QWidget tree; that call is intentional once per session or after a major UI change.
+2. **After that** — `qt_find_widgets` + `qt_get_widget` / `qt_get_geometry` / `qt_get_layout` against known ids. Do not re-dump the full tree every step.
+3. **Visual checks** — prefer `qt_capture_widget`, `qt_capture_region`, or labeled `qt_capture_sections` over full-window `qt_capture_window` / `qt_visual_snapshot`. Use a full-window shot when you need overall composition, not for every verification.
+4. **Loop** — inspect → edit source → restart app → targeted find/get + crops → verify.
+
+Disable the `pyqt-runtime` MCP in Cursor when you are not doing live UI work (tool schemas still cost context even if unused).
+
+## Security
+
+- Binds to `127.0.0.1` only.
+- Screenshots write only inside a sandbox directory (default: temp `pyqt-runtime-mcp/screenshots/`). `..` and paths outside the sandbox are rejected.
+- Widget IDs are validated. Qt property writes use writable `QMetaProperty` only.
+- No eval, exec, shell, or call-by-name Python methods.
+
+## Threading model
+
+```text
+MCP stdio process  --TCP JSON-->  bridge acceptor thread
+                                      |
+                                      | queued Qt signal
+                                      v
+                                 QApplication thread
+                                      |
+                                      v
+                                 QWidget / QLayout
+```
+
+The IPC thread never touches Qt objects. The GUI thread never waits on the socket.
+
+## Architecture
+
+Two processes, JSON only (no pickle):
+
+1. **In-app bridge** (`install_pyqt_mcp`) — widget registry (`qt://widget/N`), inspectors, screenshots, input synthesis.
+2. **MCP server** (`pyqt-runtime-mcp` / `python -m pyqt_runtime_mcp`) — official MCP Python SDK (`MCPServer` / FastMCP fallback), stdio to Cursor.
+
+### Wire protocol
+
+TCP on `127.0.0.1`, framed as a 4-byte big-endian length followed by UTF-8 JSON (max 16 MiB per frame). A discovery file (`%TEMP%/pyqt-runtime-mcp/bridge.json`) records the bound port if 8765 is busy.
+
+1. **Handshake** — client sends `{"type": "handshake", "protocol": "pyqt-mcp/1", "token": <optional>}`; the bridge replies `{"ok": true, "protocol": ..., "port": ...}` or `{"ok": false, "error": {...}}` and closes.
+2. **Request** — `{"id": <uuid>, "method": <name>, "params": {...}, "timeout": <seconds>}`. `timeout` is the client's budget; the bridge dispatches to the GUI thread with a slightly shorter deadline so it always answers first.
+3. **Response** — `{"id": <same uuid>, "ok": true, "result": ...}` or `{"id": ..., "ok": false, "error": {"code": ..., "message": ...}}`.
+
+Connections stay open and are never closed on idle. Requests are matched by `id`, so a reply to an abandoned request is skipped rather than mistaken for the current one.
+
+Framing rules the client depends on:
+
+- One exchange at a time per connection. `BridgeClient` holds a lock, because the MCP SDK runs sync tools on a thread pool and two writers on one socket would corrupt the stream.
+- A frame length of 0 or above the limit means the stream is out of sync (`PROTOCOL_ERROR`); both sides discard the connection instead of trying to resynchronise.
+- A reused connection is liveness-checked before sending, and a send failure on it is retried once on a fresh socket. A failure *after* sending is never retried, since the request may have already run.
+
+## Troubleshooting
+
+| Symptom | What to check |
+|---|---|
+| `APPLICATION_NOT_CONNECTED` | The PyQt app is not running. Start `python main.py` (or the demo). |
+| `WIDGET_NOT_FOUND` | Stale id after destroy. Widgets are rebuilt when a view is detached, so re-query the id. |
+| `objectName is not unique` | The same name exists in more than one window. Pass `window=...`, or use a runtime id from the error's `candidates`. |
+| `TIMEOUT` | The GUI thread is busy or blocked (modal dialog, long handler). The connection is dropped and the next call reconnects. |
+| `PROTOCOL_ERROR` (frame too large) | A reply exceeded 16 MiB, or something else is writing to the bridge port. Narrow the request (`max_depth`, a specific `widget_id`). |
+| Screenshots empty / tiny | Offscreen platform (`QT_QPA_PLATFORM=offscreen`) still produces pixmaps but they may look blank. Use a real display for visual QA. |
+| Resize ignored | The reply reports `matched: false` plus the window's min/max size. Maximized windows are restored first and the resize is re-applied once the window manager settles. |
+| Window will not close | `qt_close_window` reports `closed: false` when `closeEvent` calls `ignore()`. Retry with `force=true`. |
+| MCP server import error | `pip install pyqt-runtime-mcp` in the same Python Cursor uses for `command`. |
+
+## Tests
+
+From this folder:
+
+```powershell
+pip install -e ".[dev]"
+python -m pytest -q
+```
+
+(The test suite sets `QT_QPA_PLATFORM=offscreen` itself.)

pyqt_runtime_mcp-0.1.0/README.md

@@ -0,0 +1,268 @@
+# PyQt Runtime MCP
+
+Runtime inspection and interaction for **any PyQt5 QWidget application**, in the same spirit as browser DevTools / Playwright — but Qt-native.
+
+Cursor talks to an MCP stdio server. That server talks over localhost TCP to a small **bridge running inside the target app**. All `QWidget` work happens on the Qt GUI thread.
+
+This package is reusable. GCS is only one consumer.
+
+## Installation
+
+From PyPI (after the package is published):
+
+```powershell
+pip install pyqt-runtime-mcp
+```
+
+From this folder (development):
+
+```powershell
+pip install -e .
+```
+
+The in-app bridge needs **PyQt5** (already present in a PyQt app). The Cursor MCP process needs this package — it pulls in the `mcp` SDK and does **not** need Qt. Optional extra for the demo app only: `pip install "pyqt-runtime-mcp[qt]"`.
+
+In this repository, adding the `pyqt-runtime` entry to `.cursor/mcp.json` is enough. Cursor starts the server the same way as the other project MCP servers. GCS starts the in-app bridge automatically with `python main.py` — no extra environment variables.
+
+## Quick start
+
+1. Run the app (`python main.py` or the demo below). The in-app bridge listens on `127.0.0.1:8765`.
+
+2. Point Cursor at the MCP server (see [Cursor configuration](#cursor-configuration)). Reload MCP servers if you just added it.
+
+3. Ask:
+
+```text
+Inspect the current PyQt application and give me its widget hierarchy.
+```
+
+Demo without GCS (from this folder, with PyQt5 installed):
+
+```powershell
+python examples/demo_app.py
+```
+
+## Integration into an existing PyQt5 application
+
+```python
+from PyQt5.QtWidgets import QApplication
+from pyqt_runtime_mcp import install_pyqt_mcp
+
+app = QApplication(sys.argv)
+window = MainWindow()
+
+install_pyqt_mcp(app)
+
+window.show()
+sys.exit(app.exec_())
+```
+
+Equivalent:
+
+```python
+from pyqt_runtime_mcp import PyQtMCPBridge
+
+bridge = PyQtMCPBridge(app)
+bridge.start()
+```
+
+The bridge **must** be started inside the process that owns `QApplication`. It will not attach to a random already-running PyQt process.
+
+### GCS (this repository)
+
+`main.py` always starts the localhost bridge. Run the app as usual:
+
+```powershell
+python .\main.py
+```
+
+If the bridge cannot bind, GCS still runs and logs a warning.
+
+## Starting the MCP server
+
+After `pip install pyqt-runtime-mcp`, either command works:
+
+```powershell
+pyqt-runtime-mcp
+python -m pyqt_runtime_mcp
+```
+
+From this source tree without installing, use `python run_server.py`.
+
+If the app is not running, tools return `APPLICATION_NOT_CONNECTED` instead of hanging.
+
+## Cursor configuration
+
+After a PyPI / editable install, use the console script (same Python that ran `pip install`):
+
+```json
+"pyqt-runtime": {
+  "command": "pyqt-runtime-mcp"
+}
+```
+
+Equivalent:
+
+```json
+"pyqt-runtime": {
+  "command": "python",
+  "args": ["-m", "pyqt_runtime_mcp"]
+}
+```
+
+This repository's `.cursor/mcp.json` still launches `run_server.py` so GCS works without a prior `pip install`. Reload MCP servers in Cursor after saving. Start the PyQt app, then ask Cursor to inspect it.
+
+## Available MCP tools
+
+Inspection: `qt_get_application_info`, `qt_list_windows`, `qt_get_widget_tree`, `qt_find_widgets`, `qt_get_widget`, `qt_get_layout`, `qt_get_geometry`, `qt_get_ui_snapshot`
+
+Visual: `qt_capture_window`, `qt_capture_widget`, `qt_capture_region`, `qt_capture_screen_region`, `qt_capture_sections`, `qt_visual_snapshot`
+
+Interaction: `qt_click`, `qt_double_click`, `qt_move_mouse`, `qt_set_focus`, `qt_type_text`, `qt_key_press`
+
+Semantic: `qt_set_text`, `qt_set_value`, `qt_set_checked`, `qt_select_combobox`, `qt_set_current_page`
+
+Window: `qt_resize_window`, `qt_move_window`, `qt_activate_window`, `qt_close_window`, `qt_close_windows` (`confirm=true` required on both close tools)
+
+Style / meta: `qt_get_stylesheet`, `qt_set_stylesheet`, `qt_list_properties`, `qt_get_property`, `qt_set_property`
+
+Diagnostics: `qt_analyze_layout`, `qt_list_signals`, `qt_watch_signal`, `qt_get_event_log`, `qt_get_logs`, `qt_get_exceptions`, `qt_show_debug_overlay`, `qt_hide_debug_overlay`
+
+There is **no** `execute_python` / eval / shell tool.
+
+### Runtime logs
+
+`qt_get_logs` returns one bounded ring buffer holding both Qt messages (captured through
+`qInstallMessageHandler`) and the application's own stdlib `logging` records (captured with a
+handler added to the root logger). Entries are tagged `source: "qt" | "python"`; filter with
+`source`, `level`, or `contains`. Neither capture changes what the application already prints,
+and the root logger's level is left untouched — records the app filters out stay filtered out.
+
+### Selecting a widget
+
+Every tool that takes `widget_id` accepts a runtime id (`qt://widget/N`) or an `objectName`.
+Detaching a view usually clones objectNames into a second window, which makes a bare name
+ambiguous; the error then lists each candidate with the window it lives in. Pass
+`window=<window id or objectName>` to scope the lookup to one window's subtree.
+`qt_find_widgets` takes the same `window` argument.
+
+### Closing windows
+
+`qt_close_window` closes one window and verifies the result: `closed` is `false` when a
+`closeEvent` handler refused, and `force=true` then hides and deletes the widget. Dialogs are
+rejected first so an `exec_()` loop unwinds. `qt_close_windows` sweeps every visible top-level
+window — the way to clean up detached views, popups, and leftover dialogs after a test run.
+It protects `QMainWindow` instances unless `include_main=true`, and can be narrowed with
+`windows`, `class_name`, or `title_contains`. The reply splits results into `closed`,
+`failed`, `skipped`, and the `remaining` visible windows.
+
+### Example prompts
+
+```text
+Inspect the current PyQt application and give me its widget hierarchy.
+
+Take a screenshot of MainWindow.
+
+Find the widget named telemetryPanel and inspect its geometry.
+
+Resize MainWindow to 1024x600 and identify layout problems.
+
+Find all QLabel widgets whose contents are clipped.
+
+Open page 3 of the main QStackedWidget.
+
+Click the Settings button.
+
+Capture the Settings page.
+
+Capture labeled sections for the status bar, emergency rail, and map area so each can be checked separately.
+
+Inspect the layout and tell me why the bottom controls are outside the visible area.
+```
+
+### Section screenshots
+
+`qt_capture_region` grabs a rectangle in **widget-local** coordinates (default base: active window). Prefer it over `qt_capture_screen_region` when correlating to layout geometry from `qt_get_geometry` / `qt_visual_snapshot`.
+
+`qt_capture_sections` takes a list of labeled pieces in one call. Each section may be a full widget (`widget_id`), a crop of that widget (`widget_id` + `x/y/width/height`), or a region on a window. Replies include every PNG plus metadata with `label`, `source` (`widget` | `widget_region` | `region`), and paths under `sections/<label>.png` in the screenshot sandbox — so agents can cite specific crops when verifying UI.
+
+### Agent workflow (token-aware, normal for this app)
+
+Cost is expected to be normal when used this way — not “avoid trees forever.”
+
+1. **First orientation** — one `qt_get_widget_tree` (optionally `visible_only=true`, or a `root` panel) to learn objectNames / hierarchy. GCS is a deep QWidget tree; that call is intentional once per session or after a major UI change.
+2. **After that** — `qt_find_widgets` + `qt_get_widget` / `qt_get_geometry` / `qt_get_layout` against known ids. Do not re-dump the full tree every step.
+3. **Visual checks** — prefer `qt_capture_widget`, `qt_capture_region`, or labeled `qt_capture_sections` over full-window `qt_capture_window` / `qt_visual_snapshot`. Use a full-window shot when you need overall composition, not for every verification.
+4. **Loop** — inspect → edit source → restart app → targeted find/get + crops → verify.
+
+Disable the `pyqt-runtime` MCP in Cursor when you are not doing live UI work (tool schemas still cost context even if unused).
+
+## Security
+
+- Binds to `127.0.0.1` only.
+- Screenshots write only inside a sandbox directory (default: temp `pyqt-runtime-mcp/screenshots/`). `..` and paths outside the sandbox are rejected.
+- Widget IDs are validated. Qt property writes use writable `QMetaProperty` only.
+- No eval, exec, shell, or call-by-name Python methods.
+
+## Threading model
+
+```text
+MCP stdio process  --TCP JSON-->  bridge acceptor thread
+                                      |
+                                      | queued Qt signal
+                                      v
+                                 QApplication thread
+                                      |
+                                      v
+                                 QWidget / QLayout
+```
+
+The IPC thread never touches Qt objects. The GUI thread never waits on the socket.
+
+## Architecture
+
+Two processes, JSON only (no pickle):
+
+1. **In-app bridge** (`install_pyqt_mcp`) — widget registry (`qt://widget/N`), inspectors, screenshots, input synthesis.
+2. **MCP server** (`pyqt-runtime-mcp` / `python -m pyqt_runtime_mcp`) — official MCP Python SDK (`MCPServer` / FastMCP fallback), stdio to Cursor.
+
+### Wire protocol
+
+TCP on `127.0.0.1`, framed as a 4-byte big-endian length followed by UTF-8 JSON (max 16 MiB per frame). A discovery file (`%TEMP%/pyqt-runtime-mcp/bridge.json`) records the bound port if 8765 is busy.
+
+1. **Handshake** — client sends `{"type": "handshake", "protocol": "pyqt-mcp/1", "token": <optional>}`; the bridge replies `{"ok": true, "protocol": ..., "port": ...}` or `{"ok": false, "error": {...}}` and closes.
+2. **Request** — `{"id": <uuid>, "method": <name>, "params": {...}, "timeout": <seconds>}`. `timeout` is the client's budget; the bridge dispatches to the GUI thread with a slightly shorter deadline so it always answers first.
+3. **Response** — `{"id": <same uuid>, "ok": true, "result": ...}` or `{"id": ..., "ok": false, "error": {"code": ..., "message": ...}}`.
+
+Connections stay open and are never closed on idle. Requests are matched by `id`, so a reply to an abandoned request is skipped rather than mistaken for the current one.
+
+Framing rules the client depends on:
+
+- One exchange at a time per connection. `BridgeClient` holds a lock, because the MCP SDK runs sync tools on a thread pool and two writers on one socket would corrupt the stream.
+- A frame length of 0 or above the limit means the stream is out of sync (`PROTOCOL_ERROR`); both sides discard the connection instead of trying to resynchronise.
+- A reused connection is liveness-checked before sending, and a send failure on it is retried once on a fresh socket. A failure *after* sending is never retried, since the request may have already run.
+
+## Troubleshooting
+
+| Symptom | What to check |
+|---|---|
+| `APPLICATION_NOT_CONNECTED` | The PyQt app is not running. Start `python main.py` (or the demo). |
+| `WIDGET_NOT_FOUND` | Stale id after destroy. Widgets are rebuilt when a view is detached, so re-query the id. |
+| `objectName is not unique` | The same name exists in more than one window. Pass `window=...`, or use a runtime id from the error's `candidates`. |
+| `TIMEOUT` | The GUI thread is busy or blocked (modal dialog, long handler). The connection is dropped and the next call reconnects. |
+| `PROTOCOL_ERROR` (frame too large) | A reply exceeded 16 MiB, or something else is writing to the bridge port. Narrow the request (`max_depth`, a specific `widget_id`). |
+| Screenshots empty / tiny | Offscreen platform (`QT_QPA_PLATFORM=offscreen`) still produces pixmaps but they may look blank. Use a real display for visual QA. |
+| Resize ignored | The reply reports `matched: false` plus the window's min/max size. Maximized windows are restored first and the resize is re-applied once the window manager settles. |
+| Window will not close | `qt_close_window` reports `closed: false` when `closeEvent` calls `ignore()`. Retry with `force=true`. |
+| MCP server import error | `pip install pyqt-runtime-mcp` in the same Python Cursor uses for `command`. |
+
+## Tests
+
+From this folder:
+
+```powershell
+pip install -e ".[dev]"
+python -m pytest -q
+```
+
+(The test suite sets `QT_QPA_PLATFORM=offscreen` itself.)

pyqt_runtime_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "pyqt-runtime-mcp"
+dynamic = ["version"]
+description = "MCP server and in-app bridge for inspecting and controlling running PyQt5 applications"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Tigran", email = "tyavroyan@gmail.com" }]
+keywords = ["pyqt5", "mcp", "qt", "devtools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: User Interfaces",
+]
+dependencies = [
+    "mcp>=1.2",
+]
+
+[project.optional-dependencies]
+qt = ["PyQt5>=5.15"]
+dev = ["pytest>=8", "PyQt5>=5.15"]
+
+[project.scripts]
+pyqt-runtime-mcp = "pyqt_runtime_mcp.server:main"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.dynamic]
+version = { attr = "pyqt_runtime_mcp.__version__" }
+
+[tool.setuptools]
+license-files = ["LICENSE"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]
+addopts = "-q"

pyqt_runtime_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyqt_runtime_mcp-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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"]