@xctrace-analyzer/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 James Rochabrun
+
+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.

package/README.md

@@ -0,0 +1,558 @@
+# Xcode Instruments Trace Analyzer MCP Server
+
+> Model Context Protocol server for intelligent Xcode Instruments trace analysis
+
+This MCP server provides AI assistants like Claude with the ability to automate `xcrun xctrace` workflows: record traces, symbolicate traces, export TOC/XML/HAR data, detect Time Profiler bottlenecks, summarize exportable Memory/Network/Energy/Allocations/Leaks data, identify Time Profiler regressions, clean up generated traces, and provide actionable recommendations.
+
+It is an **honest Instruments companion**, not a complete GUI replacement. Recording tools open the saved `.trace` in Instruments.app by default, and any template or view that is absent from the trace or not exportable through `xctrace` is reported explicitly.
+
+## Features
+
+- 🔍 **Intelligent Analysis** - Automatically identifies performance bottlenecks
+- 🎥 **Automated Recording** - Attach to a running app, save a trace, and analyze it in one tool call
+- 🧭 **Multi-Instrument Analysis** - Auto-detects Memory, Network, Energy, Allocations, and Leaks data when exportable
+- 📊 **Regression Detection** - Compare traces to find performance regressions
+- 💡 **Actionable Recommendations** - Get specific optimization suggestions with code examples
+- 🧾 **Structured Diagnostics** - Support matrix, export attempts, and JSON output for CI or agents
+- 🧹 **Trace Cleanup** - Preview or delete generated `.trace` bundles after inspection
+- 🤖 **Natural Language Interface** - Use Claude to interact with your performance data
+- ⚙️ **Local-first** - Runs through your installed Xcode Command Line Tools
+
+## Installation
+
+### Claude Code
+
+```bash
+claude mcp add --transport stdio --scope user xctrace-analyzer -- npx -y @xctrace-analyzer/mcp-server
+```
+
+Verify the local machine has a usable `xcrun xctrace`:
+
+```bash
+npx -y @xctrace-analyzer/mcp-server --check
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "xctrace-analyzer": {
+      "command": "npx",
+      "args": ["-y", "@xctrace-analyzer/mcp-server"]
+    }
+  }
+}
+```
+
+### Building from Source
+
+```bash
+# From the monorepo root
+pnpm install --frozen-lockfile
+pnpm verify
+```
+
+## Available Tools
+
+### Recommended User Experience
+
+For human-facing use, register the bundled skill at [`../../skills/xctrace-profiler`](../../skills/xctrace-profiler/SKILL.md) in clients that support skills. Then users can stay at the prompt level:
+
+```text
+Profile this app.
+Find why this app is slow.
+Profile this app for hangs.
+Profile this app for hangs and tell me which of my code is responsible.
+Check this build for leaks and allocation churn.
+Analyze network activity.
+Launch this app and profile startup hangs.
+I will launch MyApp; record it for 60 seconds when it appears.
+Analyze this trace.
+Compare these two traces.
+Clean up profiling traces when we are done.
+```
+
+The skill is the planner for this MCP server. It chooses between recording, existing trace analysis, single-template tracking, device/template checks, scoped hang follow-ups, trace comparisons, and safe cleanup once the user no longer needs the saved trace. When the user says they will launch the app manually, the skill starts watching for the app process immediately and attaches to the first valid PID without waiting for a second prompt. The MCP server itself exposes execution tools only.
+
+### Tool Selection Guide
+
+- Use `profile_running_app` for "start profiling", "full report", or "record all issues" requests against an already-running app.
+- Use `track_running_app` for a single explicit Instruments template such as Leaks or Allocations.
+- Use `analyze_trace` when the user already has a `.trace` file, especially for scoped follow-up analysis with `timeRangeMs` and app attribution via Top User-Code Frames.
+- Use `compare_traces` when the user asks whether a current build regressed against a baseline.
+- Use `cleanup_traces` after the user confirms recorded traces are no longer needed, or as a dry-run preview for stale trace directories.
+- Use `list_templates`, `list_devices`, and `check_xctrace` for setup and troubleshooting.
+
+### Security Defaults
+
+Attach profiling and trace analysis work by default. The secure defaults do not reduce the Instruments recorded by the `full`, `memory`, `network`, or `full-ios` presets; they restrict higher-risk MCP operations.
+
+| Option | Default | Why it is useful and important |
+| --- | --- | --- |
+| `XCTRACE_ANALYZER_ALLOW_LAUNCH=1` | Disabled | Enables true startup/cold-launch profiling. It is disabled by default because `launchCommand` asks the MCP server to execute a local program through `xcrun xctrace --launch`. |
+| `XCTRACE_ANALYZER_ALLOW_ALL_PROCESSES=1` | Disabled | Enables system-wide traces when one process is not enough. It is disabled by default because the trace can include unrelated apps, services, paths, URLs, and symbols. |
+| `XCTRACE_ANALYZER_TRACE_ROOT=/path/to/traces` | `~/Library/Application Support/xctrace-analyzer/traces` | Sets the allowed trace output root. Keeping traces in one user-level folder reduces accidental project churn and makes cleanup safer. |
+| `XCTRACE_ANALYZER_ALLOW_EXTERNAL_OUTPUT=1` | Disabled | Allows `outputPath`, `outputDirectory`, `targetStdin`, and `targetStdout` outside the trace root. It is useful for CI or shared scratch volumes, but broadens where the MCP server can write. |
+| `XCTRACE_ANALYZER_ALLOW_EXTERNAL_CLEANUP=1` | Disabled | Allows destructive cleanup outside the trace root. It is useful for maintenance of a trusted trace archive, but should be paired with a dry run or exact trace paths. |
+| `XCTRACE_ANALYZER_MAX_DURATION_SECONDS=300` | `300` | Caps recording duration to avoid accidental long-running captures and very large `.trace` bundles. Raise it only for expected long repros. |
+| `XCTRACE_ANALYZER_REDACTION=balanced` | `balanced` | Controls report redaction. `balanced` hides common secrets and user paths, `strict` also hides hostnames, and `off` preserves full details for trusted local debugging. |
+
+For startup profiling with the default security posture, manually launch the app and attach by exact PID as soon as it appears. For trusted local launch profiling, start the server with:
+
+```bash
+XCTRACE_ANALYZER_ALLOW_LAUNCH=1 npx -y @xctrace-analyzer/mcp-server
+```
+
+Claude Desktop-style MCP configs can pass the same settings through `env`:
+
+```json
+{
+  "mcpServers": {
+    "xctrace-analyzer": {
+      "command": "npx",
+      "args": ["-y", "@xctrace-analyzer/mcp-server"],
+      "env": {
+        "XCTRACE_ANALYZER_ALLOW_LAUNCH": "1",
+        "XCTRACE_ANALYZER_TRACE_ROOT": "/Users/you/Library/Application Support/xctrace-analyzer/traces"
+      }
+    }
+  }
+}
+```
+
+### `profile_running_app`
+
+Record a running app once with a profiling preset and return one combined report. `durationSeconds: 60` means one 60-second recording. The preset uses a base template plus additional Instruments where Xcode supports it.
+
+**Parameters:**
+- `processName` (optional): Running process name or pid to attach to; required for attach mode
+- `target` (optional): `attach`, `launch`, or `all-processes`
+- `launchCommand`, `launchArguments`, `environment` (optional): launch target details
+- `preset` (optional): `full`, `full-ios`, `cpu`, `memory`, `network`, or `energy` (default: `full`)
+- `durationSeconds` (optional): Total recording duration in seconds (default: 60)
+- `device` (optional): Device or simulator name/UDID
+- `outputDirectory` (optional): Directory where generated `.trace` files should be saved (default: configured trace root)
+- `analyze` (optional): Analyze after recording (default: true)
+- `openInInstruments` (optional): Open the saved `.trace` in Instruments.app after recording (default: true). Set false for CI or headless runs.
+- `outputFormat` (optional): `markdown`, `json`, or `both` (default: `markdown`)
+
+Preset recordings:
+- `full`: Time Profiler base with Leaks, Allocations, and HTTP Traffic instruments
+- `full-ios`: Time Profiler base with Leaks, Allocations, HTTP Traffic, and Power Profiler instruments
+- `cpu`: Time Profiler
+- `memory`: Allocations base with Leaks instrument
+- `network`: Time Profiler base with HTTP Traffic instrument
+- `energy`: Power Profiler. This is for iOS/iPadOS targets; Xcode commonly does not expose Power Profiler data for macOS recordings.
+
+Report contents:
+- Recording metadata: process, preset, duration, trace path, base template, instruments, and Instruments.app open status
+- Support matrix and export diagnostics
+- CPU / Time Profiler: bottlenecks, top functions, threads, slow function count, and CPU recommendations
+- Hangs: main-thread hang events; severe hangs affect Overall status and Prioritized Recommendations even when Time Profiler CPU thresholds are otherwise clean
+- Top User-Code Frames: app-attributed CPU frames from Time Profiler samples
+- Time Profiler parse-failure callouts when CPU samples could not be parsed
+- Leaks: leak count, leaked bytes, top leak sites, and leak findings when Xcode exports usable data
+- Allocations: allocation counts, allocated bytes, top allocation sites, and churn findings when exportable
+- Network: request count, failed requests, transferred bytes, top hosts, and network failure findings when HAR/CFNetwork data is available
+- Prioritized Recommendations: deduplicated CPU and instrument recommendations sorted for review
+
+Reports retain trace paths and include a cleanup reminder. Use `cleanup_traces` after the user is finished inspecting the trace in Instruments.app.
+
+**Example with Claude:**
+```
+Start profiling MyApp for 60 seconds and report all issues
+```
+
+### `track_running_app`
+
+Attach to a running process with `xcrun xctrace record`, save the generated `.trace`, and optionally analyze it immediately.
+
+**Parameters:**
+- `processName` (optional): Running process name or pid to attach to; required for attach mode
+- `target` (optional): `attach`, `launch`, or `all-processes`
+- `launchCommand`, `launchArguments`, `environment` (optional): launch target details
+- `template` (optional): Instruments template, for example `Leaks`, `Allocations`, `Network`, `Power Profiler`, or `Time Profiler` (default: `Leaks`)
+- `durationSeconds` (optional): Recording duration in seconds (default: 60)
+- `device` (optional): Device or simulator name/UDID
+- `outputDirectory` (optional): Directory where the `.trace` file should be saved (default: configured trace root)
+- `outputPath` (optional): Exact output `.trace` path. Overrides `outputDirectory`
+- `analyze` (optional): Analyze after recording (default: true)
+- `openInInstruments` (optional): Open the saved `.trace` in Instruments.app after recording (default: true). Set false for CI or headless runs.
+- `outputFormat` (optional): `markdown`, `json`, or `both` (default: `markdown`)
+
+**Example with Claude:**
+```
+Track MyApp for leaks for 60 seconds on the iPhone 16 Pro Simulator
+```
+
+Use this tool when the user names a template. For broad profiling, prefer `profile_running_app`.
+
+If Leaks, Allocations, or another analysis family is `not_exportable`, the trace may still show a GUI track in Instruments.app while `xcrun export --toc` exposes no exportable table schema. Use the opened Instruments trace to verify that GUI-only data.
+
+The trace remains on disk after recording. Use `cleanup_traces` after the user is done inspecting it.
+
+### `analyze_trace`
+
+Analyze a single trace file for performance issues. The server auto-detects supported Time Profiler, Memory, Network, Energy, Allocations, and Leaks data from the trace TOC.
+
+**Parameters:**
+- `tracePath` (required): Path to .trace file
+- `slowThreshold` (optional): Threshold in ms for slow functions (default: 100)
+- `topN` (optional): Number of top functions to show (default: 10)
+- `dsymPath` (optional): dSYM file or directory. The server writes a temporary symbolicated trace before analysis.
+- `timeRangeMs` (optional): `{ startMs, endMs }` trace-relative window in milliseconds. Use this for follow-up questions like "what ran during this 5 second hang?"
+- `userBinaryHints` (optional): app or module names used when trace metadata cannot identify user binaries
+- `outputFormat` (optional): `markdown`, `json`, or `both`
+
+The report distinguishes data that is not present in the trace from data that is present but not exportable. A Time Profiler parse failure is reported as a failed CPU analysis with Export Diagnostics; do not read it as zero CPU work.
+
+Scoped analysis filters Time Profiler samples before function aggregation and filters hang events that overlap the requested window. Top User-Code Frames walks each sample backtrace from leaf to root and aggregates the deepest frame whose module matches the trace's user process names or `userBinaryHints`.
+
+**Example with Claude:**
+```
+Analyze /Users/me/app.trace and show me the performance bottlenecks
+```
+
+This tool does not record anything. It only reads trace files that already exist.
+
+### `compare_traces`
+
+Compare two Time Profiler traces to detect regressions or improvements.
+
+**Parameters:**
+- `baselinePath` (required): Path to baseline .trace file
+- `currentPath` (required): Path to current .trace file
+- `regressionThreshold` (optional): % increase to flag (default: 10)
+- `failOnRegression` (optional): Mark the MCP tool result as an error if a regression is detected (default: false)
+- `baselineDsymPath`, `currentDsymPath` (optional): dSYM paths used to symbolicate temporary traces before comparison
+- `outputFormat` (optional): `markdown`, `json`, or `both`
+
+**Example with Claude:**
+```
+Compare baseline.trace with current.trace and tell me if performance regressed
+```
+
+This comparison currently focuses on Time Profiler data. Additional instrument comparison is future work.
+
+### `cleanup_traces`
+
+Preview or delete `.trace` bundles created by profiling runs.
+
+**Parameters:**
+- `tracePaths` (optional): Exact `.trace` paths to preview or delete. This is the preferred post-report cleanup path.
+- `directory` (optional): Directory to scan when `tracePaths` is omitted (default: configured trace root)
+- `recursive` (optional): Recursively scan subdirectories in directory mode (default: false)
+- `olderThanMinutes` (optional): Only match traces older than this many minutes. Required for destructive directory cleanup.
+- `dryRun` (optional): Preview only by default. Set false after the user confirms deletion.
+- `outputFormat` (optional): `markdown`, `json`, or `both`
+
+Safety rules:
+- Only paths ending in `.trace` are deleted.
+- `dryRun` defaults to true.
+- `dryRun: false` with directory scanning requires `olderThanMinutes`, unless exact `tracePaths` are provided.
+
+**Example with Claude:**
+```
+Clean up the traces from the last profiling run.
+```
+
+### `list_templates`
+
+List all available Instruments templates on the system.
+
+**Example with Claude:**
+```
+What Instruments templates are available?
+```
+
+### `list_devices`
+
+List available devices for profiling.
+
+**Example with Claude:**
+```
+Show me available devices for profiling
+```
+
+### `check_xctrace`
+
+Check if xctrace is available and report command capabilities, templates, devices, instruments, export modes, and warnings.
+
+**Example with Claude:**
+```
+Is xctrace available on this system?
+```
+
+## Usage Examples
+
+### Full Profiling Report
+
+```
+You: Start profiling MyApp for 60 seconds and report all issues.
+
+Claude: I'll record the full profiling preset and combine the results.
+
+# Profiling Report
+
+- Process: MyApp
+- Preset: full
+- Recording strategy: combined
+- Duration: 60s
+- Base template: Time Profiler
+- Instruments: Leaks, Allocations, HTTP Traffic
+
+## Summary
+- Overall status: critical issues found
+- Traces recorded: 1/1
+- Traces analyzed: 1/1
+
+## Trace Files
+- Time Profiler: ~/Library/Application Support/xctrace-analyzer/traces/MyApp-full-...trace
+## Prioritized Recommendations
+- critical Leaks Analysis: Leaks detected - The trace contains leaked memory.
+```
+
+### Automated Leak Tracking
+
+```
+You: Track MyApp for memory leaks for 60 seconds.
+
+Claude: I'll record the running app with the Leaks template and analyze the trace.
+
+# Running App Trace Report
+
+- Process: MyApp
+- Template: Leaks
+- Duration: 60s
+- Trace: ~/Library/Application Support/xctrace-analyzer/traces/MyApp-Leaks-2026-05-02T16-30-00-000Z.trace
+
+## Additional Instrument Analysis
+
+### Leaks Analysis
+3 leaks were detected.
+```
+
+### Manual Launch Recording
+
+```
+You: I will launch MyApp; record it for 60 seconds when it appears.
+
+Claude: I'm watching for MyApp now; launch it when ready.
+
+# Profiling Report
+
+- Target: MyApp PID 12345, attached immediately after launch
+- Duration: 60s
+- Preset: full
+- Trace: ~/Library/Application Support/xctrace-analyzer/traces/MyApp-full-...trace
+- Instruments.app: opened
+```
+
+### Basic Analysis
+
+```
+You: Claude, analyze my latest performance trace at ~/traces/myapp.trace
+
+Claude: I've analyzed your trace. Here's what I found:
+
+# Performance Analysis Report
+
+**Duration:** 5.2s
+**Template:** Time Profiler
+
+## Summary
+⚠️ Found 1 critical performance issue.
+Total execution time: 5.2s across 3 threads.
+Primary bottleneck: ImageProcessor.resize() (450ms, 8.7% of time).
+
+## Performance Bottlenecks
+
+### 🔴 1. ImageProcessor.resize()
+- **Impact:** critical
+- **Duration:** 450ms (8.7% of total)
+- **Call count:** 24
+- **Suggestion:** Consider caching rendered images or using lower resolution
+
+## Optimization Recommendations
+
+### ⚠️ Implement Image Caching
+**Priority:** high | **Type:** caching
+
+Frequent image operations detected. Consider implementing NSCache
+or disk-based caching to avoid repeated processing.
+
+**Potential improvement:** 50-70% reduction in image processing time
+
+**Example:**
+```swift
+let imageCache = NSCache<NSString, UIImage>()
+
+func cachedImage(for key: String) -> UIImage? {
+    if let cached = imageCache.object(forKey: key as NSString) {
+        return cached
+    }
+    let image = processImage(key)
+    imageCache.setObject(image, forKey: key as NSString)
+    return image
+}
+```
+```
+
+### Comparing Traces
+
+```
+You: Compare my baseline trace with the current build.
+     Baseline: ~/traces/v1.0.trace
+     Current: ~/traces/v2.0.trace
+
+Claude: I've compared the two traces. Here's the analysis:
+
+# Trace Comparison Report
+
+**Baseline:** v1.0.trace
+**Current:** v2.0.trace
+
+## Summary
+⚠️ Performance regressed by 15.3% (+0.65s slower).
+🔴 Found 2 critical regressions.
+
+## Performance Delta
+⚠️ Total time change: +0.65s (+15.3%)
+- Regressions: 3
+- Improvements: 2
+- Unchanged: 15
+
+## Regressions
+
+🔴 **NetworkClient.parseJSON()** (critical)
+  50ms → 85ms (+70%)
+
+🟠 **DatabaseManager.fetchAll()** (major)
+  120ms → 180ms (+50%)
+
+## Improvements
+
+✅ **ImageProcessor.cache()***
+  200ms → 80ms (-60%)
+
+The NetworkClient regression is concerning and should be investigated.
+```
+
+### Development Workflow
+
+```
+You: I just profiled my app. Analyze the latest trace and help me optimize.
+
+Claude: Let me analyze the latest trace...
+
+[Analyzes trace]
+
+I found 3 optimization opportunities:
+
+1. 🎯 **High Impact** - ImageCache missing (save ~400ms)
+2. 🎯 **Medium Impact** - JSON parsing on main thread (save ~150ms)
+3. 🎯 **Low Impact** - Multiple small allocations (save ~50ms)
+
+Would you like me to help implement any of these optimizations?
+
+You: Yes, help with #1
+
+Claude: Great! Let's implement image caching...
+[Provides implementation guidance]
+```
+
+## Requirements
+
+- **macOS** with Xcode Command Line Tools installed
+- **Node.js** 18+ (for running the MCP server)
+- **Claude Desktop** or another MCP-compatible client
+- Time Profiler, Memory, Network, Energy, Allocations, or Leaks `.trace` files. Exported table availability depends on Xcode and the trace template.
+
+## How It Works
+
+1. **MCP Request**: The client calls a JSON-RPC tool such as `profile_running_app`.
+2. **Capability Check**: The server can inspect local `xctrace` version, templates, devices, instruments, export modes, and symbolication support.
+3. **xctrace Record**: Recording tools call `xcrun xctrace record` with attach, launch, or all-processes targets.
+4. **xctrace Export**: Analysis calls `xcrun xctrace export --toc`, TOC-discovered XPath table exports, and HAR export when available.
+5. **XML / HAR Parsing**: The core parser normalizes Time Profiler rows and supported instrument tables into typed data with export diagnostics.
+6. **Analysis Engine**: The analyzer finds bottlenecks, instrument findings, support status, and recommendations.
+7. **MCP Response**: The server returns Markdown, JSON, or both.
+
+## Troubleshooting
+
+### xctrace not found
+
+Make sure Xcode Command Line Tools are installed:
+```bash
+xcode-select --install
+```
+
+### Permission errors
+
+The .trace files must be readable. Check file permissions:
+```bash
+ls -la /path/to/trace.trace
+```
+
+### No supported data
+
+The server reads supported tables from `xcrun xctrace export --toc` and uses HAR export for Network traces when available. If Xcode does not expose usable tables for a template, analysis may return a clear no-data section instead of findings.
+
+### pnpm/Corepack warnings
+
+The root `package.json` pins `pnpm` through `packageManager`. Use Corepack or install pnpm 10.6.3:
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+```
+
+### Server not connecting
+
+1. Check Claude Desktop config file syntax (must be valid JSON)
+2. Verify the path to index.js is correct
+3. Restart Claude Desktop after config changes
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Typecheck, test, and build
+pnpm verify
+
+# Start the built server, initialize MCP, and verify tools/list
+pnpm test:mcp-smoke
+
+# Inspect schemas exposed by local traces
+pnpm inspect:trace test-traces/memory.trace
+
+# Development with watch mode
+pnpm dev:mcp
+```
+
+## Architecture
+
+```
+MCP Client (Claude)
+    ↓ JSON-RPC 2.0
+MCP Server (this package)
+    ↓
+@xctrace-analyzer/core
+    ↓
+xcrun xctrace (macOS)
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please see the main repository README for guidelines.