metal-gpu-trace 0.4.0__tar.gz

metal_gpu_trace-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.9"
+      - run: python -I test_metal_trace_mcp.py
+      # the tag, the code and server.json must name the same version
+      - run: |
+          tag=${GITHUB_REF_NAME#v}
+          code=$(sed -n 's/^__version__ = "\(.*\)"/\1/p' metal_trace_mcp.py)
+          python -I -c "import json, sys; s = json.load(open('server.json')); sys.exit(0 if s['version'] == s['packages'][0]['version'] == '$tag' == '$code' else 'tag $tag, code $code and server.json differ')"
+
+  # the GitHub release goes out even when PyPI is not set up yet
+  release:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - name: GitHub release with the changelog section
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version=${GITHUB_REF_NAME#v}
+          awk -v v="## $version " 'index($0, v) == 1 {on = 1; next} /^## / {on = 0} on' CHANGELOG.md > notes.md
+          gh release create "$GITHUB_REF_NAME" dist/* --title "$GITHUB_REF_NAME" --notes-file notes.md
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Publish to the MCP Registry
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz" | tar xz mcp-publisher
+          ./mcp-publisher login github-oidc
+          ./mcp-publisher publish

metal_gpu_trace-0.4.0/.github/workflows/test.yml

@@ -0,0 +1,16 @@
+name: test
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: macos-latest
+    strategy:
+      matrix:
+        python: ["3.9", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -I test_metal_trace_mcp.py

metal_gpu_trace-0.4.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+perf-runs/
+logs/
+.claude/
+dist/

metal_gpu_trace-0.4.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+Versions follow [Semantic Versioning](https://semver.org); each one is a `vX.Y.Z` tag. `metal-gpu-trace --version`
+and the MCP `initialize` answer (`serverInfo.version`) print the installed one.
+
+## 0.4.0 — 2026-10-17
+
+- `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.
+  Defaults (4 encoders per frame, 25 µs, 25 % short) come from bgfx 17-drawstress on an M1 Pro: 7 encoders per frame
+  and 50 % under 25 µs under Mullion, 2 and 2 % in native Metal.
+- Summaries gain `encoders` and `gpu_idle`, from `metal-gpu-intervals` and `metal-application-encoders-list`.
+  Summaries written by older versions have neither: record again to diagnose them.
+- Every tool parameter has a description; `metal-gpu-trace --version`.
+- Registry files: `server.json` (MCP Registry), `glama.json`; `CHANGELOG.md`.
+- `trace_tables` and `trace_query` take a run name; `perf_runs` says whether each run kept its `.trace`
+  (`trace_kept`).
+- A trace without `metal-gpu-intervals` fails with a hint; summaries list other missing tables in `missing_tables`.
+- `capture_summary` returns `calls_total`.
+- Tools carry `title`, `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint`; `initialize`
+  returns usage `instructions`.
+- A recording's deadline grows with its length (10 s per recorded second plus 120 s), and one that overruns leaves
+  no files behind.
+- `perf-runs/` is created only when a recording needs it. Tests run under pytest; CI on macOS with Python 3.9 and
+  3.13.
+
+## 0.2.0
+
+- First release on GitHub: `perf_record`, `perf_attach`, `perf_runs`, `perf_compare`, `trace_tables`,
+  `trace_query`, `capture_summary`, `capture_records`, `gpu_family`, and the GPU family resources.

metal_gpu_trace-0.4.0/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.

metal_gpu_trace-0.4.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,153 @@
+# 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/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."
+  ]
+}