app-creator/domain-packs/ios-app/patterns/xcode-mcp-toolchain.md

# Pattern: Xcode MCP-toolchain (Spor B)

**Status:** Anbefalt for nye iOS-prosjekter fra mai 2026. Erstatter Spor A (rent Bash `xcodebuild`-wrapper-mønster fra pre-2026 — fortsatt gyldig hvis MCP-avhengighet er uønsket).

**Verifisert:** 2026-05-15 mot installert Xcode 26.5, XcodeBuildMCP v2.5.2, Apple mcpbridge (universal binary) i Xcode.app.

## Hvorfor

iOS-utvikling med en AI-agent på CLI har historisk hatt to friksjons-punkter:

1. **Tekst-parsing av `xcodebuild`-output.** Build-feil drukner i loggene; agenten må regex-trekke feilkoder. Stort kontekstforbruk per feil.
2. **Ingen tilgang til levende Xcode-state.** Agenten kan ikke se hva som er åpent, hva som er diagnosert i editor, hva SwiftUI Preview viser, hva LLDB sier.

To MCP-servere løser dette komplementært — den ene headless, den andre med Xcode-runtime-tilgang. Begge registreres samtidig.

## Komponenter

### XcodeBuildMCP (headless, anbefalt for harness-loops)

- **Hva:** Sentrys MCP-server som wrapper `xcodebuild` CLI.
- **Hva den gir:** ~82 verktøy: build, test, run, simulator-kontroll, LLDB-debugging — alt med **strukturerte JSON-responser** i stedet for raw build-logs.
- **Hva den koster:** Ingen Xcode-prosess kreves; standalone Node.js-server. Første start trekker pakken via `npx`.
- **Når brukes:** Headless build/test (CI-aktige flyter), harness-loops der Xcode ikke kjører, simulator-kontroll uten Xcode-UI.
- **URL:** [github.com/getsentry/XcodeBuildMCP](https://github.com/getsentry/XcodeBuildMCP)

### Apple mcpbridge (krever kjørende Xcode)

- **Hva:** Apples native MCP-server som ble shipped med Xcode 26.3+. Universal binary i `/Applications/Xcode.app/Contents/Developer/usr/bin/mcpbridge`. Kjøres via `xcrun mcpbridge`.
- **Hva den gir:** ~20 verktøy: filoperasjoner i åpent prosjekt, diagnostics i editor, SwiftUI Preview-tilstand, build-status fra live Xcode.
- **Hva den koster:** Xcode må kjøre med prosjektet åpent. Bridge auto-detekterer Xcode-PID; eller sett `MCP_XCODE_PID` eksplisitt.
- **Når brukes:** Interaktiv utvikling der editor er åpen, Preview brukes, diagnostics inspiseres mens kode skrives.
- **Apple-integrert agent-launch:** `xcrun mcpbridge run-agent claude` starter Claude med Xcode-tools pre-konfigurert.

### Komplementær, ikke overlappende

| Behov | Verktøy |
|-------|---------|
| Bygge fra CLI uten Xcode | XcodeBuildMCP |
| Kjøre tester i simulator uten Xcode-UI | XcodeBuildMCP |
| Inspisere live editor-diagnostics | Apple mcpbridge |
| Hente filsti i åpent prosjekt | Apple mcpbridge |
| LLDB-debug-session i CLI | XcodeBuildMCP |
| SwiftUI Preview-state | Apple mcpbridge |

## Setup

### Per-prosjekt `.mcp.json`

Se `scaffold/mcp.json` for komplett template. Minimum:

```json
{
  "mcpServers": {
    "xcodebuildmcp": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    },
    "apple-xcode": {
      "command": "xcrun",
      "args": ["mcpbridge"]
    }
  }
}
```

> ⚠️ **`mcp`-subkommando er obligatorisk for XcodeBuildMCP.** Uten den kjører binæren i CLI-modus og henger ved stdin-venting til Claude Code's 30s MCP-timeout. Symptom: "MCP server 'xcodebuildmcp' connection timed out after 30000ms". Verifisert mot v2.5.2 (mai 2026).

### Forutsetninger

- macOS med Xcode 26.3 eller nyere (`xcrun mcpbridge --help` bekrefter installasjon).
- Node.js installert (sjekk `node --version` — XcodeBuildMCP krever v18+).
- iOS-platform-runtime + Simulator-runtime installert via Xcode > Settings > Platforms (det ene blokkerer `xcodebuild` med "iOS X.X is not installed", det andre med "CoreSimulator is out of date").
- Apple Developer Team registrert + DEVELOPMENT_TEAM-ID i `project.yml`.

### Verifiser etter setup

1. `xcrun mcpbridge --help` viser bridge-hjelp (Apple-side OK).
2. `npx -y xcodebuildmcp@latest --version` lar `npx` hente pakken (XcodeBuildMCP-side OK).
3. Restart Claude Code i prosjektmappa — MCP-servere lastes ved oppstart.
4. Verifiser at `mcp__xcodebuildmcp__*` og `mcp__apple-xcode__*` verktøy er tilgjengelige i agent-konteksten.

## Gotchas

- **Apple mcpbridge må ha Xcode åpent *med et prosjekt aktivt i workspace*.** Bare å starte Xcode er ikke nok — `mcpbridge` kobler til "Xcode's MCP tool service" som krever et aktivt workspace-dokument. Symptom: server-handshake lykkes (reconnect OK), men `tools/list` timeout etter ~30s. Fix: åpne `.xcodeproj`/`.xcworkspace` i Xcode først. Hvis du har flere Xcode-instanser: sett `MCP_XCODE_PID` eksplisitt.
- **XcodeBuildMCP er npx-hentet hver gang ved `@latest`.** Pin versjon (`xcodebuildmcp@2.3.2`) i `.mcp.json` for repeterbarhet hvis det er kritisk.
- **CoreSimulator-mismatch.** Hvis macOS-systemets CoreSimulator-framework er eldre enn Xcode's forventede versjon (`1051.49.0 < 1051.54.0`-mønsteret), feiler simulator-baserte kommandoer. Fix: åpne Xcode én gang for å fullføre komponent-installasjon, eller kjør `softwareupdate --install-rosetta` / oppgrader macOS.
- **iOS-platform ikke installert.** Selv om SDK-en finnes, kan Xcode kreve at iOS-runtime også er lastet ned (Xcode > Settings > Platforms > iOS X.X). Symptomet er `xcodebuild: error: iOS X.X is not installed`.
- **DEVELOPMENT_TEAM tom.** Build feiler ved code-signing. Ikke en MCP-feil — kommer av `project.yml`. Sett `CODE_SIGNING_ALLOWED=NO` for første bygg-test, ellers fyll inn 10-tegn-ID fra Apple Developer Portal.
- **`npm install -g` vs `npx`.** Global installasjon er raskere kaldstart, men du må manuelt `npm update -g`. `npx -y @latest` henter hver gang men er alltid oppdatert. Velg per prosjekt-stabilitet.

## Forhold til Spor A (rent Bash xcodebuild)

Spor A er fortsatt gyldig — `xcodebuild` CLI-wrappere fungerer fortsatt og er det `XcodeBuildMCP` selv kaller under panseret. Velg Spor A hvis:

- Du vil ikke ha MCP-server-avhengighet i `.mcp.json`.
- Du vil ha eksplisitt shell-skript-kontroll over build/test-flyt.
- Du har eksisterende `ios-smoke-test.sh`/`simulator-lifecycle.sh`-investering du vil beholde.

Spor B vinner når:

- Build-feil parses ofte (XcodeBuildMCP's JSON-struktur sparer mye kontekst per feil).
- Du jobber interaktivt i Xcode parallelt med Claude (Apple mcpbridge gir levende editor-state).
- Du vil ha simulator-kontroll uten å skrive egne `xcrun simctl`-wrappere.

Ingen av dem utelukker den andre. Du kan kjøre Bash `xcodebuild` for én oppgave og XcodeBuildMCP for en annen i samme sesjon.

## Referanser

- XcodeBuildMCP — [github.com/getsentry/XcodeBuildMCP](https://github.com/getsentry/XcodeBuildMCP)
- Apple `mcpbridge` — innebygd i Xcode 26.3+. Dokumentert via `xcrun mcpbridge --help`.
- Sammenligningsartikkel — [Two MCP Servers Made Claude Code an iOS Build System (blakecrosley.com)](https://blakecrosley.com/blog/xcode-mcp-claude-code)
- Komplementære alternativer: [ios-simulator-mcp (joshuayoes)](https://github.com/joshuayoes/ios-simulator-mcp), [ios-simulator-skill (conorluddy)](https://github.com/conorluddy/ios-simulator-skill).