Inspector MCP

Inspector MCP

Overview

Use this skill to set up and use the Inspector MCP bridge against a running iOS Simulator app. Prefer this when the task is live UI inspection, not static source reading.

Workflow

1. Find the Inspector package path first

Do not assume Inspector lives in the current repo. In consumer apps it is often checked out under Xcode DerivedData.

Use the bundled helper first:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/inspector-mcp/scripts/find_inspector_package.py" \
  --xcodeproj /absolute/path/to/App.xcodeproj \
  --scheme AppScheme

Or for workspaces:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/inspector-mcp/scripts/find_inspector_package.py" \
  --workspace /absolute/path/to/App.xcworkspace \
  --scheme AppScheme

If that fails:

• Check whether the app uses a local package reference instead of a DerivedData checkout.
• If you already know the Inspector repo path, use that as --package-path.
• Read consumer-app-setup.md for the fallback flow.

2. Derive the app launch inputs

You need:

• Xcode project or workspace path
• scheme
• bundle identifier

Bundle identifier pattern:

xcodebuild -project /absolute/path/to/App.xcodeproj -scheme AppScheme -showBuildSettings \
  | awk -F ' = ' '$1 ~ /^[[:space:]]*PRODUCT_BUNDLE_IDENTIFIER$/ { print $2; exit }'

Use -workspace instead of -project when appropriate.

3. Confirm the app enables the bridge

The app must opt in before Inspector.start().

Minimum pattern:

var configuration = InspectorConfiguration.config(
    enableMCPBridge: true,
    snapshotExpiration: 300
)
configuration.snapshotMaxCount = 8
Inspector.setConfiguration(configuration)
Inspector.start()

If the app does not enable the bridge, MCP setup is blocked. For full consumer-side wiring, use the sibling inspector-mcp-consumer skill.

4. Register the MCP server in the client

Codex:

codex mcp add inspector -- \
  swift --package-path /absolute/path/to/Inspector run InspectorMCPServer launch \
  --xcodeproj /absolute/path/to/App.xcodeproj \
  --scheme AppScheme \
  --bundle-id com.example.app

Claude Code:

claude mcp add inspector -- \
  swift --package-path /absolute/path/to/Inspector run InspectorMCPServer launch \
  --xcodeproj /absolute/path/to/App.xcodeproj \
  --scheme AppScheme \
  --bundle-id com.example.app

If you are inside the Inspector repo itself, you can also point the client at:

• <Inspector repo>/Examples/MCP/run-inspector-mcp.sh
• or use the example config at <Inspector repo>/Examples/MCP/codex-inspector-mcp.json (replace the cwd placeholder).

5. Use the tools effectively

Tool order matters:

1. query
2. resolve / refresh_handle
3. subtree / list_actions / list_properties
4. snapshot
5. capture_state / diff_states / save_scenario / diff_scenario when debugging semantic state drift

Start narrow. Prefer:

• accessibilityIdentifierEquals
• classNameContains
• displayNameContains
• elementNameContains
• nodeKind

Good first query:

{"accessibilityIdentifierEquals":"Content Stack View"}

Avoid broad snapshots first. First get a stable handle with query, confirm the node with resolve, then call snapshot.

For longer exploration sessions, save the node's semanticReference from query/resolve results. If a handle goes stale, prefer:

{"semanticReference":"<semanticReference returned by query or resolve>"}

with refresh_handle.

Important semantics:

• refresh is best-effort rebinding for exploration
• mutation still requires a currently valid live handle
• if rebinding is ambiguous or the logical node is gone, the call fails instead of guessing

For depth-limited app-owned tree inspection, use:

{"handle":"<handle returned by query>","maxDepth":2}

with subtree.

For interactive sessions, chain query → inspect to open the Inspector UI focused on a view:

{"handle":"<handle returned by query>"}

Response: {"handle":"...", "presented": true}. presented: true means the Inspector UI dispatch was accepted — the modal animates in asynchronously. Consecutive inspect calls stack modals; Inspector's native back affordance dismisses them.

For the first write-side app interaction primitive, use query → tap on exact-handle button-like controls:

{"handle":"<handle returned by query>"}

Response: {"handle":"...", "dispatched": true}. dispatched: true means Inspector synchronously fired one supported control action for that exact-handle UIControl. This is semantic activation, not synthetic touch injection:

• no hit-test simulation
• no gesture-recognizer dispatch for plain UIViews
• no ancestor promotion from child handle to parent button

MVP limitations:

• succeeds only for exact-handle, visible, enabled UIControls wired for .primaryActionTriggered or .touchUpInside
• fails for gesture-backed non-controls, sliders/switches/date pickers, hidden/disabled/detached controls, and stale handles
• after any successful mutation, prefer a fresh query before the next action because the UI may have changed and invalidated handles

For semantic UI operations beyond tap, use query → list_actions → perform_action:

{"handle":"<handle returned by query>"}

list_actions returns opaque actionRef values for currently available actions such as:

• Inspector panel opens (inspect)
• per-element highlight toggles (showHighlight / hideHighlight)

Then call:

{"actionRef":"<actionRef returned by list_actions>"}

Response:

{"actionRef":"...","performed":true,"refreshRecommended":true}

Because action refs are ephemeral, rediscover them after a successful action before chaining the next semantic operation.

For broader property-driven mutation, use query → list_properties → set_property:

{"handle":"<handle returned by query>","panel":"attributes","includeReadOnly":false}

list_properties returns editable descriptors plus opaque propertyRef values. set_property then applies exactly one typed value field:

• boolValue
• numberValue
• stringValue
• selectionIndex

Example:

{"propertyRef":"<propertyRef returned by list_properties>","boolValue":true}

MVP limitations:

• this reuses Inspector's existing property handlers without presenting Inspector UI
• supported kinds are scalar/editor-like properties only (switch, stepper, textField, textView, selection lists/groups)
• property refs are ephemeral and should be rediscovered after any successful mutation
• unsupported property kinds and malformed values fail fast server-side

For named semantic baselines, use:

{"name":"quicktype-baseline"}

with:

• save_scenario → capture the current live hierarchy under a stable name
• list_scenarios → enumerate saved baselines
• diff_scenario → compare the current hierarchy against that named baseline
• delete_scenario → remove obsolete baselines

capture_state / diff_states are still better for short-lived ad-hoc before/after comparisons inside one session. save_scenario is for longer-lived named references such as “clean screen”, “keyboard shown”, or “quicktype visible”.

5a. Controlling view-hierarchy layers (v2.2)

Call list_layers to see which built-in highlight layers are populated on the current screen, along with their active state:

{}

Response (success envelope):

{"layers":[
  {"name":"Wireframes","displayName":"Wireframes","active":false},
  {"name":"Controls","displayName":"Controls","active":true}
]}

Flip a layer on or off by name — toggle_layer returns the intended post-toggle state immediately (install/remove is async on the UI thread):

{"name":"Wireframes"}

Response: {"name":"Wireframes","active":true}. If the name does not match any populated layer, the response is an internalFailure envelope whose details.message names the offending input — call list_layers first to copy the exact name.