metal-gpu-trace
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PERF_ENV | No | `NAME=VALUE` pairs, separated by spaces, set for the recorded program. | |
| KEEP_RUNS | No | Keeps only the newest N recordings. | |
| KEEP_TRACE | No | `1` keeps each recording's `.trace`, for `trace_tables`, `trace_query` or Instruments. | |
| WINEPREFIX | No | The Wine prefix used when the call names none; `~/.wine` otherwise. | |
| METAL_TRACE_LOG | No | `off` silences the one-line stderr log per call. | |
| METAL_TRACE_OUT | No | Where recordings go. Give an absolute path: the default, `./perf-runs`, depends on the client's working directory. | |
| METAL_TRACE_READ | No | More directories the tools may read, separated by `:`. | |
| METAL_TRACE_WINE | No | The Wine directory (holding `bin/wine`) that `perf_record` uses when the call names none. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
| resources | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| perf_recordA | Records |
| perf_runsB | Lists the saved recordings, newest first, with frames, FPS, GPU ms per frame and memory peaks. |
| perf_compareA | 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. |
| trace_tablesB | Lists the data tables (schemas) a .trace recording holds; recordings keep their .trace only with KEEP_TRACE=1. |
| trace_queryB | Returns one page of rows of one table of a .trace as {column: value}, optionally only one process's rows. |
| capture_summaryB | Reads a Metal .gputrace capture without Xcode: command buffers, encoders, draws, debug groups, call ids. |
| capture_recordsB | Returns one page of the records of a .gputrace command stream, with their Metal call names when known. |
| gpu_familyA | 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| Apple GPU families | 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. |
| Apple7 GPU family | Apple's published facts for Apple7 |
| Apple8 GPU family | Apple's published facts for Apple8 |
| Apple9 GPU family | Apple's published facts for Apple9 |
| Apple10 GPU family | Apple's published facts for Apple10 |
TDQS
Scored across 8 tools
Tools cluster into three clear groups (perf_* recordings, trace_* .trace exploration, capture_* .gputrace exploration) plus a standalone reference tool, and within each group the actions are distinct. The only mild risk is confusing trace_* and capture_* since both inspect capture files, but the descriptions clearly separate .trace from .gputrace.
All names use consistent snake_case with a group prefix (perf_, trace_, capture_) that maps predictably to the domain area. Minor deviations: perf_runs and trace_tables use nouns rather than the verb style of their siblings, but the pattern remains readable.
Eight tools is well-scoped for a Metal tracing/analysis server, with each tool earning its place across recording, comparison, trace exploration, capture inspection, and reference lookups.
The surface covers the full workflow: record, list, compare, inspect trace tables/rows, and read gputrace captures, plus a GPU-family reference. Minor gaps like no delete/prune of saved recordings or export of results exist, but agents can work around them.