git:20261102.74e925e to git:20261102.a0d42be

1 added, 1 removed. Audit A to A.

---

name: reference

user-invocable: false

description: Reference for the Xcode MCP, MobileBuildMCP and Sosumi setup xcrew installs. Load before configuring either server, and when an Xcode MCP call fails ("not approved", "produced malformed response", "File not found in project structure", a timeout), a MobileBuildMCP tool is missing, LLDB refuses `expr`, or SourceKit reports `No such module`.

---

# xcrew reference

The routing table reaches each session at start. This file holds what each server needs to work and what to do when it doesn't. `xcrew doctor` checks what xcrew can't run without, its installation and the toolchain, and prints the fix for anything wrong.

## MobileBuildMCP

- Formerly XcodeBuildMCP: version 2.7.1 renamed the binary, the `MOBILEBUILDMCP_*` environment variables and the config folder, with no fallback to the old ones.

- Config: `.mobilebuildmcp/config.yaml`, read from the project root at server start. `xcrew setup` (or `/xcrew:setup`) writes it and marks it with `.mobilebuildmcp/.xcrew-managed`; a later setup rewrites a marked config and leaves an unmarked one alone. Delete the marker to keep hand edits.

- Enabled tool groups: `simulator`, `sim-env` (custom: erase, appearance, location, status bar, keyboard toggles), `ui-automation`, `debugging`. The session tools (`session_use_defaults_profile` and the like) are always there. Xcode MCP tools go through the `xcode` server, never MobileBuildMCP's `xcode-ide`, which is off. A tool that "doesn't exist" usually means its group is off; groups load at server start, so restart Claude Code after changing them.

- - Profiles: `unit` (the scheme that runs unit tests), `app` (app scheme and bundle ID) and `ui` (UI-test scheme); the session briefing names the ones this project has. In a project where several schemes run unit tests, setup lists them, the person picks one and it becomes `unit`. Switch with `session_use_defaults_profile`; for another module's tests, set its scheme with `session_set_defaults`. Saving defaults with `persist: true` also makes that profile active — set `activeSessionDefaultsProfile` back afterwards.

+ - Profiles: `unit` (the scheme that runs unit tests), `app` (app scheme and bundle ID) and `ui` (UI-test scheme); the session briefing names the ones this project has. Setup gives `unit` the scheme that runs the most unit-test targets; when several tie, it lists them, the person picks one and it becomes `unit`. Switch with `session_use_defaults_profile`; for another module's tests, set its scheme with `session_set_defaults`. Saving defaults with `persist: true` also makes that profile active — set `activeSessionDefaultsProfile` back afterwards.

- Tests: `test_sim` takes no scheme argument; set it in the session defaults, then pass `-only-testing:<Target>/<Class>` through `extraArgs`.

- Coverage tools need an absolute `.xcresult` path; `~` is not expanded.

- LLDB: attach, stack, breakpoints and `image list` work with the default DAP backend; `expr` needs `debuggerBackend: lldb-cli` in the config.

- The `mobilebuildmcp` command line resolves `simulatorName` on the newest installed iOS only; pass `--simulator-id` there. The MCP server is unaffected.

- Telemetry is off (`sentryDisabled: true` and `MOBILEBUILDMCP_SENTRY_DISABLED=true`). The `mobilebuildmcp://doctor` resource's "Sentry enabled" line reads only a legacy variable and says Yes regardless; its Environment Variables section is accurate.

- Leave `incrementalBuildsEnabled` off: it downloads and runs `xcodemake`, writes a large `Makefile` into the project root, and was slower than plain rebuilds in testing.

## Xcode MCP

- Works with Xcode closed once Claude Code is approved. "This agent isn't approved" → call `XcodeOpenWorkspace` on the workspace; Xcode shows a dialog the user approves and sets to always allow. `xcrun mcp-server status` lists approved agents and folders.

- File tools take **project-navigator paths**, not disk paths (`File not found in project structure` means a disk path was passed). Look paths up with `XcodeGlob` first.

- Previews, snippets and per-file diagnostics need the **active scheme** to build the file ("Active scheme does not build this file" → `XcodeSwitchScheme`). Switching scheme or destination also changes the user's Xcode window.

- Builds land in Xcode's own DerivedData, shared with the IDE, so they share its failures.

- `RenderPreview`: the first render of a module builds it (minutes), later variants take seconds. Variants: light/dark, contrast, Dynamic Type sizes, orientation, locales.

- `XcodeRefreshCodeIssuesInFile` can time out on a file created moments ago; retry once.

- Tests run through the active scheme's test plan; schemes without one fall back to their test targets.

- `XcodeWrite` re-saves the whole project file in Xcode's newer format. In a Tuist or XcodeGen project it's refused: write files with Write and the generator picks them up. In a classic project it's allowed, and it's the way a new file joins its target; projects using synchronized folders pick up files written with Write anyway. `XcodeUpdate` and `XcodeRM` are harmless but add nothing over Edit and `rm`.

## When an Xcode MCP build fails with "… produced malformed response"

Often a macro plugin (for example a mocking library's `…Macros` binary) was killed at launch: in projects generated by Tuist before 4.203, a copy phase overwrites the plugin in place with `cp -f`, and macOS kills later launches of a binary rewritten that way. The indexer's copy (`Index.noindex`) dies the same way and breaks macro expansion in the editor. The fix is to upgrade Tuist to 4.203 or later and regenerate; until then, clean the build folder and rebuild, which replaces the dead plugin. When no project has the phase, the cause is another one: a toolchain mismatch (`xcode-select -p` against the Xcode in use) or stale prebuilt macros; clean the build folder.

## When a build fails with errors that don't point at the code

After a failed build or test run, xcrew adds a note when the cause is this Mac (a corrupt module cache, a simulator that's gone) and names the fix; it never runs the fix. For an earlier failure, run `xcrew why`, which reads MobileBuildMCP's newest build log, or `xcrew why --log <file>`. When it says nothing on the Mac explains the failure, the errors are the code's.

## SourceKit `No such module` errors

Claude Code's Swift language server (sourcekit-lsp) reads build settings only from a Swift package, a compilation database or a build server; it cannot read an Xcode project. Without a `Package.swift` it checks each file alone against the macOS SDK, so `import UIKit` and every first-party import show as errors and go-to-definition finds nothing across modules. Only same-file errors are real. Check with the Xcode MCP instead; `xcode-build-server` can give sourcekit-lsp the real flags from Xcode's build log (untested by xcrew).

## Apple documentation

Sosumi first: search returns short results with links (including WWDC sessions), and each fetched page shows the API's minimum OS version. Conformance conditions in Apple's data can be wrong; check the SDK's `.swiftinterface` when one matters. The Xcode MCP's `DocumentationSearch` matches the installed SDK but omits availability and returns long results — use it offline.