blumia/gammaray-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

rename binary name to gammaray-mcp-bridge

Browse Source
This commit is contained in:
Wang Zichong
2026-07-08 13:26:08 +08:00
parent 83df5286c5
commit a6335429e5
10 changed files with 114 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
README.md
View File

@@ -1,6 +1,6 @@
# QML SceneGraph MCP Bridge
# GammaRay MCP Bridge
A [MCP](https://modelcontextprotocol.io/) server that bridges [GammaRay](https://github.com/KDAB/GammaRay) probe introspection data into MCP tools, enabling LLMs to inspect and debug Qt Quick / QML scene graphs, items, geometry, and materials.
A [MCP](https://modelcontextprotocol.io/) server that bridges [GammaRay](https://github.com/KDAB/GammaRay) probe introspection data into MCP tools, enabling LLMs to inspect and debug Qt Quick / QML scene graphs, items, geometry, materials, and Qt Widgets.
## Architecture
@@ -10,7 +10,7 @@ Target Qt/QML App ──TCP──► GammaRay MCP Bridge ──stdio──►
injected) qtmcp MCP server) Claude Desktop, etc.)
```
The bridge is a GammaRay **client**: it connects to a probe injected into a target Qt/QML app, reads the same models the GammaRay GUI uses, and translates them into MCP JSON-RPC tool calls over stdio.
The bridge is a GammaRay **client**: it connects to a probe injected into a target Qt app, reads the same models the GammaRay GUI uses, and translates them into MCP JSON-RPC tool calls over stdio. Supports both QML Quick apps (SceneGraph, QML items) and Qt Widget apps (widget hierarchy, properties, attributes).
## Prerequisites
@@ -46,6 +46,10 @@ cmake --build build
install-prefix/bin/gammaray --inject-only --listen tcp://127.0.0.1:11732 \
--injector preload /usr/lib/qt6/bin/qml /path/to/app.qml -platform offscreen
# Or inject into a widget app
install-prefix/bin/gammaray --inject-only --listen tcp://127.0.0.1:11732 \
--injector preload /path/to/widget-app
# Start the bridge (stdio MCP server)
bridge/run.sh
```
@@ -62,7 +66,7 @@ The bridge starts in lazy-connect mode. Call `connectProbe("127.0.0.1", 11732)`
| `disconnectProbe()` | Drop connection and forget URL |
| `probeStatus()` | Report connection state |
### Navigation
### QML Navigation
| Tool | Description |
|---|---|
| `listQuickWindows()` | List QQuickWindows in the target app |
@@ -92,15 +96,25 @@ The bridge starts in lazy-connect mode. Call `connectProbe("127.0.0.1", 11732)`
| `setRenderMode(mode)` | Set render mode (NormalRendering, VisualizeOverdraw, etc.) |
| `setSlowMode(enabled)` | Toggle continuous rendering |
### Widget inspection
| Tool | Description |
|---|---|
| `listWidgets()` | Recursive QWidget hierarchy (types, names, visibility) |
| `selectWidget(address)` | Select a widget, populating its property and attribute models |
| `getWidgetProperties(address)` | Get all Q_PROPERTY values (geometry, font, palette, window flags, etc.) |
| `getWidgetAttributes(address)` | Get Qt::WidgetAttribute flags (acceptDrops, enabled, etc.) |
## Testing
```bash
# Unit tests only (no probe needed):
./tests/run_tests.sh --no-probe
# QML test suite (requires a QML app probe):
./tests/run_tests.sh
# Full integration test suite (probe required):
./tests/run_tests.sh --no-probe # skips probe-dependent tests
./tests/run_tests.sh -v # verbose
# Widget test suite (requires a widget app probe):
./tests/run_widget_tests.sh
# Unit tests only:
./tests/run_tests.sh --no-probe
```
See `tests/README.md` for details.