qt-commander-mcp 0.9.0__tar.gz

qt_commander_mcp-0.9.0/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,json,md,toml}]
+indent_size = 2
+
+[*.{bat,cmd}]
+end_of_line = crlf
+
+[*.{h,cpp}]
+indent_size = 4

qt_commander_mcp-0.9.0/.gitattributes

@@ -0,0 +1,18 @@
+# Normalize on checkout so Windows and Linux contributors produce identical
+# diffs; the repository stores LF.
+* text=auto eol=lf
+
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+*.dll binary
+*.exe binary
+*.so binary
+*.dylib binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.zip binary
+*.ico binary

qt_commander_mcp-0.9.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,57 @@
+name: Bug report
+description: Attach failed, a tool returned something wrong, or the build broke
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before filing, run `qt-commander doctor --json` and paste the output
+        below. Most "cannot attach" reports are answered by it already.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you ran, and the full error/tool output (JSON preferred).
+      placeholder: |
+        qt_attach(pid=1234, mode="injection") returned
+        {"error": {"code": "E_INJECTION_FAILED", "reason": "...", ...}}
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+  - type: dropdown
+    id: mode
+    attributes:
+      label: Attach mode
+      options:
+        - injection (closed-source target)
+        - linked (qt_commander::start() in the app)
+        - not attached yet (build/install problem)
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: "`qt-commander doctor --json`"
+      description: Paste the whole JSON. Redact paths if you must.
+      render: json
+    validations:
+      required: true
+  - type: input
+    id: versions
+    attributes:
+      label: Versions
+      description: qt-commander, Qt version, target architecture, OS, MCP client
+      placeholder: "qt-commander 2.1.0, Qt 5.15.2, x64, Windows 11, Claude Code"
+    validations:
+      required: true
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else
+      description: Logs, screenshots, whether an injector was already loaded, recent rebuilds.

qt_commander_mcp-0.9.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Usage questions and ideas
+    url: https://github.com/tiefeiyu/qt-commander/discussions
+    about: Ask how to automate a specific Qt app, share recipes, or discuss the roadmap.
+  - name: Security issue
+    url: https://github.com/tiefeiyu/qt-commander/security/policy
+    about: Please report vulnerabilities privately, not as a public issue.

qt_commander_mcp-0.9.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,43 @@
+name: Feature request
+description: A tool, argument or behaviour you need for your Qt application
+title: "[feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Describe the task an agent was trying to do, not the API you have in
+        mind — the driver is what an agent needs to accomplish.
+  - type: textarea
+    id: task
+    attributes:
+      label: The task
+      description: What should an agent be able to do that it cannot do today?
+      placeholder: |
+        "Open the Settings dialog, switch the theme, and confirm it survived a restart."
+    validations:
+      required: true
+  - type: textarea
+    id: blocked
+    attributes:
+      label: What blocks it today
+      description: Which tool, error or missing information gets in the way?
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - attach / inject / artifacts
+        - query / items / get / set
+        - act / call / batch / wait / expect
+        - screenshot / annotate
+        - source mapping
+        - MCP surface (tools, resources, prompts)
+        - docs / packaging
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Target application
+      description: Framework (QWidget / QML / mixed), Qt version, closed or open source, platform.

qt_commander_mcp-0.9.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,21 @@
+## What this changes
+
+<!-- One or two sentences. Link the issue if there is one. -->
+
+## Why
+
+<!-- The behaviour or bug that motivated it. "Because it is cleaner" is fine if true. -->
+
+## Checklist
+
+- [ ] `uv run pytest -q` passes locally
+- [ ] New behaviour has a test (unit test, or an E2E script entry if it needs a real target)
+- [ ] Tool descriptions / `INSTRUCTIONS` updated if the agent-facing contract changed
+- [ ] `CHANGELOG.md` has an entry under `## [Unreleased]` for user-visible changes
+- [ ] Docs updated (README / docs/design.md / ROADMAP.md) where behaviour is described
+- [ ] No binaries or build output committed (`artifacts/`, `build/`, `dist/`)
+- [ ] If a tool response grew, it is still budgeted (limits, `compact`, truncation signals)
+
+## Notes for the reviewer
+
+<!-- Anything subtle: Windows/Linux differences, C++ changes, compatibility of artifact/manifest fields. -->

qt_commander_mcp-0.9.0/.github/workflows/ci.yml

@@ -0,0 +1,243 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  python:
+    name: python ${{ matrix.python }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # git describe needs the tags for the version
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Install
+        run: uv sync --python ${{ matrix.python }}
+      - name: Tests
+        run: uv run pytest -q
+      - name: CLI smoke
+        run: |
+          uv run qt-commander --version
+          uv run qt-commander doctor --json
+
+  package:
+    name: wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # git describe needs the tags for the version
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Build
+        run: uv build
+      - name: Install the wheel into a clean environment
+        run: |
+          uv venv .venv-check
+          uv pip install --python .venv-check/bin/python dist/*.whl
+          .venv-check/bin/qt-commander --version
+          .venv-check/bin/qt-commander doctor --json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-packages
+          path: dist/*
+          if-no-files-found: error
+
+  # Builds the injector/runtime for the platforms we can install Qt for on CI
+  # runners. First run will need tuning: pin the kits, and check that
+  # `scripts/package_artifacts.py` names the archive exactly as
+  # `qt-commander install-artifacts` expects.
+  cpp:
+    name: cpp / qt ${{ matrix.qt }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Linux Qt 5.15.2 is deliberately absent: aqtinstall cannot resolve
+          # the 5.15.2 packages for linux ("packages ['qt_base'] were not
+          # found"). A Qt 5 linux runtime can be built locally with
+          # scripts/package_artifacts.py.
+          - os: ubuntu-latest
+            qt: "6.8.3"
+            qt_major: "6"
+            arch: linux_gcc_64
+            toolchain: gcc
+          - os: windows-latest
+            qt: "5.15.2"
+            qt_major: "5"
+            arch: win64_msvc2019_64
+            toolchain: msvc
+          - os: windows-latest
+            qt: "6.8.3"
+            qt_major: "6"
+            arch: win64_msvc2022_64
+            toolchain: msvc
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # git describe needs the tags for the version
+      - name: MSVC environment
+        if: runner.os == 'Windows'
+        uses: ilammy/msvc-dev-cmd@v1
+      - uses: jurplel/install-qt-action@v4
+        with:
+          version: ${{ matrix.qt }}
+          host: ${{ runner.os == 'Windows' && 'windows' || 'linux' }}
+          target: desktop
+          arch: ${{ matrix.arch }}
+          cache: true
+      - name: Build dependencies
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ninja-build libgl1-mesa-dev libxkbcommon-x11-0
+      - name: Configure
+        run: >
+          cmake -S . -B build/ci -G Ninja
+          -DCMAKE_BUILD_TYPE=Release
+          -DQT_MAJOR_VERSION=${{ matrix.qt_major }}
+      - name: Build
+        run: cmake --build build/ci
+      - name: Package artifact layout
+        run: >
+          python scripts/package_artifacts.py
+          --build-dir build/ci
+          --qt-version ${{ matrix.qt }}
+          --toolchain ${{ matrix.toolchain }}
+          --build-type Release
+          --qt-release
+          --archive-dir dist/artifacts
+          --github-output
+      - uses: actions/upload-artifact@v4
+        with:
+          name: artifacts-${{ matrix.os }}-qt${{ matrix.qt }}
+          path: dist/artifacts/*.zip
+          if-no-files-found: error
+      # Launch-time injection (LD_PRELOAD) is a Linux-only path here: Windows
+      # has no preload hook and does not register the qt_launch tool.
+      - uses: astral-sh/setup-uv@v5
+        if: runner.os == 'Linux'
+        with:
+          enable-cache: true
+      - name: Build the injection test app
+        if: runner.os == 'Linux'
+        run: |
+          cmake -S tests/test-apps/injected -B build/injected \
+            -DQT_MAJOR_VERSION=${{ matrix.qt_major }}
+          cmake --build build/injected
+      - name: Launch-time injection e2e
+        if: runner.os == 'Linux'
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: |
+          uv sync --quiet
+          export QT_COMMANDER_RENDEZVOUS="$RUNNER_TEMP/rendezvous-launch"
+          mkdir -p "$QT_COMMANDER_RENDEZVOUS"
+          library=$(ls artifacts/*/*/*/lib/libqt_commander_inject.so | head -1)
+          echo "library: $library"
+          uv run python scripts/launch_e2e.py \
+            --program build/injected/qt-injected-test \
+            --library "$library"
+
+  # macOS has no injector (linked mode only — see docs/design.md §8), so there
+  # is no artifact to package here. This job builds the static runtime plus the
+  # linked test app and drives it through the real session path, which is the
+  # only macOS code path the project claims to support.
+  macos-linked:
+    name: macos / linked e2e
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # git describe needs the tags for the version
+      - uses: jurplel/install-qt-action@v4
+        with:
+          version: "6.8.3"
+          host: mac
+          target: desktop
+          arch: clang_64
+          cache: true
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Install
+        run: uv sync --python 3.13
+      - name: Work around Qt 6.8.3 linking a framework macOS removed
+        run: |
+          # Qt 6.8.3's FindWrapOpenGL.cmake emits "-framework AGL" even when AGL
+          # is absent, and the macOS 26 SDK no longer ships AGL. Upstream fixed
+          # this in 6.8.4 / 6.9, so this step becomes a no-op once the kit moves.
+          python3 - "$QT_ROOT_DIR/lib/cmake/Qt6/FindWrapOpenGL.cmake" <<'PY'
+          import pathlib
+          import sys
+
+          path = pathlib.Path(sys.argv[1])
+          text = path.read_text()
+          needle = (
+              "        target_link_libraries(WrapOpenGL::WrapOpenGL INTERFACE "
+              "${__opengl_agl_fw_path})\n"
+          )
+          if needle in text:
+              path.write_text(text.replace(needle, ""))
+              print("patched AGL link out of", path)
+          else:
+              print("no AGL link line in", path, "- nothing to do")
+          PY
+      - name: Build runtime, injection library and linked test app
+        run: |
+          cmake -S tests/test-apps/linked -B build/linked \
+            -DCMAKE_BUILD_TYPE=Release -DQT_MAJOR_VERSION=6
+          cmake --build build/linked
+          ls -l build/linked/qt-commander/*.dylib
+      - name: Drive the linked app
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: |
+          set -euo pipefail
+          export QT_COMMANDER_RENDEZVOUS="$RUNNER_TEMP/rendezvous"
+          mkdir -p "$QT_COMMANDER_RENDEZVOUS"
+          ./build/linked/qt-linked-test &
+          APP_PID=$!
+          trap 'kill "$APP_PID" 2>/dev/null || true' EXIT
+          descriptor=""
+          for _ in $(seq 1 100); do
+            descriptor=$(ls "$QT_COMMANDER_RENDEZVOUS"/descriptor-*.json 2>/dev/null | head -1 || true)
+            [ -n "$descriptor" ] && break
+            sleep 0.2
+          done
+          if [ -z "$descriptor" ]; then
+            echo "no descriptor appeared; is the app running?" >&2
+            exit 1
+          fi
+          uv run python scripts/linked_smoke.py --descriptor "$descriptor"
+      - name: Build the injection test app
+        run: |
+          cmake -S tests/test-apps/injected -B build/injected \
+            -DCMAKE_BUILD_TYPE=Release -DQT_MAJOR_VERSION=6
+          cmake --build build/injected
+      - name: Launch-time injection e2e (DYLD_INSERT_LIBRARIES)
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: |
+          export QT_COMMANDER_RENDEZVOUS="$RUNNER_TEMP/rendezvous-launch"
+          mkdir -p "$QT_COMMANDER_RENDEZVOUS"
+          uv run python scripts/launch_e2e.py \
+            --program build/injected/qt-injected-test \
+            --library build/linked/qt-commander/libqt_commander_inject.dylib

qt_commander_mcp-0.9.0/.github/workflows/release.yml

@@ -0,0 +1,168 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-python:
+    name: python packages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # git describe needs the tags for the version
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv build
+      - name: Verify the wheel installs and runs
+        run: |
+          uv venv .venv-check
+          uv pip install --python .venv-check/bin/python dist/*.whl
+          .venv-check/bin/qt-commander --version
+          .venv-check/bin/qt-commander doctor --json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-packages
+          path: dist/*
+          if-no-files-found: error
+
+  artifacts:
+    name: artifact / qt ${{ matrix.qt }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Linux Qt 5.15.2 is deliberately absent: aqtinstall cannot resolve
+          # the 5.15.2 packages for linux ("packages ['qt_base'] were not
+          # found"). Build a Qt 5 linux runtime locally with
+          # scripts/package_artifacts.py.
+          - os: ubuntu-latest
+            qt: "6.8.3"
+            qt_major: "6"
+            arch: linux_gcc_64
+            toolchain: gcc
+          - os: windows-latest
+            qt: "5.15.2"
+            qt_major: "5"
+            arch: win64_msvc2019_64
+            toolchain: msvc
+          - os: windows-latest
+            qt: "6.8.3"
+            qt_major: "6"
+            arch: win64_msvc2022_64
+            toolchain: msvc
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # git describe needs the tags for the version
+      - name: MSVC environment
+        if: runner.os == 'Windows'
+        uses: ilammy/msvc-dev-cmd@v1
+      - uses: jurplel/install-qt-action@v4
+        with:
+          version: ${{ matrix.qt }}
+          host: ${{ runner.os == 'Windows' && 'windows' || 'linux' }}
+          target: desktop
+          arch: ${{ matrix.arch }}
+          cache: true
+      - name: Build dependencies
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ninja-build libgl1-mesa-dev libxkbcommon-x11-0
+      - name: Configure
+        run: >
+          cmake -S . -B build/rel -G Ninja
+          -DCMAKE_BUILD_TYPE=Release
+          -DQT_MAJOR_VERSION=${{ matrix.qt_major }}
+      - name: Build
+        run: cmake --build build/rel
+      - name: Package artifact archive
+        id: package
+        run: >
+          python scripts/package_artifacts.py
+          --build-dir build/rel
+          --qt-version ${{ matrix.qt }}
+          --toolchain ${{ matrix.toolchain }}
+          --build-type Release
+          --qt-release
+          --archive-dir dist/assets
+          --github-output
+      - uses: actions/upload-artifact@v4
+        with:
+          name: artifact-${{ matrix.os }}-qt${{ matrix.qt }}
+          path: dist/assets/*.zip
+          if-no-files-found: error
+
+  checksums:
+    name: SHA256SUMS
+    needs: artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: artifact-*
+          path: assets
+          merge-multiple: true
+      - name: Generate sums
+        working-directory: assets
+        run: |
+          python -c "import hashlib,pathlib; [print(hashlib.sha256(p.read_bytes()).hexdigest() + '  ' + p.name) for p in sorted(pathlib.Path('.').glob('*.zip'))]" > SHA256SUMS
+          cat SHA256SUMS
+      - uses: actions/upload-artifact@v4
+        with:
+          name: artifact-sums
+          path: assets/SHA256SUMS
+          if-no-files-found: error
+
+  github-release:
+    name: GitHub release
+    needs: [build-python, artifacts, checksums]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: "*"
+          path: assets
+          merge-multiple: true
+      - name: Publish
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          tag="${GITHUB_REF_NAME}"
+          if [ -z "$tag" ] || [ "$tag" = "master" ]; then
+            echo "workflow_dispatch without a tag ref; nothing to publish"
+            exit 0
+          fi
+          gh release view "$tag" >/dev/null 2>&1 || \
+            gh release create "$tag" --generate-notes --title "qt-commander $tag"
+          gh release upload "$tag" assets/* --clobber
+
+  # Trusted Publishing; no API token is stored in the repository. Set the
+  # repository variable PYPI_PUBLISH=true once the publisher is configured on
+  # PyPI, otherwise this job is a no-op (see docs/release/RELEASE-CHECKLIST.md).
+  pypi:
+    name: PyPI
+    needs: build-python
+    if: vars.PYPI_PUBLISH == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/qt-commander-mcp
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-packages
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

qt_commander_mcp-0.9.0/.gitignore

@@ -0,0 +1,29 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+artifacts/
+.venv/
+.test-venv/
+.pytest_cache/
+.test-workspace/
+.codegraph/
+.portal/
+# Local triage notes and feedback: useful while working, not part of the
+# published documentation (that lives in docs/).
+dev-docs/
+*.o
+*.obj
+*.exe
+*.dll
+*.so
+*.dylib
+.superpowers/
+*.gcov
+*.gcda
+*.gcno
+.coverage
+*.tmp
+.vscode/
+portal.db