Metadata-Version: 2.4
Name: qinspector-mcp
Version: 0.1.1
Summary: stdio MCP bridge for Qt apps that embed QInspector
Project-URL: Homepage, https://github.com/DebiruC/QInspector
Author: NineYYY
License: MIT
Keywords: debug,mcp,qinspector,qt
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# QInspector MCP Server

stdio MCP bridge for Qt apps that embed **QInspector**. This process **listens** on TCP; apps connect out as clients (default `127.0.0.1:9876`). Up to 8 apps can be connected at once.

```text
Agent  --stdio MCP-->  qinspector-mcp  --TCP-->  Qt app(s) with QInspector
```

Your Qt app must call `QInspector::Connect()` and `Attach(...)`. See the main [QInspector](https://github.com/DebiruC/QInspector) repository for the C++ library and demos.

## Install

Requires [uv](https://docs.astral.sh/uv/) (recommended) or Python ≥ 3.10.

```bash
uvx qinspector-mcp
```

Other options:

```bash
# from Git
uvx --from "git+https://github.com/DebiruC/QInspector.git#subdirectory=mcp" qinspector-mcp

# from a local clone
uvx --from /path/to/QInspector/mcp qinspector-mcp

# pip
pip install qinspector-mcp
qinspector-mcp
```

Only one process may bind the configured port (default `9876`).

## MCP host config

Add to Claude Code, Cursor, or any host that supports MCP stdio servers:

```json
{
  "mcpServers": {
    "qinspector": {
      "command": "uvx",
      "args": ["qinspector-mcp"],
      "env": {
        "QINSPECTOR_HOST": "127.0.0.1",
        "QINSPECTOR_PORT": "9876",
        "QINSPECTOR_RPC_TIMEOUT": "10"
      }
    }
  }
}
```

From Git instead of PyPI:

```json
{
  "mcpServers": {
    "qinspector": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/DebiruC/QInspector.git#subdirectory=mcp",
        "qinspector-mcp"
      ],
      "env": {
        "QINSPECTOR_HOST": "127.0.0.1",
        "QINSPECTOR_PORT": "9876"
      }
    }
  }
}
```

From a local checkout, point `--from` at your `mcp` directory (forward slashes work on Windows):

```json
{
  "mcpServers": {
    "qinspector": {
      "command": "uvx",
      "args": ["--from", "/path/to/QInspector/mcp", "qinspector-mcp"],
      "env": {
        "QINSPECTOR_HOST": "127.0.0.1",
        "QINSPECTOR_PORT": "9876"
      }
    }
  }
}
```

No `cwd` or `PYTHONPATH` is required when using `uvx`.

## Usage

1. Start the MCP server (host config or `uvx qinspector-mcp`).
2. Start your Qt app so it connects and sends `session.hello`.
3. Call `list_sessions`, then tools with the session `name` (for example `main-window` or `qtquick-main` in the demos).

### App identity

Each app sends `app.hello` with `appId` (default `QCoreApplication::applicationName()`) and `pid`. The bridge keys apps by `appId`; duplicates become `editor#2`, etc. Apps that never send `app.hello` get `app-N`.

Pass the optional tool argument `app` only when the same session name exists on more than one connected app (the error message lists candidates).

### Tools

| Tool | Purpose |
|------|---------|
| `list_sessions` | Connected apps and their sessions |
| `ping` | Health check on a session |
| `ui_tree` | UI tree under the Attach root (compact; `qt_*` chrome hidden by default) |
| `ui_properties` | Read properties of the root or a named descendant |
| `ui_set` | Write one property (requires `SetInputInjectionEnabled(true)` in the app) |
| `ui_find` | Search the full tree by class / objectName / text |
| `ui_screenshot` | Screenshot at original size (MCP image, or `save_path` to disk) |
| `ui_click` / `ui_drag` / `ui_wheel` / `ui_type` | Synthetic input (requires injection enabled) |
| `app_logs` | Captured qDebug / QML logs (requires `SetLogCaptureEnabled(true)`) |
| `wait_for` | Poll a property until it matches (MCP-side; no extra RPC) |
| `raw_call` | Raw JSON-RPC (only if `QINSPECTOR_MCP_ALLOW_RAW=1`) |

### Environment

| Variable | Default | Meaning |
|----------|---------|---------|
| `QINSPECTOR_HOST` | `127.0.0.1` | Listen address |
| `QINSPECTOR_PORT` | `9876` | Listen port |
| `QINSPECTOR_RPC_TIMEOUT` | `10` | Seconds to wait for an app response |
| `QINSPECTOR_MCP_ALLOW_RAW` | off | Enable `raw_call` |

## License

MIT
