apple-instruments-mcp 1.0.0__tar.gz

apple_instruments_mcp-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint-typecheck-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package and dev tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Ruff
+        run: ruff check src tests
+
+      - name: Pyright
+        run: pyright
+
+      - name: Unit tests
+        run: python -m unittest discover -s tests -v

apple_instruments_mcp-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "[0-9]*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build backend
+        run: python -m pip install --upgrade pip build
+
+      - name: Verify tag matches package version
+        run: |
+          PKG_VERSION="$(python -c 'import tomllib, pathlib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
+          if [ "$GITHUB_REF_NAME" != "$PKG_VERSION" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match pyproject version $PKG_VERSION" >&2
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/apple-instruments-mcp
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

apple_instruments_mcp-1.0.0/.gitignore

@@ -0,0 +1,43 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+build/
+dist/
+wheels/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Installer / package manager state
+pip-wheel-metadata/
+
+# Test / type-check / lint caches
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Editor / OS
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Profiling artifacts produced by this tool
+*.xctrace
+*.trace
+instruments-mcp-*/

apple_instruments_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,372 @@
+Metadata-Version: 2.4
+Name: apple-instruments-mcp
+Version: 1.0.0
+Summary: MCP server for Apple platform profiling via xctrace/Instruments
+Project-URL: Homepage, https://github.com/dogo/apple-instruments-mcp
+Project-URL: Repository, https://github.com/dogo/apple-instruments-mcp
+Project-URL: Issues, https://github.com/dogo/apple-instruments-mcp/issues
+Author-email: Diogo Autilio <diautilio@gmail.com>
+License: MIT
+Keywords: instruments,ios,macos,mcp,model-context-protocol,performance,profiling,xctrace
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.380; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# apple-instruments-mcp
+
+`apple-instruments-mcp` is a Python MCP server for profiling Apple platform apps and processes with Instruments through `xcrun xctrace`. It lets MCP clients such as Claude Desktop record traces, inspect existing `.xctrace` bundles, and return concise performance reports with actionable recommendations.
+
+The server can target iOS, iPadOS, macOS, tvOS, watchOS, visionOS, simulators, physical devices, and host processes when those targets are visible to the installed Xcode/Instruments toolchain. Actual template and device support is determined by `xcrun xctrace list devices` and `xcrun xctrace list templates` on your Mac.
+
+## Features
+
+- Record new traces with `xctrace` from an MCP client.
+- Analyze existing `.xctrace` files without recording again.
+- Report launch time, memory allocations, leaks, CPU hot spots, and network activity.
+- Launch apps by bundle ID or executable path.
+- Attach to running processes by process name or PID.
+- Record all processes when an Instruments template supports it.
+- List available devices, simulators, runtimes, and Instruments templates.
+- Return raw or JSON-structured device/template listings.
+- Preview the generated `xctrace` command with `dry_run`.
+- Keep `.xctrace` and XML artifacts for later inspection.
+- Return human-readable summaries with top offenders and suggested fixes.
+- Runs as a standard stdio MCP server.
+
+## Requirements
+
+- macOS
+- Xcode with Instruments installed
+- Xcode Command Line Tools: `xcode-select --install`
+- Python 3.11 or newer
+- A supported target visible to `xctrace`: booted simulator, connected device, local macOS app, running process, or all-processes recording.
+
+Physical devices may require enabling UI automation in `Settings > Developer`.
+
+## Installation
+
+The package is published on PyPI. The recommended way is to run it through [`uvx`](https://github.com/astral-sh/uv), which downloads and caches the server on demand without polluting your environment:
+
+```bash
+uvx apple-instruments-mcp
+```
+
+Alternatively, install it globally with `pipx` or `pip`:
+
+```bash
+pipx install apple-instruments-mcp
+# or
+python -m pip install apple-instruments-mcp
+```
+
+Either path provides the `apple-instruments-mcp` executable.
+
+## MCP Client Configuration
+
+`apple-instruments-mcp` is a standard stdio MCP server, so any MCP-compatible client works — Claude Desktop, Claude Code, Codex CLI, Kiro, Cursor, Cline, Continue, Windsurf, Zed, or anything else that speaks MCP.
+
+The simplest config uses `uvx`, so the client launches the server on demand with no separate install step. Example for Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "apple-instruments": {
+      "command": "uvx",
+      "args": ["apple-instruments-mcp"]
+    }
+  }
+}
+```
+
+To pin a specific version, replace the arg with `apple-instruments-mcp@1.0.0`.
+
+For Claude Code:
+
+```bash
+claude mcp add apple-instruments -- uvx apple-instruments-mcp
+```
+
+If you prefer a global install (`pipx` or `pip`), point the client at the resulting binary instead:
+
+```json
+{
+  "mcpServers": {
+    "apple-instruments": {
+      "command": "apple-instruments-mcp"
+    }
+  }
+}
+```
+
+Other clients (Codex CLI, Kiro, Cursor, Cline, Continue, Windsurf, Zed) accept the same `command` / `args` shape under their own MCP server config — check the client's docs for the exact file path. Restart the client after saving.
+
+## Example Prompts
+
+```text
+List the devices and Instruments templates available on this Mac.
+Record an App Launch trace for com.example.app on this iPhone simulator and show the startup offenders.
+Launch /Applications/MyMacApp.app with Time Profiler and show CPU hot methods.
+Attach Allocations to the running process named MyMacApp for 30 seconds.
+Attach Time Profiler to PID 1234.
+Record all processes with Time Profiler for 10 seconds.
+Analyze network activity for com.example.app and flag slow requests.
+Analyze the existing trace at ~/Desktop/launch.xctrace.
+Compare ~/Desktop/baseline.xctrace and ~/Desktop/candidate.xctrace for launch regressions.
+```
+
+## Tools
+
+| Tool | Instruments template | Description |
+| --- | --- | --- |
+| `list_devices` | - | Lists devices, simulators, runtimes, and host targets visible to `xctrace`. |
+| `list_devices_structured` | - | Returns the device/runtime listing as JSON. |
+| `list_templates` | - | Lists Instruments templates installed on this Mac. |
+| `list_templates_structured` | - | Returns the template listing as JSON. |
+| `profile_ios_app` | Selected by `profile_type` | Profiles an iOS, iPadOS, tvOS, watchOS, or visionOS app by bundle ID on a simulator/device. |
+| `profile_mac_app` | Selected by `profile_type` | Profiles a macOS `.app` or executable by launch path. |
+| `profile_process` | Selected by `profile_type` | Profiles a running process by process name or PID. |
+| `profile_all_processes` | Selected by `profile_type` | Profiles all processes on the host or selected device. |
+| `analyze_launch` | App Launch | Records and analyzes app startup time. |
+| `analyze_launch_trace` | App Launch | Analyzes an existing App Launch `.xctrace`. |
+| `analyze_allocations` | Allocations | Records memory allocations and reports top allocation types. |
+| `analyze_allocations_trace` | Allocations | Analyzes an existing Allocations `.xctrace`. |
+| `analyze_leaks` | Leaks | Records leak information and reports likely retain-cycle issues. |
+| `analyze_leaks_trace` | Leaks | Analyzes an existing Leaks `.xctrace`. |
+| `analyze_time_profiler` | Time Profiler | Records CPU samples and reports hot methods. |
+| `analyze_time_profiler_trace` | Time Profiler | Analyzes an existing Time Profiler `.xctrace`. |
+| `analyze_network` | Network | Records network requests, latency, transfer sizes, and status codes. |
+| `analyze_network_trace` | Network | Analyzes an existing Network `.xctrace`. |
+| `compare_launch_traces` | App Launch | Compares two App Launch traces and reports startup deltas. |
+| `compare_memory_traces` | Allocations | Compares two Allocations traces and reports memory deltas. |
+| `compare_cpu_traces` | Time Profiler | Compares two Time Profiler traces and reports CPU deltas. |
+| `build_xctrace_command` | Any | Returns the exact `xcrun xctrace record` command for a target without executing it. |
+
+## Recording Targets
+
+Recording tools accept exactly one target mode:
+
+- `bundle_id`: app bundle identifier, for example `com.example.app`. Use with `device_id` for iOS, iPadOS, tvOS, watchOS, and visionOS simulator/device launches.
+- `launch_path`: executable path or `.app` path. Use this for macOS apps and command-line tools.
+- `process_name`: attach to a running process by name.
+- `pid`: attach to a running process by process ID.
+- `all_processes`: record all processes when the selected template supports it.
+
+Additional recording arguments:
+
+- `device_id`: optional simulator UUID or physical device identifier from `list_devices`. Omit it for host macOS profiling.
+- `launch_args`: optional shell-style arguments passed after `launch_path`.
+- `time_limit_seconds`: recording duration, from 5 to 120 seconds. Defaults to 20.
+- `dry_run`: return the generated `xctrace` command without recording.
+- `keep_trace`: keep generated `.xctrace` and XML artifacts, and include their paths in the report.
+- `output_dir`: optional parent directory for generated artifacts. Each run creates a dedicated subdirectory inside it.
+
+Examples:
+
+```json
+{ "bundle_id": "com.example.app", "device_id": "SIMULATOR-UUID" }
+{ "launch_path": "/Applications/MyMacApp.app" }
+{ "launch_path": "/usr/bin/python3", "launch_args": "--version" }
+{ "process_name": "MyMacApp" }
+{ "pid": 1234 }
+{ "all_processes": true }
+{ "launch_path": "/Applications/MyMacApp.app", "dry_run": true }
+{ "bundle_id": "com.example.app", "device_id": "SIMULATOR-UUID", "keep_trace": true, "output_dir": "~/Desktop/traces" }
+```
+
+The `profile_*` tools are higher-level wrappers around the generic `analyze_*` tools. Prefer them when you know the target shape:
+
+```json
+{ "profile_type": "launch", "bundle_id": "com.example.app", "device_id": "SIMULATOR-UUID" }
+{ "profile_type": "time_profiler", "launch_path": "/Applications/MyMacApp.app" }
+{ "profile_type": "allocations", "process_name": "MyMacApp" }
+{ "profile_type": "time_profiler", "pid": 1234 }
+{ "profile_type": "time_profiler" }
+```
+
+Supported `profile_type` values are `launch`, `allocations`, `leaks`, `time_profiler`, and `network`.
+
+## Custom Thresholds
+
+The generic `analyze_*` and `analyze_*_trace` tools expose parser-specific thresholds. Use these when the defaults are too strict or too loose for a device class, platform, workload, or CI budget.
+
+Launch:
+
+- `launch_good_ms`
+- `launch_critical_ms`
+- `offender_warning_ms`
+- `offender_critical_ms`
+
+Allocations:
+
+- `memory_warning_mb`
+- `memory_critical_mb`
+- `memory_cache_warning_mb`
+
+Leaks:
+
+- `leak_critical_count`
+
+Time Profiler:
+
+- `total_good_ms`
+- `total_critical_ms`
+- `method_warning_ms`
+- `method_critical_ms`
+
+Network:
+
+- `request_warning_ms`
+- `request_critical_ms`
+- `slow_request_critical_count`
+- `transfer_warning_mb`
+
+Example:
+
+```json
+{
+  "bundle_id": "com.example.app",
+  "device_id": "SIMULATOR-UUID",
+  "launch_good_ms": 700,
+  "launch_critical_ms": 1500,
+  "offender_warning_ms": 150,
+  "offender_critical_ms": 500
+}
+```
+
+## Trace Analysis Arguments
+
+Trace analysis tools accept:
+
+- `trace_path`: absolute path to an existing `.xctrace` bundle.
+- `bundle_id`: optional target name used in the generated report.
+
+Trace comparison tools accept:
+
+- `baseline_trace_path`: absolute path to the baseline `.xctrace` bundle.
+- `candidate_trace_path`: absolute path to the candidate `.xctrace` bundle.
+- `bundle_id`: optional target name used in the generated report.
+
+Example:
+
+```json
+{
+  "baseline_trace_path": "~/Desktop/baseline.xctrace",
+  "candidate_trace_path": "~/Desktop/candidate.xctrace",
+  "bundle_id": "com.example.app"
+}
+```
+
+## Example Report
+
+```markdown
+# App Launch Analysis - com.example.app
+
+Warning: Launch time 1240ms - above 400ms. Users may notice the delay.
+
+**Total:** 1240ms
+
+## Phases
+- **pre-main (dyld + static init):** 434ms (35%)
+- **post-main (AppDelegate + UI):** 806ms (65%)
+
+## Top Offenders
+
+Critical: `-[DatabaseManager setup]` [post-main]
+   Self: **540ms** | Total: 540ms | 43%
+   Suggestion: Move database initialization to a background queue or use lazy loading.
+
+Warning: `+[AnalyticsSDK configure:]` [post-main]
+   Self: **210ms** | Total: 210ms | 17%
+   Suggestion: Defer analytics SDK initialization after first frame is rendered.
+
+## Recommendations
+- Fix 1 critical offender(s) - each adds 300ms+ to launch.
+- Target: total launch under 400ms.
+```
+
+## Notes
+
+- Temporary `.xctrace` files created by recording tools are cleaned up after each run.
+- All analysis is based on the XML exported by `xcrun xctrace export`.
+- The parsers support multiple XML shapes emitted by different Xcode/Instruments versions, but Instruments output can vary between releases.
+- Reports include an `Analysis Quality` section when the exported XML is empty or no recognizable data was found for the selected parser.
+- If you already have a trace, prefer the `_trace` tools to avoid recording again.
+
+## Troubleshooting
+
+Recording tools run a few pre-flight checks before invoking `xctrace`. A target is rejected up front when `launch_path` does not exist on this Mac, `pid` is not a positive integer or no longer running, or `bundle_id` contains characters Instruments does not accept. When `xctrace` itself fails, the error message is classified per target (bundle not installed, dead process, unresolved device, invalid `launch_path`, missing Xcode tools) and the report includes a fix hint scoped to that target instead of a generic checklist.
+
+If recording fails, check these first:
+
+- The target app is installed on the selected simulator or device, or the local launch path exists.
+- The simulator/device is booted and visible in `xcrun xctrace list devices`.
+- The process exists when using `process_name` or `pid`.
+- Xcode and command line tools are selected correctly: `xcode-select -p`.
+- The Instruments template exists on your machine: use `list_templates`.
+- Physical devices are trusted, unlocked, connected, and allowed to run UI automation.
+
+Use `build_xctrace_command` to inspect the exact command that would run, without recording. The returned command also surfaces any pre-flight warnings detected against the chosen target.
+
+You can also verify `xctrace` directly:
+
+```bash
+xcrun xctrace list devices
+xcrun xctrace list templates
+```
+
+## Development
+
+Clone the repository and install the editable build with the `dev` extra:
+
+```bash
+git clone git@github.com:dogo/apple-instruments-mcp.git
+cd apple-instruments-mcp
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+Run linters, type check, and the test suite:
+
+```bash
+ruff check src tests
+pyright
+PYTHONPATH=src python -m unittest discover -s tests -v
+```
+
+The package ships a `py.typed` marker so downstream consumers can type-check against its public API. A `uv.lock` is committed for reproducible dependency installs with [uv](https://github.com/astral-sh/uv); CI runs the same checks across Python 3.11–3.13 via `.github/workflows/ci.yml`.
+
+Run the MCP server locally:
+
+```bash
+python -m apple_instruments_mcp
+```
+
+### Releasing
+
+Releases are published to PyPI through GitHub Actions trusted publishing — no API tokens stored in the repo. Steps:
+
+1. Bump `version` in `pyproject.toml`, commit, and push to `main`.
+2. Tag the commit with `X.Y.Z` (no `v` prefix) matching that version and push the tag.
+3. The `Release` workflow builds `sdist` + `wheel`, verifies the tag matches `pyproject.toml`, and uploads to PyPI via OIDC.
+
+One-time PyPI setup: on https://pypi.org, register the project name and add a Trusted Publisher pointing at this repository, the `release.yml` workflow, and the `pypi` environment.
+
+## License
+
+MIT