Xcode Debugger Mcp Workflow

---
name: xcode-debugger-mcp-workflow
description: Diagnose a running Apple app through Xcode’s active LLDB debugging session and assess the experimental Xcode 27 lldb-mcp executable. Use when setting breakpoints, inspecting frames or variables, issuing LLDB commands, or distinguishing a usable Xcode debugger session from an unavailable standalone debugger MCP server.
---

# Xcode Debugger MCP Workflow

## Purpose

Use Xcode's active debugger session through `xcrun mcpbridge` as the stable agent-facing LLDB route. Treat the standalone `xcrun lldb-mcp` executable as experimental until it starts successfully on the selected Xcode toolchain and exposes a documented tool contract.

## Xcode And LLDB MCP Boundaries

Xcode 27 exposes two distinct MCP paths:

- `xcrun mcpbridge` is Xcode's STDIO bridge. It connects an external MCP client to a running Xcode process, selecting it with `MCP_XCODE_PID` or `MCP_XCODE_SESSION_ID` when needed. It owns Xcode project tools and the active run/debug-session tools. On the locally observed surface, `InvokeDebuggerCommand` sends a focused LLDB command to that active debugging session.
- `xcrun lldb-mcp` is LLDB's standalone STDIO-to-socket bridge. It discovers an LLDB MCP server or launches a separate background `lldb` process when none exists. Its documented surface is one general `lldb_command` tool plus debugger and target resources. It does not document a way to select or take ownership of Xcode's active debugging session.

For a running Xcode app, start with `mcpbridge`, the active session, and the smallest Xcode-provided debugger command. Use standalone `lldb-mcp` only for a separately owned LLDB workflow after its startup and tool discovery both succeed.

## Current Xcode 27 Beta 3 State

On 2026-07-12, the selected Xcode 27.0 Beta 3 toolchain (`27A5218g`) resolves both `mcpbridge` and `lldb-mcp`. `mcpbridge --help` works and documents STDIO bridge behavior, Xcode PID/session selection, and agent export behavior. `lldb-mcp --help` fails before startup because dyld cannot resolve `@rpath/lib_CompilerSwiftIDEUtils.dylib`, even though that library exists elsewhere inside the Xcode bundle.

This is a local Beta 3 packaging observation. Public Xcode release notes announce `lldb-mcp`, but neither those notes nor the public LLDB documentation identify this dyld failure as a known issue. Do not claim it affects every Xcode installation or beta. Do not work around this with copied libraries, symlinks, modified Xcode bundles, or a persistent loader-path override. Recheck a later Xcode beta or release before claiming standalone `lldb-mcp` support.

## Workflow

1. Classify the need: breakpoint, crash/exception, stalled thread, incorrect value, object lifetime, framework behavior, or an ordinary build/test failure.
2. For normal project execution, use `xcode-build-run-workflow` to open the project, select the destination, and run with the debugger attached. Do not attach a debugger merely to replace a build log.
3. Connect through `mcpbridge` to the intended running Xcode. When multiple Xcode apps are open, use `MCP_XCODE_PID`; use `MCP_XCODE_SESSION_ID` only when the caller owns a specific Xcode tool session. Verify an active Xcode debug session before sending a command. If no session exists, report that prerequisite instead of inventing a process identifier or attaching to an unrelated process.
4. Discover the tools exposed by that Xcode session. Use its active-session debugger command surface for focused LLDB requests: `bt`, `thread list`, `frame variable`, `po`, a named breakpoint, or a bounded step. In the observed Beta 3 surface, `InvokeDebuggerCommand` shares Xcode's own LLDB state.
5. Capture the smallest evidence packet: the triggering action, stopped thread/frame, relevant variables, exception or return state, and the exact command output. Redact user content, secrets, and unnecessary memory values.
6. Hand off by evidence type: tests to `xcode-testing-workflow`, simulator trace or memgraph evidence to `ios-runtime-forensics-workflow`, device selection or capture to `xcode-device-hub-workflow`, and source repair to the owning code workflow.
7. If the request specifically requires standalone `lldb-mcp`, run a no-mutation capability probe on the selected toolchain first. If startup succeeds, discover `lldb_command` and the debugger/target resources before sending a bounded command to a separately owned LLDB debugger ID. If startup fails, return the loader failure and use the Xcode active-session path only when a project debug session exists.

## Guards

- Do not claim `lldb-mcp` is available merely because `xcrun --find lldb-mcp` returns a path.
- Do not modify Xcode, inject dylibs, change loader paths, or attach to arbitrary user processes to make an experimental debugger server work.
- Do not run unbounded `continue`, expression evaluation with side effects, or process-control commands without user intent and a clear debug-session owner.
- Do not treat a debugger value as a leak, performance profile, or test result without the matching runtime or test evidence.
- Do not replace Xcode's normal debugger session with an unverified third-party MCP server.
- Do not assume standalone `lldb-mcp` reaches the debugger that Xcode already owns; its public contract describes LLDB MCP discovery or a separately launched `lldb` process.

## Physical-device debugging

For a physical-device failure, keep the XCUITest or run result as the primary failure record. Confirm the paired device identity, app build, OS version, and triggering action through `xcode-device-hub-workflow`, then use the active Xcode debugger session for one focused breakpoint, backtrace, frame inspection, or bounded LLDB command. Preserve only the minimum device-specific diagnostics or screen evidence needed to explain the failure, and do not alter pairing, Developer Mode, app data, or device settings unless the user explicitly requests that state change.

## References

- `references/beta3-capability-evidence.md`
- `references/active-session-debugging-contract.md`
- `references/xcode-27-debugging-mcp-surface.md`