dcc-mcp-renderdoc 0.3.2__tar.gz → 0.4.0__tar.gz

dcc_mcp_renderdoc-0.4.0/.release-please-manifest.json

@@ -0,0 +1,2 @@
+{".":"0.4.0"}
+

{dcc_mcp_renderdoc-0.3.2 → dcc_mcp_renderdoc-0.4.0}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.4.0](https://github.com/dcc-mcp/dcc-mcp-renderdoc/compare/v0.3.3...v0.4.0) (2026-07-23)
+
+
+### Features
+
+* auto-download RenderDoc runtime ([e380b95](https://github.com/dcc-mcp/dcc-mcp-renderdoc/commit/e380b95c9cd7f86a031e4634b39740111af507ec))
+
+
+### Bug Fixes
+
+* classify render work by API operation ([f5cf5a6](https://github.com/dcc-mcp/dcc-mcp-renderdoc/commit/f5cf5a69b31cd4066d47d28c6701262d3c3225ac))
+* reject captures without rendering work ([5799193](https://github.com/dcc-mcp/dcc-mcp-renderdoc/commit/57991932e74c57e2826ffba10cbb3f433e55dca7))
+
+## [0.3.3](https://github.com/dcc-mcp/dcc-mcp-renderdoc/compare/v0.3.2...v0.3.3) (2026-07-22)
+
+
+### Bug Fixes
+
+* accept POSIX target ident exit status ([e35d14e](https://github.com/dcc-mcp/dcc-mcp-renderdoc/commit/e35d14ed7dfdd429f5356ac8a5d5a98411a9dc28))
+* harden target control lifecycle ([1a1eca8](https://github.com/dcc-mcp/dcc-mcp-renderdoc/commit/1a1eca82fb453ec40b11a33791160d6074e70a6f))
+* isolate target control sidecar ([2e16b2b](https://github.com/dcc-mcp/dcc-mcp-renderdoc/commit/2e16b2b009c76136a5ad2889c4943c458401923a))
+* normalize target names across platforms ([44602a0](https://github.com/dcc-mcp/dcc-mcp-renderdoc/commit/44602a0fca3fd2749688f56f169280d18ddcb989))
+* trigger captures through RenderDoc Target Control ([68d93aa](https://github.com/dcc-mcp/dcc-mcp-renderdoc/commit/68d93aa9c0629b61cac75275ca53a55a65f29729))
+* trigger captures through target control ([f0a11c8](https://github.com/dcc-mcp/dcc-mcp-renderdoc/commit/f0a11c844a5597c0ae6b022a8ec07c32d7a15806))
+* verify target before capture trigger ([a392e9f](https://github.com/dcc-mcp/dcc-mcp-renderdoc/commit/a392e9fc974152d5d2dc183c1ed8b60ed15c2195))
+
 ## [0.3.2](https://github.com/dcc-mcp/dcc-mcp-renderdoc/compare/v0.3.1...v0.3.2) (2026-07-22)
 
 

{dcc_mcp_renderdoc-0.3.2 → dcc_mcp_renderdoc-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dcc-mcp-renderdoc
-Version: 0.3.2
+Version: 0.4.0
 Summary: RenderDoc capture and replay automation skills for DCC-MCP
 Project-URL: Homepage, https://github.com/dcc-mcp/dcc-mcp-renderdoc
 Project-URL: Repository, https://github.com/dcc-mcp/dcc-mcp-renderdoc
@@ -78,8 +78,8 @@ attach a stable session id with `--meta-json`, query `dcc-mcp-cli stats --range
 RenderDoc capture and replay automation for the DCC Model Context Protocol ecosystem.
 
 The adapter is headless-first: it reuses the official `renderdoccmd` executable for capture and
-conversion, so agents can automate graphics regression triage without keeping the RenderDoc GUI
-open or installing a second bridge.
+conversion. Delayed capture uses RenderDoc's official Target Control API through the sibling
+`qrenderdoc` bundled Python runtime, without foreground focus or synthetic keyboard input.
 
 ## Install
 
@@ -103,25 +103,37 @@ through the stable gateway at `http://127.0.0.1:9765/mcp`; set
 ## Agent workflows
 
 - Launch a game or test executable under RenderDoc and wait for a typed `.rdc` capture.
-- Trigger F12 automatically after a configurable delay, with optional child-process window focus.
-- Inject into a visible Windows process that had to be launched by a platform client, then trigger and collect a capture.
-- Inspect capture driver, machine identity, chunk version, API-call counts, and representative calls.
+- Trigger a capture through official Target Control after a configurable delay.
+- Inject into a process that had to be launched by a platform client, then trigger and collect a capture.
+- Reject no-work captures with actionable diagnostics while preserving the `.rdc` artifact.
+- Inspect capture driver, machine identity, chunk version, frame-work and Present counts, and representative calls.
 - Export a capture thumbnail for visual review.
 - Export Chrome trace JSON for timeline tooling.
 
 The capture tool launches only the explicit executable and arguments supplied by the caller. It
 never invokes a shell. Analysis tools are read-only with respect to the `.rdc` input.
 
-For interactive Windows programs, pass `trigger_after_secs` to `capture_program`. When a launcher
-creates the rendered child process, also pass `trigger_process_name`. Use `capture_process` only
-when the target is already running; late injection may not capture graphics devices created before
-RenderDoc was attached.
+Pass `trigger_after_secs` to `capture_program` for a Target Control trigger. This requires
+`qrenderdoc` beside `renderdoccmd`. The official RenderDoc runtime supports Windows and Linux;
+macOS is covered only by this project's Python unit tests. Linux Target Control requires an X or
+Wayland display, so headless hosts must run under Xvfb (or explicitly configure a working Qt
+platform). The official Linux archive does not bundle Qt's `offscreen` platform plugin. Each
+sidecar uses an isolated Qt data profile with RenderDoc analytics explicitly opted out, preventing
+the first-run consent dialog without reading or changing the user's qrenderdoc configuration.
+
+When a launcher creates the rendered child process, set `hook_children=true` and pass
+`trigger_process_name`. The adapter first checks the launched target itself; if its name does not
+match, it follows only that target's official `NewChild` messages to find a unique named child. A
+child name without child hooking fails before launch. Use `capture_process` only when the target is
+already running; late injection may not capture graphics devices created before RenderDoc was
+attached.
 
 ## Real CI
 
-CI discovers the current stable RenderDoc build from the official downloads page. It compiles a
-small OpenGL program, captures a real frame under Xvfb, calls the MCP analysis tool against the
-resulting `.rdc`, and verifies thumbnail and timeline exports.
+CI discovers the current stable Linux RenderDoc build from the official downloads page. It
+compiles a small OpenGL program, requests a real frame through Target Control under Xvfb using
+Qt's bundled `xcb` platform, asserts the structured trigger mode, calls the MCP analysis tool
+against the resulting `.rdc`, and verifies thumbnail and timeline exports.
 
 ## Development
 

{dcc_mcp_renderdoc-0.3.2 → dcc_mcp_renderdoc-0.4.0}/README.md

@@ -50,8 +50,8 @@ attach a stable session id with `--meta-json`, query `dcc-mcp-cli stats --range
 RenderDoc capture and replay automation for the DCC Model Context Protocol ecosystem.
 
 The adapter is headless-first: it reuses the official `renderdoccmd` executable for capture and
-conversion, so agents can automate graphics regression triage without keeping the RenderDoc GUI
-open or installing a second bridge.
+conversion. Delayed capture uses RenderDoc's official Target Control API through the sibling
+`qrenderdoc` bundled Python runtime, without foreground focus or synthetic keyboard input.
 
 ## Install
 
@@ -75,25 +75,37 @@ through the stable gateway at `http://127.0.0.1:9765/mcp`; set
 ## Agent workflows
 
 - Launch a game or test executable under RenderDoc and wait for a typed `.rdc` capture.
-- Trigger F12 automatically after a configurable delay, with optional child-process window focus.
-- Inject into a visible Windows process that had to be launched by a platform client, then trigger and collect a capture.
-- Inspect capture driver, machine identity, chunk version, API-call counts, and representative calls.
+- Trigger a capture through official Target Control after a configurable delay.
+- Inject into a process that had to be launched by a platform client, then trigger and collect a capture.
+- Reject no-work captures with actionable diagnostics while preserving the `.rdc` artifact.
+- Inspect capture driver, machine identity, chunk version, frame-work and Present counts, and representative calls.
 - Export a capture thumbnail for visual review.
 - Export Chrome trace JSON for timeline tooling.
 
 The capture tool launches only the explicit executable and arguments supplied by the caller. It
 never invokes a shell. Analysis tools are read-only with respect to the `.rdc` input.
 
-For interactive Windows programs, pass `trigger_after_secs` to `capture_program`. When a launcher
-creates the rendered child process, also pass `trigger_process_name`. Use `capture_process` only
-when the target is already running; late injection may not capture graphics devices created before
-RenderDoc was attached.
+Pass `trigger_after_secs` to `capture_program` for a Target Control trigger. This requires
+`qrenderdoc` beside `renderdoccmd`. The official RenderDoc runtime supports Windows and Linux;
+macOS is covered only by this project's Python unit tests. Linux Target Control requires an X or
+Wayland display, so headless hosts must run under Xvfb (or explicitly configure a working Qt
+platform). The official Linux archive does not bundle Qt's `offscreen` platform plugin. Each
+sidecar uses an isolated Qt data profile with RenderDoc analytics explicitly opted out, preventing
+the first-run consent dialog without reading or changing the user's qrenderdoc configuration.
+
+When a launcher creates the rendered child process, set `hook_children=true` and pass
+`trigger_process_name`. The adapter first checks the launched target itself; if its name does not
+match, it follows only that target's official `NewChild` messages to find a unique named child. A
+child name without child hooking fails before launch. Use `capture_process` only when the target is
+already running; late injection may not capture graphics devices created before RenderDoc was
+attached.
 
 ## Real CI
 
-CI discovers the current stable RenderDoc build from the official downloads page. It compiles a
-small OpenGL program, captures a real frame under Xvfb, calls the MCP analysis tool against the
-resulting `.rdc`, and verifies thumbnail and timeline exports.
+CI discovers the current stable Linux RenderDoc build from the official downloads page. It
+compiles a small OpenGL program, requests a real frame through Target Control under Xvfb using
+Qt's bundled `xcb` platform, asserts the structured trigger mode, calls the MCP analysis tool
+against the resulting `.rdc`, and verifies thumbnail and timeline exports.
 
 ## Development
 

{dcc_mcp_renderdoc-0.3.2 → dcc_mcp_renderdoc-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dcc-mcp-renderdoc"
-version = "0.3.2"
+version = "0.4.0"
 description = "RenderDoc capture and replay automation skills for DCC-MCP"
 readme = "README.md"
 requires-python = ">=3.9"

{dcc_mcp_renderdoc-0.3.2 → dcc_mcp_renderdoc-0.4.0}/release-please-config.json

@@ -1 +1 @@
-{"packages":{".":{"release-type":"python","package-name":"dcc-mcp-renderdoc","changelog-path":"CHANGELOG.md","include-component-in-tag":false,"extra-files":[{"type":"toml","path":"pyproject.toml","jsonpath":"$.project.version"},{"type":"generic","path":"src/dcc_mcp_renderdoc/__version__.py"},{"type":"toml","path":"uv.lock","jsonpath":"$.package[?(@.name=='dcc-mcp-renderdoc')].version"}]}}}
+{"packages":{".":{"release-type":"python","package-name":"dcc-mcp-renderdoc","changelog-path":"CHANGELOG.md","include-component-in-tag":false,"extra-files":[{"type":"toml","path":"pyproject.toml","jsonpath":"$.project.version"},{"type":"generic","path":"src/dcc_mcp_renderdoc/__version__.py"},{"type":"generic","path":"uv.lock"}]}}}

dcc_mcp_renderdoc-0.4.0/src/dcc_mcp_renderdoc/__version__.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "0.4.0"  # x-release-please-version

dcc_mcp_renderdoc-0.4.0/src/dcc_mcp_renderdoc/_target_control.py

@@ -0,0 +1,185 @@
+"""RenderDoc 1.45 bundled-Python bridge for headless Target Control capture."""
+
+import json
+import os
+import time
+
+
+def _positive_int(name):
+    value = int(os.environ[name])
+    if value <= 0:
+        raise ValueError("{} must be positive".format(name))
+    return value
+
+
+def _nonnegative_float(name):
+    value = float(os.environ[name])
+    if value < 0:
+        raise ValueError("{} must not be negative".format(name))
+    return value
+
+
+def _open_target(rd, ident):
+    target = rd.CreateTargetControl("", ident, "dcc-mcp-renderdoc", False)
+    if target is None:
+        raise RuntimeError("RenderDoc target ident {} is busy or unavailable".format(ident))
+    if not target.Connected():
+        busy_client = target.GetBusyClient()
+        detail = " (busy client: {})".format(busy_client) if busy_client else ""
+        target.Shutdown()
+        raise RuntimeError("could not connect to RenderDoc target ident {}{}".format(ident, detail))
+    return target
+
+
+def _target_name_matches(actual, expected):
+    actual = str(actual).replace("\\", "/").rsplit("/", 1)[-1].casefold()
+    expected = str(expected).replace("\\", "/").rsplit("/", 1)[-1].casefold()
+    return (
+        actual == expected
+        or (actual.endswith(".exe") and actual[:-4] == expected)
+        or (expected.endswith(".exe") and expected[:-4] == actual)
+    )
+
+
+def _wait_for_child_target(rd, parent, target_name, trigger_at, deadline):
+    matches = []
+    quiet_deadline = None
+    try:
+        while time.monotonic() < deadline:
+            now = time.monotonic()
+            if (
+                len(matches) == 1
+                and quiet_deadline is not None
+                and now >= trigger_at
+                and now >= quiet_deadline
+            ):
+                return matches.pop()
+            message = parent.ReceiveMessage(None)
+            if message is not None and message.type == rd.TargetControlMessageType.NewChild:
+                child_ident = int(message.newChild.ident)
+                child_pid = int(message.newChild.processId)
+                child = _open_target(rd, child_ident)
+                try:
+                    if int(child.GetPID()) != child_pid:
+                        raise RuntimeError(
+                            "RenderDoc child target PID did not match NewChild message"
+                        )
+                    if _target_name_matches(child.GetTarget(), target_name):
+                        matches.append(child)
+                        child = None
+                finally:
+                    if child is not None:
+                        child.Shutdown()
+                if matches:
+                    if len(matches) > 1:
+                        raise RuntimeError("multiple child targets matched {}".format(target_name))
+                    quiet_deadline = time.monotonic() + 0.25
+                    if quiet_deadline > deadline:
+                        raise RuntimeError("insufficient time to select a unique child target")
+                continue
+            if message is not None and message.type == rd.TargetControlMessageType.Disconnected:
+                if len(matches) == 1:
+                    return matches.pop()
+                raise RuntimeError("RenderDoc parent Target Control disconnected before child")
+            for match in matches:
+                child_message = match.ReceiveMessage(None)
+                if (
+                    child_message is not None
+                    and child_message.type == rd.TargetControlMessageType.Disconnected
+                ):
+                    raise RuntimeError("RenderDoc child Target Control disconnected before trigger")
+            time.sleep(0.05)
+        if len(matches) == 1:
+            raise RuntimeError("insufficient time to select a unique child target")
+        raise RuntimeError("no child target matched {}".format(target_name))
+    finally:
+        for match in matches:
+            match.Shutdown()
+
+
+def _pump_until(rd, target, deadline):
+    while time.monotonic() < deadline:
+        message = target.ReceiveMessage(None)
+        if message is not None and message.type == rd.TargetControlMessageType.Disconnected:
+            raise RuntimeError("RenderDoc Target Control disconnected before trigger")
+        time.sleep(0.05)
+
+
+def main():
+    status_path = os.environ.get("DCC_MCP_RENDERDOC_TARGET_STATUS")
+    status = {
+        "schema_version": 1,
+        "connected": False,
+        "triggered": False,
+        "shutdown": False,
+        "timed_out": False,
+        "target_pid": None,
+        "capture_path": None,
+        "error": None,
+    }
+    target = None
+    try:
+        import renderdoc as rd
+
+        ident = _positive_int("DCC_MCP_RENDERDOC_TARGET_IDENT")
+        capture_wait_secs = _positive_int("DCC_MCP_RENDERDOC_TARGET_TIMEOUT_SECS")
+        trigger_after_secs = _nonnegative_float("DCC_MCP_RENDERDOC_TRIGGER_AFTER_SECS")
+        target_name = os.environ.get("DCC_MCP_RENDERDOC_TARGET_NAME", "").strip()
+        expected_pid_value = os.environ.get("DCC_MCP_RENDERDOC_EXPECTED_PID", "").strip()
+        expected_pid = int(expected_pid_value) if expected_pid_value else None
+        if expected_pid is not None and expected_pid <= 0:
+            raise ValueError("DCC_MCP_RENDERDOC_EXPECTED_PID must be positive")
+        trigger_at = time.monotonic() + trigger_after_secs
+        capture_deadline = trigger_at + capture_wait_secs
+        target = _open_target(rd, ident)
+        if target_name and not _target_name_matches(target.GetTarget(), target_name):
+            child = _wait_for_child_target(rd, target, target_name, trigger_at, capture_deadline)
+            try:
+                target.Shutdown()
+            except BaseException:
+                child.Shutdown()
+                raise
+            target = child
+        status["connected"] = True
+        status["target_pid"] = int(target.GetPID())
+        if expected_pid is not None and status["target_pid"] != expected_pid:
+            raise RuntimeError(
+                "RenderDoc target PID {} did not match expected PID {}".format(
+                    status["target_pid"], expected_pid
+                )
+            )
+        _pump_until(rd, target, trigger_at)
+        target.TriggerCapture(1)
+        status["triggered"] = True
+        while time.monotonic() < capture_deadline:
+            message = target.ReceiveMessage(None)
+            if message is not None and message.type == rd.TargetControlMessageType.NewCapture:
+                status["capture_path"] = str(message.newCapture.path)
+                break
+            if message is not None and message.type == rd.TargetControlMessageType.Disconnected:
+                raise RuntimeError("RenderDoc Target Control disconnected before capture")
+            time.sleep(0.05)
+        if status["capture_path"] is None:
+            status["timed_out"] = True
+            raise RuntimeError("timed out waiting for RenderDoc NewCapture")
+    except BaseException as exc:
+        status["error"] = str(exc)
+    finally:
+        if target is not None:
+            try:
+                target.Shutdown()
+                status["shutdown"] = True
+                target = None
+            except BaseException as exc:
+                status["error"] = status["error"] or ("Target Control shutdown failed: " + str(exc))
+        if status_path:
+            with open(status_path, "w") as status_file:
+                json.dump(status, status_file)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except BaseException:
+        pass
+    raise SystemExit(0)

dcc_mcp_renderdoc-0.4.0/src/dcc_mcp_renderdoc/downloader.py

@@ -0,0 +1,88 @@
+"""Download and cache the official RenderDoc command-line bundle."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import sys
+import tarfile
+import urllib.request
+import zipfile
+from pathlib import Path
+
+
+def _cache_root() -> Path:
+    configured = os.environ.get("DCC_MCP_RUNTIME_CACHE")
+    if configured:
+        return Path(configured).expanduser().resolve() / "renderdoc"
+    if os.name == "nt":
+        root = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData/Local"))
+        return root / "dcc-mcp/renderdoc"
+    return Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "dcc-mcp/renderdoc"
+
+
+def _safe_destination(root: Path, member_name: str) -> Path:
+    destination = (root / member_name).resolve()
+    try:
+        destination.relative_to(root.resolve())
+    except ValueError as exc:
+        raise RuntimeError(f"Archive member escapes destination: {member_name}") from exc
+    return destination
+
+
+def _extract(archive: Path, destination: Path) -> None:
+    destination.mkdir(parents=True, exist_ok=True)
+    if zipfile.is_zipfile(archive):
+        with zipfile.ZipFile(archive) as bundle:
+            for member in bundle.infolist():
+                _safe_destination(destination, member.filename)
+            bundle.extractall(destination)
+        return
+    with tarfile.open(archive, "r:gz") as bundle:
+        for member in bundle.getmembers():
+            _safe_destination(destination, member.name)
+            if member.issym() or member.islnk():
+                raise RuntimeError(f"Archive links are not accepted: {member.name}")
+        bundle.extractall(destination)
+
+
+def download_latest() -> Path:
+    request = urllib.request.Request(
+        "https://renderdoc.org/builds", headers={"User-Agent": "dcc-mcp-renderdoc"}
+    )
+    with urllib.request.urlopen(request, timeout=30) as response:
+        html = response.read().decode("utf-8")
+    versions = set(re.findall(r"/stable/([0-9]+\.[0-9]+)/", html))
+    if not versions:
+        raise RuntimeError("No stable RenderDoc versions found on the official builds page")
+    version = max(versions, key=lambda value: tuple(int(part) for part in value.split(".")))
+    if sys.platform == "win32":
+        archive_name, command_name = f"RenderDoc_{version}_64.zip", "renderdoccmd.exe"
+    elif sys.platform.startswith("linux"):
+        archive_name, command_name = f"renderdoc_{version}.tar.gz", "renderdoccmd"
+    else:
+        raise RuntimeError(f"RenderDoc has no supported desktop bundle for {sys.platform}")
+    destination = _cache_root() / version
+    existing = next(destination.rglob(command_name), None) if destination.exists() else None
+    if existing:
+        return existing.resolve()
+    archive = _cache_root() / archive_name
+    _cache_root().mkdir(parents=True, exist_ok=True)
+    try:
+        with (
+            urllib.request.urlopen(
+                f"https://renderdoc.org/stable/{version}/{archive_name}", timeout=120
+            ) as response,
+            archive.open("wb") as stream,
+        ):
+            shutil.copyfileobj(response, stream)
+        _extract(archive, destination)
+    finally:
+        archive.unlink(missing_ok=True)
+    command = next(destination.rglob(command_name), None)
+    if command is None:
+        raise RuntimeError(f"Downloaded bundle did not contain {command_name}")
+    if sys.platform.startswith("linux"):
+        command.chmod(command.stat().st_mode | 0o111)
+    return command.resolve()