XcodeBuildMCP

Ein Model Context Protocol (MCP)-Server, der Xcode-bezogene Tools für die Integration mit KI-Assistenten und anderen MCP-Clients bereitstellt.

Inhaltsverzeichnis

Überblick
Warum?
Merkmale
Erste Schritte
Inkrementelle Build-Unterstützung
Fehlerbehebung
- Diagnosetool
  - Verwendung mit Mise
  - Verwendung mit npx
- MCP-Serverprotokolle
Datenschutz
- Was wird an Sentry gesendet?
- Abmeldung von Sentry
Selektive Werkzeugregistrierung
Demos
Beitragen
Lizenz

Überblick

Dieses Projekt implementiert einen MCP-Server, der Xcode-Operationen als Tools bereitstellt, die von KI-Agenten über das MCP-Protokoll aufgerufen werden können. Es ermöglicht die programmatische Interaktion mit Xcode-Projekten über eine standardisierte Schnittstelle, die für agentengesteuerte Entwicklungsabläufe optimiert ist.

Warum?

Das XcodeBuild MCP-Tool dient in erster Linie dazu, die Interaktion zwischen KI-Agenten und Xcode-Projekten zu optimieren und zu standardisieren. Durch die Bereitstellung dedizierter Tools für gängige Xcode-Operationen entfällt die Abhängigkeit von manuellen oder möglicherweise fehlerhaften Befehlszeilenaufrufen.

Dies gewährleistet einen zuverlässigen und effizienten Entwicklungsprozess und ermöglicht es Agenten, die Funktionen von Xcode nahtlos zu nutzen und gleichzeitig das Risiko von Konfigurationsfehlern zu reduzieren.

Entscheidend ist, dass dieses MCP es KI-Agenten ermöglicht, Codeänderungen selbstständig zu validieren, indem sie Projekte erstellen, Fehler prüfen und autonom iterieren. Im Gegensatz zu benutzergesteuerten Tools wie Sweetpad ermöglicht XcodeBuild MCP Agenten die effektive Automatisierung dieser Workflows.

Merkmale

Der XcodeBuildMCP-Server bietet die folgenden Toolfunktionen:

Xcode-Projektmanagement

Projekte entdecken : Entdeckung von Xcode-Projekten und Arbeitsbereichen
Build-Operationen : Plattformspezifische Build-Tools für macOS, iOS-Simulator und iOS-Geräteziele
Projektinformationen : Tools zum Auflisten von Schemata und Anzeigen von Build-Einstellungen für Xcode-Projekte und -Arbeitsbereiche
Clean Operations : Bereinigen Sie Build-Produkte mit der nativen Clean-Aktion von xcodebuild
Inkrementelle Build-Unterstützung : Blitzschnelle Builds mit inkrementeller Build-Unterstützung (experimentell, Opt-in erforderlich)

Simulatorverwaltung

Simulatorsteuerung : iOS-Simulatoren auflisten, starten und öffnen
App-Bereitstellung : Installieren und starten Sie Apps auf iOS-Simulatoren
Protokollerfassung : Erfassen Sie Laufzeitprotokolle von einem Simulator
UI-Automatisierung : Interagieren Sie mit Simulator-UI-Elementen (Beta)
Screenshot : Screenshots von einem Simulator aufnehmen (Beta)

App-Dienstprogramme

Bundle-ID-Extraktion : Extrahieren Sie Bundle-IDs aus iOS- und macOS-App-Bundles
App-Start : Starten Sie erstellte Anwendungen sowohl auf Simulatoren als auch auf macOS

Erste Schritte

Voraussetzungen

macOS 14.5 oder höher
Xcode 16.x oder höher
mise

Einzeiliges Setup mit Mise

So installieren Sie Mise:

# macOS (Homebrew)
brew install mise

# Other installation methods
# See https://mise.jdx.dev/getting-started.html

Weitere Informationen zu Mise finden Sie in der offiziellen Dokumentation .

Konfigurieren von MCP-Clients

Konfigurieren Sie Ihren MCP-Client (Windsurf, Cursor, Claude Desktop usw.) für die Verwendung des XcodeBuildMCP-Servers, indem Sie die MCP-Konfiguration Ihrer Clientanwendung ändern und die Versionsnummer so ändern, dass sie mit der Version übereinstimmt, die Sie verwenden möchten:

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.4.0",
        "--",
        "xcodebuildmcp"
      ]
    }
  }
}

[!NOTE] Vermeiden Sie bei der Verwendung von mise die Verwendung des @latest-Tags, da mise das Paket zwischenspeichert und möglicherweise nicht automatisch auf die neueste Version aktualisiert. Verwenden Sie stattdessen lieber eine explizite Versionsnummer.

[!WICHTIG] Bitte beachten Sie, dass XcodeBuildMCP xcodebuild auffordert, die Makrovalidierung zu überspringen. Dies dient dazu, Fehler beim Erstellen von Projekten mit Swift-Makros zu vermeiden.

Mit einem Klick in VS Code installieren

Aktivieren der UI-Automatisierung (Beta)

Für UI-Automatisierungsfunktionen (Tippen, Wischen, Screenshot usw.) müssen Sie idb_companion von Facebook installieren:

brew tap facebook/fb
brew install idb-companion

Der idb-Client wird ebenfalls benötigt, XcodeBuildMCP versucht jedoch, ihn für Sie zu installieren. Sollten die UI-Automatisierungsfunktionen weiterhin nicht verfügbar sein, können Sie den Client manuell mit dem folgenden Befehl installieren (vorausgesetzt, Sie haben Python installiert):

pipx install fb-idb==1.1.7

[!WICHTIG] Bitte beachten Sie, dass sich die Funktionen zur UI-Automatisierung derzeit in der Betaphase befinden und daher noch einige Unvollständigkeiten aufweisen können. Sollten Sie auf Probleme stoßen, melden Sie diese bitte im Issue Tracker .

[!NOTE] Das Anzeigen von Bildern in Tool-Antworten und deren Einbettung in den Chat-Kontext wird möglicherweise nicht von allen MCP-Clients unterstützt. Derzeit ist bekannt, dass dies in Cursor unterstützt wird.

Inkrementelle Build-Unterstützung

XcodeBuildMCP bietet experimentelle Unterstützung für inkrementelle Builds. Diese Funktion ist standardmäßig deaktiviert und kann durch Setzen der Umgebungsvariable INCREMENTAL_BUILDS_ENABLED auf true aktiviert werden:

Um inkrementelle Builds zu aktivieren, setzen Sie die Umgebungsvariable INCREMENTAL_BUILDS_ENABLED auf true :

Beispiel für eine MCP-Clientkonfiguration:

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.4.0",
        "--",
        "xcodebuildmcp"
      ],
      "env": {
        "INCREMENTAL_BUILDS_ENABLED": "true"
      }        
    }
  }
}

[!WICHTIG] Bitte beachten Sie, dass die Unterstützung inkrementeller Builds derzeit experimentell ist und Ihre Ergebnisse variieren können. Bitte melden Sie auftretende Probleme im Issue Tracker .

Fehlerbehebung

Wenn bei XcodeBuildMCP Probleme auftreten, kann das Diagnosetool Ihnen bei der Identifizierung des Problems helfen, indem es detaillierte Informationen zu Ihrer Umgebung und Ihren Abhängigkeiten bereitstellt.

Diagnosetool

Das Diagnosetool ist ein eigenständiges Dienstprogramm, das Ihre Systemkonfiguration überprüft und den Status aller von XcodeBuildMCP benötigten Abhängigkeiten meldet. Es ist besonders nützlich bei der Meldung von Problemen.

Verwendung mit Mise

# Run the diagnostic tool using mise
mise x npm:xcodebuildmcp@1.4.0 -- xcodebuildmcp-diagnostic

Verwendung mit npx

# Run the diagnostic tool using npx
npx xcodebuildmcp@1.4.0 xcodebuildmcp-diagnostic

Das Diagnosetool gibt umfassende Informationen aus über:

System- und Node.js-Umgebung
Xcode-Installation und -Konfiguration
Erforderliche Abhängigkeiten (xcodebuild, idb usw.)
Umgebungsvariablen, die XcodeBuildMCP beeinflussen
Status der Funktionsverfügbarkeit

Wenn Sie Probleme auf GitHub melden, fügen Sie bitte die vollständige Ausgabe des Diagnosetools bei, um die Fehlerbehebung zu erleichtern.

MCP-Serverprotokolle

Es kann hilfreich sein, Zugriff auf die Protokollmeldungen des MCP-Servers zu haben, um etwaige Probleme zu identifizieren. Die Protokolle werden von der Client-Anwendung erfasst, beispielsweise in Cursor:

Cursor:

find ~/Library/Application\ Support/Cursor/logs -name "Cursor MCP.log" -exec zip -r matching_logs.zip {} +

Wenn Ihr MCP-Client keine Protokolldateien hat, können Sie den Server direkt mit dem MCP Inspector-Tool ausführen. Weitere Informationen hierzu finden Sie unter Debuggen . Nach dem Ausführen des MCP-Tools werden alle Protokollmeldungen im Fehlerbereich angezeigt, was bei der Diagnose hilfreich sein kann.

Datenschutz

Dieses Projekt verwendet Sentry zur Fehlerüberwachung und -diagnose. Sentry hilft uns, Probleme, Abstürze und unerwartete Fehler zu verfolgen, um die Zuverlässigkeit und Stabilität von XcodeBuildMCP zu verbessern.

Was wird an Sentry gesendet?

Standardmäßig werden nur Protokolle auf Fehlerebene und Diagnoseinformationen an Sentry gesendet.
Fehlerprotokolle können Details wie Fehlermeldungen, Stacktraces und (in einigen Fällen) Dateipfade oder Projektnamen enthalten. Sie können die Quellen in diesem Repository überprüfen, um genau zu sehen, was protokolliert wird.

Abmeldung von Sentry

Wenn Sie keine Fehlerprotokolle an Sentry senden möchten, können Sie dies ablehnen, indem Sie die Umgebungsvariable SENTRY_DISABLED=true festlegen.

Beispiel für eine MCP-Clientkonfiguration:

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.4.0",
        "--",
        "xcodebuildmcp"
      ],
      "env": {
        "SENTRY_DISABLED": "true"
      }        
    }
  }
}

Selektive Werkzeugregistrierung

Standardmäßig sind alle Tools aktiviert. Für manche Clients kann es jedoch sinnvoll sein, nur bestimmte Tools zu aktivieren, um die an den Client gesendete Kontextmenge zu reduzieren. Dies kann durch das Setzen bestimmter Umgebungsvariablen in der MCP-Konfiguration Ihres Clients erreicht werden.

Sobald Sie ein oder mehrere Tools oder Toolgruppen aktiviert haben, werden alle anderen Tools deaktiviert. Um beispielsweise nur die Simulator-bezogenen Tools zu aktivieren, können Sie die Umgebungsvariable auf XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW=true setzen. Dadurch werden nur Tools zum Erstellen, Ausführen und Debuggen auf Simulatoren verfügbar.

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.4.0",
        "--",
        "xcodebuildmcp"
      ],
      "env": {
        "XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW": "true"
      }        
    }
  }
}

Eine Liste der verfügbaren Tools und detaillierte Anweisungen zum Aktivieren dieser Tools finden Sie in der Datei TOOL_OPTIONS.md .

Demos

Autonomes Beheben von Build-Fehlern im Cursor

Nutzung der neuen UI-Automatisierungs- und Bildschirmaufnahmefunktionen

Erstellen und Ausführen einer iOS-App in Claude Desktop

https://github.com/user-attachments/assets/e3c08d75-8be6-4857-b4d0-9350b26ef086

Beitragen

Beiträge sind willkommen! So können Sie XcodeBuildMCP verbessern.

Weitere Informationen zum Konfigurieren Ihrer lokalen Umgebung und zum Beitragen zum Projekt finden Sie in unserem Dokument „ BEITRAGEN“ .

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – Einzelheiten finden Sie in der Datei LICENSE .

Integrations