metal-gpu-trace 0.4.0__py3-none-any.whl

metal_gpu_trace/data/apple-gpu-families.json

@@ -0,0 +1,63 @@
+{
+  "about": "Apple silicon GPU families Apple7 to Apple10: chips, first family with each feature, and limits that differ. Facts restated from Apple's public documents, not Apple's text. Check a device with MTLDevice.supportsFamily; families nest, so an Apple9 GPU also supports Apple7 and Apple8.",
+  "sources": {
+    "families": "https://developer.apple.com/documentation/metal/mtlgpufamily",
+    "feature_set_tables": "https://developer.apple.com/metal/Metal-Feature-Set-Tables.pdf",
+    "feature_set_tables_date": "2026-05-21",
+    "m3_tech_talk": "https://developer.apple.com/videos/play/tech-talks/111375/"
+  },
+  "guards": {
+    "M1 only": "Apple7 && !Apple8",
+    "before M3": "!Apple9"
+  },
+  "families": {
+    "Apple7": {
+      "mac_chips": ["M1", "M1 Pro", "M1 Max", "M1 Ultra"],
+      "other_chips": ["A14"],
+      "adds": ["mesh shading", "SIMD-scoped and quad-scoped reductions", "SIMD-scoped matrix multiply",
+               "floating-point atomics", "primitive ID", "barycentric coordinates", "border color",
+               "layered rendering to multisample textures", "MetalFX temporal upscaling",
+               "acquire/release memory ordering atomics", "Metal 4"],
+      "limits": {"mesh_grid_threadgroups": 1024, "argument_buffer_samplers_per_stage": 996,
+                 "mesh_payload_and_geometry_per_draw": "up to 4 GB", "texture_2d_px": 16384}
+    },
+    "Apple8": {
+      "mac_chips": ["M2 series"],
+      "other_chips": ["A15", "A16"],
+      "adds": ["lossy texture compression", "SIMD shift and fill", "sparse depth/stencil on every device",
+               "placement sparse on every device", "query texture LOD on every device",
+               "64-bit atomic min/max on ulong in buffers and textures, macOS only"],
+      "limits": {"mesh_grid_threadgroups": 1024, "argument_buffer_samplers_per_stage": 996,
+                 "mesh_payload_and_geometry_per_draw": "up to 4 GB", "texture_2d_px": 16384}
+    },
+    "Apple9": {
+      "mac_chips": ["M3 series", "M4 series"],
+      "other_chips": ["A17 Pro", "A18"],
+      "adds": ["full 64-bit atomics", "BC pixel formats on every device", "mesh draws in indirect command buffers",
+               "indirect mesh draw arguments", "ICB memory barriers for rendering",
+               "row-major matrices in acceleration structures", "per-component motion in ray tracing",
+               "MetalFX denoised upscaling", "Dynamic Caching (registers allocated as the program runs)"],
+      "limits": {"mesh_grid_threadgroups": 1048575, "argument_buffer_samplers_per_stage": 500000,
+                 "mesh_payload_and_geometry_per_draw": "not stated", "texture_2d_px": 16384}
+    },
+    "Apple10": {
+      "mac_chips": ["M5 series"],
+      "other_chips": ["A19"],
+      "adds": ["depth bounds testing", "sampler min/max reduction", "sampler LOD bias",
+               "pre-raster per-vertex values", "ICB raster and depth/stencil state", "atomics on cube map textures",
+               "universal texture compression", "32 768 px textures", "16x16 tiles with 8x MSAA"],
+      "limits": {"mesh_grid_threadgroups": 4194303, "argument_buffer_samplers_per_stage": 500000,
+                 "mesh_payload_and_geometry_per_draw": "not stated", "texture_2d_px": 32768}
+    }
+  },
+  "same_on_all": {"threads_per_threadgroup": 1024, "threadgroup_memory_bytes": 32768,
+                  "mesh_pipeline_payload_bytes": 16384,
+                  "argument_buffer_textures_or_buffers_per_stage": 1000000},
+  "footnotes": [
+    "64-bit atomics: none on Apple7; Apple8 has only ulong min/max, only on macOS; the full set starts with Apple9.",
+    "Mesh draws in indirect command buffers start with Apple9; earlier families refuse such mesh pipelines.",
+    "Inline constexpr samplers count toward the argument buffer sampler limit.",
+    "Mesh shaders on Apple7 and Apple8 can use up to 4 GB of payload and mesh geometry per draw.",
+    "Function pointers and ray tracing in render pipelines are not compatible with mesh shading."
+  ]
+}

metal_gpu_trace/gputrace_read.py

@@ -0,0 +1,108 @@
+"""Reads the command stream of a Metal .gputrace bundle directly, without Xcode, and summarizes it as JSON.
+
+Usage: python3 -I gputrace_read.py <capture.gputrace> [--records]
+The `capture` file is "MTSP": a 4-byte magic and a 4-byte word, then records of
+[u32 size][i32 call id][...][u32 at +0x20][signature at +0x24, NUL-padded][arguments].
+The record layout follows tmc/gputrace (MIT, https://github.com/tmc/gputrace); the 8-byte header, the call ids
+and their names below were worked out here against a capture whose command list Xcode showed (macOS 27.0.1).
+"""
+import argparse
+import collections
+import json
+import pathlib
+import re
+import struct
+import sys
+
+# call id -> (Metal call, certainty): "confirmado" matched one by one against Xcode's command list
+CALLS = {
+    -16244: ("pushDebugGroup", "confirmado"),
+    -16245: ("insertDebugSignpost", "confirmado"),
+    -16243: ("popDebugGroup", "confirmado"),
+    -16218: ("drawPrimitives", "confirmado"),
+    -16279: ("setRenderPipelineState", "confirmado"),
+    -16254: ("setDepthStencilState", "confirmado"),
+    -16253: ("setStencilReferenceValue", "confirmado"),
+    -16264: ("setTriangleFillMode", "confirmado"),
+    -16268: ("setCullMode", "confirmado"),
+    -16267: ("setDepthClipMode", "confirmado"),
+    -16266: ("setDepthBias", "confirmado"),
+    -16269: ("setFrontFacingWinding", "confirmado"),
+    -16255: ("setBlendColor", "confirmado"),
+    -16077: ("setViewports", "confirmado"),
+    -16076: ("setScissorRects", "confirmado"),
+    -16224: ("setVertexBufferOffset", "confirmado"),
+    -15819: ("useResource", "confirmado"),
+    -16353: ("renderCommandEncoder", "probable"),
+    -16246: ("endEncoding", "probable"),
+    -16343: ("commandBuffer", "probable"),
+    -10240: ("buffer contents", "probable"),
+    -15416: ("drawMeshThreadgroups", "probable"),
+    -15415: ("drawMeshThreadgroupsWithIndirectBuffer", "probable"),
+    -16327: ("dispatchThreadgroups", "probable"),
+}
+
+
+def records(path):
+    """Yields (offset, size, call id, signature, printable strings) for each record of an MTSP file."""
+    data = pathlib.Path(path).read_bytes()
+    off = 8 if data[:4] == b"MTSP" else 0
+    while off + 8 <= len(data):
+        size, call = struct.unpack_from("<Ii", data, off)
+        if size < 8 or off + size > len(data):
+            raise ValueError(f"{path}: record at 0x{off:x} has size {size}; the stream is not MTSP as expected")
+        rec = data[off:off + size]
+        signature = rec[0x24:].split(b"\0", 1)[0].decode("latin1") if size > 0x24 else ""
+        tail = rec[0x24 + len(signature) + 1:]
+        strings = [s.decode("latin1") for s in re.findall(rb"[ -~]{3,}", tail)]
+        yield off, size, call, signature, strings
+        off += size
+
+
+def summarize(capture):
+    """Returns counts of encoders, draws and debug markers, and every call id seen, for a .gputrace bundle."""
+    capture = pathlib.Path(capture)
+    stream = capture / "capture"
+    if not stream.exists():
+        raise FileNotFoundError(f"{capture} has no capture file")
+    calls, labels = collections.Counter(), collections.defaultdict(list)
+    count = 0
+    for _, _, call, signature, strings in records(stream):
+        calls[(call, signature)] += 1
+        count += 1
+        if call in (-16244, -16245) and strings:
+            labels[CALLS[call][0]].append(strings[0])
+    named = lambda call: sum(n for (c, _), n in calls.items() if c == call)
+    return {
+        "capture": capture.name,
+        "records": count,
+        "command_buffers": named(-16343),
+        "render_encoders": named(-16353),
+        # only the drawPrimitives overload seen so far; indexed, mesh and indirect draws have other ids
+        "draw_primitives": named(-16218),
+        "debug_groups": labels.get("pushDebugGroup", []),
+        "signposts": labels.get("insertDebugSignpost", []),
+        "pops": named(-16243),
+        "calls": [
+            {"id": c, "signature": s, "count": n, "name": CALLS.get(c, (None, None))[0], "certainty": CALLS.get(c, (None, None))[1]}
+            for (c, s), n in sorted(calls.items(), key=lambda kv: -kv[1])
+        ],
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("capture", type=pathlib.Path)
+    parser.add_argument("--records", action="store_true", help="print every record instead of the summary")
+    args = parser.parse_args()
+    if args.records:
+        for off, size, call, signature, strings in records(args.capture / "capture"):
+            name = CALLS.get(call, ("?", ""))[0]
+            print(f"0x{off:06x} {size:5d} {call:7d} {signature:14s} {name:26s} {strings[:3]}")
+        return
+    json.dump(summarize(args.capture), sys.stdout, indent=2, ensure_ascii=False)
+    print()
+
+
+if __name__ == "__main__":
+    main()

metal_gpu_trace/metal_trace_mcp.py

@@ -0,0 +1,422 @@
+"""MCP server (stdio, JSON-RPC 2.0, standard library only) that records Wine or macOS programs with Instruments'
+Metal System Trace and reads the recordings and Metal .gputrace captures.
+
+Environment: METAL_TRACE_OUT is where recordings go (default ./perf-runs); METAL_TRACE_READ lists more directories,
+separated by ':', whose files the tools may read; METAL_TRACE_WINE is the default Wine directory; KEEP_RUNS caps the
+recordings kept; METAL_TRACE_LOG=off silences the one stderr line per call.
+"""
+import json
+import os
+import pathlib
+import shlex
+import shutil
+import signal
+import subprocess
+import sys
+import time
+
+__version__ = "0.4.0"
+TOOLS_DIR = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(TOOLS_DIR))
+import gputrace_read  # noqa: E402
+import perf_report  # noqa: E402
+
+OUT = pathlib.Path(os.environ.get("METAL_TRACE_OUT", "perf-runs")).resolve()
+READ = [OUT] + [pathlib.Path(p).resolve() for p in os.environ.get("METAL_TRACE_READ", "").split(":") if p]
+FAMILIES = json.loads((TOOLS_DIR / "data" / "apple-gpu-families.json").read_text())
+MAX_LIMIT = 500
+# newest first; initialize answers with the client's version when listed here, else the first
+PROTOCOL_VERSIONS = ("2025-06-18", "2025-03-26", "2024-11-05")
+# results stay under Claude Code's 50 000-character limit, above which it saves them to a file
+MAX_TEXT = 40_000
+INSTRUCTIONS = (
+    "Records GPU use on Apple silicon with Metal System Trace. One recording runs at a time; keep other GPU work off "
+    "the Mac while it records. Under Wine record 30 s or more: Wine's start-up takes part of the recording. Reading a "
+    "recording back takes 1 to 9 s per recorded second. Compare only recordings with 100 frames or more, and repeat "
+    "a run before calling a change real. perf_diagnose says whether a run splits its GPU work into too many short "
+    "encoders, as translation layers do; perf_compare says how much two runs differ. trace_tables and trace_query need the .trace, kept only with KEEP_TRACE=1. "
+    "When perf_record ends it stops every program of its Wine prefix, or every process named like a native program."
+)
+
+
+class ToolError(Exception):
+    """A failure the caller can fix; its message says how."""
+
+
+def allowed(path, roots=None):
+    """Returns `path` resolved, or raises ToolError when it lies outside the readable directories."""
+    resolved = pathlib.Path(path).expanduser().resolve()
+    if not any(resolved.is_relative_to(root) for root in roots or READ):
+        raise ToolError(f"{resolved.name} is outside the readable directories; add its directory to METAL_TRACE_READ")
+    return resolved
+
+
+def name_ok(name):
+    """Returns whether `name` holds only letters, digits, '.', '_' and '-'."""
+    return name.replace("-", "").replace("_", "").replace(".", "").isalnum()
+
+
+def run_path(run):
+    """Returns the summary path of a recording named as perf_runs lists it."""
+    if not name_ok(run):
+        raise ToolError("a run name holds only letters, digits, '.', '_' and '-'; take it from perf_runs")
+    path = OUT / f"{run}.json"
+    if not path.exists():
+        raise ToolError(f"no run {run}; perf_runs lists them")
+    return path
+
+
+def trace_path(trace):
+    """Returns the .trace of a run named as perf_runs lists it, or `trace` as a path inside the readable
+    directories."""
+    if name_ok(trace):
+        return OUT / f"{trace.removesuffix('.trace')}.trace"
+    return allowed(trace)
+
+
+def page(items, offset, limit):
+    """Returns one page of `items` with the total and the offset of the next page (None at the end)."""
+    offset, limit = max(0, int(offset)), min(max(1, int(limit)), MAX_LIMIT)
+    rows = items[offset:offset + limit]
+    more = offset + len(rows) < len(items)
+    return {"total": len(items), "offset": offset, "rows": rows, "next_offset": offset + len(rows) if more else None}
+
+
+def tool_perf_record(label, program, seconds=20, wine=None, prefix=None, workdir=None, args=""):
+    """Records `program` (an .exe under Wine, or a macOS binary with wine="native") for `seconds` with Metal System
+    Trace and returns its summary: GPU ms per frame, frame intervals, FPS, Metal and resident memory. When it ends it
+    stops every program of that Wine prefix (wineserver -k), or every process named like the program with native."""
+    wine = wine or os.environ.get("METAL_TRACE_WINE")
+    if not wine:
+        raise ToolError("pass wine (a Wine directory holding bin/wine, or native) or set METAL_TRACE_WINE")
+    program = pathlib.Path(program).expanduser()
+    if not program.exists():
+        raise ToolError(f"no program at {program.name}")
+    workdir = pathlib.Path(workdir).expanduser() if workdir else program.parent
+    prefix = pathlib.Path(prefix or os.environ.get("WINEPREFIX", "~/.wine")).expanduser()
+    return record(label, seconds, wine, prefix, workdir, [str(program.resolve()), *shlex.split(args)])
+
+
+def tool_perf_attach(label, process, seconds=20):
+    """Records a program that is already running, by pid or by a name in its command line (Game.exe under Wine),
+    for `seconds` and returns the same summary as perf_record; the program keeps running. For games started by
+    Steam, CrossOver, NotProton or any launcher: start the game or its benchmark there first."""
+    return record(label, seconds, "attach", "-", "-", [str(process)])
+
+
+def deadline(seconds):
+    """Returns the seconds a recording of `seconds` may take in all; reading it back takes about 9 s per second."""
+    return int(seconds) * 10 + 120
+
+
+def record(label, seconds, wine, prefix, workdir, command):
+    """Runs perf_record.sh and returns the summary it wrote, stopping the whole recording and deleting its files if
+    it overruns."""
+    if not name_ok(label):
+        raise ToolError("label holds only letters, digits, '.', '_' and '-'")
+    env = dict(os.environ, PERF_OUT=str(OUT))
+    before = set(OUT.glob(f"{label}_*"))
+    proc = subprocess.Popen(["zsh", str(TOOLS_DIR / "perf_record.sh"), label, str(int(seconds)), str(wine),
+                             str(prefix), str(workdir), *command],
+                            stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, env=env,
+                            start_new_session=True)
+    try:
+        _, stderr = proc.communicate(timeout=deadline(seconds))
+    except subprocess.TimeoutExpired:
+        os.killpg(proc.pid, signal.SIGKILL)
+        proc.wait()
+        if wine not in ("native", "attach"):
+            subprocess.run([str(pathlib.Path(wine) / "bin" / "wineserver"), "-k"], env=dict(env, WINEPREFIX=str(prefix)),
+                           capture_output=True, timeout=30)
+        if (OUT / ".recording").is_dir():
+            (OUT / ".recording").rmdir()
+        # the partial .trace and CSVs of this run
+        for path in set(OUT.glob(f"{label}_*")) - before:
+            shutil.rmtree(path) if path.is_dir() else path.unlink()
+        raise ToolError(f"the recording took over {deadline(seconds)} s and was stopped; nothing was saved")
+    new = sorted(set(OUT.glob(f"{label}_*.json")) - before)
+    if proc.returncode or not new:
+        reason = (stderr.strip().splitlines() or ["no summary was written"])[-1]
+        raise ToolError(f"recording failed (exit {proc.returncode}): {reason}")
+    return json.loads(new[-1].read_text())
+
+
+def tool_perf_runs(offset=0, limit=50):
+    """Lists the saved recordings, newest first, with frames, FPS, GPU ms per frame and memory peaks."""
+    runs = []
+    for path in sorted(OUT.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True):
+        try:
+            s = json.loads(path.read_text())
+        except ValueError:  # a summary still being written
+            continue
+        gpu = s.get("gpu", {})
+        runs.append({"run": path.stem, "program": (s.get("process") or {}).get("arguments"),
+                     "frames": gpu.get("frames"), "fps": gpu.get("fps_estimate"),
+                     "gpu_ms_mean": (gpu.get("frame_gpu_ms") or {}).get("mean"),
+                     "metal_mib_peak": (s.get("metal_memory_mib") or {}).get("peak"),
+                     "rss_mib_max": (s.get("process_rss_mib") or {}).get("max"),
+                     "trace_kept": path.with_suffix(".trace").is_dir()})
+    return page(runs, offset, limit)
+
+
+def tool_perf_compare(a, b):
+    """Compares two saved recordings (names from perf_runs): each headline number, its change and change in %.
+    Recordings with under 100 frames are flagged: too short to compare."""
+    sa, sb = (json.loads(run_path(r).read_text()) for r in (a, b))
+    metrics = {
+        "fps": lambda s: s["gpu"].get("fps_estimate"),
+        "gpu_ms_mean": lambda s: s["gpu"]["frame_gpu_ms"].get("mean"),
+        "gpu_ms_p95": lambda s: s["gpu"]["frame_gpu_ms"].get("p95"),
+        "frame_interval_ms_p95": lambda s: s["gpu"]["frame_interval_ms"].get("p95"),
+        "metal_mib_peak": lambda s: s.get("metal_memory_mib", {}).get("peak"),
+        "rss_mib_max": lambda s: s.get("process_rss_mib", {}).get("max"),
+    }
+    out = {}
+    for name, get in metrics.items():
+        try:
+            va, vb = get(sa), get(sb)
+        except (KeyError, TypeError):
+            va = vb = None
+        change = None if va is None or vb is None else round(vb - va, 3)
+        out[name] = {"a": va, "b": vb, "change": change,
+                     "change_pct": None if change is None or not va else round(100 * change / va, 1)}
+    short = [r for r, s in ((a, sa), (b, sb)) if (s.get("gpu") or {}).get("frames", 0) < 100]
+    return {"a": a, "b": b, "metrics": out, "too_short": short}
+
+
+def tool_perf_diagnose(run, min_encoders=4, short_us=25, short_share=0.25):
+    """Says whether a saved recording splits its GPU work into too many short encoders, the pattern of translation
+    layers such as DXMT, Mullion or MoltenVK, with the numbers behind it: encoders and command buffers per frame, the
+    share of short encoders, the labels with the most GPU time and the GPU's idle time. Read the idle time together
+    with the FPS: a program waiting for vsync idles too. Defaults come from bgfx 17-drawstress on an M1 Pro: 7
+    encoders per frame and 50% under 25 us under Mullion, 2 and 2% in native Metal."""
+    s = json.loads(run_path(run).read_text())
+    encoders = s.get("encoders")
+    if not encoders:
+        raise ToolError(f"{run} was summarized before version 0.4.0 and has no encoder numbers; record it again")
+    share = encoders["short_share"].get(str(int(short_us)))
+    if share is None:
+        raise ToolError(f"short_us is one of {', '.join(map(str, perf_report.SHORT_US))}")
+    per_frame = encoders["per_frame"].get("p50", 0)
+    frames = (s.get("gpu") or {}).get("frames", 0)
+    return {"run": run, "too_many_short_encoders": per_frame >= min_encoders and share >= short_share,
+            "thresholds": {"min_encoders": min_encoders, "short_us": int(short_us), "short_share": short_share},
+            "encoders_per_frame_p50": per_frame,
+            "command_buffers_per_frame_p50": encoders["command_buffers_per_frame"].get("p50"),
+            "short_encoder_share": share, "fps": (s.get("gpu") or {}).get("fps_estimate"),
+            "gpu_idle": s.get("gpu_idle"), "by_label": encoders["by_label"], "too_short": frames < 100}
+
+
+def tool_trace_tables(trace):
+    """Lists the data tables (schemas) a .trace recording holds; recordings keep their .trace only with KEEP_TRACE=1."""
+    toc = perf_report.toc_of(trace_path(trace))
+    return {"tables": sorted({t.attrib["schema"] for t in toc.iter("table") if "schema" in t.attrib})}
+
+
+def tool_trace_query(trace, schema, offset=0, limit=50, pid=None):
+    """Returns one page of rows of one table of a .trace as {column: value}, optionally only one process's rows."""
+    if not schema.replace("-", "").isalnum():
+        raise ToolError("schema holds only letters, digits and '-'; trace_tables lists them")
+    xpath = f'/trace-toc/run[@number="1"]/data/table[@schema="{schema}"]'
+    rows = []
+    for row in perf_report.rows(perf_report.export(trace_path(trace), xpath=xpath)):
+        if pid is not None and "process" in row and perf_report.pid_of(row["process"]) != int(pid):
+            continue
+        rows.append({k: (v.attrib.get("fmt") or v.text) if v is not None else None for k, v in row.items()})
+    return page(rows, offset, limit)
+
+
+def tool_capture_summary(capture):
+    """Reads a Metal .gputrace capture without Xcode: command buffers, encoders, draws, debug groups, and the 100
+    most frequent call ids out of calls_total."""
+    summary = gputrace_read.summarize(allowed(capture))
+    summary["calls_total"] = len(summary["calls"])
+    summary["calls"] = summary["calls"][:100]
+    return summary
+
+
+def tool_capture_records(capture, offset=0, limit=100):
+    """Returns one page of the records of a .gputrace command stream, with their Metal call names when known."""
+    out = [{"offset": off, "size": size, "id": call, "signature": signature,
+            "name": gputrace_read.CALLS.get(call, (None,))[0], "strings": strings[:3]}
+           for off, size, call, signature, strings in gputrace_read.records(allowed(capture) / "capture")]
+    return page(out, offset, limit)
+
+
+def family_of(name):
+    """Returns the Metal family key for a family ("apple7") or chip name ("M1 Pro", "A15"), or None."""
+    wanted = name.strip().lower().replace(" ", "")
+    for key, family in FAMILIES["families"].items():
+        chips = [c.lower().replace(" ", "").removesuffix("series") for c in family["mac_chips"] + family["other_chips"]]
+        base = wanted.removesuffix("ultra").removesuffix("max").removesuffix("pro")
+        if wanted == key.lower() or wanted in chips or base in chips:
+            return key
+    return None
+
+
+def tool_gpu_family(name):
+    """Apple's published facts for one GPU family, by family ("Apple7") or chip ("M1 Pro"): its chips, what it adds,
+    its limits, plus the limits shared by all families and the footnotes. Source URLs are in the result."""
+    key = family_of(name)
+    if key is None:
+        raise ToolError(f"unknown family or chip {name!r}; try one of {', '.join(FAMILIES['families'])} or a chip "
+                        "such as M1 Pro, M2, M3 Max, A17 Pro")
+    return {"family": key, **FAMILIES["families"][key], "same_on_all": FAMILIES["same_on_all"],
+            "footnotes": FAMILIES["footnotes"], "guards": FAMILIES["guards"], "sources": FAMILIES["sources"]}
+
+
+RESOURCES = {"metal-trace://gpu-families": ("Apple GPU families", FAMILIES["about"], lambda: FAMILIES)} | {
+    f"metal-trace://gpu-families/{key.lower()}": (f"{key} GPU family", f"Apple's published facts for {key}",
+                                                  lambda key=key: tool_gpu_family(key))
+    for key in FAMILIES["families"]}
+
+S, I = {"type": "string"}, {"type": "integer"}
+PAGE = {"offset": {**I, "description": "first row, default 0"},
+        "limit": {**I, "description": f"rows per page, default 50, at most {MAX_LIMIT}"}}
+TRACE = {**S, "description": "a run name from perf_runs whose trace_kept is true, or the path of a .trace"}
+CAPTURE = {**S, "description": "path of a .gputrace bundle saved from Xcode, inside METAL_TRACE_OUT or METAL_TRACE_READ"}
+
+
+def schema(properties, required=()):
+    """Returns a JSON Schema object with these properties."""
+    return {"type": "object", "properties": properties, "required": list(required)}
+
+
+def hints(title, destructive=None):
+    """Returns a tool's MCP annotations: read-only unless `destructive` says whether its writes stop programs."""
+    if destructive is None:
+        return {"title": title, "readOnlyHint": True, "openWorldHint": False}
+    return {"title": title, "readOnlyHint": False, "destructiveHint": destructive, "idempotentHint": False,
+            "openWorldHint": False}
+
+
+TOOLS = {
+    "perf_record": (tool_perf_record, schema(
+        {"label": {**S, "description": "name for the run: letters, digits, '.', '_', '-'"},
+         "program": {**S, "description": "path of the .exe, or of the macOS binary with wine=native"},
+         "seconds": {**I, "description": "recording length, default 20; use 30 under Wine, whose start-up takes part of it; the export afterwards takes about a minute"},
+         "wine": {**S, "description": "Wine directory holding bin/wine, or native"},
+         "prefix": {**S, "description": "Wine prefix, default WINEPREFIX or ~/.wine; ignored with native"},
+         "workdir": {**S, "description": "directory the program starts in, default the program's own"},
+         "args": {**S, "description": "program arguments as in a shell, quotes included"}}, ["label", "program"]),
+        hints("Record a program", destructive=True)),
+    "perf_attach": (tool_perf_attach, schema(
+        {"label": {**S, "description": "name for the run: letters, digits, '.', '_', '-'"},
+         "process": {**S, "description": "pid, or a name in the program's command line such as Game.exe"},
+         "seconds": {**I, "description": "recording length, default 20; the export afterwards takes about a minute"}},
+        ["label", "process"]), hints("Record a running program", destructive=False)),
+    "perf_runs": (tool_perf_runs, schema(PAGE), hints("List recordings")),
+    "perf_compare": (tool_perf_compare, schema(
+        {"a": {**S, "description": "run name from perf_runs: the reference, such as the run before a change"},
+         "b": {**S, "description": "run name from perf_runs: the run to compare against a"}}, ["a", "b"]),
+        hints("Compare two recordings")),
+    "perf_diagnose": (tool_perf_diagnose, schema(
+        {"run": {**S, "description": "a run name from perf_runs"},
+         "min_encoders": {**I, "description": "encoders per frame (median) from which the verdict can be yes, default 4"},
+         "short_us": {**I, "description": "an encoder under this GPU time counts as short: 10, 25 (default), 50, 100, "
+                                          "250, 500 or 1000"},
+         "short_share": {"type": "number", "description": "share of short encoders from which the verdict is yes, "
+                                                          "default 0.25"}}, ["run"]),
+        hints("Diagnose encoder use")),
+    "trace_tables": (tool_trace_tables, schema({"trace": TRACE}, ["trace"]), hints("List a trace's tables")),
+    "trace_query": (tool_trace_query, schema(
+        {"trace": TRACE, "schema": {**S, "description": "a table name that trace_tables lists, such as metal-gpu-intervals"},
+         "pid": {**I, "description": "keep only this process's rows"}, **PAGE}, ["trace", "schema"]),
+                    hints("Read a trace table")),
+    "capture_summary": (tool_capture_summary, schema({"capture": CAPTURE}, ["capture"]), hints("Summarize a capture")),
+    "capture_records": (tool_capture_records, schema({"capture": CAPTURE, **PAGE}, ["capture"]),
+                        hints("Read a capture's records")),
+    "gpu_family": (tool_gpu_family, schema(
+        {"name": {**S, "description": "a family (Apple7 to Apple10) or a chip (M1 Pro, M2, M4 Max, A17 Pro)"}},
+        ["name"]), hints("Apple GPU family facts")),
+}
+
+
+def log(message):
+    """Writes one line to stderr, the only log channel a stdio server may use."""
+    if os.environ.get("METAL_TRACE_LOG") != "off":
+        print(f"metal-trace: {message}", file=sys.stderr, flush=True)
+
+
+def call(name, arguments):
+    """Runs one tool and returns its MCP result, with failures as isError results that say what to do."""
+    started = time.monotonic()
+    try:
+        value = TOOLS[name][0](**arguments)
+        text = json.dumps(value, ensure_ascii=False)
+        if len(text) > MAX_TEXT:
+            raise ToolError(f"the result has {len(text)} characters; ask for a smaller page with limit")
+        result = {"content": [{"type": "text", "text": text}], "structuredContent": value}
+    except TypeError as error:
+        result = {"content": [{"type": "text", "text": f"bad arguments: {error}"}], "isError": True}
+    except (ToolError, FileNotFoundError, ValueError, RuntimeError, subprocess.TimeoutExpired) as error:
+        result = {"content": [{"type": "text", "text": str(error)}], "isError": True}
+    except Exception as error:  # an unexpected failure is reported to the client, not fatal to the server
+        result = {"content": [{"type": "text", "text": f"internal error: {type(error).__name__}"}], "isError": True}
+    log(f"{name} {'error' if result.get('isError') else 'ok'} in {time.monotonic() - started:.1f} s")
+    return result
+
+
+def handle(message):
+    """Answers one JSON-RPC request; returns None for notifications."""
+    if not isinstance(message, dict):
+        return {"jsonrpc": "2.0", "id": None, "error": {"code": -32600, "message": "Invalid Request"}}
+    method, mid, params = message.get("method"), message.get("id"), message.get("params") or {}
+    if mid is None:
+        return None
+    if not isinstance(params, dict):
+        return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32600, "message": "params must be an object"}}
+    if method == "initialize":
+        asked = params.get("protocolVersion")
+        result = {"protocolVersion": asked if asked in PROTOCOL_VERSIONS else PROTOCOL_VERSIONS[0],
+                  "capabilities": {"tools": {}, "resources": {}},
+                  "serverInfo": {"name": "metal-trace", "version": __version__}, "instructions": INSTRUCTIONS}
+    elif method == "ping":
+        result = {}
+    elif method == "resources/templates/list":
+        result = {"resourceTemplates": []}
+    elif method == "resources/list":
+        result = {"resources": [{"uri": uri, "name": name, "description": about, "mimeType": "application/json"}
+                                for uri, (name, about, _) in RESOURCES.items()]}
+    elif method == "resources/read":
+        uri = params.get("uri")
+        if uri not in RESOURCES:
+            return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32002, "message": "Resource not found",
+                                                           "data": {"uri": uri}}}
+        result = {"contents": [{"uri": uri, "mimeType": "application/json",
+                                "text": json.dumps(RESOURCES[uri][2](), ensure_ascii=False)}]}
+    elif method == "tools/list":
+        result = {"tools": [{"name": n, "description": f.__doc__.strip(), "inputSchema": s,
+                             "annotations": hints} for n, (f, s, hints) in TOOLS.items()]}
+    elif method == "tools/call":
+        name = params.get("name")
+        if name not in TOOLS:
+            return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32602, "message": f"unknown tool {name}"}}
+        result = call(name, params.get("arguments") or {})
+    else:
+        return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32601, "message": f"unknown method {method}"}}
+    return {"jsonrpc": "2.0", "id": mid, "result": result}
+
+
+def main():
+    """Serves newline-delimited JSON-RPC on stdin and stdout until stdin closes; --version prints the version."""
+    if sys.argv[1:] == ["--version"]:
+        print(f"metal-gpu-trace {__version__}")
+        return
+    for line in sys.stdin:
+        if not line.strip():
+            continue
+        try:
+            reply = handle(json.loads(line))
+        except json.JSONDecodeError:
+            reply = {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "parse error"}}
+        except Exception as error:  # a malformed request must not stop the server
+            log(f"internal error {type(error).__name__}")
+            reply = {"jsonrpc": "2.0", "id": None, "error": {"code": -32603, "message": "internal error"}}
+        if reply is not None:
+            sys.stdout.write(json.dumps(reply) + "\n")
+            sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

metal_gpu_trace/perf_record.sh

@@ -0,0 +1,71 @@
+#!/bin/zsh
+# Records a Wine or macOS program with Metal System Trace into $PERF_OUT, keeping the newest KEEP_RUNS runs.
+# Usage: [PERF_OUT=dir] [KEEP_TRACE=1] [KEEP_RUNS=N] perf_record.sh <label> <seconds> <wine dir|native> <prefix> <working dir> <program> [args...]
+#    or: perf_record.sh <label> <seconds> attach - - <pid|name>   (records a running program, left running afterwards)
+set -euo pipefail
+
+here=${0:A:h}
+label=$1 seconds=$2 wine=$3 prefix=$4 workdir=$5
+shift 5
+[[ $label =~ '^[A-Za-z0-9._-]+$' ]] || { echo "label may hold only letters, digits, '.', '_' and '-'" >&2; exit 2; }
+[[ $seconds == <1-3600> ]] || { echo "seconds must be 1 to 3600" >&2; exit 2; }
+[[ $wine == (native|attach) || -x $wine/bin/wine ]] || { echo "no Wine at $wine/bin/wine (or pass native or attach)" >&2; exit 2; }
+if [[ $wine == attach ]]; then
+  pid=$1
+  # a name matches the newest process whose command line holds it, such as Game.exe under Wine
+  [[ $pid == <-> ]] || pid=$(ps -axo pid=,command= | awk -v name="$1" 'index($0, name) && !/xctrace|awk|zsh|perf_record|ps -axo/ {p = $1} END {print p}')
+  [[ -n $pid ]] && kill -0 $pid 2>/dev/null || { echo "no running process matches $1" >&2; exit 2; }
+fi
+name=${label}_$(date +%Y%m%d-%H%M%S)
+# default: logs/perf beside the script's directory when it exists, else ./perf-runs
+out=${PERF_OUT:-${here:h}/logs/perf}
+[[ -n ${PERF_OUT:-} || -d $out ]] || out=$PWD/perf-runs
+mkdir -p $out
+
+# one recording at a time: two programs sharing the GPU spoil both measurements
+lock=$out/.recording
+mkdir $lock 2>/dev/null || { echo "another recording is running ($lock); remove it if none is" >&2; exit 3; }
+trap 'rmdir $lock 2>/dev/null' EXIT
+
+[[ $wine == attach ]] || cd $workdir
+# the resident memory of the program's Wine process, once a second, while Instruments records
+exe=${1:t}
+(
+  echo "time_s,rss_kib" > $out/$name.rss.csv
+  for ((t = 0; t <= seconds + 5; t++)); do
+    if [[ $wine == attach ]]; then
+      rss=$(ps -o rss= -p $pid | awk '{print $1 + 0}')
+    else
+      rss=$(ps -axo rss=,command= | awk -v exe="$exe" 'index($0, exe) && !/xctrace|awk|zsh|perf_record|ps -axo/ {sum += $1} END {print sum + 0}')
+    fi
+    echo "$t,$rss" >> $out/$name.rss.csv
+    sleep 1
+  done
+) &
+sampler=$!
+# PERF_ENV="NAME=VALUE ..." sets the program's variables (MULLION_DIAG=profile labels Mullion's encoders)
+extra=()
+for pair in ${=PERF_ENV:-}; do extra+=(--env $pair); done
+if [[ $wine == attach ]]; then
+  xcrun xctrace record --template "Metal System Trace" --time-limit ${seconds}s --output $out/$name.trace \
+    --attach $pid || true
+elif [[ $wine == native ]]; then
+  xcrun xctrace record --template "Metal System Trace" --time-limit ${seconds}s --output $out/$name.trace \
+    $extra --launch -- "$@" || true
+  pkill -x $exe || true
+else
+  xcrun xctrace record --template "Metal System Trace" --time-limit ${seconds}s --output $out/$name.trace \
+    --env WINEPREFIX=$prefix --env WINEDEBUG=-all --env "WINEDLLOVERRIDES=mscoree=;mshtml=" $extra \
+    --launch -- $wine/bin/wine "$@" || true
+  # the program outlives the recording; stop what is left of its Wine
+  WINEPREFIX=$prefix $wine/bin/wineserver -k || true
+fi
+kill $sampler 2>/dev/null || true
+[ -d $out/$name.trace ] || { echo "no recording at $out/$name.trace" >&2; exit 1; }
+
+python3 -I $here/perf_report.py $out/$name.trace --label $name --out $out
+# the .trace goes once its numbers are in the .json; KEEP_TRACE=1 keeps it for trace_tables, trace_query or Instruments
+[[ ${KEEP_TRACE:-0} == 1 ]] || rm -rf $out/$name.trace
+if [[ ${KEEP_RUNS:-} == <1-> ]]; then
+  for old in $out/*.json(N.om[$((KEEP_RUNS + 1)),-1]); do rm -rf ${old:r}.*(N); done
+fi

metal_gpu_trace/perf_report.py

@@ -0,0 +1,293 @@
+"""Summarizes an Instruments "Metal System Trace" recording of one launched program: GPU time per frame and memory.
+
+Usage: python3 -I perf_report.py <recording.trace> [--label NAME] [--out DIR]
+Writes <out>/<label>.json (summary), <label>.frames.csv (one row per GPU frame) and <label>.metal_memory.csv (Metal
+memory over time). A <recording>.rss.csv beside the trace adds the process's resident memory.
+"""
+import argparse
+import collections
+import csv
+import json
+import os
+import pathlib
+import re
+import statistics
+import subprocess
+import sys
+import tempfile
+import xml.etree.ElementTree as ET
+
+
+def export(trace, xpath=None, toc=False, timeout=600):
+    """Returns the path of a temporary XML file holding the trace's table of contents or the table that `xpath`
+    selects; `rows` and `toc_of` delete it once read."""
+    if not pathlib.Path(trace).is_dir():
+        raise FileNotFoundError(f"no recording at {pathlib.Path(trace).name}: perf_record.sh deletes the .trace once "
+                                "its summary is written, unless KEEP_TRACE=1")
+    out = tempfile.NamedTemporaryFile(suffix=".xml", delete=False)
+    out.close()
+    cmd = ["xcrun", "xctrace", "export", "--input", str(trace), "--output", out.name]
+    cmd += ["--toc"] if toc else ["--xpath", xpath]
+    proc = subprocess.run(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, text=True, timeout=timeout)
+    if proc.returncode:
+        os.unlink(out.name)
+        reason = (proc.stderr.strip().splitlines() or ["no message"])[-1]
+        raise RuntimeError(f"xctrace export of {pathlib.Path(trace).name} failed (exit {proc.returncode}): {reason}")
+    return out.name
+
+
+def toc_of(trace):
+    """Returns the root element of the trace's table of contents."""
+    path = export(trace, toc=True)
+    try:
+        return ET.parse(path).getroot()
+    finally:
+        os.unlink(path)
+
+
+def rows(path):
+    """Yields each row of an exported table as {column mnemonic: element}, with xctrace's id/ref values resolved,
+    and deletes the file when done or closed early."""
+    ids, columns = {}, []
+    try:
+        for _, el in ET.iterparse(path, events=("end",)):
+            if "id" in el.attrib:
+                ids[el.attrib["id"]] = el
+            if el.tag == "col":
+                columns.append(el.findtext("mnemonic"))
+            elif el.tag == "row":
+                values = [ids.get(c.attrib["ref"], c) if "ref" in c.attrib else c for c in el]
+                yield dict(zip(columns, values))
+    finally:
+        os.unlink(path)
+
+
+def public_arguments(arguments):
+    """Returns a command line with each absolute path cut to its file name, so summaries can be shared."""
+    return " ".join(pathlib.Path(a).name if a.startswith("/") else a for a in (arguments or "").split())
+
+
+def text(el):
+    """Returns an exported cell's formatted value, or "" for a missing cell."""
+    return (el.attrib.get("fmt") or el.text or "").strip() if el is not None else ""
+
+
+def number(el):
+    return int(el.text) if el is not None and el.text and el.text.strip().lstrip("-").isdigit() else None
+
+
+def pid_of(process):
+    """Returns the pid of a <process> value, whose <pid> child may itself be a reference."""
+    if process is None:
+        return None
+    pid = process.find("pid")
+    return int(pid.attrib.get("fmt") or pid.text) if pid is not None and (pid.text or pid.attrib.get("fmt")) else None
+
+
+def stats(values):
+    """Returns count, mean, median, 95th percentile and maximum of `values`, rounded to microseconds when in ms."""
+    if not values:
+        return {"count": 0}
+    ordered = sorted(values)
+    return {
+        "count": len(ordered),
+        "mean": round(statistics.fmean(ordered), 3),
+        "p50": round(ordered[len(ordered) // 2], 3),
+        "p95": round(ordered[min(len(ordered) - 1, int(len(ordered) * 0.95))], 3),
+        "max": round(ordered[-1], 3),
+    }
+
+
+def missing_tables(toc):
+    """Returns the optional tables a trace's table of contents lacks; raises ValueError when it lacks the GPU
+    intervals every summary needs, as when an Xcode version renames them."""
+    schemas = {t.attrib.get("schema") for t in toc.iter("table")}
+    if "metal-gpu-intervals" not in schemas:
+        raise ValueError("the trace has no metal-gpu-intervals table; this Xcode may name it differently: "
+                         "trace_tables lists the tables it has")
+    return sorted({"metal-current-allocated-size", "gpu-performance-state-intervals",
+                   "metal-application-encoders-list"} - schemas)
+
+
+# encoder GPU times, in µs, whose share of all encoders each summary keeps
+SHORT_US = (10, 25, 50, 100, 250, 500, 1000)
+
+
+def label_name(label):
+    """Returns an encoder label without Instruments' "[n] " prefix and trailing index, so the same pass groups."""
+    return re.sub(r" \d+$", "", re.sub(r"^\[\d+\] ", "", label)) or "?"
+
+
+def encoder_stats(spans, labels):
+    """Returns encoders and command buffers per frame, each encoder's GPU time, the share of encoders shorter than
+    each of SHORT_US and the 20 labels with the most GPU time. `spans` holds (frame, start ns, duration ns, encoder
+    id, command buffer id) and `labels` maps an encoder id to its label."""
+    encoders, buffers, busy = collections.defaultdict(set), collections.defaultdict(set), collections.Counter()
+    for frame, _, duration, encoder, buffer in spans:
+        if encoder:
+            encoders[frame].add(encoder)
+            busy[encoder] += duration
+        if buffer:
+            buffers[frame].add(buffer)
+    us = [ns / 1000 for ns in busy.values()]
+    grouped = collections.defaultdict(list)
+    for encoder, ns in busy.items():
+        grouped[label_name(labels.get(encoder, ""))].append(ns / 1000)
+    frames = len({s[0] for s in spans}) or 1
+    top = sorted(grouped.items(), key=lambda kv: -sum(kv[1]))[:20]
+    return {
+        "per_frame": stats([len(e) for e in encoders.values()]),
+        "command_buffers_per_frame": stats([len(b) for b in buffers.values()]),
+        "encoder_us": stats(us),
+        "short_share": {str(cut): round(sum(u < cut for u in us) / len(us), 3) for cut in SHORT_US} if us else {},
+        "by_label": [{"label": name, "per_frame": round(len(v) / frames, 2), "total_ms": round(sum(v) / 1000, 3),
+                      "mean_us": round(statistics.fmean(v), 1), "stdev_us": round(statistics.pstdev(v), 1)}
+                     for name, v in top],
+    }
+
+
+def idle_gaps(spans):
+    """Returns the time the GPU ran none of the process's work between its first and last interval: per frame (each
+    gap counts in the frame of the work that ends it), gaps over 1 ms and share of the whole span. `spans` as in
+    encoder_stats."""
+    ordered = sorted((start, start + duration, frame) for frame, start, duration, _, _ in spans)
+    if not ordered:
+        return {"idle_ms_per_frame": {"count": 0}}
+    idle, gaps, end = collections.Counter({frame: 0 for _, _, frame in ordered}), [], ordered[0][1]
+    for start, stop, frame in ordered[1:]:
+        if start > end:
+            gaps.append((start - end) / 1e6)
+            idle[frame] += (start - end) / 1e6
+        end = max(end, stop)
+    whole = (end - ordered[0][0]) / 1e6
+    return {"idle_ms_per_frame": stats(list(idle.values())), "gaps_over_1ms": sum(g > 1 for g in gaps),
+            "idle_share": round(sum(gaps) / whole, 3) if whole else None}
+
+
+def summarize(trace, label=None, out=None):
+    """Summarizes `trace`, writes the JSON and CSV files into `out` (default: beside it) and returns the summary."""
+    trace = pathlib.Path(trace)
+    label = label or trace.stem
+    out = pathlib.Path(out) if out else trace.parent
+    out.mkdir(parents=True, exist_ok=True)
+
+    toc = toc_of(trace)
+    launched = next((p for p in toc.iter("process") if p.attrib.get("type") in ("launched", "attached")), None)
+    if launched is None:
+        raise ValueError("the trace has no launched or attached process; record it with xctrace --launch or --attach")
+    pid = int(launched.attrib["pid"])
+    summary = {
+        "label": label,
+        "trace": trace.name,
+        "process": {k: launched.attrib.get(k) for k in ("name", "pid", "termination-reason")}
+                   | {"arguments": public_arguments(launched.attrib.get("arguments"))},
+        # the machine's name and UUID stay out: these summaries are meant to be shared
+        "device": {
+            k: v
+            for k, v in (toc.find(".//device").attrib.items() if toc.find(".//device") is not None else [])
+            if k in ("platform", "model", "memory-size", "os-version")
+        },
+        "template": toc.findtext(".//template-name"),
+        "duration_s": float(toc.findtext(".//summary/duration") or 0),
+        # their numbers come out empty
+        "missing_tables": missing_tables(toc),
+    }
+
+    # GPU work of the launched process, per frame and per channel (vertex, fragment, compute)
+    frames = collections.defaultdict(lambda: collections.defaultdict(float))
+    first_start = {}
+    intervals = 0
+    spans = []
+    for row in rows(export(trace, xpath='/trace-toc/run[@number="1"]/data/table[@schema="metal-gpu-intervals"]')):
+        if pid_of(row.get("process")) != pid:
+            continue
+        frame, start, duration = number(row.get("frame-number")), number(row.get("start")), number(row.get("duration"))
+        if frame is None or duration is None:
+            continue
+        channel = (row.get("channel-name").text or "?").strip() if row.get("channel-name") is not None else "?"
+        frames[frame][channel] += duration / 1e6
+        first_start[frame] = min(first_start.get(frame, start), start)
+        intervals += 1
+        if start is not None:
+            spans.append((frame, start, duration, text(row.get("encoder-id")), text(row.get("cmdbuffer-id"))))
+
+    ordered = sorted(frames)
+    channels = sorted({c for f in frames.values() for c in f})
+    totals = [sum(frames[f].values()) for f in ordered]
+    starts = [first_start[f] / 1e6 for f in ordered]
+    gaps = [b - a for a, b in zip(starts, starts[1:]) if b > a]
+    summary["gpu"] = {
+        "intervals": intervals,
+        "frames": len(ordered),
+        "frame_gpu_ms": stats(totals),
+        "per_channel_ms": {c: stats([frames[f].get(c, 0.0) for f in ordered]) for c in channels},
+        "frame_interval_ms": stats(gaps),
+        "fps_estimate": round(1000 / statistics.median(gaps), 1) if gaps else None,
+    }
+
+    # how the work splits into encoders, and when the GPU waits for it
+    labels = {}
+    if "metal-application-encoders-list" not in summary["missing_tables"]:
+        xpath = '/trace-toc/run[@number="1"]/data/table[@schema="metal-application-encoders-list"]'
+        labels = {text(row.get("encoder-id")): text(row.get("encoder-label-indexed"))
+                  for row in rows(export(trace, xpath=xpath))}
+    summary["encoders"] = encoder_stats(spans, labels)
+    summary["gpu_idle"] = idle_gaps(spans)
+
+    # Metal memory the launched process holds over time
+    allocated = []
+    for row in rows(export(trace, xpath='/trace-toc/run[@number="1"]/data/table[@schema="metal-current-allocated-size"]')):
+        size, start = number(row.get("current-allocated-size")), number(row.get("start"))
+        if pid_of(row.get("process")) == pid and size is not None and start is not None:
+            allocated.append((start / 1e6, size))
+    allocated.sort()
+    mib = [size / 2**20 for _, size in allocated]
+    summary["metal_memory_mib"] = (
+        {"samples": len(mib), "peak": round(max(mib), 2), "final": round(mib[-1], 2), "mean": round(statistics.fmean(mib), 2)}
+        if mib else {"samples": 0}
+    )
+    with open(out / f"{label}.metal_memory.csv", "w", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow(["time_ms", "metal_allocated_bytes"])
+        writer.writerows((round(t, 3), size) for t, size in allocated)
+
+    # the process's resident memory, sampled by perf_record.sh beside the trace
+    rss_csv = trace.with_suffix(".rss.csv")
+    if rss_csv.exists():
+        with open(rss_csv) as f:
+            rss = [int(r["rss_kib"]) / 1024 for r in csv.DictReader(f) if r["rss_kib"].isdigit()]
+        summary["process_rss_mib"] = stats(rss) if rss else {"count": 0}
+
+    # the GPU's clock states over the recording, as a share of time
+    states = collections.Counter()
+    for row in rows(export(trace, xpath='/trace-toc/run[@number="1"]/data/table[@schema="gpu-performance-state-intervals"]')):
+        state, duration = row.get("gpu-performance-state"), number(row.get("duration"))
+        if state is not None and duration:
+            states[(state.attrib.get("fmt") or state.text or "?").strip()] += duration
+    total_state = sum(states.values())
+    summary["gpu_performance_state_share"] = {k: round(v / total_state, 3) for k, v in states.most_common()} if total_state else {}
+
+    with open(out / f"{label}.frames.csv", "w", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow(["frame", "start_ms"] + [f"gpu_ms_{c.lower()}" for c in channels] + ["gpu_ms_total"])
+        for frame, start, total in zip(ordered, starts, totals):
+            writer.writerow([frame, round(start, 3)] + [round(frames[frame].get(c, 0.0), 4) for c in channels] + [round(total, 4)])
+    (out / f"{label}.json").write_text(json.dumps(summary, indent=2, ensure_ascii=False) + "\n")
+    return summary
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("trace", type=pathlib.Path)
+    parser.add_argument("--label", help="name of the output files; defaults to the trace's name")
+    parser.add_argument("--out", type=pathlib.Path, help="output directory; defaults to the trace's directory")
+    args = parser.parse_args()
+    try:
+        summary = summarize(args.trace, args.label, args.out)
+    except (ValueError, FileNotFoundError, RuntimeError) as error:
+        sys.exit(str(error))
+    print(json.dumps({k: summary.get(k) for k in ("gpu", "metal_memory_mib", "process_rss_mib")}, indent=2))
+
+
+if __name__ == "__main__":
+    main()

metal_gpu_trace-0.4.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.5
+Name: metal-gpu-trace
+Version: 0.4.0
+Summary: Measure Wine and macOS programs' GPU use on Apple silicon with Metal System Trace, from the shell or an MCP client
+Project-URL: Homepage, https://github.com/partprogramming09/metal-gpu-trace
+Project-URL: Changelog, https://github.com/partprogramming09/metal-gpu-trace/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/partprogramming09/metal-gpu-trace/issues
+License: MIT
+License-File: LICENSE
+Keywords: apple-silicon,gpu,instruments,mcp,mcp-server,metal,profiling,wine,xctrace
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Benchmark
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# metal-gpu-trace
+
+[![test](https://github.com/partprogramming09/metal-gpu-trace/actions/workflows/test.yml/badge.svg)](https://github.com/partprogramming09/metal-gpu-trace/actions/workflows/test.yml)
+
+<!-- mcp-name: io.github.partprogramming09/metal-gpu-trace -->
+
+Measure how a Wine or macOS program uses the GPU on an Apple silicon Mac, from the command line or through an AI
+coding agent: GPU time per frame, frame pacing, FPS and memory, recorded with Instruments' Metal System Trace; whether
+a translation layer (DXMT, Mullion, MoltenVK) splits the work into too many short encoders; Metal
+`.gputrace` captures read without Xcode; and Apple's published facts on each GPU family to read the numbers against.
+Python 3.9+ standard library, `zsh`, and Xcode (for `xctrace`). MIT license. [Español](es/README.md).
+
+| File | What it does |
+| --- | --- |
+| `perf_record.sh` | Records a program for N seconds with Metal System Trace and writes `<label>_<date>.json` (GPU ms per frame, frame intervals, FPS, Metal and resident memory) plus per-frame and memory CSVs. Deletes the `.trace` afterwards unless `KEEP_TRACE=1`. |
+| `perf_report.py` | Summarizes an existing `.trace` the same way. |
+| `gputrace_read.py` | Reads a Metal `.gputrace` capture without Xcode: command buffers, encoders, draws, debug groups. Call names marked `probable` are not confirmed. |
+| `data/apple-gpu-families.json` | Apple7 to Apple10: chips, what each family adds, limits that differ, with Apple's sources. |
+| `metal_trace_mcp.py` | An MCP server over all of the above. |
+| `test_metal_trace_mcp.py` | Self-check without Instruments: `python3 -I test_metal_trace_mcp.py` prints `ok`; `pytest` runs the same tests. |
+
+## Recording
+
+```sh
+PERF_OUT=~/perf-runs zsh perf_record.sh game-d3d12 30 /path/to/wine ~/.wine /path/to/game game.exe
+PERF_OUT=~/perf-runs zsh perf_record.sh app-metal 30 native - /path/to/app ./app
+```
+
+Arguments: label, seconds, a Wine directory holding `bin/wine` (or `native`), the Wine prefix, the working directory,
+the program and its arguments. Without `PERF_OUT`, runs go to `./perf-runs`. Reading the trace afterwards takes about
+a minute on an M1 Pro (87 s for a 10 s recording); through the MCP server the whole call times out after 10 s per
+recorded second plus 120 s, and an overrun recording leaves no files behind. One recording runs at a time; keep other GPU work off the Mac while it records.
+
+Under Wine, give it 30 s: Wine's start-up takes part of the recording. A recording with under 100 frames is too short
+to compare.
+
+## Disk use
+
+Each recording keeps a JSON summary and three CSVs, about 2 MB for 10 s (most of it the Metal memory samples). The
+`.trace` (tens to hundreds of MB) is deleted unless `KEEP_TRACE=1`. `KEEP_RUNS=N` keeps only the newest N recordings.
+
+## MCP server
+
+### Install
+
+The server runs with [`uvx`](https://docs.astral.sh/uv/) straight from this repo, with nothing to clone
+(`brew install uv` installs it). Recording also needs Xcode installed (`xcrun xctrace version` prints a version).
+
+```sh
+uvx --from git+https://github.com/partprogramming09/metal-gpu-trace metal-gpu-trace
+```
+
+This is the command each client below runs. Desktop apps do not see Homebrew's `PATH`: give them the full path that
+`which uvx` prints (`/opt/homebrew/bin/uvx` on Apple silicon). `uvx` keeps the version it first downloaded; run
+the command once with `--refresh` after `uvx` to get the latest.
+
+The server reads these environment variables:
+
+| Variable | What it sets |
+| --- | --- |
+| `METAL_TRACE_OUT` | Where recordings go. Give an absolute path: the default, `./perf-runs`, depends on the client's working directory. |
+| `METAL_TRACE_WINE` | The Wine directory (holding `bin/wine`) that `perf_record` uses when the call names none. |
+| `WINEPREFIX` | The Wine prefix used when the call names none; `~/.wine` otherwise. |
+| `METAL_TRACE_READ` | More directories the tools may read, separated by `:`. |
+| `METAL_TRACE_LOG` | `off` silences the one-line stderr log per call. |
+| `KEEP_TRACE` | `1` keeps each recording's `.trace`, for `trace_tables`, `trace_query` or Instruments. |
+| `KEEP_RUNS` | Keeps only the newest N recordings. |
+| `PERF_ENV` | `NAME=VALUE` pairs, separated by spaces, set for the recorded program. |
+
+### Claude Code
+
+```sh
+claude mcp add --scope user metal-trace -e METAL_TRACE_OUT=$HOME/perf-runs -e METAL_TRACE_WINE=/path/to/wine \
+  -- uvx --from git+https://github.com/partprogramming09/metal-gpu-trace metal-gpu-trace
+claude mcp list
+```
+
+`claude mcp list` shows `metal-trace` as connected. `--scope user` makes it available in every project; leave it out
+to add it to the current project only.
+
+### Claude Desktop, Cursor and other JSON clients
+
+These apps do not expand `~` or `$HOME`: write absolute paths.
+
+```json
+{
+  "mcpServers": {
+    "metal-trace": {
+      "command": "/opt/homebrew/bin/uvx",
+      "args": ["--from", "git+https://github.com/partprogramming09/metal-gpu-trace", "metal-gpu-trace"],
+      "env": {
+        "METAL_TRACE_OUT": "/absolute/path/to/perf-runs",
+        "METAL_TRACE_WINE": "/absolute/path/to/wine"
+      }
+    }
+  }
+}
+```
+
+| Client | File |
+| --- | --- |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (Settings, Developer, Edit Config); restart the app |
+| Cursor | `~/.cursor/mcp.json` |
+| VS Code | `.vscode/mcp.json` in the project; the top key is `servers` instead of `mcpServers`, and the server adds `"type": "stdio"` |
+
+### Codex CLI
+
+In `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.metal-trace]
+command = "/opt/homebrew/bin/uvx"
+args = ["--from", "git+https://github.com/partprogramming09/metal-gpu-trace", "metal-gpu-trace"]
+env = { METAL_TRACE_OUT = "/absolute/path/to/perf-runs", METAL_TRACE_WINE = "/absolute/path/to/wine" }
+```
+
+### Tools
+
+| Tool | Reads or records |
+| --- | --- |
+| `perf_record` | Records a program and returns its summary; when it ends it stops every program of its Wine prefix, or every process named like a native program |
+| `perf_attach` | Records a program that is already running, by pid or name, and leaves it running |
+| `perf_runs` | Lists recordings, newest first, one page at a time, and whether each kept its `.trace` |
+| `perf_compare` | Compares two recordings; flags those under 100 frames |
+| `perf_diagnose` | Says whether a recording splits its GPU work into too many short encoders, as translation layers do, with encoders and command buffers per frame, the labels with the most GPU time and the GPU's idle time |
+| `trace_tables` | Lists the tables of a kept `.trace`, named by its run or its path |
+| `trace_query` | One page of rows of one table, optionally one process |
+| `capture_summary` | Summarizes a `.gputrace`; lists its 100 most frequent calls out of `calls_total` |
+| `capture_records` | One page of a `.gputrace`'s records |
+| `gpu_family` | Apple's facts for a family or chip (`Apple7`, `M1 Pro`, `M3 Max`) |
+
+The same facts are MCP resources: `metal-trace://gpu-families` (all) and `metal-trace://gpu-families/apple7` to
+`apple10`. They restate Apple's [Metal Feature Set Tables](https://developer.apple.com/metal/Metal-Feature-Set-Tables.pdf)
+of 21 May 2026, [`MTLGPUFamily`](https://developer.apple.com/documentation/metal/mtlgpufamily) and the
+[M3 tech talk](https://developer.apple.com/videos/play/tech-talks/111375/); check a device with `supportsFamily`.
+
+How it follows the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18) and
+[Claude Code's limits](https://code.claude.com/docs/en/mcp):
+
+- stdout carries only MCP messages; each tool call logs one line to stderr (`METAL_TRACE_LOG=off` silences it), with
+  no arguments or paths.
+- Lists come in pages (`offset`, `limit`, default 50, at most 500) with `total` and `next_offset`; a result over
+  40 000 characters is refused with a hint to ask for a smaller page.
+- Files are read only inside `METAL_TRACE_OUT` and the directories in `METAL_TRACE_READ` (separated by `:`).
+- Failures come back as `isError` results that say what to do, without stack traces or local paths. Summaries cut
+  absolute paths to file names, so they can be shared.
+- Every `xctrace` call has a timeout.
+
+## Credits
+
+- The record layout of a `.gputrace` command stream follows [tmc/gputrace](https://github.com/tmc/gputrace) (MIT); no
+  code is copied. The call ids were matched against Xcode's command list on macOS 27.0.1.
+- GPU family facts: Apple's documents linked above, restated, not quoted.

metal_gpu_trace-0.4.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+metal_gpu_trace/data/apple-gpu-families.json,sha256=uxkfgIb0byeeAxScdTh1CM6zKSxdV11eN8kiTVassAU,3984
+metal_gpu_trace/gputrace_read.py,sha256=NNJ-0aNCwhMwd4anUG3AyfqV_vZHbUoVvRPnKVqX_54,4781
+metal_gpu_trace/metal_trace_mcp.py,sha256=YxNpEVoeJ_cnxia4Y6yoeCsBnOX_QtZBPk-V8ahGJ-g,23689
+metal_gpu_trace/perf_record.sh,sha256=tpApDBuEG2D5S63NQKzk-YzCYPv5_aAUxzbH1ryhKqE,3651
+metal_gpu_trace/perf_report.py,sha256=-2KLsNnxDaA-4zrvurTFb9fR4mDq5ZnL4_dlBhQ5oiY,14044
+metal_gpu_trace-0.4.0.dist-info/METADATA,sha256=7s9R2-THLUfRTMS8_sMNbiBYE2Ncg_K3TOS3Svz-40Y,9443
+metal_gpu_trace-0.4.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+metal_gpu_trace-0.4.0.dist-info/entry_points.txt,sha256=VoBr5DCK_qnj09z035IA6MNOgODMjX3o1Z7Qssj4qCA,73
+metal_gpu_trace-0.4.0.dist-info/licenses/LICENSE,sha256=I-cLehXzQocq5DYArHNzaRh_8VFB7oQCegREwaWhF-c,1078
+metal_gpu_trace-0.4.0.dist-info/RECORD,,

metal_gpu_trace-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

metal_gpu_trace-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+metal-gpu-trace = metal_gpu_trace.metal_trace_mcp:main

metal_gpu_trace-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hernan Flórez Burgos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.