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

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:

{
  "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
• 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)
• Komplementære alternativer: ios-simulator-mcp (joshuayoes), ios-simulator-skill (conorluddy).