--- 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`