# tiefeiyu/qt-commander architecture

> Architecture diagram of the GitHub repository tiefeiyu/qt-commander, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tiefeiyu/qt-commander
- Repository: https://github.com/tiefeiyu/qt-commander

## Overview

qt-commander is an MCP server for introspecting and automating running Qt applications. An agent calls the Python server, which manages sessions and launches an injector; the injected library exposes UI operations over authenticated, framed TCP RPC. The graph also preserves the documented build/environment, process discovery, snapshot/pruning, lookup, capture, and input capabilities. Some tool implementations and native dispatch details were not sampled, so those links follow explicit README architecture or are omitted where ownership is uncertain.

Main entry points: [`src/library/rpc/rpc_server.cpp`](https://github.com/tiefeiyu/qt-commander/blob/master/src/library/rpc/rpc_server.cpp) (RPC dispatcher), [`qt_commander/server.py`](https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/server.py) (MCP tools), [`qt_commander/session.py`](https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/session.py) (Session manager), [`qt_commander/rpc_client.py`](https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/rpc_client.py) (Injector client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP interface"]
  node_server["MCP tools<br/>[server.py]"]
  node_occlusion["Snapshot pruning<br/>[occlusion.py]"]
end

subgraph group_lifecycle["Discovery and sessions"]
  node_environment["Kit detection"]
  node_builder["On-demand build<br/>[builder.py]"]
  node_processes["Qt processes"]
  node_sessions["Session manager<br/>[session.py]"]
  node_rpcclient["Injector client<br/>[rpc_client.py]"]
end

subgraph group_injection["Process injection"]
  node_injector["Injector CLI<br/>[main.cpp]"]
  node_injectops["Platform injection<br/>[injector.h]"]
end

subgraph group_engine["In-process UI engine"]
  node_library["Injected library<br/>[entry_win.cpp]"]
  node_scanner["UI scanner<br/>[ui_scanner.cpp]"]
  node_elements[("Element map<br/>[element_map.cpp]")]
  node_selector["Element lookup<br/>[selector.cpp]"]
  node_screenshots["Screenshot capture<br/>[screenshot.cpp]"]
  node_events["Input injection<br/>[event_injector.cpp]"]
end

subgraph group_transport["RPC transport"]
  node_rpcserver["RPC dispatcher<br/>[rpc_server.cpp]"]
  node_framing["Frame protocol<br/>[framing.h]"]
end

node_agent(("AI agent"))
node_target["Running Qt app"]
node_workspace[("Session files")]

node_agent -->|"calls tools"| node_server
node_server -->|"detects kits"| node_environment
node_server -->|"builds runtime"| node_builder
node_server -->|"lists processes"| node_processes
node_server -->|"manages sessions"| node_sessions
node_sessions -->|"connects via"| node_rpcclient
node_rpcclient -->|"launches"| node_injector
node_injector -->|"injects or ejects"| node_injectops
node_injectops -->|"loads library"| node_target
node_target -->|"runs in process"| node_library
node_library -->|"starts server"| node_rpcserver
node_rpcclient -->|"frames requests"| node_framing
node_rpcserver -->|"decodes frames"| node_framing
node_rpcserver -->|"scans UI"| node_scanner
node_rpcserver -->|"refreshes map"| node_elements
node_rpcserver -->|"finds elements"| node_selector
node_rpcserver -->|"captures UI"| node_screenshots
node_rpcserver -->|"dispatches input"| node_events
node_server -->|"prunes snapshots"| node_occlusion
node_server -->|"stores snapshots"| node_workspace
node_sessions -->|"persists metadata"| node_workspace
node_processes -->|"discovers"| node_target
node_rpcserver -->|"serves UI operations"| node_target

click node_server "https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/server.py"
click node_environment "https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/environment_detector.py"
click node_builder "https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/builder.py"
click node_processes "https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/process_detector.py"
click node_sessions "https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/session.py"
click node_rpcclient "https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/rpc_client.py"
click node_injector "https://github.com/tiefeiyu/qt-commander/blob/master/src/injector/main.cpp"
click node_injectops "https://github.com/tiefeiyu/qt-commander/blob/master/src/injector/injector.h"
click node_library "https://github.com/tiefeiyu/qt-commander/blob/master/src/library/entry_win.cpp"
click node_rpcserver "https://github.com/tiefeiyu/qt-commander/blob/master/src/library/rpc/rpc_server.cpp"
click node_framing "https://github.com/tiefeiyu/qt-commander/blob/master/src/common/framing.h"
click node_scanner "https://github.com/tiefeiyu/qt-commander/blob/master/src/library/core/ui_scanner.cpp"
click node_elements "https://github.com/tiefeiyu/qt-commander/blob/master/src/library/core/element_map.cpp"
click node_selector "https://github.com/tiefeiyu/qt-commander/blob/master/src/library/selector/selector.cpp"
click node_screenshots "https://github.com/tiefeiyu/qt-commander/blob/master/src/library/core/screenshot.cpp"
click node_events "https://github.com/tiefeiyu/qt-commander/blob/master/src/library/core/event_injector.cpp"
click node_occlusion "https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/occlusion.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_occlusion toneBlue
class node_environment,node_builder,node_processes,node_sessions,node_rpcclient,node_workspace toneAmber
class node_injector,node_injectops toneMint
class node_library,node_scanner,node_elements,node_selector,node_screenshots,node_events toneRose
class node_rpcserver,node_framing,node_agent,node_target toneIndigo
```

## Components

### MCP interface

- [MCP tools](https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/server.py): `qt_commander/server.py`
- [Snapshot pruning](https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/occlusion.py): `qt_commander/occlusion.py`

### Discovery and sessions

- [Kit detection](https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/environment_detector.py): `qt_commander/environment_detector.py`
- [On-demand build](https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/builder.py): `qt_commander/builder.py`
- [Qt processes](https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/process_detector.py): `qt_commander/process_detector.py`
- [Session manager](https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/session.py): `qt_commander/session.py`
- [Injector client](https://github.com/tiefeiyu/qt-commander/blob/master/qt_commander/rpc_client.py): `qt_commander/rpc_client.py`

### Process injection

- [Injector CLI](https://github.com/tiefeiyu/qt-commander/blob/master/src/injector/main.cpp): `src/injector/main.cpp`
- [Platform injection](https://github.com/tiefeiyu/qt-commander/blob/master/src/injector/injector.h): `src/injector/injector.h`

### In-process UI engine

- [Injected library](https://github.com/tiefeiyu/qt-commander/blob/master/src/library/entry_win.cpp): `src/library/entry_win.cpp`
- [UI scanner](https://github.com/tiefeiyu/qt-commander/blob/master/src/library/core/ui_scanner.cpp): `src/library/core/ui_scanner.cpp`
- [Element map](https://github.com/tiefeiyu/qt-commander/blob/master/src/library/core/element_map.cpp): `src/library/core/element_map.cpp`
- [Element lookup](https://github.com/tiefeiyu/qt-commander/blob/master/src/library/selector/selector.cpp): `src/library/selector/selector.cpp`
- [Screenshot capture](https://github.com/tiefeiyu/qt-commander/blob/master/src/library/core/screenshot.cpp): `src/library/core/screenshot.cpp`
- [Input injection](https://github.com/tiefeiyu/qt-commander/blob/master/src/library/core/event_injector.cpp): `src/library/core/event_injector.cpp`

### RPC transport

- [RPC dispatcher](https://github.com/tiefeiyu/qt-commander/blob/master/src/library/rpc/rpc_server.cpp): `src/library/rpc/rpc_server.cpp`
- [Frame protocol](https://github.com/tiefeiyu/qt-commander/blob/master/src/common/framing.h): `src/common/framing.h`

### Other components

- **AI agent**
- **Running Qt app**
- **Session files**

## Connections

- AI agent → MCP tools: calls tools
- MCP tools → Kit detection: detects kits
- MCP tools → On-demand build: builds runtime
- MCP tools → Qt processes: lists processes
- MCP tools → Session manager: manages sessions
- Session manager → Injector client: connects via
- Injector client → Injector CLI: launches
- Injector CLI → Platform injection: injects or ejects
- Platform injection → Running Qt app: loads library
- Running Qt app → Injected library: runs in process
- Injected library → RPC dispatcher: starts server
- Injector client → Frame protocol: frames requests
- RPC dispatcher → Frame protocol: decodes frames
- RPC dispatcher → UI scanner: scans UI
- RPC dispatcher → Element map: refreshes map
- RPC dispatcher → Element lookup: finds elements
- RPC dispatcher → Screenshot capture: captures UI
- RPC dispatcher → Input injection: dispatches input
- MCP tools → Snapshot pruning: prunes snapshots
- MCP tools → Session files: stores snapshots
- Session manager → Session files: persists metadata
- Qt processes → Running Qt app: discovers
- RPC dispatcher → Running Qt app: serves UI operations