xcodeinstrumentmcp

xcodeinstrumentmcp is a local-first CLI and MCP server for turning Xcode Instruments artifacts into bounded, agent-sized evidence.

It ships one package with:

• CLI workflows for doctor, list, record, import, summarize, compare, prompt, db, signpost, and mcp
• local SQLite caching with stable snapshot, comparison, and prompt-pack IDs
• fixture-backed analyzers for Time Profiler, Allocations, Hangs, Network, Leaks, Energy Log, Memory Graph, and experimental Processor Trace
• Swift-only signpost scan/plan/apply/revert/status flows backed by the xim-swiftsignpost SwiftSyntax helper
• a bounded MCP surface over the same high-value workflows

Install

Repo-local install:

pnpm install
pnpm exec tsup
node dist/index.js doctor

Requirements:

• macOS 14+
• Node.js 22+
• Xcode / xctrace
• Swift toolchain for signpost helper build/use

CLI Quick Start

Check the local environment:

xcodeinstrumentmcp doctor

Import and persist a Time Profiler trace:

xcodeinstrumentmcp import --instrument time-profiler --input ./run.trace

Summarize a supported family fixture or artifact:

xcodeinstrumentmcp summarize --instrument allocations --input ./allocations.xml --format markdown
xcodeinstrumentmcp summarize --instrument network --input ./session.har --format json

Compare two stored snapshots:

xcodeinstrumentmcp compare --baseline-snapshot snap_base --candidate-snapshot snap_new --format json

Generate a reusable prompt pack:

xcodeinstrumentmcp prompt --snapshot snap_abc --size medium --format json

Scan and apply Swift signpost instrumentation:

xcodeinstrumentmcp signpost scan --project-root .
xcodeinstrumentmcp signpost plan --project-root . --strategy explicit-symbols --symbol GatewayViewModel.refresh
xcodeinstrumentmcp signpost apply --plan plan_abc

Inspect the local cache:

xcodeinstrumentmcp db stats
xcodeinstrumentmcp db list-snapshots

Support Matrix

• time-profiler: stable first-class analyzer with record, summarize, compare, and prompt support
• allocations: stable first-class analyzer from trace export or exported detail XML
• hangs: stable first-class analyzer from hang tables or fixture XML
• network: stable first-class analyzer from HAR import with redaction by default
• leaks: stable summary analyzer with conservative confidence language
• energy-log: stable summary analyzer from exported summary XML
• memory-graph: stable summary analyzer from imported .memgraph fixtures
• processor-trace: experimental gated analyzer with explicit caveats in CLI and MCP responses

MCP Setup

Cursor / generic stdio client:

{
  "command": "xcodeinstrumentmcp",
  "args": ["mcp"]
}

Repo-local stdio launch:

{
  "command": "node",
  "args": ["/absolute/path/to/dist/index.js", "mcp"]
}

Current MCP surface includes bounded workflow tools such as:

• record_time_profile
• record_profile
• import_source
• summarize_trace
• summarize_snapshot
• compare_traces
• compare_snapshots
• generate_optimization_prompt
• generate_prompt_pack
• list_snapshots
• get_snapshot
• get_comparison
• get_findings
• plan_signposts
• apply_signpost_plan
• revert_signpost_patch

Limitations

• Processor Trace is experimental and returns experimental: true in MCP responses.
• Network analysis is HAR-first in this release; trace-side network capture is still target/platform dependent.
• Memory Graph support is import-oriented rather than a unified xctrace record path.
• Outputs are intentionally bounded; raw exports are not returned by default.

Privacy

The tool is local-only. Persistence is local SQLite under ~/Library/Application Support/xcodeinstrumentmcp/cache.db unless XIM_DB_PATH overrides it for tests or custom local workflows.

Network outputs keep bodies, auth headers, and sensitive query values redacted by default. Sensitive network fields require an explicit opt-in flag or MCP argument.

Troubleshooting

xctrace not found:

• Run xcodeinstrumentmcp doctor.
• Confirm xcrun --find xctrace succeeds.

No Time Profiler table found:

• Re-record with the Time Profiler template or import a supported Time Profiler trace.

Processor Trace record/import is unavailable:

• The analyzer is experimental and capability-gated.
• Prefer importing a known-good Processor Trace artifact when host/target versions differ.

Signpost helper build fails:

• Confirm swift --version works.
• Re-run xcodeinstrumentmcp doctor and swift build -c release --package-path tools/xim-swiftsignpost.

compare --baseline-snapshot fails:

• Ensure both snapshots come from the same family, or pass explicit source artifacts with a supported comparison strategy.